AGENT SKILL

filter-escapers-with-mixscape

Label and remove escaping cells in a pooled CRISPR screen with single-cell readout (Perturb-seq, CROP-seq) with Mixscape from pertpy, from a log-normalized AnnData with a guide or perturbation column and a non-targeting control to adata_mixscape.h5ad without the non-perturbed (NP) cells, plus the NP fraction of every perturbation. Use before per-perturbation differential expression when guide-assigned cells may have escaped knockout or knockdown and dilute the comparison, or when asked which cells of a screen were actually perturbed. Optional step with a heavy dependency; without pertpy the script exits cleanly and the DE runs on all guide-assigned cells.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 0
Forks
2

01 前言 Front Matter

name
filter-escapers-with-mixscape
license
MIT
metadata
{ "tags": "crispr, perturb-seq, crop-seq, scrna-seq, mixscape, pertpy, escaping-cells", "author": "Yijun Sun", "status": "community", "aliases": "mixscape_escape_filter", "compute": "1 CPU, 0.85 GB peak RAM, about 12 s for 240 cells x 47 genes (mostly pertpy import and JIT compilation)", "version": "1.0.0", "category": "crispr-screens", "scheduler": "none", "tested-with": "pertpy 1.4.0, scanpy 1.12.1, anndata 0.12.16, pandas 2.3.3, numpy 2.4.6, scipy 1.17.1, scikit-learn 1.9.1, pynndescent 0.6.0, numba 0.68.0, Python 3.13.9", "requires-gpu": "false", "requires-network": "install", "requires-secrets": "none" }
description
Label and remove escaping cells in a pooled CRISPR screen with single-cell readout (Perturb-seq, CROP-seq) with Mixscape from pertpy, from a log-normalized AnnData with a guide or perturbation column and a non-targeting control to adata_mixscape.h5ad without the non-perturbed (NP) cells, plus the NP fraction of every perturbation. Use before per-perturbation differential expression when guide-assigned cells may have escaped knockout or knockdown and dilute the comparison, or when asked which cells of a screen were actually perturbed. Optional step with a heavy dependency; without pertpy the script exits cleanly and the DE runs on all guide-assigned cells.
compatibility
Python 3.12+ with scanpy, anndata and pertpy 1.4 (pip). No GPU, no scheduler. Without pertpy the script skips and exits 0.

02 资源文件 2

03 SKILL.md 正文

Remove escaping cells with Mixscape

In a real screen a fraction of the guide-assigned cells escape knockout or knockdown and look transcriptionally like control. Keeping them dilutes every downstream comparison. scripts/reference.py runs Mixscape (Papalexi et al., Nat. Genetics 2021, as implemented in pertpy): it computes a local perturbation signature for every cell and classifies each cell as perturbed (KO), non-perturbed (NP, escaped) or control, then writes the AnnData without the NP cells for the per-perturbation DE (compare-perturbations-to-control).

This step is optional. pertpy is a heavy dependency and its Mixscape API drifts between versions. If pertpy cannot be imported, the script prints a SKIPPED note and exits 0; the DE then runs on all guide-assigned cells, a conservative, effect-diluting choice that the report must state.

The most likely mistake is reading an NP fraction of 1.0 as "every cell escaped". Mixscape first looks for genes that differ between the perturbation and the control; with fewer than 5 such genes it labels the whole perturbation NP. A silent guide therefore loses all its cells here (the tests show it). That is "no detectable signature", the same result the E-distance ranking calls silent, and it means the filtered file holds no cells of that perturbation.

Tested on synthetic data only (tests/: 240 cells, 47 genes, a non-targeting control of 100 cells; a knockout of 80 cells of which 40 lost the target and switched on a 5-gene program and 40 escaped; and a silent guide of 60 cells) with pertpy 1.4.0, scanpy 1.12.1, anndata 0.12.16, pandas 2.3.3, numpy 2.4.6, scipy 1.17.1, scikit-learn 1.9.1 and Python 3.13.9. Mixscape kept exactly the 40 knocked-out cells (NP fraction 0.5), removed all 60 cells of the silent guide and kept every control cell. The skip path is tested with pertpy made unimportable. No real-screen run is recorded here.

