10x Genomics
Chromium Single Cell Gene Expression

Cell Ranger6.3, printed on 12/26/2024

Interoperability

Table of Contents

• Importing and exporting projections
• Categories
• Feature lists
• Filters

We recognize there are many scripts and packages in the single cell analysis ecosystem, and 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 describe the types and formats of data that you can import and export into and out of Loupe Browser.

Importing and exporting 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:

• First row must be a header
• First column: barcodes that are at least a subset of the barcodes in the .cloupe file
• Second column: numbers which represent the X coordinates
• Third column: numbers which represent the Y coordinates

We have computed a UMAP projection for the AML Tutorial 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

Download the full AML Tutorial UMAP projection and import it. To import new projections, click on the action button to the right of the projection selector.

Importing the above AML Tutorial 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.

In Loupe Browser 6.0 and later, you can also export the selected projection t-SNE or UMAP coordinates as a CSV file, including projections generated with the filtering and reclustering wizard, for further analysis in other software packages.

Categories

In Loupe Cell Browser 1.0.5 and later and Loupe Browser 4.0 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
• The first column header must be barcode and the column's contents must match at least a subset of the barcodes in the .cloupe file
• Additional 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 called "id" and the two clusters that will be created will be called "Monocytes" and "Mature Ery". You can also download a full example that you can import into the AML Tutorial 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

• First row must be a header
• The first column header must be List
• Additional column headers are Name and/or Ensembl
• 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, exported, and used across datasets similarly to other features we have discussed on this page. However, we recommend that you do not manually create filters as they use a json specification that's specific to Loupe Browser and are subject to modification.