Specimen Label Format

There are three formats on the main CP page:

  • Specimen 
  • Derivative
  • Aliquot

There are similar fields at every specimen requirement level. The user can define different label formats for each specimen requirement or keep it the same as defined at the main CP level.

Tokens to generate specimen label format

You can set any label format to auto-generate specimen labels using specific tokens

 Click here to view the tokens...

Token Name

Description

Example
SYS_UID(n)

Assign a system-wide unique identifier

(n): Optionally specify the number of digits. For example, if (2) is used, then the numbers generated will be 01, 02, 03 etc.

e.g. If label format is 'WB%SYS_UID%', label generated will be 'WB193', where 193 is a system-wide unique identifier generated.
PPIParticipant protocol identifiere.g. If label format is '%PPI%.%SP_TYPE%.%PPI_SPEC_TYPE_UID% label generated will be 'PW-0001.WB.2', where 'PW-0001' is the PPI, 'WB' is the specimen type abbreviation set for whole blood and '2' is the unique sequence number related to PPI and specimen type.
SP_TYPESpecimen type abbreviation. For example, an abbreviation for 'Whole Blood' is WB. How to set abbreviations?e.g If label format is '%PPI%.%SP_TYPE%.%PPI_SPEC_TYPE_UID% label generated will be 'PW-0001.WB.4, where 'PW-0001' is the PPI, 'WB' is the specimen type abbreviation set for whole blood and '4' is the unique sequence number related to PPI and specimen type.
YR_OF_COLLYear of collection (four digits).e.g. if label format is %PPI%.%SP_TYPE%.YR_OF_COLL%_%PPI_YOC_UID%
'PW-0001.WB.2017_1', where 'PW-0001' is the PPI, 'WB' is the specimen type abbreviation set for whole blood, '2017' is the year of collection and '1' is unique sequence number for the participant within the year of collection.
PPI_YOC_UID(n)

The unique sequence number for the participant within the year of collection. This is generally used in combination of 'YR_OF_COLL' token.

Note: If this token is used individually, the label generated might not be unique across different years of collection.

(n): Optionally specify the number of digits. For example, if (2) is used, then the numbers generated will be 01, 02, 03 etc.

e.g. If label format is '%PPI%.%SP_TYPE%.%PPI_YOC_UID%' label generated will be 'PW-0001.WB.2017_1', where 'PW-001' is the PPI, 'WB' is the specimen type abbreviation set for whole blood '2017_1' is the unique sequence number for the participant within the year 2017.
PSPEC_LABELParent specimen's labele.g. If label format is '%PSPEC_LABEL%.%PSPEC_UID%', label generated will be 'PW-0001.WB.2017_1.2', where '2' is the unique sequence number within the parent specimen 'PW-0001.WB.2017_1'
PSPEC_UID(n)Unique sequence number within a parent specimen.e.g. If label format is '%PSPEC_LABEL%.%PSPEC_UID(2)%', label generated will be 'PW-0001.WB.2017_1.02', where '2' is the unique sequence number within the parent specimen 'PW-0001.WB.2017_1'
EVENT_LABELVisit event labele.g. If label format is '%PPI%_%EVENT_LABEL%.%EVENT_DATE%_%SYS_UID%', the label generated will be 'PW-001_Visit-01.20161106_309', where 'PW-001' is the PPI, 'Visit-01' is the event label, '20161106' is the visit date and '309' is the system generated a unique identifier
EVENT_DATEVisit date. Generates date in the format YYYYMMDDe.g. If label format is '%PPI%_%EVENT_LABEL%.%EVENT_DATE%_%SYS_UID%', the label generated will be 'PW-001_Visit-01.20161106_309', where 'PW-001' is the PPI, 'Visit-01' is the event label, '20161106' is the visit date and '309' is the system generated the unique identifier
SP_PATH_STATUSSpecimen pathology status abbreviatione.g. If label format is '%PPI%.%SP_TYPE%_%SP_PATH_STATUS%_%SYS_UID%', label generated will be 'PW-001.WB_T_2', where 'PW-001' is the PPI, 'WB' is the specimen type abbreviation set for whole blood 'T' is the pathology status abbreviation set for 'Malignant' pathology status and '2' is the unique sequence number.
VISIT_NAMEVisit namee.g. If label format is '%VISIT_NAME%_%SP_TYPE%_%PPI_SPEC_TYPE_UID%', label generated will be 'PW-0001_Baseline_29308.WB_2', where 'PW-0001_Baseline_29308' is the visit name, 'WB' is the specimen type abbreviation set for whole blood and '2' is the unique sequence number related to specific PPI and type of specimen.
PPI_SPEC_TYPE_UID(n, output_one)