1. Environment setup

mamba create -y -n pertpy_1.4 -c conda-forge python=3.13 pip
source "$(conda info --base)/etc/profile.d/conda.sh"
conda activate pertpy_1.4
pip install scanpy==1.12.1 anndata==0.12.16 pandas==2.3.3 numpy==2.4.6 scipy==1.17.1 pertpy==1.4.0
python -c "import pertpy; print(pertpy.__version__)"

The pip install line is the one tested, in a plain Python 3.13.9 venv. The first import pertpy takes tens of seconds while it compiles; later imports take a few seconds.

The call to ms.mixscape passes the label column and the control by position because pertpy 1.0 and earlier name the label argument labels and pertpy 1.4 names it pert_key. If your pertpy rejects the call, read help(pt.tl.Mixscape.mixscape) and adapt that one line.

2. Prepare inputs

  • An AnnData file with log-normalized expression in X (the signature averages control neighbours with expm1 and returns to log1p) and a guide or perturbation label per cell in an obs column, including the non-targeting control. The script reads adata_qc.h5ad from $AISCIENTIST_WORK, else the file named by $AISCIENTIST_DATASET.
  • The output goes to $AISCIENTIST_WORK as well; this script writes no tables.

Mixscape classifies within each level of the perturbation column, so give it the same level (guide or target gene) that the DE will use. Identify the column and the control level from the data as for the DE step, and keep the control cells through QC.

3. Configure

Variable Meaning Default
PERT_KEY the obs column naming the guide or perturbation perturbation
CONTROL the shared non-targeting level of PERT_KEY NT

The Mixscape calls use pertpy's defaults. In pertpy 1.4.0 those are: the signature of a cell is its difference from the mean of its 20 nearest control cells, searched in the first 15 PCs (pertpy computes a PCA if X_pca is missing); a perturbation needs at least 5 genes with adjusted p < 0.05 and |log fold change| ≥ 0.25 against control; and a cell with posterior above 0.5 in the perturbed component is KO. To change them, add keyword arguments to the two calls: perturbation_type="KD" labels CRISPRi cells KD instead of KO (the filter keeps both), and split_by="<column>" runs the steps within each replicate or lane (pertpy's own example uses split_by="replicate"). Record any change in the report.

4. Run

export AISCIENTIST_WORK=/path/to/work
# or, with no adata_qc.h5ad in the work directory:
export AISCIENTIST_DATASET=/path/to/screen.h5ad
python scripts/reference.py

In AiScientist: read the file with read_skill_reference, set the values for this dataset, and run it with run_code, which sets the variables.

5. Validate before using the output

The JSON summary on stdout, and $AISCIENTIST_WORK/adata_mixscape.h5ad holding the kept cells with obs["mixscape_class"], obs["mixscape_class_global"] (KO, NP or the control label), obs["mixscape_class_p_ko"] and the signature in layers["X_pert"].

  1. mixscape: OK, or SKIPPED with the reason. After a skip, the DE runs on all guide-assigned cells: say so.
  2. The control: every control cell is kept; class_counts shows them under the control label.
  3. np_fraction_by_perturbation: between 0 and 1 for a perturbation with a signature; a high fraction means many escapers, or a weak guide. Exactly 1.0 means no signature (above); cross-check with the E-distance ranking.
  4. n_cells_before and n_cells_after_removing_NP: every perturbation you will test still has enough cells for the DE (MIN_CELLS, default 30).
  5. Point the DE at the filtered file: in compare-perturbations-to-control, change the checkpoint line to read adata_mixscape.h5ad.

Report

