Cell Ranger4.0, printed on 12/21/2024
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.
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:
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.
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:
barcode and the column's contents must match at
least a subset of the barcodes in the .cloupe filebarcode,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.
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 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.