Unique sequence number related to specific PPI and type of specimen. This is generally used in combination of '%SP_TYPE%' token.

n: Optionally specify the number of digits. For example, if (2) is used, then the numbers generated will be 01, 02, 03 etc.

output_one: Optionally specify whether to output the count 1 or not. When not included, the counting starts from the second specimen as 2. The first specimen does not get any UID.


e.g. If label format is '%PPI%_%SP_TYPE%%PPI_SPEC_TYPE_UID%', this will generate label like '0001_WB, where '0001' is PPI, WB is specimen type abbreviation for 'Whole Blood'. The sequence will continue as '0001_WB2' for another whole blood collected under the same patient. If a different type of specimen is collected, then the sequence restarts.PW-0001_WB', 'PW-0001_WB2'


e.g. %PPI%_%SP_TYPE%%PPI_SPEC_TYPE_UID(0, output_one)% generates labels as PW-0001_WB1, PW-0001_WB2 etc

CP_CODECollection protocol shortcode valuee.g. If label format is '%CP_CODE%_%PPI%_%SP_TYPE%_%PPI_SPEC_TYPE_UID%', label generated will be 'PW_PW-0001_WB_2', where 'PW' is the CP code set while creating a CP, 'PW-0001' is the PPI, 'WB' is the specimen type abbreviation for whole blood and '2' is the unique sequence number related to specific PPI and type of specimen.
EVENT_CODEThe event code of the evente.g. If label format is '%EVENT_CODE%_%PPI%_%SP_TYPE%_%PPI_SPEC_TYPE_UID%', label generated will be 'Surgery_SPW1_7_WB_4', where 'Surgery' is the event code set while creating events, SPW1_7' is the PPI, 'WB' is the specimen type abbreviation for whole blood and '4' is the unique sequence number related to specific PPI and type of specimen.
SR_CODESpecimen requirement codee.g. If label format is '%SR_CODE%_%PPI%_%SP_TYPE%_%PPI_SPEC_TYPE_UID%', label generated will be 'E1-WB_SPW1_7_WB_4', where 'E1-WB' is the specimen requirement code set specimen requirement level, 'SPW1_7' is the PPI, 'WB' is the specimen type abbreviation for whole blood and '4' is the unique sequence number related to specific PPI and type of specimen.
VISIT_SP_TYPE_UID(n, output_one)

Unique sequence number related to specific visit and type of specimen. Similar to 'PPI_SPEC_TYPE_UID' above but the sequence here is within a visit.

n: Optionally specify the number of digits. For example, if (2) is used, then the numbers generated will be 01, 02, 03 etc.

output_one: Optionally specify whether to output the count 1 or not. When not included, the counting starts from the second specimen as 2. The first specimen does not get any UID.

e.g if label format is '%PPI%_%SP_TYPE%_%VISIT_SP_TYPE_UID%' label generated will be 'PW-0001_WB', where 'PW-0001' is the PPI, 'WB' is the specimen type abbreviation for whole blood. The sequence will continue as '0001_WB2' for another whole blood collected within the same visit where '2' is the unique sequence number generated from the 2nd specimen.



