sc-perturb

sc-perturb

Classify observed Perturb-seq cells with pertpy Mixscape. Guide labels and a non-targeting control group must already exist; otherwise use sc-perturb-prep. This is not an in-silico knockout predictor.

Key CLI

python skills/singlecell/scrna/sc-perturb/sc_perturb.py --demo --seed 0 --output /tmp/sc_perturb_demo
python skills/singlecell/scrna/sc-perturb/sc_perturb.py --input prepared.h5ad --pert-key perturbation --control NT --split-by replicate --seed 0 --output results/perturb

mixscape (--method mixscape) is the only method. Tune --n-neighbors, --logfc-threshold, --pval-cutoff and --perturbation-type KO|OE explicitly.

Workflow

Upstream: sc-perturb-prep, or an AnnData with verified screen labels. Validate labels, supply/compute PCA, build perturbation signatures, then classify cells. Both pertpy stages receive --seed (API random_state, default 0). Downstream: sc-de or sc-enrichment after reviewing target-level calls.

Matrix Contract

Uses normalized expression. Count-like X is saved in layers['counts'] and log-normalized. Existing X_pca is reused; otherwise PCA is computed before the legacy normalization step. Prefer an upstream PCA on appropriate normalized features for real screens. The API leaves its input unchanged.

Inputs & Outputs

Input: .h5ad with a perturbation column, control label and optional split key. The CLI writes processed.h5ad, report.md, result.json, reproducibility/commands.sh, tables/mixscape_cell_classes.csv, tables/mixscape_class_counts.csv, tables/mixscape_global_class_counts.csv and figures/mixscape_global_classes.png. Plot data and their manifest are in figure_data/; R-enhanced figures are optional.

Gotchas

• result.json → data.params.split_by records the CLI's resolved split key. A missing CLI split column warns and disables splitting; the API instead raises unless you pass split_by=None.
• tables/mixscape_global_class_counts.csv must contain biological signal before you interpret a run. Exit 0 alone does not establish an effect; the example asserts KO detection in both known-effect groups.
• tables/mixscape_cell_classes.csv preserves target-specific and global classes plus mixscape_class_p_ko (or _oe). Posterior probabilities are not experimental validation.
• For pertpy 1.0.3, split-based signatures use controls within each split rather than nearest-neighbour selection. n_neighbors affects the split_by=None path.

API

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

mixscape(adata, *, pert_key='perturbation', control='NT', split_by='replicate', n_neighbors=20, logfc_threshold=0.25, pval_cutoff=0.05, perturbation_type='KO', random_state=0)

Return an AnnData copy with Mixscape classes and posterior probabilities.

Uses normalized expression, preserving count-like X in layers['counts'] before log-normalization. split_by=None selects nearest-neighbour controls. Both pertpy stages receive random_state; a missing control or split column raises ValueError. Requires pertpy (validated with 1.0.3 and sklearn 1.7.2).

run_info(adata, *, keep: bool=True)

Return method, seed and output columns; keep=False removes the run record.

class_counts(adata)

Return class and n_cells columns for target-specific Mixscape labels.

global_class_counts(adata)

Return global_class and n_cells columns for control, KO/OE and NP cells.

global_class_figure(adata)

Return a Figure of global Mixscape cell counts without saving files.

<!-- api:end -->

Dependencies

anndata, matplotlib, numpy, pandas, pertpy, scanpy, scipy, scikit-learn, filelock

The Python 3.11 CPU example is verified with pertpy==1.0.3, scikit-learn==1.7.2, anndata==0.11.4, statsmodels==0.14.6 and filelock==4.0.12. statsmodels 0.15 removed a private import used by this pertpy release. It also needs filelock at import time but omits it from dependency metadata. Its dependencies include JAX; use the separate extended environment. blitzgsea may need pip's isolated source build, which the production wheels-only installer does not perform.