• Unique Sample Names are Provided: Unique sample names are provided to the system
• Column Name is "SampleID" or "Name"
• Column Name is Something Else
• Generate Names with Naming Patterns: Generate unique names within the system
• Default Naming Pattern
• See and Set genId
• Date Based Naming
• Incorporate Column Values
• Incorporate Lineage Lookups
• Naming Pattern Elements/Tokens
• Formatting Values
• Default Values
• Incrementing Sample Counters
• :withCounter Modifier
• Naming Pattern Validation
• Examples

Unique Sample Names are Provided

If your data already includes the unique sample names to use, identify the column name that contains them.

Naming Column is "SampleID" or "Name"

If the name of this column is "SampleID" or "Name", these default column names are automatically recognized as containing sample names. To confirm that they are used, be sure to Delete the default naming pattern that is provided in the user interface (and ignore the grayed out placeholder text that remains).

Naming Column is Something Else

If the column containing unique sample names is named something else, you provide that column name using a simple naming pattern expression that specifies the name of the column to use, rather than an expression to generate one.

For example, if the sample names are in a column named "Identifier", you would enter the naming pattern:

${Identifier}

Note that while this is entered as a naming pattern, it does not generate any portion to make the sample names unique, so you are responsible for ensuring uniqueness.

Generate Names with Naming Patterns

If your data does not already contain unique names, the system can generate them upon import using a naming pattern that contains tokens, including counters to ensure names are unique. The system can build a unique name from syntax elements, such as:

• String constants
• Incrementing numbers
• Dates and partial dates
• Values from columns in the imported data, such as tissue types, lab names, subject ids, etc.
• Separators such as '_' underscores and '-' hyphens
• Note that if you use a hyphen '-', you will want to use double quotes when you later search for your samples. An unquoted search for Sample-11 would interpret the hyphen as a minus sign and seek pages with "Sample" without "11".

Default Naming Pattern

The default naming pattern in Sample Manager generates names from two elements: the prefix "S-" plus an incrementing integer.

S-${genId}

The first few samples would be:

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

See and Set genId

genId is an incrementing counter which starts from 1 by default, and is maintained internally for each container. When you include ${genId} in a naming pattern, you will see a blue banner indicating the current value of genId.

If desired, click Edit genId to set it to a higher value than it currently is. This action will reset the container counter and cannot be undone.

Date Based Naming

Another possible naming pattern for samples is to incorporate the date of creation. For example:

S-${now:date}-${dailySampleCount}

This three-part pattern will generate an incrementing series of samples for each day.

1. The S- prefix is simply a string constant with a separator dash. Using separators like "-" and "_" is optional but will help users parse sample names.
2. The now:date token will be replaced by the date of sample creation.
3. The dailySampleCount token will be replaced by an incrementing counter that resets daily.

Incorporate Column Values

If you want to use a column from your data as part of the name, but it does not contain unique values for all samples, you can incorporate it in the pattern by using the column name in token brackets and also including an additional uniqueness element like a counter. For example, if you want to name many samples for each participant, and the participant identifier is in a "ParticipantID" column, you could use the pattern:

${ParticipantID}-${genId}

Multiple column names and other substitutions can be included in a naming pattern, for example:

${ParticipantID}-${CollectionDate}-${LabName}-${now:date}-${genId}

Incorporate Lineage Lookups

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

• Specific data type inputs: MaterialInputs/SampleType1/propertyA, DataInputs/DataClass2/propertyA, etc.
• Import alias references: parentSampleA/propertyA, parentSourceA/propertyA, etc.
• In some scenarios, you may be able to use a shortened syntax referring to an unambiguous parent property: Inputs/propertyA, MaterialInputs/propertyA, DataInputs/propertyA
• This option is not recommended and can only be used when 'propertyA' only exists for a single type of parent. Using a property common to many parents, such as 'Name' will produce unexpected results.

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 Elements/Tokens

The following elements, or "tokens" are available for building naming patterns.

Formatting 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

Additional string modifiers are available. Find a list in this topic: String Expression Format Functions

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

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 Type. See the Scope column for the specific incrementing behavior. When the scope is container-based, within a given Sample Type, values will be sequential but not necessarily contiguous.

Date-based sample counters are available that will be incremented based on the date when the sample is inserted. These counters are incrementing, but since they apply to all sample types, within a given sample type, values will be sequential but not necessarily contiguous.

• dailySampleCount
• weeklySampleCount
• monthlySampleCount
• yearlySampleCount

• As standalone elements of a name expression, i.e. ${dailySampleCount}, in which case they will provide a counter across all sample types in a container based on the date of creation.
• As modifiers of another date column using a colon, i.e. ${SampleDate:dailySampleCount}, in which case the counter applies to the value in the named column ("SampleDate") and not the date of creation.

: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 in the LabKey documentation here:

• Aliquot Naming Patterns

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

Naming Pattern Validation

During creation of a Sample Type, both sample and aliquot naming patterns will be validated. While developing your naming pattern, the admin can hover over the for a tooltip containing either an example name or an indication of a problem.

When you click Finish Creating/Updating Sample Type, you will see a banner about any syntax errors and have the opportunity to correct them.

Errors reported include:

• Invalid substitution tokens (i.e. columns that do not exist or misspellings in syntax like ":withCounter").
• Keywords like genId, dailySampleCount, now, etc. included without being enclosed in braces.
• Mismatched or missing quotes, curly braces, and/or parentheses in patterns and formatting.
• Use of curly quotes, when straight quotes are required. This can happen when patterns are pasted from some other applications.

Caution: Using Numbers-Only as Sample IDs

Note that while you could create or use sample names that are just strings of digits, you may run into issues if those "number-names" overlap with row numbers of other samples. In such a situation, when there is ambiguity between sample name and row ID, the system will presume that the user intends to use the value as the name.

Examples

Example String Modifiers

The following naming patterns show usage of string modifiers.

Related Topics

• Create a Sample Type
• Date and Number Formats Reference
• String Expression Format Functions