YR_OF_COLL2
Year of the collection (two digits)e.g. if label format is %PPI%.%SP_TYPE%.YR_OF_COLL2%_%PPI_YOC_UID%
'PW-0001.WB.17_1', where 'PW-0001' is the PPI, 'WB' is the specimen type abbreviation set for whole blood, '17' is the year of collection and '1' is unique sequence number for the participant within the year of collection.
PPI_UID(n)

New in v3.1! For including a unique sequence number within the PPI

(n): Optionally specify the number of digits. For example, if (2) is used, then the numbers generated will be 01, 02, 03 etc.

%PPI_UID% generates a unique ID within the PPID irrespective of whatever type of sample it is.

e.g. if label format is''%SR_CODE%_%PPI_UID%, label generated will be 'E1-WB_1', where 'E1-WB' is the specimen requirement code set and '1' is the unique sequence number within the PPI.

If there are more derivatives created, the label generated would be 'E1-P_2', 'E1-Sr_3' and so on.

SPEC_CP_UID(n)

New in v3.3.1! For including a unique sequence number within the CP

(n): Optionally specify the number of digits. For example, if (2) is used, then the numbers generated will be 01, 02, 03 etc.

e.g. if label format is '%SR_CODE%_%SPEC_CP_UID(3)%', label generated will be 'E1-WB_001', where 'E1-WB' is the specimen requirement code set and '001' is the 3 digits unique sequence number within the CP
CP_PPI_UID(n)

New in v4.1.4! For including a unique sequence number within the CP and PPI

(n): Optionally specify the number of digits. For example, if (2) is used, then the numbers generated will be 01, 02, 03 etc.

e.g. if label format is '%SR_CODE%_%CP_PPI_UID%', label generated will be 'E1-WB_1', where 'E1-WB' is the specimen requirement code set and '1' is the unique sequence number within the CP and PPI.
PSPEC_COUNTER(n)

New in v4.3! To create child specimens by incrementing the count by 1 in the number that appears at the end of the parent specimen label.

(n): New in v8.1! Optionally, specify the number of digits of the parent specimen label that needs to remain fixed. 

e.g If aliquot label format is %PSPEC_COUNTER%.

If parent specimen label is "PA400" then generated labels for aliquots will be "PA401", "PA402", "PA403" …

%PSPEC_COUNTER(2)% will generate the labels as "PA401", "PA402", "PA403", ...,  "PA409", "PA4010", "PA4011" and like that.

PRIMARY_SPEC_COUNTER(n)

New in v8.1! Generates child specimen labels by incrementing the number that appears at the end of the primary specimen label. 

In case of PSPEC_COUNTER, the immediate parent label counter/number is used to generate the child specimen label. Whereas in case of this token, the topmost specimen label counter/number is used.

(n): Optionally, specify the number of digits of the primary specimen label that needs to remain fixed.

e.g. If aliquot label format is %PRIMARY_SPEC_COUNTER%

If primary specimen label is "PA400" then the generated labels for aliquots will be "PA401", "PA402", "PA403" ...

%PRIMARY_SPEC_COUNTER(2)% will generate the labels as "PA401", "PA402", "PA403", ...,  "PA409", "PA4010", "PA4011" and like that.

CUSTOM_FIELD(level, fieldName)

New in v5.0! Include the value of any custom field identified by "fieldName" at the specified level. The field name is the same as the attribute name that appears in the custom form designer. The allowed values of level for visit names are "specimen", "visit", "cpr" and "cp"

Works v5.0 onward

e.g.

  1. CUSTOM_FIELD(cp, piCode) will include the value of CP custom field "piCode" 
  2. CUSTOM_FIELD(cpr, patientId) will include the value of registration custom field "patientId"
  3. CUSTOM_FIELD(visit, visitNum) will include the value of visit custom field "visitNum"
  4. CUSTOM_FIELD(specimen, part) will include the value of specimen custom field "part"
  5. CUSTOM_FIELD(parentSpecimen, part) will include the value of parent specimen custom field part
