This topic provides guidelines and tips to help you compile a sample list, in Microsoft Excel format, for importing into BaseSpace Clarity LIMS.
Import up 3456 samples from a single sample list file. To import more than 3456 samples, divide the samples into multiple files.
If an error is detected in the spreadsheet, the import process aborts. No sample imports until the error condition is resolved. See #troubleshooting.
An asterisk indicates a *mandatory field.
Regular font, without an asterisk, indicates an optional field. See #optional-fields for details.
Text enclosed in angle brackets indicates a placeholder custom field name to replace with a value.
Italicized text indicates a group of fields that depend on each other. All headers in the group must be either all present or all absent.
The following column headers can be used in the sample list:
*Sample/Name—Specify the name of the sample. If the system has the unique sample name option enabled and there are duplicate sample names in the spreadsheet, expect an error message. The message provides information on this error condition. No sample is imported until duplicate names are resolved.
Sample/Volume—Specify the volume of the sample.
Container/Type—Specify the name of the container type to use for this sample. When specifying a value for this column, verify it exists in the system already. For instance, you can specify 100 well MALDI plate as a value, provided this container type is configured in the system.
Container/Name—Specify the name of the container to place this sample. If the name does not match a container already in the system, a new container by this name (and of the specified type) is created.
Sample/Well Location—Specify the well location for the sample. Values for this column are formatted like the following examples: A:1, B:12, or 1:10.
The import process validates this location against the container type specified. If the location is out of range, the process rejects it. If placing a sample into an existing container, the process checks if the well location is already occupied and rejects it if occupied.
Sample/Reagent Label—Specify the reagent label name to use for this sample. Values for this column are optional. They can exist in the system or, if the reagent label is not found, a new one is created. Only one reagent label is supported per sample via batch sample import.
Custom Field/<Name of Custom Field>—Add a custom field instance to the sample. The name of the custom field must exist in the system. If the custom field name specified is not in the system, an error message displays.
You can specify a value for this custom field in the remaining cells of this column. For example, if there is a custom field by the name Clinical Source, you may have a column header Custom Field/Clinical Source and a value of hospital for the sample. See #optional-fields for details.
Container/Custom Field/<Name of Custom Field>—Add a custom field instance to container. This field functions in a similar way to the sample custom field previously described, except the values must be defined on each row (per container). If not, an error message displays.
Take Custom Field as an example. Its optional nature in the spreadsheet is contingent on whether a particular field is defined as optional or required in Clarity LIMS.
If there is a required custom field for a sample, there must be a column in the spreadsheet for this field. A value must be specified for it, before any sample can be imported.
Custom field values are validated against their type defined in Clarity LIMS, as follows.
Date type—For example, if there is a custom field type of Date and the name is Completion Date, the best practice method is to have a column header Custom Field/Completion Date. The remaining values for the cells in the file should be formatted using one of the Excel date formats.
Numeric type with a range defined—The value is first validated as a number. Then, the number is validated against the range defined in Clarity LIMS.
If the validation fails, error messages display.
No sample is imported until the value is validated.
Custom field with values defined in a group of defaults—If a custom field is configured to have one or more values defined in a group of defaults and is only allowed to have one of these defined values, Clarity LIMS validates the value entered against the defined values.
If the value in the spreadsheet does not match one of the default values, validation fails.
If the validation fails, an error message displays. No sample is imported.
If Clarity LIMS expects certain information to be provided and this information is not included in the sample list, the samples are not imported.
Consider the following examples:
If an option or field is mandatory, the sample list must contain a column to capture that information. The sample list must use the appropriate column title.
If the samples must contain unique names, the sample list must not contain duplicate names or the names of samples already recorded in Clarity LIMS.
Containers types referenced in the sample list must already be defined in Clarity LIMS. For example, 96-well plate or tube.
The sample list must not place a sample into a container well that is already populated with another sample.
Any custom fields referenced in the sample list must be defined in Clarity LIMS.
When you add samples to Clarity LIMS, you must add them to a project. Clarity LIMS uses projects as the basis for all work performed in the system.
There are two ways to add samples to projects:
Add samples individually to one or more projects. See #add-samples.
Upload a sample list (Excel spreadsheet) to a project. See #upload-and-modify-samples.
The Sample Management screen allows for convenient sample accessioning. On this screen, add multiple samples to a single project or to multiple projects, and modify samples already added to the system.
There are two ways to access the Sample Management screen:
The main menu bar, which allows for adding samples to one project or to multiple projects.
The Project and Samples tab, which allows for adding samples to a project or modifying samples already added to a project.
On the main menu bar, hover over Projects and Samples tab and select Add Samples when the option displays.
In the Sample Management screen, select a project from the Project Name drop-down list. This selection auto-populates the fields in the Project Details area.
Edit the project details if necessary.
To upload files to the project, select Upload File.
In the Sample Details area, provide the following information:
Enter the name of the sample.
Choose a container from the drop-down list.
Enter the container name.
Complete any other applicable fields (mandatory fields are marked with an asterisk).
NOTE: LIMS ID (Submitted Sample), Date Submitted, and LIMS ID (Container) fields are automatically populated after the sample is saved.
To upload sample files, select Upload File at the bottom of the Sample Details section.
To add another sample, select Sample +. Add this sample to the same project or select a different project from the Project Name drop-down list.
Repeat steps 3 to 5 as required.
When all samples are added, select Submit Samples. Clarity LIMS validates, saves the samples, and returns to the Project and Samples tab.
On the Project and Samples tab, the projects with recently added samples are automatically selected.
While adding samples, note the following details:
To view a subset of samples, remove selected samples from view. For details, see #remove-sample-from-view.
Copy values across to adjacent samples by selecting the arrows to the left of the fields. Clarity LIMS automatically populates the Well field.
If editing well information, make those changes last (before submitting the samples). Changes to Container, Container Name, LIMS ID (Container), and Sample Name may reorder the well locations.
Use the paging buttons to scroll pages of samples.
In this method, only add samples to the project selected. It is not possible to select a different project as described in the previous section of the documentation.
On the Project and Samples tab, select a project to add samples.
In the Submit Samples section, select Add Samples.
On the Sample Management screen, because the project has already been specified, the project details are automatically completed.
Follow steps 3 to 7 of the previous section to add the sample details.
On the Project and Samples tab, select a project to add samples.
In the samples list, select the submitted samples to modify (derived samples cannot be modified).
Select Modify Samples.
Modify the sample and project details as required (the Project Name or Container Name fields cannot be modified).
To save the changes, select Submit Samples.
NOTE: To avoid modifying or seeing all the samples selected, remove them from the view. See #remove-sample-from-view.
Clarity LIMS validates the modifications, saves the samples, and returns to the Project and Samples tab. On the Project and Samples tab, the projects containing the modified samples are automatically selected.
On the Sample Management screen, hovering over a sample displays a small Remove from view (X) button in the upper-right corner.
The effects of selecting this button differ depending on the circumstances.
If there are many samples to process, add them to the system by uploading a Microsoft Excel spreadsheet file (*.xls or *.xlsx). Use the same method to modify information for multiple samples.
By default, a maximum of 3456 samples can be uploaded from a single sample list file. To upload more than 3456 samples, divide the samples into multiple files.
In the sample list, specify container placement and include values for standard and user-defined options and fields (for details, see #create-a-sample-list).
Samples can be added individually in the Sample Management screen. For details, see #add-samples.
Navigate to the Projects and Samples tab.
In the Projects list, select a project to add samples. The Project Details area updates to show the details for the selected project.
Select Upload Sample List.
If a sample list is not readily available, select the Download Example Sample List link to download a sample list template. Open the template file in Excel, populate it with the sample details, and save the file. For details, see #create-a-sample-list.
In the Upload File dialog, select Choose File and browse to and open the sample list file.
Select Upload File.
As part of the upload process, Clarity LIMS validates the file to make sure the custom field data it contains meet the requirements, presets, and restrictions that apply to submitted samples. If the file contains invalid data, an error message displays.
When the upload process completes, the samples display in the Submitted Samples list for the project.
The Submitted Samples list allows the following actions:
Hover over the Information icon for a sample to view the details associated with it.
Modify sample details.
Add samples to a workflow.
If samples have been created in error, delete them from the sample list and the project (provided no work has been done on them). To complete this action, select the samples and select Delete.
After uploading, the submitted samples can be assigned to a workflow. When they are assigned, the samples are available for lab scientists to work on.
Navigate to the Projects and Samples tab.
In the Projects list, select the project containing the samples to modify.
Select Modify Samples.
Clarity LIMS generates a sample list containing all samples in the project and downloads it.
Open the file in Excel. It contains the Clarity LIMS IDs of all samples and all custom field data.
Update the sample information as required.
Return to the LIMS and upload the modified sample list. Follow the steps outlined in #upload-a-sample-list.
A sample list can be uploaded/imported in which custom field values have been changed, removed, or added.
While sample custom fields can only be updated, the sample list can contain other columns of data. The original data from the sample list does not have to be removed.
If the system does not require the custom field, leave the cell blank or enter NULL.
A ‘blank’ value will leave existing data in the system intact.
A NULL value will clear any existing data in the system for that field.
Clarity LIMS uses the information defined in the sample list (sample name, container type, and so on) and looks for matching samples in the project. If a matching sample is found, the system updates the sample with the values specified in the sample list.
This section describes how to add a large number of samples to the LIMS by importing a sample list - a Microsoft® Excel® *.xls or *.xlsx spreadsheet file.
To process many samples, add them to Clarity LIMS by importing a Microsoft Excel spreadsheet file (*.xls or *.xlsx). This method also applies to updating sample information.
The sample list must be in *.xls or *.xlsx format.
The sample list's column header names must match the default fields in the LIMS.
The following column header names cannot be changed: Sample/Name, Container/Name, and Sample/Well Location.
The following columns must be populated: Sample/Name and any sample-level custom fields that the system administrator requires.
By default, import up to a maximum of 3456 samples from a single sample list file. To import more than 3456 samples, divide the samples into multiple files.
Download a sample list template from the Projects and Samples view in Clarity LIMS.
Open the sample list template.
By default, the template contains the following information:
<TABLE HEADER> and <SAMPLE ENTRIES> tags (red/purple text).
These identifying tags are required by the LIMS import process. Do not edit these tags.
Column headers (white text on blue background)
These headers must reference the names of the fields containing the information to capture for a sample. If editing the column headers or creating additional headers, make corresponding changes to the fields in Clarity LIMS. See #add-and-configure-custom-fields.
Populate the columns with the information associated with the samples. Enter the data into the rows between the <TABLE HEADER> and <SAMPLE ENTRIES> tags. Insert additional rows as needed.
Save the file and import it into a project (see #upload-and-modify-samples).
If the sample list specifies a container name that does not exist in Clarity LIMS, the system creates the container.
Refer also to Guidelines and Tips for Batch Sample Import.
Enter dates using Excel date cell formatting.
To preserve currency characters (e.g. $), currency is best entered as a string (rather than using the Excel currency category).
Numbers can be entered either as numeric or string values.
If there are drop-down lists of values in Clarity LIMS, enter these exact values in the sample list.
Container well locations are always Row:Column. The actual dimensions depend on the container type configuration.
Excel may sometimes automatically alter values, depending on the type of data being entered.
For example, for Boolean fields such as Stored On Site? below, numeric values of zero and false will evaluate to FALSE whereas non-zero numeric values and true will evaluate to TRUE. Other values will result in an error on import.
Spreadsheet programs like Microsoft Excel contain features for increasing usability and speed when entering data. For example, the following configurations are available:
Add drop-down lists of options that correspond to options available in Clarity LIMS. Use the Named Range and Data Validation Excel features.
Hide header columns required by the system but not required.
The Clarity LIMS support team can create custom, efficient sample list templates.
Custom Field/Sample Material
Custom Field/Stored On Site?
Custom Field/Sample Location
Custom Field/Date Received
Tissue
1 (TRUE)
Freezer #1
06/01/2014
Serum
true (TRUE)
Freezer #1
06/01/2014
Tissue
0 (FALSE)
Fridge #2
07/15/2014
Serum
false (FALSE)
Fridge #2
07/15/2014
Tissue
yes (ERROR)
Fridge #2
07/15/2014