A single
specimen, or sample, is collected and may be divided into many
vials, or other aliquots, which each then have various
events happen to them. The properties of specimens are defined and stored as fields/columns in three tables: study.SpecimenEvent, study.Vial, and study.Specimen. There are interactions among these tables to support a wide variety of specimen management needs and configurations.
- Specimen fields apply to a group of vials
- Vial fields apply to individual vials (or other aliquots of a specimen)
- SpecimenEvent fields apply to individual events for a vial, such as processing or a change of location.
The fields in each of these tables can be customized by an administrator to suit their specific requirements. There are also
rollup rules between the tables, building in functionality like 'Max-' and 'Latest-' automatically.
Edit Specimen, Vial, and SpecimenEvent Fields
The fields (columns) describing specimens are in three related tables. There are some fields which are used internally or optimized based on specific naming and ordering and cannot be altered or removed, but for other fields you can:
- Assign custom labels
- Provide descriptions
- Add validators or conditional formatting
- Reorder fields
- Add new fields
- Remove unnecessary fields (when not required by the system)
- Click the Manage tab.
- In the Specimen Repository Settings section, you can review and edit each set of fields via the respective links:
- Edit Specimen Fields.
- Edit Vial Fields
- Edit Specimen Event Fields
- Currently defined fields are listed.
- The first set of fields are built-in and required - a checkbox indicates required and the name and datatype panels are gray indicating that you cannot edit them. There is no 'X' for deleting these fields.
- Built-in fields which can be edited or removed if desired follow. You can change the name, type, edit other attributes by expanding the field with the , or use the on the left to delete.
- Use caution if you delete a field as that will delete all its data as well.
- To reorder fields, drag and drop them using the six-block handle on the left.
- To add more fields, click Add Field.
- Edit other attributes of specimen fields following the general instructions in the topic: Field Editor.
- After changing fields as required, click Save.
Since the Vial and Specimen tables are often combined, such as in the SpecimenDetail view, admins should not define fields with the same name on both tables. It is, however, possible to have fields of the same name on the Vial and SpecimenEvent tables.
Note: if you customize specimen fields and want to export the specimen archive for import into another study, the customized fields will not be included in a standalone archive - you must export the entire study to include admin-customized specimen fields.
Define Specimen Field Rollups
A single
specimen, or sample, is collected at a given time and place and then divided into many
vials, or other aliquots, which then have various
events happen to them. Sometimes you are interested in aggregated or sequenced results, such as the total volume in all vials for a given specimen. Events are also ordered by date, so maybe you sometimes want to see who first processed a given vial, and other times need to know the last person to process it.
There are three specimen tables with a hierarchical relationship: each
Specimen table row represents a collected sample and can have multiple rows in the
Vial table (portions of the same specimen sample), and each Vial can in turn have multiple rows in the
SpecimenEvent table (every change in status or location is an event). For additional details, see
Specimen Data Tables.
Using specific
naming pre- and post-fixes on these tables, fields may roll values "up" from the event to vial or from the vial to specimen tables using 'group by' clauses. There are built-in rollups already defined, and you may also define new rollup fields from either new custom fields you define, or from existing built-in fields.
Rollup Examples:
Built-in rollup of built-in field: "ProcessedByInitials" on the event table rolls up into "FirstProcessedByInitials" on the vial table.
User-defined rollup of built-in field: You could add "LatestProcessedByInitials" on the vial table, as there is no restriction on multiple rollups from the same field. Or you might rollup the built-in vial field "PrimaryVolume" into a new "TotalPrimaryVolume" field on the specimen table.
User-defined rollup of user-defined field: You might add a text field "Barcode" on the event and vial tables, then use "MaxBarcode" and "MinBarcode" on the specimen table to give you the ability to ensure all barcodes matched across all events and all vials by ensuring the two max and min values were the same.
Multi-level rollups: If desired, you can also roll up a field from vial to specimen that is already a rollup from event. For instance, you could watch for a diminishing resource by defining "MinLatestYield" on the specimen table that would store the minimum value of "LatestYield" across all vials of that specimen.
Rollups from SpecimenEvent to Vial Table
Events are ordered by date; sequence fields like 'first' and 'latest' apply to the date order of event rows, not to the order in the table itself.
| Prefix | Postfix Option? | From Type (on Event) | To Type (on Vial) | Behavior |
|---|
| First | no | any | must match | Vial field contains the value of the base field from the first event. |
| Latest | no | any | must match | Vial field contains the value of the root field from the latest event. |
| LatestNonBlank | no | any | must match | Vial field contains the latest non blank value of the root field. |
| Combine | no | numeric | must be promotable from "From Type" | All non-empty values are summed. |
| Combine | no | text | must match | All non-empty values are concatenated together in event order separated by a comma and space. |
Rollups from Vial to Specimen Table
Vials are not ordered by date, so the useful rollups from the Vial to Specimens table are different kinds of aggregation:
| Prefix | Postfix Option? | From Type (on Vial) | To Type (on Specimen) | Behavior |
|---|
| Count | yes | boolean | integer | Keeps a count of all 'true' settings of the root field on the vials for that specimen. |
| Total | yes | numeric | must be promotable from "From Type" | Sum of root field settings on all vials for that specimen. |
| SumOf | no | numeric | must be promotable from "From Type" | Sum of root field settings on all vials for that specimen (same as "Total" but can only be used as a prefix). |
| Max | yes | numeric | must be promotable from "From Type" | Contains the maximum value of the root field for all vials. |
| Max | yes | text | must match | Contains the alphabetically 'last' value (useful where all vials are expected to have the same value). |
| Min | yes | numeric | must be promotable from "From Type" | Contains the minimum value of the root field for all vials. |
| Min | yes | text | must match | Contains the alphabetically 'first' value. |
For fields to roll up from the Vial table to the Specimen table, they must also be defined on the SpecimenEvent table. For instance, if you have a field "Beta" on the Vial table and want to roll up into "TotalBeta" on the Specimen table, you also need to define "Beta" on the SpecimenEvent table.
When defining rollup fields, it is important to match types as well as observe the naming conventions. If you attempt to define rollup fields without the expected related fields on the other tables, a popup warning will give you additional information and offer the option to
Edit and Resolve Issues or
Save Changes without resolving issues.
Determine "At Repository" for a Specimen
The boolean field "At Repository" is set based on the interaction of other fields. If you are importing an archive or updating rows, the most recent SpecimenEvent row for a given vial will give the vial's current location in the "lab_id" field. The labs.tsv maps lab_id to lab_name, aka "location". If that lab_id refers to a location marked as a repository, then the "At Repository" field will be true.
To see whether given locations are marked as repositories, select
Manage > Manage Locations in your study.
Customize Aliquot Types (optional)
Different types of specimen material may be divided in different ways. A common specimen aliquot is a vial, and that terminology is used by default in the LabKey tools. If the specimen is divided in another way, such as into blocks of tissue, which may be further subdivided into many slides, you may edit the column (field) names to better describe the aliquots involved. This step is optional whether your specimens are vials or not and does not affect the underlying data tables, just the display names.
- Select (Admin) > Developer Links > Schema Browser.
- Open the Study schema and Specimen Detail query.
- Click Edit Metadata.
- Customize the Label for any given column.
- Click Save when finished.
- Click Specimen Data and select any view to see your revised column headings.
Note that some features within the UI are hard-coded to use the term "Vial" regardless of the changes made to column labels in the Schema Browser.
Related Topics