VISIT_UID(n)New in v5.0! For generating and including a unique sequence number within the visit.

(n): Optionally specify the number of digits. For example, if n = 2 is used, then the numbers generated will be 01, 02, 03 etc.

e.g. if label format is %VISIT_NAME%.%VISIT_UID(2)%, the generated specimens labels will be
TS-0005.01
TS-0005.02
TS-0005.03
TS-0005.04
REG_GREEK_SEQ
New in v5.2. Generates unique Greek letter sequences for specimens of the same participant.

e.g. if label format is %PPI%.%REG_GREEK_SEQ%, the generated specimen labels will be

TS-007.α
TS-007.β
TS-007.γ
TS-007.δ

VISIT_GREEK_SEQNew in v5.2. Generates unique Greek letter sequences for specimens of the same visit.

e.g. if label format is %VISIT_NAME%.%VISIT_GREEK_SEQ%, the generated specimen labels will be

TS-0005.01.α
TS-0005.01.β
TS-0005.01.γ
TS-0005.01.δ

PSPEC_GREEK_SEQ
New in v5.2. Generates unique Greek letter sequences for child specimens underneath the same parent.

e.g. if label format is %PSPEC_LABEL%.%PSPEC_GREEK_SEQ%, the generated specimens labels will be

TS-0005.01.α.α
TS-0005.01.α.β
TS-0005.01.β.α
TS-0005.01.β.β

PR_SPEC_LABELNew in v5.2. This token is suitable for use in the child specimen label formats. The token interpolates the child labels with the primary specimen label.

e.g. Assume the primary specimen (lineage = New) label is TS-0005.01.  When the aliquot label format is %PR_SPEC_LABEL%.%CP_PPI_UID(2)%, the aliquot labels are generated as below. The aliquots could be at any level (direct children, grandchildren, great-grandchildren) underneath the parent specimen:

TS-0005.01.01
TS-0005.01.02
TS-0005.01.03
TS-0005.01.04

SP_TYPE_ABBR_UIDNew in v6.0. Generates unique ID/sequences for specimen type abbreviations within a given visit or participant registration or parent specimen or primary specimen. If 2 or more specimen types have the same abbreviation then they will share the same counter/sequence.

e.g. %SP_TYPE_ABBR_UID([0-9]+, default|output_one, registration|visit)%

%SP_TYPE_ABBR_UID(0, default, registration)%: Generates unique sequences for specimen type abbreviations at the participant registration level.

%SP_TYPE_ABBR_UID(0, default, visit)%: Unique sequences for specimen type abbreviations at the visit level.

%SP_TYPE_ABBR_UID(2, output_one, registration)%: Generates sequences that are 2 digits in width at the registration level. The sequence numbering starts from 1.

%SP_TYPE_ABBR_UID(2, output_one, parent_specimen)%: Generates sequences of 2 digits in width at the parent specimen level. The sequence numbering starts from 1.

%SP_TYPE_ABBR_UID(2, output_one, primary_specimen)%: Generates sequences of 2 digits in width at the primary specimen level. The sequence numbering starts from 1.


EVAL(expr)
New in v6.2. Includes the result of expression evaluation in the generated visit names. The expression can be a field name or complex expression.

e.g.

