The Specimen Properties defined by default in the study.SpecimenEvent, study.Vial, and study.Specimen tables are provided to support a wide variety of specimen management needs and configurations. A project administrator may also customize these properties to better suit the specific requirements of the project.
Edit Specimen Properties
There are some columns which are used internally or optimized based on specific naming and ordering thus cannot be altered or removed, but for others you can optionally:
- Assign custom labels (for example, "Used" or "Unused")
- Define field properties like custom descriptions and validators
- Reorder properties
- Add new properties
- Remove unused properties
- Click the Manage tab.
- In the Specimen Repository Settings section, click Edit Specimen Properties.
- Current Specimen Properties are listed by table, each starting with required built-in fields that cannot be edited. Built-in fields which can be edited or removed if desired follow.
- By clicking Add Field it is possible to add new user-defined specimen fields to each table. New fields will be added after the field you select, so to add fields to the end of the table, first select the last built-in field as shown:
- To reorder properties, use the up and down arrows, if available. If the arrow boxes are inactive (gray) reordering is not permitted.
- To remove a property, click the x to the left of the name. Use caution since when you delete a property, you will delete all of its data as well.
- After changing fields as required, click Save and Close.
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 properties will not be included in a standalone archive - you must export the entire study to include admin-customized specimen fields.
Define Specimen Property 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 Archive Data Destinations.
Using specific
naming pre- and post-fixes on these tables, properties 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 properties from either new custom properties you define, or from existing built-in properties.
Rollup Examples:
Built-in rollup of built-in property: "ProcessedByInitials" on the event table rolls up into "FirstProcessedByInitials" on the vial table.
User-defined rollup of built-in property: 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 property: 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 values were the same.
Multi-level rollups: If desired, you can also rollup 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 property contains the value of the base property from the first event. |
| Latest | no | any | must match | Vial property contains the value of the root property from the latest event. |
| LatestNonBlank | no | any | must match | Vial property contains the latest non blank value of the root property. |
| 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 property on the vials for that specimen. |
| Total | yes | numeric | must be promotable from "From Type" | Sum of root property settings on all vials for that specimen. |
| SumOf | no | numeric | must be promotable from "From Type" | Sum of root property 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 properties 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 property "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 properties, it is important to match types as well as observe the naming conventions. If you attempt to define properties without the expected related properties on the other tables, a popup warning will give you additional information and offer the option to proceed or cancel and fix the issue.
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 folder and Specimen Detail spreadsheet.
- Select 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.
