correction/cellbender_remove_background

Description

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

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.

Type

python_script

Launch

Run this component

Run the following command to execute this component with Nextflow:

cat > params.yaml <<'EOM'  
modality: [ "rna" ]  
output: "$id.$key.output.h5mu"  
layer_output: [ "cellbender_corrected" ]  
obs_background_fraction: [ "cellbender_background_fraction" ]  
obs_cell_probability: [ "cellbender_cell_probability" ]  
obs_cell_size: [ "cellbender_cell_size" ]  
obs_droplet_efficiency: [ "cellbender_droplet_efficiency" ]  
obs_latent_scale: [ "cellbender_latent_scale" ]  
var_ambient_expression: [ "cellbender_ambient_expression" ]  
obsm_gene_expression_encoding: [ "cellbender_gene_expression_encoding" ]  
expected_cells_from_qc: [ false ]  
model: [ "full" ]  
epochs: [ 150 ]  
low_count_threshold: [ 5 ]  
z_dim: [ 64 ]  
z_layers: [ 512 ]  
training_fraction: [ 0.9 ]  
empty_drop_training_fraction: [ 0.2 ]  
fpr: [ 0.01 ]  
projected_ambient_count_threshold: [ 0.1 ]  
learning_rate: [ 0.0001 ]  
num_training_tries: [ 1 ]  
learning_rate_retry_mult: [ 0.2 ]  
posterior_batch_size: [ 128 ]  
estimator: [ "mckp" ]  
id: "run"  
publish_dir: "output/"  
EOM

nextflow run https://packages.viash-hub.com/vsh/openpipeline.git \  
  -revision 1.0.0 \  
  -main-script target/nextflow/correction/cellbender_remove_background/main.nf \  
  -params-file params.yaml

Inputs

Name	Type & Properties	Description
--input -i	file required	Input h5mu file. Data file on which to run tool. Data must be un-filtered: it should include empty droplets.
--modality	string	List of modalities to process.

Name

Type & Properties

--input

-i

file

required

--modality

string

Outputs

Name	Type & Properties	Description
--output -o	file required output	Full count matrix as an h5mu file, with background RNA removed. This file contains all the original droplet barcodes.
--output_compression	string
--layer_output	string	Output layer
--obs_background_fraction	string
--obs_cell_probability	string
--obs_cell_size	string
--obs_droplet_efficiency	string
--obs_latent_scale	string
--var_ambient_expression	string
--obsm_gene_expression_encoding	string

Name

Type & Properties

--output

-o

file

required

output

--output_compression

string

--layer_output

string

--obs_background_fraction

string

--obs_cell_probability

string

--obs_cell_size

string

--obs_droplet_efficiency

string

--obs_latent_scale

string

--var_ambient_expression

string

--obsm_gene_expression_encoding

string

Arguments

