bulkrna-trajblend

bulkrna-trajblend

When to use

Run when you have a bulk RNA-seq cohort and a single-cell reference with pre-computed pseudotime, and you want each bulk sample placed on that pseudotime axis. The current implementation is a sklearn-based NNLS-plus-nearest-neighbour pipeline (PCA → kNN against ref); it does not use VAE / GNN despite the skill name's connotation.

Inputs & Outputs

Inputs

• File types: .csv, .tsv, .h5ad

Outputs

• tables/cell_fractions.csv
• tables/pseudotime_estimates.csv
• figures/bulk_on_trajectory.png
• figures/fraction_heatmap.png
• figures/pseudotime_distribution.png
• figures/trajectory_embedding.png
• report.md
• result.json

Flow

1. Load bulk counts + sc reference.
2. Find common genes between bulk and reference (bulkrna_trajblend.py:117 raises ValueError if < 50 genes overlap).
3. Run NNLS deconvolution to estimate per-sample cell-type fractions.
4. Project bulk samples into the reference's PCA space; use sklearn.neighbors.NearestNeighbors to find each bulk sample's k nearest reference cells.
5. Estimate per-sample pseudotime as mean (and std) of the neighbour set's reference pseudotime values.
6. Render trajectory figures; emit fractions + pseudotime tables.

Gotchas

• Gene-namespace mismatch hard-fails at 50. bulkrna_trajblend.py:117 raises if fewer than 50 gene IDs overlap between bulk and reference. Most common cause: bulk uses Ensembl IDs while sc reference uses HGNC symbols. Pre-run bulkrna-geneid-mapping to harmonise.
• --n-epochs is currently a no-op. The argparse help text at :354 reads "VAE epochs (unused in fallback)" — there is no VAE / GNN code path in this version (the script imports only sklearn, numpy, pandas). The flag is preserved as a forward-compat hook; passing any value has no effect on output. Do not report results as "VAE+GNN-derived" until that code lands.
• Pseudotime placement is a kNN average, not a likelihood-based fit. Each bulk sample's pseudotime is the mean of its k nearest reference cells' pseudotimes — it doesn't carry uncertainty in the way a probabilistic model would. Use pseudotime_std and mean_neighbor_dist (per bulkrna_trajblend.py:184-188) as crude confidence proxies; large neighbour distances mean the bulk sample doesn't cleanly resemble any reference cell.
• Reference pseudotime values must be supplied externally. This skill consumes pseudotime; it does not compute it. Run sc-pseudotime on the reference first (or use a published pre-pseudotimed reference) so the input AnnData has the relevant obs column.