bulkrna-deconvolution

name	bulkrna-deconvolution
description	Load when estimating cell-type proportions in bulk RNA-seq samples from a single-cell or signature-matrix reference. Skip if the data is already single-cell (no deconvolution needed) or for spatial deconvolution (use spatial-deconv).
version	0.3.0
author	OmicsClaw
license	MIT
tags	["bulkrna","deconvolution","NNLS","cell-type-proportion"]

bulkrna-deconvolution

When to use

Run on a bulk RNA-seq cohort when you have a reference (single-cell profile or signature matrix) and want per-sample cell-type proportions. Built-in NNLS solver is the only backend currently implemented; the wrapper does not call CIBERSORTx or MuSiC.

Inputs & Outputs

Input	Format	Required
Bulk count matrix	.csv (gene × sample)	yes (or --demo)
Reference	--reference CSV (signature matrix) or .h5ad (sc reference)	yes (or --demo)

Output	Path	Notes
Proportions	tables/proportions.csv	sample × cell_type, rows sum to 1
Dominant types	tables/dominant_types.csv	per-sample top cell type
Stacked-bar plot	figures/proportions_stacked.png	per-sample composition
Heatmap	figures/proportions_heatmap.png	sample × cell_type intensity
Report	report.md + result.json	always

Flow

1. Load bulk matrix (bulkrna_deconvolution.py:368 raises ValueError if --input missing without --demo).
2. Load reference (:370 raises ValueError if --reference missing without --demo; :76 raises FileNotFoundError if path doesn't exist).
3. Align gene namespaces between bulk and reference (:131 raises ValueError if no overlap).
4. Run scipy.optimize.nnls per sample to estimate per-cell-type weights, then row-normalise to proportions.
5. Render stacked-bar + heatmap; emit tables/proportions.csv + tables/dominant_types.csv.

Gotchas

• --reference is REQUIRED for non-demo runs. Unlike most bulkrna skills, this one needs two inputs. bulkrna_deconvolution.py:370 raises with "--reference is required when not using --demo" if you forget; no silent fallback.
• Gene-namespace mismatch is fatal. :131 raises ValueError when bulk and reference share zero gene IDs (typical cause: bulk uses Ensembl, reference uses HGNC symbols). Pre-run bulkrna-geneid-mapping to harmonise.
• NNLS is the only backend; there is no --method flag. Despite the skill catalog historically advertising CIBERSORTx and MuSiC bridges, the script (bulkrna_deconvolution.py:347-358 argparser) accepts only --input, --output, --demo, --reference. The summary dict (:163-172) records n_genes_shared, n_samples, n_cell_types, cell_types, proportions_df, dominant_types, mean_proportions, residuals — no method field, because there is no choice.
• Negative residuals are not surfaced as a warning. NNLS by definition produces non-negative weights, but the per-sample reconstruction residuals (saved in result.json["residuals"]) measure how well the linear combination explains the bulk profile. Sanity-check that residuals are small relative to library size; large residuals indicate the reference is missing a major cell type from the bulk.

Key CLI

python omicsclaw.py run bulkrna-deconvolution --demo
python omicsclaw.py run bulkrna-deconvolution \
  --input counts.csv --reference signature.csv --output results/
python omicsclaw.py run bulkrna-deconvolution \
  --input counts.csv --reference scref.h5ad --output results/

See also

• references/parameters.md — every CLI flag and tuning hint
• references/methodology.md — NNLS solver, gene-overlap requirement, residual interpretation
• references/output_contract.md — exact output directory layout
• Adjacent skills: bulkrna-geneid-mapping (run upstream to harmonise gene IDs), bulkrna-trajblend (parallel: per-sample pseudotime placement using the same NNLS proportions plus nearest-neighbour mapping), spatial-deconv (spatial-side sibling: spot-level proportions with multiple methods)