Scrublet

Scrublet is a transcription-based doublet detecting software. We have provided a wrapper script that enables Scrublet to be easily run from the command line but we also provide example code so that users can run manually as well depending on their data.

Data

This is the data that you will need to have prepare to run Scrublet:

Required

  • A counts matrix ($COUNTS)

    • Scrublet expects counts to be in the cellranger output format either as

      • h5 file (filtered_feature_bc_matrix.h5)

        or

      • matrix directory (directory containing barcodes.tsv, genes.tsv and matrix.mtx or barcodes.tsv.gz, features.tsv.gz and matrix.mtx.gz)

      • If you don’t have your data in this format, you can run Scrublet manually in python and load the data in using a method of your choosing.

Optional

  • Output directory ($SCRUBLET_OUTDIR)

    • If you don’t provide an $SCRUBLET_OUTDIR, the results will be written to the present working directory.

  • Filtered barcode file

    • A list of barcodes that are a subset of the barcodes in your h5 or matrix.mtx files. This is useful if you have run other QC softwares such as CellBender or DropletQC to remove empty droplets or droplets with damaged cells.

    • Expectation is that there is no header in this file

Run Scrublet

:octicon:`stopwatch` Expected Resource Usage

~1min using a total of 15Mb memory when using 2 thread for the full Test Dataset which contains ~20,982 droplets of 13 multiplexed donors,

You can either run Scrublet with the wrapper script we have provided or you can run it manually if you would prefer to alter more parameters. In addition, we provide an example for filtering the single cell matrix to a subsetted list of barcodes

Note

It is a good idea to try multiple different percentile variable numbers. We typically try, 80, 85, 90 and 95. Then we choose the one that has the best defined bimodal distribution based on the doublet_score_histogram.png (see Scrublet Results and Interpretation for details).

First, let’s assign the variables that will be used to execute each step.

Example Variable Settings

Below is an example of the variables that we can set up to be used in the command below. These are files provided as a test dataset available in the Data Preparation Documentation Please replace paths with the full path to data on your system.

SCRUBLET_OUTDIR=/path/to/output/scrublet
COUNTS=/path/to/TestData4PipelineFull/test_dataset/outs/filtered_gene_bc_matrices/Homo_sapiens_GRCh38p10/

To run Scrublet with our wrapper script, simply execute the following in your shell:

singularity exec Demuxafy.sif Scrublet.py -m $COUNTS -o $SCRUBLET_OUTDIR

To see all the parameters that this wrapper script will accept, run:

singularity exec Demuxafy.sif Scrublet.py -h



usage: Scrublet.py [-h] -m COUNTS_MATRIX [-b BARCODES] [-f FILTERED_BARCODES]
             [-r SIM_DOUBLET_RATIO] [-c MIN_COUNTS] [-e MIN_CELLS]
             [-v MIN_GENE_VARIABILITY_PCTL] [-p N_PRIN_COMPS]
             [-t SCRUBLET_DOUBLET_THRESHOLD] [-o OUTDIR]

wrapper for scrublet for doublet detection of transcriptomic data.

optional arguments:
  -h, --help            show this help message and exit
  -m COUNTS_MATRIX, --counts_matrix COUNTS_MATRIX
                        cell ranger counts matrix directory containing matrix files or full path to matrix.mtx. Can also also provide the 10x h5.
  -b BARCODES, --barcodes BARCODES
                        barcodes.tsv or barcodes.tsv.gz from cellranger
  -f FILTERED_BARCODES, --filtered_barcodes FILTERED_BARCODES
                        File containing a filtered list of droplet barcodes.
                        This may be used if you want to use a filtered list of
                        barcodes for doublet detection (ie need to remove
                        droplets that are empty or high in ambient RNA).
  -r SIM_DOUBLET_RATIO, --sim_doublet_ratio SIM_DOUBLET_RATIO
                        Number of doublets to simulate relative to the number of observed transcriptomes.
  -c MIN_COUNTS, --min_counts MIN_COUNTS
                        Used for gene filtering prior to PCA. Genes expressed at fewer than min_counts in fewer than min_cells are excluded.
  -e MIN_CELLS, --min_cells MIN_CELLS
                        Used for gene filtering prior to PCA. Genes expressed at fewer than min_counts in fewer than are excluded.
  -v MIN_GENE_VARIABILITY_PCTL, --min_gene_variability_pctl MIN_GENE_VARIABILITY_PCTL
                        Used for gene filtering prior to PCA. Keep the most highly variable genes in the top min_gene_variability_pctl percentile), as measured by the v-statistic [Klein et al., Cell 2015].
  -p N_PRIN_COMPS, --n_prin_comps N_PRIN_COMPS
                        Number of principal components used to embed the transcriptomes priorto k-nearest-neighbor graph construction.
  -t SCRUBLET_DOUBLET_THRESHOLD, --scrublet_doublet_threshold SCRUBLET_DOUBLET_THRESHOLD
                        Manually Set the scrublet doublet threshold location. For running a second time if scrublet incorrectly places the threshold the first time
  -o OUTDIR, --outdir OUTDIR
                        The output directory

Scrublet Results and Interpretation

After running the Scrublet, you will have four files in the $SCRUBLET_OUTDIR:

/path/to/output/scrublet
├── doublet_score_histogram.png
├── scrublet_results.tsv
├── scrublet_summary.tsv
└── UMAP.png

We have found these to be the most helpful:

  • scrublet_summary.tsv

    • A summary of the number of singlets and doublets predicted by Scrublet.

    scrublet_DropletType

    Droplet N

    doublet

    1851

    singlet

    19131

  • scrublet_results.tsv

    Barcode

    scrublet_DropletType

    scrublet_Scores

    AAACCTGAGATAGCAT-1

    singlet

    0.0545

    AAACCTGAGCAGCGTA-1

    singlet

    0.1179

    AAACCTGAGCGATGAC-1

    singlet

    0.1356

    AAACCTGAGCGTAGTG-1

    singlet

    0.0844

    AAACCTGAGGAGTTTA-1

    singlet

    0.0958

    AAACCTGAGGCTCATT-1

    singlet

    0.1329

    AAACCTGAGGGCACTA-1

    doublet

    0.4474

  • doublet_score_histogram.png

    • This is the method that Scrublet uses to identify doublets - it assumes a bimodal distribution of doublet scores. Those droplets with lower scores should be singlets and those with higher scores should be doublets. It identifies the correct threshold by identifying the minimum of the bimodal distribution of simulated doublets (right).

    • However, sometimes there is not a good bimodal distribution and sometimes you will have to set the threshold manually.

    • Here is an example of a good distribution (left) and a bad distribution (left)

      Good Distribution

      Bad Distribution

      https://user-images.githubusercontent.com/44268007/104436850-016db600-55de-11eb-8f75-229338f7bac7.png
      https://user-images.githubusercontent.com/44268007/88889203-ed780700-d27e-11ea-9104-60d7015f2510.png
      • In the case of the left sample, we would rerun with different parameters to try to get a better distribution and possibly manually set the threshold to ~0.2 depending on the results. In the event that we can’t achieve a clear bimodal distribution, we don’t use scrublet for doublet detecting.

Merging Results with Other Software Results

We have provided a script that will help merge and summarize the results from multiple softwares together. See Combine Results.

Citation

If you used the Demuxafy platform for analysis, please reference our preprint as well as Scrublet.