Name	Type & Properties	Description
--expected_cells_from_qc	boolean	Will use the Cell Ranger QC to determine the estimated number of cells
--expected_cells	integer	Number of cells expected in the dataset (a rough estimate within a factor of 2 is sufficient).
--total_droplets_included	integer	The number of droplets from the rank-ordered UMI plot that will have their cell probabilities inferred as an output. Include the droplets which might contain cells. Droplets beyond TOTAL_DROPLETS_INCLUDED should be 'surely empty' droplets.
--force_cell_umi_prior	integer	Ignore CellBender's heuristic prior estimation, and use this prior for UMI counts in cells.
--force_empty_umi_prior	integer	Ignore CellBender's heuristic prior estimation, and use this prior for UMI counts in empty droplets.
--model	string	Which model is being used for count data. * 'naive' subtracts the estimated ambient profile. * '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 (via PCR chimeras). * 'full' uses a combined ambient and swapping model.
--epochs	integer	Number of epochs to train.
--low_count_threshold	integer	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).
--z_dim	integer	Dimension of latent variable z.
--z_layers	integer multiple	Dimension of hidden layers in the encoder for z.
--training_fraction	double	Training detail: the fraction of the data used for training. The rest is never seen by the inference algorithm. Speeds up learning.
--empty_drop_training_fraction	double	Training detail: the fraction of the training data each epoch that is drawn (randomly sampled) from surely empty droplets.
--ignore_features	integer multiple	Integer indices of features to ignore entirely. In the output count matrix, the counts for these features will be unchanged.
--fpr	double multiple	Target 'delta' false positive rate in [0, 1). Use 0 for a cohort of samples which will be jointly analyzed for differential expression. 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.
--exclude_feature_types	string multiple	Feature types to ignore during the analysis. These features will be left unchanged in the output file.
--projected_ambient_count_threshold	double	Controls how many features are included in the analysis, which can lead to a large speedup. If a feature is expected to have less than PROJECTED_AMBIENT_COUNT_THRESHOLD counts total in all cells (summed), then that gene is excluded, and it will be unchanged in the output count matrix. For example, PROJECTED_AMBIENT_COUNT_THRESHOLD = 0 will include all features which have even a single count in any empty droplet.
--learning_rate	double	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).
--final_elbo_fail_fraction	double	Training is considered to have failed if (best_test_ELBO - final_test_ELBO)/(best_test_ELBO - initial_test_ELBO) > FINAL_ELBO_FAIL_FRACTION. Training will automatically re-run if --num-training-tries > 1. By default, will not fail training based on final_training_ELBO.
--epoch_elbo_fail_fraction	double	Training is considered to have failed if (previous_epoch_test_ELBO - current_epoch_test_ELBO)/(previous_epoch_test_ELBO - initial_train_ELBO) > EPOCH_ELBO_FAIL_FRACTION. Training will automatically re-run if --num-training-tries > 1. By default, will not fail training based on epoch_training_ELBO.
--num_training_tries	integer	Number of times to attempt to train the model. At each subsequent attempt, the learning rate is multiplied by LEARNING_RATE_RETRY_MULT.
--learning_rate_retry_mult	double	Learning rate is multiplied by this amount each time a new training attempt is made. (This parameter is only used if training fails based on EPOCH_ELBO_FAIL_FRACTION or FINAL_ELBO_FAIL_FRACTION and NUM_TRAINING_TRIES is > 1.)
--posterior_batch_size	integer	Training detail: size of batches when creating the posterior. Reduce this to avoid running out of GPU memory creating the posterior (will be slower).
--posterior_regulation	string	Posterior regularization method. (For experts: not required for normal usage, see documentation). * PRq is approximate quantile-targeting. * PRmu is approximate mean-targeting aggregated over genes (behavior of v0.2.0). * PRmu_gene is approximate mean-targeting per gene.
--alpha	double	Tunable parameter alpha for the PRq posterior regularization method (not normally used: see documentation).
--q	double	Tunable parameter q for the CDF threshold estimation method (not normally used: see documentation).
--estimator	string	Output denoised count estimation method. (For experts: not required for normal usage, see documentation).
--estimator_multiple_cpu	boolean_true	Including the flag --estimator-multiple-cpu will use more than one CPU to compute the MCKP output count estimator in parallel (does nothing for other estimators).
--constant_learning_rate	boolean	Including the flag --constant-learning-rate will use the ClippedAdam optimizer instead of the OneCycleLR learning rate schedule, which is the default. Learning is faster with the OneCycleLR schedule. However, training can easily be continued from a checkpoint for more epochs than the initial command specified when using ClippedAdam. On the other hand, if using the OneCycleLR schedule with 150 epochs specified, it is not possible to pick up from that final checkpoint and continue training until 250 epochs.
--debug	boolean_true	Including the flag --debug will log extra messages useful for debugging.
--cuda	boolean_true	Including the flag --cuda will run the inference on a GPU.

Name

Type & Properties

--expected_cells_from_qc

boolean

--expected_cells

integer

--total_droplets_included

integer

--force_cell_umi_prior

integer

--force_empty_umi_prior

integer

--model

string

--epochs

integer

--low_count_threshold

integer

--z_dim

integer

--z_layers

integer

multiple

--training_fraction

double

--empty_drop_training_fraction

double

--ignore_features

integer

multiple

--fpr

double

multiple

--exclude_feature_types

string

multiple

--projected_ambient_count_threshold

double

--learning_rate

double

--final_elbo_fail_fraction

double

--epoch_elbo_fail_fraction

double

--num_training_tries

integer

--learning_rate_retry_mult

double

--posterior_batch_size

integer

--posterior_regulation

string

--alpha

double

--q

double

--estimator

string

--estimator_multiple_cpu

boolean_true

--constant_learning_rate

boolean

--debug

boolean_true

--cuda

boolean_true