• 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
• Date Based Naming
• Incorporate Column Values
• Incorporate Lineage Lookups
• Naming Pattern Elements/Tokens
• Formatting Values
• Default Values
• Incrementing Sample Counters
• :withCounter Modifier
• 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...

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.

• 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 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

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 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.

: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')}

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