Each sample in a Sample Set must have a unique name/id. If your data does not already contain unique names, the system can generate them upon import using a name expression. Administrators can customize name generation using templates that build a unique name from syntax elements, such as:
  • string constants
  • incrementing numbers
  • random numbers
  • dates and partial dates
  • values from the imported data, such as tissue types, lab names, subject ids, etc.
For example the template

S-${randomId}

generates names from two elements, a string constant plus a four-digit random number:

S-2315
S-6295
S-1241
and so on...

Name Expression Elements/Tokens

Naming templates are called "name expressions". The following elements are available:

Name ElementDescriptionScope0000000000000000000000000
genIdAn incrementing number starting from 1. This counter is specific to the individual Sample Set or Data Class.Current Sample Set/Data Class
dailySampleCountAn incrementing counter, starting with the integer '1', that resets each day.All Sample Sets/Data Classes in the current folder
weeklySampleCountAn incrementing counter, starting with the integer '1', that resets each week.All Sample Sets/Data Classes in the current folder
monthlySampleCountAn incrementing counter, starting with the integer '1', that resets each month.All Sample Sets/Data Classes in the current folder
yearlySampleCountAn incrementing counter, starting with the integer '1', that resets each year.All Sample Sets/Data Classes in the current folder
randomIdA four digit random number for each sample row.Current Sample Set/Data Class
batchRandomIdA four digit random number applied to the entire set of incoming sample records. On each import event, this random batch number will be regenerated.Current Sample Set/Data Class
nowThe current date, which you can format using string String Expression Format Functions.Current Sample Set/Data Class
InputsA collection of all DataInputs and MaterialInputs for the current sample. You can concatenate using one or more value from the collection.Current Sample Set/Data Class
DataInputsA collection of all DataInputs for the current sample. You can concatenate using one or more value from the collection.Current Sample Set/Data Class
MaterialInputsA collection of all MaterialInputs for the current sample. You can concatenate using one or more value from the collection.Current Sample Set/Data Class
<SomeDataColumn>Loads data from some field in the data being imported. For example, if the data being imported has a column named "SampleType", use the element/token "${SampleType}"Current Sample Set/Data Class

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 modifier with the following syntax. The 'value' argument provided must be a String in ' single quotes.

${ColumnName:defaultValue('value')}

Incrementing Sample Counters

The sample counters are incremented for the date when the sample is inserted, but can use a different date by attaching the counter to a date column. For example, ${SampleDate:dailySampleCount} will use the date found in the row's "SampleDate" column or today's date if the column has no value.

Some auto-incrementing counters calculate the next value based on all samples in a given container, while others calculate based on only the current sample set. See the Scope column for the specific incrementing behavior. When the scope is container-based, within a given sample set, values will be sequential but not necessarily contiguous.

Examples

Name ExpressionExample OutputDescription
S-${genId}S-101
S-102
S-103
S-104
S- + a simple sequence
${Lab:defaultValue('Unknown')}_${genId}Hanson_1
Hanson_2
Krouse_3
Unknown_4
The originating Lab + a simple sequence. If the Lab value is null, then use the string 'Unknown'.
S_${randomId}S_3294
S_1649
S_9573
S_8843
S_ + random numbers
S_${now:date}_${dailySampleCount}S_20170202_1
S_20170202_2
S_20170202_3
S_20170202_4
S_ + the current date + daily resetting incrementing integer
S_${Column1}_${Column2}S_Blood_PT101Create an id from the letter 'S' and two values from the current row of data, separated by underscore characters.

String Modifiers

The following name expressions are used in combination with string modifiers.

Name Expression00000000000000000000000000000000000000000000000Example Output000000000000000000Description
S-${Column1}-${now:date}-${batchRandomId}S-Blood-20170103-9001 
S-${Column1:suffix('-')}${Column2:suffix('-')}${batchRandomId}S-Blood-PT101-5862 
${Column1:defaultValue('S')}-${now:date('yy-MM-dd')}-${randomId}Blood-17-01-03-2370
S-17-01-03-1166
${Column1:defaultValue('S')} means 'Use the value of Column1, but if that is null, then use the default: the letter S'
${DataInputs:first:defaultValue('S')}-${Column1}Nucleotide1-5
S-6
${DataInputs:first:defaultValue('S')} means 'Use the first DataInput value, but if that is null, use the default: the letter S'
${DataInputs:join('_'):defaultValue('S')}-${Column1}Nucleotide1_Nucleotide2-1${DataInputs:join('_'):defaultValue('S')} means 'Join together all of the DataInputs separated by undescores, but if that is null, then use the default: the letter S'

Advanced Options: XML Counter Columns

If you want a sequential counter based on values in other columns, such as an incrementing series for each lot of material on a plate, you can 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 set for a given plate:

Name (from expression)LotSampleInLotPlate Id
S-A-1A1P1234
S-A-2A2P1234
S-B-1B1P1234
S-B-2B2P1234

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="MySampSet" 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 unique value counters:

  • The counter you create is scoped to a single Sample Set.
  • 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 set 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

Discussion

Was this content helpful?

Log in or register an account to provide feedback


previousnext
 
expand all collapse all