Bulk RNA-seq deconvolution with Bulk2Single

Overview

Use this skill when a user wants to reconstruct single-cell profiles from bulk RNA-seq together with a matched reference scRNA-seq atlas. It follows [tbulk2single.ipynb](../../omicverseguide/docs/Tutorials-bulk2single/t_bulk2single.ipynb), which demonstrates how to harmonise PDAC bulk replicates, train the beta-VAE generator, and benchmark the output cells against dentate gyrus scRNA-seq.

Instructions

1. Load libraries and data

- Import omicverse as ov, scanpy as sc, scvelo as scv, anndata, and matplotlib.pyplot as plt, then call ov.plotset() to match omicverse styling. - Read the bulk counts table with ov.read(...)/ov.utils.read(...) and harmonise gene identifiers via ov.bulk.MatrixIDmapping(<df>, 'genesets/pairGRCm39.tsv'). - Load the reference scRNA-seq AnnData (e.g., scv.datasets.dentategyrus()) and confirm the cluster labels (stored in adata.obs['clusters']).

1. Initialise the Bulk2Single model

- Instantiate ov.bulk2single.Bulk2Single(bulkdata=bulkdf, singledata=adata, celltypekey='clusters', bulkgroup=['dgd1', 'dgd2', 'dgd3'], topmarkernum=200, rationum=1, gpu=0). - Explain GPU selection (gpu=-1 forces CPU) and how bulk_group names align with column IDs in the bulk matrix.

1. Estimate cell fractions

- Call model.predictedfraction() to run the integrated TAPE estimator, then plot stacked bar charts per sample to validate proportions. - Encourage saving the fraction table for downstream reporting (df.tocsv(...)).

1. Preprocess for beta-VAE

- Execute model.bulkpreprocesslazy(), model.singlepreprocesslazy(), and model.prepare_input() to produce matched feature spaces. - Clarify that the lazy preprocessing expects raw counts; skip if the user has already log-normalised data and instead provide aligned matrices manually.

1. Train or load the beta-VAE

- Train with model.train(batchsize=512, learningrate=1e-4, hiddensize=256, epochnum=3500, vaesavedir='...', vaesavename='dgvae', generatesavedir='...', generatesavename='dg'). - Mention early stopping via patience and how to resume by reloading weights with model.load('.../dgvae.pth'). - Use model.plot_loss() to monitor convergence.

1. Generate and filter synthetic cells

- Produce an AnnData using model.generate() and reduce noise through model.filtered(generateadata, leidensize=25). - Store the filtered AnnData (.writeh5ad) for reuse, noting it contains PCA embeddings in obsm['Xpca'].

1. Benchmark against the reference atlas

- Plot cell-type compositions with ov.bulk2single.bulk2singleplotcellprop(...) for both generated and reference data. - Assess correlation using ov.bulk2single.bulk2singleplotcorrelation(singledata, generateadata, celltypekey='clusters'). - Embed with generateadata.obsm['Xmde'] = ov.pl.mde(generateadata.obsm['Xpca']) and visualise via ov.pl.embedding(..., color=['clusters'], palette=ov.pl.sccolor()).

1. Defensive validation

``python # Before Bulk2Single: verify gene name overlap between bulk and reference sharedgenes = set(bulkdf.index) & set(adata.varnames) assert len(sharedgenes) > 100, f"Only {len(sharedgenes)} shared genes — check gene ID format (Ensembl vs symbol)" # Verify bulkgroup column names match for g in bulkgroup: assert g in bulkdf.columns, f"Bulk group '{g}' not found in bulk data columns" # Verify cell type key exists assert celltypekey in adata.obs.columns, f"Cell type column '{celltypekey}' not found in reference AnnData" ``

1. Troubleshooting tips

- If marker selection fails, increase topmarkernum or provide a curated marker list. - Alignment errors typically stem from mismatched bulk_group names—double-check column IDs in the bulk matrix. - Training on CPU can take several hours; advise switching gpu to an available CUDA device for speed.

Examples

• "Estimate cell fractions for PDAC bulk replicates and generate synthetic scRNA-seq using Bulk2Single."
• "Load a pre-trained Bulk2Single model, regenerate cells, and compare cluster proportions to the dentate gyrus atlas."
• "Plot correlation heatmaps between generated cells and reference clusters after filtering noisy synthetic cells."

References

• Tutorial notebook: [tbulk2single.ipynb](../../omicverseguide/docs/Tutorials-bulk2single/t_bulk2single.ipynb)
• Example data and weights: [omicverseguide/docs/Tutorials-bulk2single/data/](../../omicverseguide/docs/Tutorials-bulk2single/data/)
• Quick copy/paste commands: [reference.md](reference.md)