CellBender remove-background report¶

This output report from cellbender remove-background contains a summary of the run, including counts remaining, counts removed, further analyses, and any warnings or suggestions if the run seems to be abnormal.

This HTML report is created from a jupyter notebook at

cellbender/cellbender/remove-background/report.ipynb

within the CellBender codebase. Feel free to run the notebook yourself and make any changes you see fit, or use it as a starting point for further analyses.

The commentary in this report is generated using automated heuristics and best guesses based on hundreds of real datasets. If any of the automated commentary in this report seems incorrect for your dataset, please submit a question or an issue at our github repository https://github.com/broadinstitute/CellBender

Cellarium Lab .. Methods Group .. Data Sciences Platform .. Broad Institute


Input and output files¶

(Modify this section if you run this notebook yourself.)

Input file: /om2/user/benjames/raw/human_brain_3k.h5ad
Output file: /net/vast-storage/scratch/vast/kellislab/benjames/cellbender/human_brain_3k/cellbender.h5

Report¶

CellBender version 0.3.0¶

2023-12-05 21:10:01

cellbender.h5¶

Loaded dataset¶

AnnData object with n_obs × n_vars = 8159 × 36601
    obs: 'background_fraction', 'cell_probability', 'cell_size', 'droplet_efficiency', 'n_raw', 'n_cellbender'
    var: 'ambient_expression', 'feature_type', 'genome', 'gene_id', 'cellbender_analyzed', 'n_raw', 'n_cellbender'
    uns: 'cell_size_lognormal_std', 'empty_droplet_size_lognormal_loc', 'empty_droplet_size_lognormal_scale', 'swapping_fraction_dist_params', 'estimator', 'features_analyzed_inds', 'fraction_data_used_for_testing', 'learning_curve_learning_rate_epoch', 'learning_curve_learning_rate_value', 'learning_curve_test_elbo', 'learning_curve_test_epoch', 'learning_curve_train_elbo', 'learning_curve_train_epoch', 'target_false_positive_rate'
    obsm: 'cellbender_embedding'
    layers: 'raw', 'cellbender'

Examine how many counts were removed in total¶

removed 428626 counts from non-empty droplets
removed 1.11% of the counts in non-empty droplets
Rough estimate of expectations based on nothing but the plot above:
roughly 54476 noise counts should be in non-empty droplets
that is approximately 0.14% of the counts in non-empty droplets
with a false positive rate [FPR] of 1.0%, we would expect to remove about 1.14% of the counts in non-empty droplets

It looks like the algorithm did a great job meeting that expectation.

Assessing convergence of the algorithm¶

The learning curve tells us about the progress of the algorithm in inferring all the latent variables in our model. We want to see the ELBO increasing as training epochs increase. Generally it is desirable for the ELBO to converge at some high plateau, and be fairly stable.

What to watch out for:

1. large downward spikes in the ELBO (of value more than a few hundred) 2. the test ELBO can be smaller than the train ELBO, but generally we want to see both curves increasing and reaching a stable plateau. We do not want the test ELBO to dip way back down at the end. 3. lack of convergence, where it looks like the ELBO would change quite a bit if training went on for more epochs.

Automated assessment --------

  • We hope to see the test ELBO follow the training ELBO, increasing almost monotonically (though there will be deviations, and that is expected). There may be a large gap, and that is okay. However, this curve ends with a low test ELBO compared to the max test ELBO value during training. The output could be suboptimal.

Summary:

This is slightly unusual behavior, and a reduced --learning-rate might be indicated. Consider re-running with half the current learning rate to compare the results.

Examine count removal per gene¶

Pearson correlation coefficient for the above is 0.9317

This meets expectations.

Table of top genes removed¶

Ranked by fraction removed, and excluding genes with fewer than 2171 total raw counts (90th percentile)

ambient_expression feature_type genome gene_id cellbender_analyzed n_raw n_cellbender n_removed fraction_removed fraction_remaining n_raw_cells n_cellbender_cells n_removed_cells fraction_removed_cells fraction_remaining_cells
gene_name
MT-ND3 0.004209 Gene Expression GRCh38 ENSG00000198840 True 5977 4868 1109 0.185545 0.814455 5154 4868 286 0.055491 0.944509
MT-ATP6 0.006080 Gene Expression GRCh38 ENSG00000198899 True 9017 7382 1635 0.181324 0.818676 7804 7382 422 0.054075 0.945925
MT-CYB 0.004366 Gene Expression GRCh38 ENSG00000198727 True 6383 5241 1142 0.178913 0.821087 5544 5241 303 0.054654 0.945346
MT-CO2 0.010887 Gene Expression GRCh38 ENSG00000198712 True 16173 13326 2847 0.176034 0.823966 14060 13326 734 0.052205 0.947795
MT-ND2 0.004485 Gene Expression GRCh38 ENSG00000198763 True 6975 5799 1176 0.168602 0.831398 6118 5799 319 0.052141 0.947859
MT-CO1 0.011273 Gene Expression GRCh38 ENSG00000198804 True 17899 15014 2885 0.161182 0.838818 15808 15014 794 0.050228 0.949772
MT-ND1 0.004616 Gene Expression GRCh38 ENSG00000198888 True 7543 6334 1209 0.160281 0.839719 6666 6334 332 0.049805 0.950195
MT-CO3 0.007446 Gene Expression GRCh38 ENSG00000198938 True 12440 10462 1978 0.159003 0.840997 10995 10462 533 0.048477 0.951523
MT-ND5 0.001510 Gene Expression GRCh38 ENSG00000198786 True 2656 2235 421 0.158509 0.841491 2357 2235 122 0.051761 0.948239
MT-ND4 0.005869 Gene Expression GRCh38 ENSG00000198886 True 11474 9935 1539 0.134129 0.865871 10361 9935 426 0.041116 0.958884

Cell probabilities¶

The inferred posterior probability that each droplet is non-empty.

We sometimes write "non-empty" instead of "cell" because dead cells and other cellular debris can still lead to a "non-empty" droplet, which will have a high posterior cell probability. But these kinds of low-quality droplets should be removed during cell QC to retain only high-quality cells for downstream analyses.

Concordance of data before and after remove-background¶

The intent is to change the input data as little as possible while achieving noise removal. These plots show general summary statistics about similarity of the input and output data. We expect to see the data lying close to a straight line (gray). There may be outlier genes/features, which are often those highest-expressed in the ambient RNA.

The plots here show data for inferred cell-containing droplets, and exclude the empty droplets.

PCA of encoded gene expression¶

We are not looking for anything specific in the PCA plot of the gene expression embedding, but often we see clusters that correspond to different cell types. If you see only a single large blob, then the dataset might contain only one cell type, or perhaps there are few counts per droplet.

Summary of warnings:¶

Final test ELBO is much lower than the max test ELBO.