/sc-perturb

name: sc-perturb
description: Load when classifying perturbed vs non-perturbed cells in a Perturb-seq / CRISPR-screen scRNA
  AnnData via the pertpy Mixscape workflow. Skip when guide labels are not yet attached to the expression
  object (use sc-perturb-prep); in-silico KO predictions on unperturbed data (use sc-in-silico-perturbation).
tags:
- singlecell
- scrna
- perturbation
- perturb-seq
- crispr
- mixscape
- pertpy

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.