Whether Mixscape ran (with the pertpy version) or was skipped and why; the perturbation column, the control level and the level (guide or target); any argument changed from pertpy's defaults; the NP fraction of every perturbation, with the perturbations labelled NP as a whole named as having no detectable signature; and the cells before and after. If it was skipped, state that the DE used all guide-assigned cells and that effects may be diluted.

04 同仓库更多 Skills

lijinbio
lijinbio/aiscientist-skills

verb-object-with-tool

One or two sentences on what the skill does and when to use it. Name the tool, the input it takes and the output it produces, then list the situations that should trigger it (for example "Use when setting up X, writing a Y config, or diagnosing a failed Z run").

★ 0
lijinbio
lijinbio/aiscientist-skills

write-variant-tables

Write the five standard variant-annotation result tables - consequence, impact and ClinVar-significance distributions, a ClinVar pathogenic and likely-pathogenic list, and a shortlist of rare, damaging variants not in ClinVar - plus a JSON summary, from an annotated per-variant TSV (VEP consequence and impact, SIFT, PolyPhen, max population AF, rsID, ClinVar significance), in pure Python without re-parsing the VCF or re-running VEP. Use when a study needs these tables with a different rarity cutoff, impact set or damaging-predictor rule, or when rebuilding them from an existing annotation table. In AiScientist, annotate_variants already writes the default tables, so use this only for a custom cut.

★ 0
lijinbio
lijinbio/aiscientist-skills

rank-phenotype-differentials-with-mcp

Map clinical phenotype text to grounded HPO terms and rank a research differential through an already configured phenotype-diagnosis MCP service with LIRICAL and optional literature adjudication. Use for explicit service-based analysis while preserving negation, uncertainty and original probabilities; retain the established workflow when the service is unavailable.

★ 0
lijinbio
lijinbio/aiscientist-skills

qc-vcf-callset

Judge whether a germline VCF callset is trustworthy before interpreting any variant - Ti/Tv, Het/Hom, SNP, indel and multiallelic counts, sample count and genotype call rate from bcftools stats (falling back to cyvcf2, then to a plain-Python Ti/Tv scan) - and flag values outside the expected human WGS or WES ranges. Writes tables/vcf_qc_summary.csv and data/vcf_qc.json with a qc_flags list. Use when a VCF (one sample or a cohort) arrives for annotation or prioritization, when a Ti/Tv or Het/Hom value needs interpreting, or when deciding whether downstream variant tables must carry a low-confidence caveat.

★ 0
lijinbio
lijinbio/aiscientist-skills

prioritize-clinical-variants

Rank annotated variants into research-triage tiers (ClinVar pathogenic, likely pathogenic, VUS favouring pathogenic, VUS, likely benign, benign) from ClinVar significance used verbatim, gnomAD allele frequency against a dominant or recessive disease-model cutoff and the ACMG BA1 5 percent rule, and in-silico predictors (SIFT, PolyPhen, REVEL, CADD, AlphaMissense) as supporting evidence only. Pure Python; reads a per-variant annotation TSV and writes a tier-sorted CSV with the evidence for each tier plus a JSON of tier counts. Use when a rare-variant list from VEP, ClinVar and gnomAD annotation must be ordered for review (which variants to look at first) or when choosing the disease model and cutoffs for that ordering. Research triage only, NOT a clinical ACMG/AMP classification.

★ 0
lijinbio
lijinbio/aiscientist-skills

normalize-vcf-with-bcftools

Normalize a VCF with bcftools norm before annotation or ClinVar/gnomAD matching - split multiallelic sites into biallelic records, atomize MNPs into SNPs, then left-align and trim indels against the reference FASTA of the same build - writing an indexed normalized.vcf.gz and a JSON of record counts before and after. Use when a VCF not known to be normalized (especially an indel-heavy one) will be matched against ClinVar, gnomAD or dbSNP, compared between callers or loaded into PLINK, or when a known pathogenic indel comes back as not in ClinVar. In AiScientist, the offline annotate_variants path already normalizes, so do not plan it as a separate step there.

★ 0