• Overview and Basic Examples
• Naming Pattern Elements/Tokens
• Format Number Values
• Include Default Values
• Use String Modifiers
• Incorporate Lineage Lookups
• Naming Pattern Examples
• Incorporate Sample Counters
• Date Based Counters
• withCounter Modifier
• Advanced Options: XML Counter Columns

Overview and Basic Examples

Administrators can customize how sample IDs are generated using templates that build a unique name from syntax elements including:

• String constants
• Incrementing numbers
• Dates and partial dates
• Values from the imported data file, such as tissue types, lab names, subject ids, etc.

S-${genId}

...to generate sample IDs:

S-1
S-2
S-3
and so on...

This example builds a sample ID from values in the imported data file, and trusts that the combination of these column values is always unique in order to keep sample IDs unique:

${ParticipantId}_${DrawDate}_${PortionNumber}

...which might generate IDs like:

123456_2021-2-28_1
123456_2021-2-28_2
123456_2021-2-28_3

Naming Pattern Elements/Tokens

Naming patterns can incorporate the following elements. When surrounded by ${ } syntax, they will be substituted during sample creation; most can also accommodate various formatting options detailed below.

Format Number Values

You can use formatting syntax to control how the tokens are added. For example, "${genId}" generates an incrementing counter 1, 2, 3. If you use a format like the following, the incrementing counter will have three digits: 001, 002, 003.

${genId:number('000')}

Learn more about formatting numbers and date/time values in this topic: Date and Number Formats Reference

Include Default Values

When you are using a data column in your string expression, you can specify a default to use if no value is provided. Use the defaultValue string modifier with the following syntax. The 'value' argument provided must be a String in ' single straight quotes. Double quotes or curly quotes will cause an error during sample creation.

${ColumnName:defaultValue('value')}

Use String Modifiers

Most naming pattern elements can be modified with string modifiers, including but not limited to:

• :date - Use only the date portion of a datetime value.
• :date('yy-MM-dd') - Use only the date portion of a datetime value and format it with the given format.
• :suffix('-') - Apply the suffix shown in the argument if the value is not null.
• :join('_') - Combine a collection of values with the given argument as separator.
• :first - Use the first of a series of values.

• String Expression Format Functions

Incorporate Lineage Lookups

Incorporate Lineage Lookups

To include properties of sample sources or parents in sample names, use lookups into the lineage of the sample.

• General parent input: Inputs/propertyA, MaterialInputs/propertyA, DataInputs/propertyA
• Specific data type inputs: MaterialInputs/SampleType1/propertyA, DataInputs/DataClass2/propertyA, etc.
• Import alias references: parentSampleA/propertyA, parentSourceA/propertyA, etc.

Blood-${DataInputs/Mouse/Strain}-${genId}

You can use the qualifier :first to select the first of a given set of inputs when there might be several.

If there might be multiple parent samples, you could choose the first one in a naming pattern like this:

Blood-${parentBlood/SampleID:first}-${genId}

Naming Pattern Examples

Incorporate Sample Counters

Date Based Counters

Several sample counters are available that will be incremented for the date when the sample is inserted, but can use a different date by attaching the counter to a date column.

• dailySampleCount
• weeklySampleCount
• monthlySampleCount
• yearlySampleCount

In addition, you can "attach" the counter to another date column by using the same element as a modifier after a colon, i.e. ${SampleDate:dailySampleCount}. This would use the date found in the row's "SampleDate" column (or today's date if the column has no value) and so provide a daily count for that "SampleDate".

withCounter Modifier

Another alternative for adding a counter to a field is to use :withCounter, a nested substitution syntax allowing you to add a counter specific to any column value when you create new samples. This modifier is particularly useful when naming aliquots which incorporate the name of the parent sample, and the desire is to provide a counter for only the aliquots of that particular sample. Using :withCounter will guarantee unique values, meaning that if a name with counter would match an existing sample, that counter will be skipped.

The syntax for using :withCounter is to prefix it with an expression that will be evaluated first, then surround the outer modified expression in ${ } brackets so that it too will be evaluated at creation time. The default naming pattern for creating aliquots combines the value in the AliquotedFrom column (the originating Sample ID), a dash, and a counter specific to that Sample ID:

${${AliquotedFrom}-:withCounter}

You could also use this modifier with another column name as well as strings in the inner expression. Given the example shown for an XML counter in the next section, names like Blood-A-1, Blood-A-2, etc would be generated with this expression:

${Blood-${Lot}-:withCounter}

Learn more about using this syntax in naming patterns for aliquots here:

• Aliquot Naming Patterns

${${AliquotedFrom}-:withCounter(42,'000')}

Advanced Options: XML Counter Columns

Another way to create a sequential counter based on values in other columns, such as an incrementing series for each lot of material on a plate, is to use XML metadata to define a new "counter" column paired with one or more existing columns to provide and store this incrementing value. You then use the new column in your name expression.

For example, consider that you would like to generate the following sample type for a given plate:

The "SampleInLot" column contains a value that increments from 1 independently for each value in the "Lot" column. In this example, the name expression would be S-${Lot}-${SampleInLot}. To define the "SampleInLot" column, you would create it with data type integer, then use XML metadata similar to this:

<tables xmlns="http://labkey.org/data/xml">
  <table tableName="MySampType" tableDbType="NOT_IN_DB">
    <javaCustomizer class="org.labkey.experiment.api.CountOfUniqueValueTableCustomizer">
        <properties>
            <property name="counterName">SampleCounter</property>
            <property name="counterType">org.labkey.api.data.UniqueValueCounterDefinition</property>
            <!-- one or more pairedColumns used to derive the unique value -->
            <property name="pairedColumn">Lot</property>
            <!-- one or more attachedColumns where the incrementing counter value is placed -->
            <property name="attachedColumn">SampleInLot</property>
        </properties>
    </javaCustomizer>
  </table>
</tables>

The following rules apply to these XML counters:

• The counter you create is scoped to a single Sample Type.
• The definition of the counter column uses one or more columns to determine the unique value. When you use the counter in a name expression, be sure to also include all the paired columns in addition to your counter column to ensure the sample name generated will be unique.
• The incrementing counter is maintained within the LabKey database.
• Gaps in the counter's sequence are possible because it is incremented outside the transaction. It will be sequential, but not necessarily contiguous.
• When you insert into a sample type with a unique counter column defined, you can supply a value for this unique counter column, but the value must be equal to or less than the current counter value for the given paired column.

Related Topics

• String Expression Format Functions
• Create Sample Type
• Data Classes
• Generate Unique Storage IDs: Generate barcode values
• Aliquot Naming Patterns