Generate a 10x Genomics Loupe file with custom annotations and projections:

Introduction

This process has gotten simpler with 10X Genomics Loupe Browser 5.0.0+. I try to keep a cache of all 10X downloads internal to JAX here (must be on the VPN):

http://singlecell-software.s3-far.jax.org/list.html

where you can download the latest version of Loupe Browser for your OS. Otherwise, head over to the 10X site:

https://support.10xgenomics.com/single-cell-gene-expression/software/downloads/latest#loupe

The main idea of all of this is:

Use 10X CellRanger to create an aggregated datasetthat includes all libraries present in your dataset prior to filtering
[Skip with Loupe 5.0.0] Save your finalized barcodes which should be strictly less than the total cells initially aggregated
[Skip with Loupe 5.0.0] Subset cellranger’s aggregation using this finalized barcode list using cellranger reanalyze
Grab the loupe file and add your own data to it.

Step 1

Run cellranger aggr on all libraries you’re interested in. This should take less than 4 hours with a few CPUs. Something like:

module load singularity
img="library://jaxreg.jax.org/singlecell/cellranger:3.1.0"
singularity run $img aggr \
    --id="aggregation" \
    --csv=”path/to/aggregation.csv" \
    --localcores=${localcores} \
    --localmem="60"

where aggregation.csv looks like:

library_id,molecule_h5,optional_category1
LIB20001,/projects/.../LIB20001/cellranger/molecule_info.h5,cat1
LIB20002,/projects/.../LIB20002/cellranger/molecule_info.h5,cat1
LIB20003,/projects/.../LIB20003/cellranger/molecule_info.h5,cat2
...

Step 2

Once you have the output of the aggregation, you need to save the final list of barcodes from your Seurat object.
CellRanger’s aggregation expects barcodes to look like:

AAAAAAAAAAAAAAAA-1
AAAAAAAAAAAAAACT-1  <<-- #1 denotes LIB20001
...
AAAAAAAAAAAAAAGA-1
AAAAAAAAAAAAAAAA-2  <<-- #2 denotes LIB20002
...
AAAAAAAAAAAAAACT-2
AAAAAAAAAAAAAAGA-3  <<-- #3 denotes LIB20003
...
AAAAAAAAAAAAAACT-3

The cell barcodes from Seurat might look different. You will need to transform your Seurat cell barcodes to this format and save them to a file like (the header line is important):

> cat loupe_barcodes.csv
Barcode
AAACCTGGTGCAACGA-1
AAAGATGTCTCGGACG-1
AACCGCGAGTCCCACG-1
AACTCTTTCTGCTGCT-1
AAGGAGCAGCACGCCT-1
AAGGTTCGTCTAAACC-1
ACACCAAAGCCGATTT-1

Step 3

While you’re doing this, you should export (a) all the categorical data and (b) UMAP coordinates for each barcode from your Seurat object. Save those to two files like this:

> cat loupe_metadata.csv
barcode,Custom Cluster,Sample ID,Sample Name,Tumor Status,Tumor Type,Tumor vs Normal,Chemistry Version,Viability,Doublet
AAACCTGGTGCAACGA-1,Cluster 04,KP16027,non-IBC-3,HR+,non-IBC,tumor,v2,,False
AAAGATGTCTCGGACG-1,Cluster 04,KP16027,non-IBC-3,HR+,non-IBC,tumor,v2,,False
AACCGCGAGTCCCACG-1,Cluster 05,KP16027,non-IBC-3,HR+,non-IBC,tumor,v2,,False
AACTCTTTCTGCTGCT-1,Cluster 05,KP16027,non-IBC-3,HR+,non-IBC,tumor,v2,,False
AAGGAGCAGCACGCCT-1,Cluster 01,KP16027,non-IBC-3,HR+,non-IBC,tumor,v2,,False
AAGGTTCGTCTAAACC-1,Cluster 03,KP16027,non-IBC-3,HR+,non-IBC,tumor,v2,,False
ACACCAAAGCCGATTT-1,Cluster 05,KP16027,non-IBC-3,HR+,non-IBC,tumor,v2,,False
ACACCGGGTCACTTCC-1,Cluster 01,KP16027,non-IBC-3,HR+,non-IBC,tumor,v2,,False
ACACTGACAGGTCGTC-1,Cluster 01,KP16027,non-IBC-3,HR+,non-IBC,tumor,v2,,False
 
> cat loupe_umap.csv
barcode,x coordinate,y coordinate
AAACCTGGTGCAACGA-1,3.549409,3.5673845
AAAGATGTCTCGGACG-1,3.1289513,3.5883684
AACCGCGAGTCCCACG-1,2.307969,0.18370046
AACTCTTTCTGCTGCT-1,2.8757167,0.008365445
AAGGAGCAGCACGCCT-1,-1.1723694,-0.32921985
AAGGTTCGTCTAAACC-1,1.4734324,2.0925035
ACACCAAAGCCGATTT-1,2.169127,0.1465863
ACACCGGGTCACTTCC-1,-3.5472584,0.5523026
ACACTGACAGGTCGTC-1,-0.72905755,0.3362291

The column headers of the UMAP file need to be exactly like that. The column headers in the metadata file can be whatever you want (except the first must be “barcode”).
These will show up in the Loupe file exactly as you specify in this file.
I would also recommend zero-padding your cluster numbers (and possibly prefixing them with “Cluster”) as I’ve shown above.

Step 4

SKIP IF YOU HAVE LOUPE 5.0.0!

Once you have these files, you need to rerun cellranger reanalyze with these barcodes.
This should take a short amount of time, like 30 minutes.

module load singularity
img="library://jaxreg.jax.org/singlecell/cellranger:3.1.0"
singularity run $img reanalyze \
    --id=aggregation_subset \
    --matrix=”/path/to/aggregation/outs/filtered_feature_bc_matrix.h5" \
    --agg=”/path/to/aggregation/outs/aggregation.csv" \
    --barcodes=”/path/to/loupe_barcodes.csv" \
    --localcores=${localcores} \
    --localmem="28"

Step 5

If using Loupe Cell Browser 5.0.0+, locate the Loupe file from Step 1. Otherwise, locate the loupe file from step 4. You must then copy this loupe file and your metadata.csv/umap.csv locally to the machine where you have Loupe installed.
Open up the Loupe file with the most current version of the Loupe Cell Browser.

Follow the instructions here to add your custom categorical data (metadata) and custom projections (UMAP): https://support.10xgenomics.com/single-cell-gene-expression/software/visualization/latest/tutorial-interoperability