Cellbender remove background v0 2

Eliminating technical artifacts from high-throughput single-cell RNA sequencing data.

Info

ID: cellbender_remove_background_v0_2
Namespace: correction

This module removes counts due to ambient RNA molecules and random barcode swapping from (raw) UMI-based scRNA-seq count matrices. At the moment, only the count matrices produced by the CellRanger count pipeline is supported. Support for additional tools and protocols will be added in the future. A quick start tutorial can be found here.

Fleming et al. 2022, bioRxiv.

Example commands

You can run the pipeline using nextflow run.

View help

You can use --help as a parameter to get an overview of the possible parameters.

nextflow run openpipelines-bio/openpipeline \
  -r 1.0.1 -latest \
  -main-script target/nextflow/correction/cellbender_remove_background_v0_2/main.nf \
  --help

Run command

Example of params.yaml 
# Inputs
input: # please fill in - example: "input.h5mu"
modality: "rna"

# Outputs
# output: "$id.$key.output.h5mu"
# output_compression: "gzip"
layer_output: "corrected"
obs_latent_rt_efficiency: "latent_rt_efficiency"
obs_latent_cell_probability: "latent_cell_probability"
obs_latent_scale: "latent_scale"
var_ambient_expression: "ambient_expression"
obsm_latent_gene_encoding: "cellbender_latent_gene_encoding"

# Arguments
# expected_cells: 1000
# total_droplets_included: 25000
expected_cells_from_qc: true
model: "full"
epochs: 150
low_count_threshold: 15
z_dim: 100
z_layers: [500]
training_fraction: 0.9
empty_drop_training_fraction: 0.5
fpr: [0.01]
exclude_antibody_capture: false
# learning_rate: 1.0E-4
cuda: false

# Nextflow input-output arguments
publish_dir: # please fill in - example: "output/"
# param_list: "my_params.yaml"
nextflow run openpipelines-bio/openpipeline \
  -r 1.0.1 -latest \
  -profile docker \
  -main-script target/nextflow/correction/cellbender_remove_background_v0_2/main.nf \
  -params-file params.yaml
Note

Replace -profile docker with -profile podman or -profile singularity depending on the desired backend.

Argument groups

Inputs

Name Description Attributes
--input Input h5mu file. file, required, example: "input.h5mu"
--modality List of modalities to process. string, default: "rna"

Outputs

Name Description Attributes
--output Full count matrix as an h5mu file, with background RNA removed. This file contains all the original droplet barcodes. file, required, example: "output.h5mu"
--output_compression string, example: "gzip"
--layer_output Output layer string, default: "corrected"
--obs_latent_rt_efficiency string, default: "latent_rt_efficiency"
--obs_latent_cell_probability string, default: "latent_cell_probability"
--obs_latent_scale string, default: "latent_scale"
--var_ambient_expression string, default: "ambient_expression"
--obsm_latent_gene_encoding string, default: "cellbender_latent_gene_encoding"

Arguments

Name Description Attributes
--expected_cells Number of cells expected in the dataset (a rough estimate within a factor of 2 is sufficient). integer, example: 1000
--total_droplets_included The number of droplets from the rank-ordered UMI plot that will be analyzed. The largest ‘total_droplets’ droplets will have their cell probabilities inferred as an output. integer, example: 25000
--expected_cells_from_qc Will use the Cell Ranger QC to determine the estimated number of cells boolean, default: TRUE
--model Which model is being used for count data. ‘simple’ does not model either ambient RNA or random barcode swapping (for debugging purposes – not recommended). ‘ambient’ assumes background RNA is incorporated into droplets. ‘swapping’ assumes background RNA comes from random barcode swapping. ‘full’ uses a combined ambient and swapping model. string, default: "full"
--epochs Number of epochs to train. integer, default: 150
--low_count_threshold Droplets with UMI counts below this number are completely excluded from the analysis. This can help identify the correct prior for empty droplet counts in the rare case where empty counts are extremely high (over 200). integer, default: 15
--z_dim Dimension of latent variable z. integer, default: 100
--z_layers Dimension of hidden layers in the encoder for z. List of integer, default: 500, multiple_sep: ";"
--training_fraction Training detail: the fraction of the data used for training. The rest is never seen by the inference algorithm. Speeds up learning. double, default: 0.9
--empty_drop_training_fraction Training detail: the fraction of the training data each epoch that is drawn (randomly sampled) from surely empty droplets. double, default: 0.5
--fpr Target false positive rate in (0, 1). A false positive is a true signal count that is erroneously removed. More background removal is accompanied by more signal removal at high values of FPR. You can specify multiple values, which will create multiple output files. List of double, default: 0.01, multiple_sep: ";"
--exclude_antibody_capture Including the flag –exclude-antibody-capture will cause remove-background to operate on gene counts only, ignoring other features. boolean_true
--learning_rate Training detail: lower learning rate for inference. A OneCycle learning rate schedule is used, where the upper learning rate is ten times this value. (For this value, probably do not exceed 1e-3). double, example: 1e-04
--cuda Including the flag –cuda will run the inference on a GPU. boolean_true