Bulkrna Trajblend

bulkrna-trajblend

When to use

Place bulk samples on an observed single-cell pseudotime axis and estimate cell-type fractions. Use bulkrna-deconvolution for fractions without placement and sc-pseudotime to infer a trajectory on the reference first.

Use from a step

from skills._sdk.notebook import load_skill, write_output
library = load_skill('bulkrna-trajblend')
data, reference, labels, pseudotime = library.demo_data(random_state=42)
result = library.map_trajectory(data, reference=reference, labels=labels, pseudotime=pseudotime)
write_output(result, 'tables/pseudotime_estimates.csv')

For real files, pass read_fastq, read_log or read_reference as appropriate to read_input(..., reader=...). examples/example_step.py is executable.

API

<!-- api:begin generated from _api.py; regenerate with run.py api <skill dir> --write -->

read_reference(path: str | Path, *, cell_type_key: str='cell_type', pseudotime_key: str='pseudotime') -> tuple

Read a reference with annotations; pass this function as reader= to read_input.

:param path: H5AD with expression in X, or cell-by-gene CSV/TSV with annotation columns. :param cell_type_key: CLI default cell_type; change for a named annotation column. :param pseudotime_key: CLI default pseudotime; supply an observed reference trajectory value. :returns: Cell-by-gene DataFrame, indexed cell-type Series and indexed pseudotime Series. :raises ValueError: Required annotations are missing. :raises ImportError: H5AD reading needs anndata; install it with install_skill_deps.

map_trajectory(bulk: pd.DataFrame, *, reference: pd.DataFrame, labels: pd.Series, pseudotime: pd.Series, k: int=15, random_state: int=42) -> pd.DataFrame

Return bulk pseudotime estimates from NNLS and joint PCA/kNN placement.

:param bulk: Sample-by-gene nonnegative expression on a scale comparable with the reference. :param reference: Cell-by-gene expression with at least fifty shared genes. :param labels: Cell-type labels indexed by reference cell identifiers. :param pseudotime: Observed reference pseudotime indexed by cell identifiers; never synthesized. :param k: CLI default 15 nearest reference cells; reduce for a smaller reference. :param random_state: CLI seed 42 forwarded to PCA; change to assess randomized-solver sensitivity. :returns: New sample-indexed pseudotime table; fractions and embeddings remain in attrs. :raises ValueError: Matrices, annotations, gene overlap or neighbor count are invalid. :raises ImportError: Missing scipy/scikit-learn; use install_skill_deps.

fractions(result: pd.DataFrame) -> pd.DataFrame

Return the estimated cell-type fractions.

:param result: Output of map_trajectory retaining attrs. :returns: A separate sample-by-cell-type DataFrame. :raises KeyError: Fraction diagnostics are absent.

run_info(result: pd.DataFrame, *, keep: bool=True) -> dict

Read placement diagnostics and plot data.

:param result: Output of map_trajectory. :param keep: True preserves attrs; False removes diagnostics before serialization. :returns: Separate method, seed, fractions, embedding and annotation values. :raises TypeError: The result is not a DataFrame.

trajectory_figure(result: pd.DataFrame)

Plot bulk and reference PCA coordinates colored by reference pseudotime.

:param result: Placement result retaining its diagnostic attrs. :returns: A matplotlib Figure without writing files. :raises KeyError: Embedding diagnostics are absent.