Update Single Cell Sample Name
There are a number of situations where the sample name needs to be updated:
- When analyzing
- scATAC-Seq or scV(D)J-Seq with matched scRNA-Seq, data originating from the same sample must be annotated with the same sample name.
- spatial transcriptomics data, the Spatial Transcriptomics Plot and corresponding Expression Matrix/Dimensionality Reduction Plot must have the same sample name.
- Multiple samples may be multiplexed with a hashtag identifying the sample. The hashtags are first translated to Cell Annotations (
) (see Create Cell Annotations from Hashtags) and then the samples are demultiplexed using these annotations.
Update Single Cell Sample Name can be used in such situations. It can be found in the Toolbox here:
Toolbox | Single Cell Analysis (
) | Utility Tools (
) | Update Single Cell Sample Name (
)
The tool takes one element as input of one of the following types:
- Sequence List (
) that has been annotated with Annotate Single Cell Reads;
- Expression Matrix (
) / (
);
- Peak Count Matrix (
);
- Velocity Matrix (
);
- Cell Clusters (
);
- Cell Annotations ();
- Cell Clonotypes (
) / (
);
- Spatial Transcriptomics Plot (
).
The output is a copy of the input where the sample name is updated. Typically the input and output will contain the same cells, but note that sometimes cells can be discarded, see From cell annotations below.
The sample name can be provided in one of three ways.
From element
When the input contains only one sample, the sample name can be updated to that found in a second element provided in the Element option. The element can only contain one sample and can be of one of the following types:
- Sequence List () that has been annotated with Annotate Single Cell Reads;
- Expression Matrix () / ();
- Peak Count Matrix ();
- Velocity Matrix ();
- Cell Clusters ();
- Cell Annotations ();
- Cell Clonotypes () / ();
- Dot Plot (
);
- Violin Plot (
);
- Dimensionality Reduction Plot (
);
- Spatial Transcriptomics Plot ().
Specify sample name
When the input contains only one sample, the sample name can be set as specified in the Sample name option.
When the tool is run from the Toolbox, the option supports the placeholder {nameOrBatchId}, which sets the sample name to the name of the input. When the tool is run as part of a workflow, this option will set the sample name to the name of the input for simple workflows, and to the name of the batch identifier for batching/iterating workflows.
Note that it can also be set to an explicit name, such as `Individual_1', or to a complex pattern such as `Individual_{nameOrBatchId}_1'.
Additional placeholders are available when the tool is run as part of a workflow (see figure 18.2).
Figure 18.2: Options for configuring `Sample name' when Update Single Cell Sample Name is run in a workflow.
From cell annotations
The sample name can be set from a category from a Cell Annotations () element. The barcodes from the input are matched with the barcodes from the Cell Annotations.
This makes it possible to demultiplex to multiple samples. One of the following conditions must be met by both input and Cell Annotations:
- Contain only one sample.
- Have unique barcodes across all samples.
- The input and Cell Annotations must be for the same samples. That is, the barcode and sample name are equal for the same cell in the two elements.
It is possible that the sample name cannot be determined for some cells. Two options are available:
- Use original sample name. The sample name in the output will be the same as in the input for such cells.
- Discard cell. The cells will not be part of the output.
As Sequence Lists () can only represent one sample, their sample name cannot be set using Cell Annotations.