%EVAL(#specimen.pathologicalStatus.conceptCode)%: Outputs the concept code of the specimen pathological status in the generated labels.

%EVAL(#formatDate(#specimen.createdOn, "yyyy"))%: Outputs the year of specimen creation in the generated labels.

VISIT_SP_PATH_UID(n, output_one)New in v6.3. Unique sequence number related to the specific visit and pathology_status of the specimen. Similar to 'VISIT_SP_TYPE_UID'.

n: Optionally specify the number of digits. For example, if (2) is used, then the numbers generated will be 01, 02, 03, etc.

output_one: Optionally specify whether to output the count 1 or not. When not included, the counting starts from the second specimen as 2. The first specimen does not get any UID.

e.g if label format is '%PPI%_%SP_TYPE%_%VISIT_SP_PATH_UID%' label generated will be 'PW-0001_WB', where 'PW-0001' is the PPI, 'WB' is the specimen type abbreviation for whole blood. Suppose the pathology_status is 'Malignant'.

The sequence will continue as '0001_WB2' for another whole blood (Malignant) collected within the same visit where '2' is the unique sequence number generated from the 2nd specimen (Malignant).

For a new specimen path_status (say, Non-Malignant) the unique sequence number generated would start from 1.

TODAY_DATE(Format)

New in v7.0! The Format can be optionally specified by the end-user. If the format is not specified, OpenSpecimen will take the default date format for the set locale. (e.g; For US: MM-dd-yyyy)

e.g. If the label format is '%SP_TYPE%_%SPEC_CP_UID(3)%_%TODAY_DATE("dd-MM-yyyy HH:mm:ss")%' label generated will be 'WB_001_03-12-2019 10:42:33', where 'WB' is specimen type abbreviation for whole blood, '001' is unique ID for the specimen under the CP, and '03-12-2019 10:42:33' is the DateTime generated by the passed format.


%TODAY_DATE("yyyy")% will generate current year in 'yyyy' format. (eg: 2020)

The input format will generate DateTime up to milliseconds precision.

Advanced Tokens

 Click here to view the advanced tokens...

You can use the EVAL(expr) token to add advanced tokens at the specimen level. This token includes the result of expression evaluation in the generated labels. The expression can be a field name or complex expression.

Token Name

Description

Example

%EVAL(#specimen.pathologicalStatus.conceptCode)%

Outputs the concept code of the specimen pathological status in the generated labels.

001_WB01_T

%EVAL(#formatDate(#specimen.createdOn, "yyyy"))%Outputs the year of specimen creation in the generated labels.001_WB01_2020
%EVAL(#specimen.specimenRequirement.name)%Outputs the year of specimen requirement name in the generated labels.001_WB01_Tigertop
%EVAL(#specimen.tissueSite.value)%Outputs the anatomic site value001_WB01_Lung, NOS
%EVAL(#formatDate(#specimen.visit.visitDate, "dd-MM-yy"))%Outputs the visit date in the generated labels.30-04-2021_001_WB01
%EVAL(#specimen.registration.externalSubjectId)%Outputs the external subject ID entered for participant registration 
%EVAL(#specimen.registration.site.code)%Outputs the registration site code entered for participant registration

Examples

 Click here to view the examples...
Example
Comment

GC_%PPI%_%SP_TYPE%_%YR_OF_COLL%_%PPI_YOC_UID%

This will generate a label of the sort: GC_1892_WB_1999_1. This is

for a specimen with PPI 1892, a type is a Whole Blood, collected in the year 1999 with a unique number 1.

CP_%PPI%_%SP_TYPE%_%PSPEC_UID%

This will generate a label of the sort: CP_1890_S_1 – for a specimen with PPI 1890, type Saliva & 1st child specimen for the particular parent.

%PSPEC_LABEL%.%PSPEC_UID%
This is generally used for aliquots. This will generate a label of the sort: CP_1890_Se_1.1, for the 1st child specimen of the parent with label 'CP_1890_Se_1'


Steps to configure specimen label format

 Click here to view the steps...
  1. Go to the collection protocols list page and click on the 'View Details' icon of the CP for which the PPID Format has to be set
  2. Click on 'Settings' icon from the left side menu of the overview page and select option 'Label Format and Print' 
  3. Set the desired specimen label format and click on 'Save' button

System-Level Aliquot Format

 Click here to expand...

Super admins can change default system level format through 'Settings->Biospecimen→Aliquot Label Format'. If format is not set at specimen requirement and CP then system will generate aliquot labels based on the format specified at system level.


The default label format can be changed by specifying desired format in new value field.