How the data is generated

In droplet-based single-cell RNA-sequencing (10x Genomics Chromium), each droplet (a GEM, Gel Bead-in-EMulsion) captures one or more cells together with a barcoded gel bead, so every cell’s transcripts inherit a shared cell barcode and each molecule gets a unique molecular identifier (UMI). Most droplets contain a single cell (a singlet), but some capture two or more; when those cells come from different species, the droplet is a human-mouse multiplet.

To tell the two species apart, reads are aligned with cellranger count against a combined (“barnyard”) reference that contains both genomes, for example GRCh38 (human) and GRCm39 (mouse). In this reference every gene is prefixed by its genome of origin (e.g. GRCh38-EPCAM, GRCm39-Col1a1), so each read can be attributed to human or mouse. For every cell barcode, Cell Ranger counts how many reads map to each genome and, using fixed count thresholds, labels the barcode as human, mouse, or a multiplet. This per-barcode, two-genome summary is written to the GEM classification file.

Where to find it

The file is written only when the reference is a multi-genome (barnyard) reference. For a run with --id=<SAMPLE>, it is located at:

<SAMPLE>/outs/analysis/gem_classification.csv

The full expression matrix lives separately at <SAMPLE>/outs/filtered_feature_bc_matrix/. multipletR does not need the matrix, only gem_classification.csv, although the Seurat/SingleCellExperiment helper later joins the calls back onto a matrix-derived object by barcode.

What it contains

One row per cell barcode, with these columns:

A typical file looks like:

barcode,GRCh38,GRCm39,call
AAACCTGAGAAACCAT-1,10432,58,GRCh38
AAACCTGAGATCCGAG-1,71,9903,GRCm39
AAACCTGCACGTGTGA-1,4821,5210,Multiplet

The first row is dominated by human reads (a human singlet), the second by mouse reads (a mouse singlet), and the third has substantial reads from both genomes (a multiplet).

The package ships a real PDX example (sample PC65). Here are the first rows:

gem_file <- system.file("extdata", "PC65_gem_classification.csv",
  package = "multipletR"
)
head(read.csv(gem_file))
#>              barcode GRCh38 GRCm39      call
#> 1 AAACCAAAGCAAGTGG-1   8755    123    GRCh38
#> 2 AAACCAAAGCGAACTC-1   1099  31769 Multiplet
#> 3 AAACCAAAGGAGGCAC-1  78678    452    GRCh38
#> 4 AAACCATTCAATGGCC-1  16813    168    GRCh38
#> 5 AAACCATTCAGCAACC-1   1007     27    GRCh38
#> 6 AAACCATTCGCATGGT-1 100603  11623 Multiplet

Why this is the input multipletR needs

The package’s whole premise is that a true human-mouse multiplet has substantial reads from both genomes, whereas a singlet is dominated by one. The GEM classification file provides exactly the two numbers needed to test that: the human and mouse read counts per barcode. From them, multipletR derives, for each barcode, the total reads (human + mouse) and the percent mouse (mouse / total x 100), and applies its adaptive thresholds in that total-reads by percent-mouse space rather than trusting Cell Ranger’s fixed call. The call column is kept only for the comparison plots. See make-data.R for how this bundled PC65 example was created.

Column-name flexibility

Because the genome columns are named after whichever reference build was used, multipletR recognizes several common names automatically, so you do not have to rename anything:

• Human: GRCh38, hg38, human_reads, human
• Mouse: GRCm39, mm10, mm39, mouse_reads, mouse
• Barcode: barcode, Barcode, barcodes (if none is present, the row index is used as a fallback)
• Call: call, Call, classification

As long as the file has a human read-count column and a mouse read-count column, detect_multiplets() will run; the barcode and call columns are optional but recommended (the barcode is what lets you match results back to a Seurat or SingleCellExperiment object).

Tip: barcode suffixes must match between the GEM file and any object you later filter. Cell Ranger writes barcodes with a trailing -1; if your object’s cell names lack it (or vice versa), remove_multiplets() will match nothing. Make the two consistent before joining.

Reading the diagnostic plots

Each plot has two panels: the left colored by Cell Ranger’s call, the right by the multipletR classification. Across both panels human singlets are blue and mouse singlets are green; Cell Ranger’s multiplets are orange (left) and multipletR’s are red (right), so it is easy to see which cells each method flags.

In the percent plot, multiplets sit in the central percent-mouse band, where a droplet carries a real mix of human and mouse reads; pure human cells fall near 0% mouse and pure mouse cells near 100%. In the total-reads plot, true multiplets have substantial reads from both genomes, so they sit away from the two axes.

The contrast with Cell Ranger is the key point. In this PDX sample Cell Ranger’s fixed thresholds label many predominantly single-species barcodes as multiplets, whereas the adaptive method keeps only the balanced droplets. You can see the size of that gap directly:

# Cell Ranger's multiplet calls (from the GEM file)
sum(read.csv(gem_file)$call == "Multiplet")
#> [1] 579
# multipletR's multiplet calls
sum(res$our_classification == "Multiplet")
#> [1] 59

We can confirm the multiplets multipletR keeps are genuinely balanced by looking at their composition, which centers near a mixed human/mouse split rather than sitting at one extreme:

mult <- res[res$our_classification == "Multiplet", ]
summary(mult$pct_human)
#>    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
#>   18.02   21.39   37.03   39.81   55.19   74.27
summary(mult$pct_mouse)
#>    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
#>   25.73   44.81   62.97   60.19   78.61   81.98

Adjusting the thresholds

The defaults are the recommended values and rarely need changing, but every parameter is adjustable. The three starting thresholds are T1 (upper percent mouse), T2 (lower percent mouse), and T3 (lower total-reads percentile); the two stopping sensitivities are overlapDrop and modeDiff. For example, a more conservative run:

res_strict <- detect_multiplets(
  fileIn      = gem_file,
  fileOut     = tempfile(fileext = ".csv"),
  overlapDrop = 5, # stop expanding sooner
  modeDiff    = 0.5 # stricter on distribution similarity
)

See ?detect_multiplets for the full list of arguments.