Introduction
‘Specimen Type’ is an important dropdown. Each specimen type belongs to a 'Specimen class,' such as Fluid, Molecular, Tissue, Cell, and others. In the recent versions, OpenSpecimen has added the ability to create custom specimen classes and support for multiple specimen units per specimen type per Collection Protocol.
Create a custom ‘Specimen Class’
Before v10.3, only 4 specimen classes (Fluid, Molecular, Tissue, and Cell) were supported. From v10.3 onwards you can add different specimen classes like plants, microbes, etc. depending on your requirements.
Go to 'Dropdown Manager'
Click on the 'Specimen Type' value
Click on 'Add'
Enter the Class name in ‘Dropdown value', leaving 'Parent Dropdown’ blank.
Add the mandatory properties: ‘quantity_unit', ‘concentration_unit’, and ’container_color_coding’:
Once the new class is added, this can be used as a ‘Parent Dropdown' for new specimen types.
Below are the specimen-type properties
Attribute | Property Name | Property Value | Description |
|---|---|---|---|
Specimen Type | quantity_unit | Quantity units for the specific specimen type | Used to display the units on the specimen pages. Value can only be plain text. If special characters like symbols need to be used, then it needs to be specified under quantity_display_unit. E.g., μg/m3 By default, the units are set at class level which will apply to all types under it:
|
Specimen Type | concentration_unit | Concentration unit for the specific specimen type | For example - microgram/ml |
Specimen Type | container_color_coding | The color representing the specimen class in the container location view | For example - background=red, opacity=0.5 |
Specimen Units (Dropdown values)
From v11.0, you can create/ update a list of the units you want to use in the system (Extras → Dropdown Manager → Specimen Unit). This list can be used to define specimen quantity/concentration units for specimen class/ type on system/CP level.
Specimen Units (Define specimen class/ CP specific units)
From v11.0, OpenSpecimen supports specimen units per CP. A common issue for clients with multiple groups was to make units uniform across the collection protocols. E.g., some groups wanted to use ul vs ml as units for fluids like serum/ plasma. With this feature, users can keep the units specific per specimen type within one collection protocol.
Configure specimen quantity/ concentration units using the UI
System-level
Navigate to Home → Extras → Specimen Units
Click on ‘Add’
Add all relevant values and add quantity and concentration units for any specimen class/ type for the selected CP.
CP level
Navigate to Home → Collection Protocols → View CP details → Settings → Specimen units
Follow steps #2 and #3 similar to system level
Working with units for live clients
From v11.0 onwards the system will automatically pick all the specimen units defined at individual specimen levels in specimen units (CP or system level). Manual intervention is not required.
If units are updated after specimens are collected, then the existing specimens won't be automatically recalculated. For example, if blood is changed from ml to μL, then the system won't change the values proportionately to μL. 1 ml won’t be updated to 1000 μL automatically. Users will have to change it manually via bulk upload.
Display the unit using the following logic:
Use the units specified either at the CP level or system level using the following fallback mechanisms: (cp, class, type) -> (cp, class, *) -> (*, class, type) -> (*, class, *) where * represents all of that category E.g., (cp, class, *): All specimen types of a given class for a specific CP.
When specimen type is changed, use the units specified either at the CP or system level for the selected type/class using the above mechanism.
There is no support for displaying specimen units in the query results view nor in the query exported CSV
Units are not stored with the specimen or specimen requirements. Their units are auto-computed based on what is configured either at the system or CP level
There is no mechanism to allow the lab user to override the units for any particular or selected specimens. Any update to the unit applies to all the specimens of that type.