10x Genomics
Chromium Single Cell Gene Expression

Cell Ranger5.1, printed on 12/24/2024

Interoperability

We recognize that there are many scripts and packages in the single-cell analysis ecosystem, and that you may want to import and export projections, categorical labels, gene lists and filters into and out of Loupe Browser. Options to import and export data in Loupe Browser are usually inside a menu that is displayed after clicking a button with three vertical dots.

On this page, we will enumerate the types of data that you can import and export into and out of Loupe Browser and document the formats.

Projections

In Loupe Cell Browser 3.1.0 and later, or Loupe Browser 4.0 and later, you can import custom projections. This allows you to compute a projection of the data using your favorite software packages like Seurat or Scanpy to compute UMAP, t-SNE, PCA, or MDS projections. You can also import layouts from trajectory inference methods.

The CSV format for importing projections is as follows:

• A header is required.
• First column: barcodes that are at least a subset of the barcodes in the .cloupe file.
• Second column: numbers which represents the X coordinates.
• Third column: numbers which represents the Y coordinates.

We've computed a UMAP projection for the AMLTutorial dataset. Here are the first five lines of that projection:

Barcode,UMAP-1,UMAP-2
AAACATACGGTACT-1,-10.18537,-5.062836
AAACATTGCTCGCT-1,-7.0603027,2.789417
AAACATTGCTTCTA-1,-8.413968,-3.3959498
AAACATTGGCGATT-1,-3.0396965,-7.3784895
AAACCGTGCCTACC-1,-7.6169457,2.5746179

Let's download the full AMLTutorial UMAP projection and import it. To import new projections, click on the action button to the right of the projection selector.

Importing the above AMLTutorial UMAP projection will display the following barcode plot.

Once a custom projection is uploaded, you will also be able to rename it or delete it by clicking the same action button that you used to import the projection.

Categories

In Loupe Cell Browser 1.0.5 and later, you can both import and export categories. This allows you to integrate clustering data from other pipelines or scripts, or export manually assigned categories into custom scripts. To do so, when Categories mode is active, simply click on the action button to the right of the active category name, and select from one of the import/export options.

To create a categories CSV file the format is as follows:

• first row must be a header
• a column header must be barcode and the column's contents must match at least a subset of the barcodes in the .cloupe file
• addition column headers are category names and the column's contents are cluster labels

barcode,id
AAACATACAGTACC-1,Monocytes
AAACCGTGTCGTGA-1,Monocytes
AAACATACCATTCT-1,Mature Ery
AAACATACTCGCAA-1,Mature Ery
AAACCGTGGCCATA-1,Mature Ery

In the above case, the category name will be named "id" and the two clusters that will be created will be named "Monocytes" and "Mature Ery". You can also download a full example that you can import into the AMLTutorial dataset bundled with Loupe Browser. It's a set of manual annotations for the Patient sample. You can import multiple categories at once from a single CSV file; each column will encode its own category.

Feature Lists

There are two ways to create feature lists that you can use to quickly find cells of interest within your data, as described in the Identifying Cell Types portion of the tutorial. The first is to use the Gene/Feature Expression sidebar to create and export a list of features within Loupe Browser.

However, you can create a feature list CSV file with a simple text editor or Microsoft Excel. This may be useful if you have already identified a set of features for a particular pathway or cell type and want to quickly import those features into Loupe Browser.

The Loupe Browser feature list file format is simple. Here's an example:

List,Name,Ensembl
T Cell Markers,CD3D,ENSG00000167286
B Cell Markers,CD79A,ENSG00000105369
B Cell Markers,CD79B,ENSG00000007312
Monocyte Markers,CD14,ENSG00000170458

The first line in the CSV file must be a header, and 'List' must be the first element. You can then either supply a 'Name' or 'Ensembl' column or both. The first entry in each row must be the list that the feature belongs to (e.g., "T Cell Markers"), then the feature name and/or Ensembl ID.

When importing a list, Loupe Browser will attempt to match the rows against Ensembl IDs first, if specified, to avoid naming conflicts. If none of the features in the list match the features found in the dataset (e.g., importing a list of mouse features to a human dataset), Loupe Browser will notify you of this, and not import the list.

Filters

Filters can be imported and exported and used across datasets similarly to other features we've discussed on this page. However we recommend that you do not manually create filters as they use a json spec that's specific to Loupe Browser and is subject to modification.