/sc-perturb-prep

name: sc-perturb-prep
description: Load when attaching cell-barcode → sgRNA assignments from a mapping TSV/CSV onto a Perturb-seq
  expression AnnData, producing standardised perturbation / sgRNA / target-gene obs columns. Skip when
  the AnnData already has perturbation labels (use sc-perturb); raw guide-calling from FASTQ (use upstream
  demuxlet / cellranger guide pipelines).
tags:
- singlecell
- scrna
- perturb-prep
- perturb-seq
- crispr
- sgrna-assignment

sc-perturb-prep

Attach an upstream barcode-to-guide table to expression data. This is the `mapping_tsv` method, not a FASTQ guide caller. It needs no pertpy installation.

Key CLI

python skills/singlecell/scrna/sc-perturb-prep/sc_perturb_prep.py --demo --output /tmp/sc_perturb_prep_demo
python skills/singlecell/scrna/sc-perturb-prep/sc_perturb_prep.py --input expression.h5ad --mapping-file mapping.tsv --output results/prep

Mapping columns are inferred from common names, or selected with `--barcode-column`, `--sgrna-column`, and `--target-column`. Without target values, `--delimiter _ --gene-position 0` extracts the target from a guide ID. Pass `--keep-multi-guide` only when retaining multi-guide cells is intended.

Workflow

Upstream: expression counts and guide calls from the same cells. Standardize mapping columns, collapse guides per barcode, match assigned cells, retain gene-expression features and canonicalize the matrix. Downstream: use `sc-perturb` for observed perturbation signatures, or `sc-preprocessing` for clustering. The API returns objects; the example step writes them explicitly.

Matrix Contract

Raw counts are preferred; canonicalization can recover counts from a layer or raw snapshot. Inspect `omicsclaw_matrix_contract` and `run_info` for the actual expression source. A normalized matrix is not evidence of raw counts.

Inputs & Outputs

Input: `.h5ad`, 10x H5 or a matrix directory, plus mapping TSV/CSV for real runs. The CLI writes `processed.h5ad`, `report.md`, `result.json`, `reproducibility/commands.sh`, `tables/perturbation_assignments.csv`, `tables/assignment_status_counts.csv`, `tables/perturbation_counts.csv`, `tables/feature_type_summary.csv` and `figures/perturbation_counts.png`. `tables/dropped_multi_guide_cells.csv` is written only when rows were dropped. Plot data are also written under `figure_data/`.

Gotchas

• `tables/perturbation_assignments.csv` uses status `assigned`, `control` or retained `multi_guide`; dropped rows do not appear in the output AnnData.
• Control tokens match whole words separated by punctuation: `NT_sg1` is a control, while `WNT3_sg1`, `NTRK1_sg1` and `NT5E_sg1` are not. Review `tables/perturbation_assignments.csv` after choosing custom patterns.
• `result.json` → `summary.n_cells_multi_guide_dropped` counts dropped multi-guide cells. No matching barcodes raises `ValueError` in the API.
• `tables/feature_type_summary.csv` describes the input feature types. Filtering needs `var['feature_types']`; absent labels cannot identify guide or antibody features.

API

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

`standardize_mapping(table, *, barcode_column=None, sgrna_column=None, target_column=None)`

Return barcode, sgRNA and target_gene columns from a pandas table.

Column names may be supplied explicitly. Missing target genes are inferred later from guide names; duplicate rows and empty barcode/guide rows are removed.

`collapse_assignments(mapping, *, delimiter='_', gene_position=0, control_patterns=('NT', 'NTC', 'NON-TARGET', 'NON_TARGET', 'NEGATIVE_CONTROL', 'NEG_CTRL'), control_label='NT', drop_multi_guide=True)`

Return (assigned, dropped) tables with one row per barcode.

Controls match whole tokens, not substrings of gene names. Multiple guides are dropped by default; retained multi-guide cells keep their status.

`attach_assignments(adata, assignments, *, pert_key='perturbation', sgrna_key='sgRNA', target_key='target_gene', species='human')`

Return a gene-expression AnnData with assignments on matching cells.

The input is unchanged. Gene features and the expression matrix are canonicalized using the single-cell input contract; no pertpy is needed.

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

Return preparation provenance; keep=False removes the run record.

`assignment_summary(adata)`

Return assignment_status and n_cells columns for the retained cells.

`perturbation_counts(adata, *, pert_key='perturbation')`

Return perturbation and n_cells columns, ordered by decreasing cell count.

`perturbation_counts_figure(adata, *, pert_key='perturbation', n_top=20)`

Return a Figure of cell counts for up to n_top perturbations; save it separately.

<!-- api:end -->

Dependencies

`anndata`, `matplotlib`, `numpy`, `pandas`, `scanpy`, `scipy`