✨ Auto-populate Sample, Container on Biospecimen create/update

[znatty22]

Motivation

#643 introduced the Sample and Container tables in order to address the shortcomings of the Biospecimen table. Now we need a way to populate these tables. And since a sample and container may be derived from a biospecimen, we can auto-populate them.

Approach

Each time a biospecimen is created or updated via an HTTP POST/PATCH, derive the sample and container from the input biospecimen and update sample/container tables.

Sample, Container Management

1. Find Sample - check if a sample already exists for this biospecimen

   • Use a specific set of biospecimen attributes to uniquely identify the sample:
   • sample_event_key = concat(participant_id, external_sample_id, age_at_event_days)
   • analyte_type
   • composition
   • source_text_tissue_type
   • source_text_anatomic_site
   • preservation_method
   • method_of_sample_procurement
   • concentration_mg_per_ml

2. Create Sample - if the sample does not exist - create it using the relevant subset of biospecimen attributes

   • All parameters above, plus:
   • participant_id
   • external_sample_id
   • volume_ul

3. Update Sample - if the sample exists - update it using the relevant subset of biospecimen attributes

4. Find Container - check if a container already exists for this biospecimen

   • Use a specific set of biospecimen attributes to uniquely identify the container:
   • biospecimen_id

5. Create Container - if the container does not exist - create it using the relevant subset of biospecimen attributes

   • All parameters above, plus:
   • sample_id
   • specimen_status
   • volume_ul

6. Update Container - if the container exists - update it using the relevant subset of biospecimen attributes

7. Sum Volume - update the the sample's volume_ul field with the sum of it's container volumes

[calkinsh]

everything in this PR makes sense to me except the idea that we might update a participant ID. I think participant ID should be part of the defining characteristics of a sample so I'm struggling to understand how we could both identify an existing sample (which implies the participant ID on the sample matches that on the specimen being registered) but then update the sample participant ID field (which implies the participant ID does not match the specimen being registered).

[calkinsh]

Oh hold on... is this related to participant.kf_id really being the primary ID for particpant and participant_id being a sort of secondary/external ID? So we are updating the external ID if it changes but relying on the kf_id/PK for confirming the sample already exists?

[znatty22]

@calkinsh Yep, the primary key for participant is participant.kf_id and the sample has a foreign key to it sample.participant_id so I think that does make it a defining characteristic of the sample.

[znatty22]

Technically we may not need the Sample.participant_id or Sample.external_id bc they are captured in the Sample.sample_event_key but I included them in the Sample table in case we want to populate the sample event key with something else and bc I felt it would be ok to have some redundancy to gain some clarity on which participant the sample came from and what the original biospecimen's external sample ID was

[znatty22]

Need to change this approach. Read, modify, write is an anti-pattern and doesn't work with concurrent requests. Use postgresql internal upsert (update on conflict)

[znatty22]

Closing for now. New approach is to implement the Sample table only. This is an MVP to meet Portal Beta requirements. Will try to autopopulate the Sample table from Biospecimens similar to approach here