DoubletDetection

DoubletDetection is a transcription-based doublet detection software. This was one of the better-performing doublet detecting softwares that we identified in our paper (CITE) and it is also relatively fast to run. We have provided a wrapper script that enables DoubletDetection 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 DoubletDetection:

Required

  • A counts matrix ($COUNTS)

    • DoubletDetection 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 either of these formats, you can run DoubletDetection manually in python and load the data in using a method of your choosing.

Optional

  • Output directory ($DOUBLETDETECTION_OUTDIR)

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

Run DoubletDetection

You can either run DoubletDetection with the wrapper script we have provided or you can run it manually if you would prefer to alter more parameters.

singularity exec Demuxafy.sif DoubletDetection.py -m $COUNTS -o $DOUBLETDETECTION_OUTDIR

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

singularity exec Demuxafy.sif DoubletDetection.py -h

usage: DoubletDetection.py [-h] -m COUNTS_MATRIX [-b BARCODES] [-o OUTDIR] [-i N_ITERATIONS] [-p PHENOGRAPH] [-s STANDARD_SCALING] [-t P_THRESH] [-v VOTER_THRESH]

wrapper for DoubletDetection for doublet detection from 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
                        File containing droplet barcodes. Use barcodes from provided 10x dir by default.
  -o OUTDIR, --outdir OUTDIR
                        The output directory; default is current working directory
  -i N_ITERATIONS, --n_iterations N_ITERATIONS
                        Number of iterations to use; default is 50
  -p PHENOGRAPH, --phenograph PHENOGRAPH
                        Whether to use phenograph (True) or not (False); default is False
  -s STANDARD_SCALING, --standard_scaling STANDARD_SCALING
                        Whether to use standard scaling of normalized count matrix prior to PCA (True) or not (False); default is True
  -t P_THRESH, --p_thresh P_THRESH
                        P-value threshold for doublet calling; default is 1e-16
  -v VOTER_THRESH, --voter_thresh VOTER_THRESH
                        Voter threshold for doublet calling; default is 0.5

DoubletDetection Results and Interpretation

After running the DoubletDetection, you will have multiple files in the $DOUBLETDETECTION_OUTDIR:

.
├── convergence_test.pdf
├── DoubletDetection_doublets_singlets.tsv
├── DoubletDetection_summary.tsv
└── threshold_test.pdf

We have found these to be the most helpful:

  • DoubletDetection_summary.tsv

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

    DoubletDetection_DropletType

    Droplet N

    doublet

    2594

    singlet

    18388

  • DoubletDetection_doublets_singlets.tsv

    • The per-barcode singlet and doublet classification from DoubletDetection.

      Barcode

      DoubletDetection_DropletType

      AAACCTGAGATAGCAT-1

      singlet

      AAACCTGAGCAGCGTA-1

      singlet

      AAACCTGAGCGATGAC-1

      singlet

      AAACCTGAGCGTAGTG-1

      singlet

      AAACCTGAGGAGTTTA-1

      singlet

      AAACCTGAGGCTCATT-1

      singlet

      AAACCTGAGGGCACTA-1

      singlet

  • convergence_test.pdf

    • The expectation is that after multiple rounds, the expected number of doublets will converge. If that is not the case, we suggest that you run DoubletDetection for more iterations (try 150, or even 250 if that isn’t convincing).

    • Here are two figures - one of a sample that came to convergence after 50 iterations (left) and one that did not (right)

      Good Converged

      Bad Convergence

      https://user-images.githubusercontent.com/44268007/104434976-ccf8fa80-55db-11eb-9f30-00f71e4592d4.png
      https://user-images.githubusercontent.com/44268007/95423527-f545dd00-098c-11eb-8a48-1ca6bb507151.png

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 paper (REFERENCE) as well as DoubletDetection.