Introduction
‘Specimen Type’ is a dropdown that defines the specimens you collect in OpenSpecimen. 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. This list can be used to define specimen quantity/concentration units for specimen class/ type on system/CP level.
Note: After upgrading to v11, all the values present in the specimen type properties for quantity and concentration will be added to this list automatically.
Navigate to Home → Extras → Dropdown Manager→ Specimen Unit
You will be navigated to the below page which has all the units
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 or capture quantity of DNA or RNA in ‘ul’ vs ‘ug’. With this feature, users have the ability to configure the units specific to each specimen type within a single collection protocol.
Configure specimen quantity/ concentration units using the UI
System-level
Navigate to Home → Extras → Specimen Units
User will be navigated to the list of current unit setup. The units visible here are being populated from the list configured in the ‘Dropdown manager’→ ‘Specimen Unit’ attribute
In this list, users can edit any of the existing unit values by clicking on the edit icon
Click on ‘Add’ to setup new unit configuration
Specimen Class Units
To add units at the specimen class level across the system, select specimen class and units from the dropdown.
Specimen Type Units
To add units per specimen type across the system, select specimen class and type and the units from the dropdown
CP level
There are 2 methods to add the CP specific units
Select the collection protocol from the list. Select specimen class and/or type for which you want to add quantity and concentration units.
Navigate to Home → Collection Protocols → View CP details → Settings → Specimen units
Working with units for live clients
From v11.0 onwards, the system will automatically pick all the specimen units defined for specimen types in the dropdown manager to the specimen units. 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 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.
On making any changes to the specimen units, please refresh your browser page once for the new configuration to be shown