Scrublet

Scrublet identifies doublets in single-cell RNA-seq data using a raw (unnormalized) UMI counts matrix where cells are rows and genes are columns.

To use Scrublet, initialize the Scrublet class with your counts_matrix, then call scrub_doublets() to obtain doublet scores and predictions.

• doublet_scores: A continuous score between 0 and 1 for each cell.
• predicted_doublets: A boolean array where True indicates a predicted doublet and False indicates a single cell.

import scrublet as scr
scrub = scr.Scrublet(counts_matrix)
doublet_scores, predicted_doublets = scrub.scrub_doublets()

You can install Scrublet via PyPI using pip, or install it from the source repository.

Via PyPI

pip install scrublet

From Source

git clone https://github.com/swolock/scrublet.git
cd scrublet
pip install -r requirements.txt
pip install --upgrade .

To ensure accurate doublet detection, follow these best practices:

• Run on samples separately: Do not run Scrublet on merged datasets. Because it detects technical doublets from random co-encapsulation, it performs poorly if cell type proportions in a merged dataset do not represent any single sample. Run Scrublet on each sample individually.
• Validate the threshold: Ensure the doublet score threshold is reasonable. Ideally, the threshold should separate the two peaks of a bimodal simulated doublet score histogram. Adjust the threshold manually if necessary.
• Visualize predictions: Check your results by visualizing predicted doublets in a 2-D embedding (e.g., UMAP or t-SNE). Predicted doublets should mostly co-localize in clusters. If they do not, consider adjusting the score threshold or changing pre-processing parameters to better resolve cell states.

Scrublet requires a scipy sparse CSC matrix as input. The matrix E must be structured with cells as rows and genes as columns.

If you are loading from a standard 10X Genomics .mtx file (which typically has genes as rows and cells as columns), you must transpose the matrix using .T and convert it to CSC format using .tocsc().

import scipy.io
import scipy.sparse
import scrublet as scr
import numpy as np

# Load from mtx and transpose so cells are rows and genes are columns
E = scipy.io.mmread('matrix.mtx').T.tocsc()

# Load gene names using scrublet utility
genes = np.array(scr.load_genes('genes.tsv', delimiter='\t', column=1))

After running sc.tl.woublet, the results are stored in the adata object:

• adata.obs['doublet_score']: The calculated score for each observed cell.
• adata.uns['sim_doublet_score']: The scores for the simulated doublets.

To classify cells, you should manually inspect the distribution of observed vs. simulated scores and set a threshold. Cells with a score above this threshold are labeled as 'doublet', and those below are 'singlet'.

# Example of manual thresholding and classification
threshold = 0.25

doub_obs = adata.obs['doublet_score']
adata.obs['predicted_doublets'] = pd.Categorical(['doublet' if x > threshold else 'singlet' for x in doub_obs])

Scrublet Class

scr.Scrublet(counts_matrix)

Initializes the Scrublet object.

• Parameters:
  • counts_matrix: A raw (unnormalized) UMI counts matrix with cells as rows and genes as columns.

scrub_doublets() method

doublet_scores, predicted_doublets = scrub.scrub_doublets()

Simulates doublets from the observed data and uses a k-nearest-neighbor classifier to calculate scores.

• Returns:
  • doublet_scores: A continuous doublet_score (between 0 and 1) for each transcriptome.
  • predicted_doublets: A boolean array where True represents a predicted doublet.

Once doublets are predicted, you can visualize the doublet_score and the predicted_doublets classification on a UMAP embedding using sc.pl.umap.

sc.pl.umap(adata, ['doublet_score', 'predicted_doublets'], color_map='Reds', size=40)

Use scr.load_genes() to load a gene list from a TSV file. You can specify which column contains the gene names using the column parameter.

import scrublet as scr
import numpy as np

genes = np.array(scr.load_genes('path/to/genes.tsv', column=1))

If the automatically detected threshold from scrub_doublets() is not ideal, you can manually set a new threshold using call_doublets(threshold=new_threshold). It is recommended to inspect the plot_histogram() output first to find a threshold that separates the simulated doublet scores from the observed scores effectively.

# After running scrub_doublets()
scrublet.plot_histogram()

# If the threshold needs adjustment:
scrublet.call_doublets(threshold=0.25)

To use Scrublet, initialize the Scrublet class with a counts matrix (scipy sparse matrix with cells as rows and genes as columns).

Key parameters:

• expected_doublet_rate: The expected fraction of transcriptomes that are doublets (typically 0.05-0.1).
• sim_doublet_ratio: The number of doublets to simulate relative to observed transcriptomes. Default is 2. Lower values (e.g., 0.5) are often sufficient and faster.
• n_neighbors: Number of neighbors for the KNN classifier. Default is round(0.5*sqrt(n_cells)).

Note: The counts matrix should be in CSC format for optimal performance.

import scrublet as scr
# counts_matrix should be a scipy sparse matrix (cells as rows, genes as columns)
scrub = scr.Scrublet(counts_matrix, expected_doublet_rate=0.06)

After calculating scores, use the call_doublets method to identify specific cells as doublets based on a provided threshold. It is recommended to inspect the simulated doublet score histogram using plot_histogram() to determine an appropriate threshold for your data.

# Set threshold based on histogram inspection
predicted_doublets = scrub.call_doublets(threshold=0.33)

# Visualize the histogram to help choose a threshold
scrub.plot_histogram()