/sc-in-silico-perturbation

name: sc-in-silico-perturbation
description: Load when predicting in-silico gene knockout effects on a normalised scRNA AnnData via GRN-based
  propagation (Python) or scTenifoldKnk (R). Skip when you have a real Perturb-seq / CRISPR screen (use
  sc-perturb); predicting drug sensitivity (use sc-drug-response).
tags:
- singlecell
- scrna
- in-silico-perturbation
- knockout
- grn
- sctenifoldknk

sc-in-silico-perturbation

Explore descriptive gene associations or run the optional scTenifoldKnk R method. The default `grn_ko` name is retained for CLI compatibility; its Pearson edge-removal score is not a causal knockout simulation or a significance test.

Method Selection Table

| Method | What it returns | Requirement | |---|---|---| | `grn_ko` | Absolute correlation edge-removal scores; no p-values | Python science stack | | `sctenifoldknk` | R scTenifoldKnk differential-regulation table | Rscript + scTenifoldKnk |

Key CLI

python skills/singlecell/scrna/sc-in-silico-perturbation/sc_in_silico_perturbation.py --demo --output /tmp/sc_iko_demo
python skills/singlecell/scrna/sc-in-silico-perturbation/sc_in_silico_perturbation.py --input expression.h5ad --ko-gene TP53 --n-top-genes 2000 --output results/associations
python skills/singlecell/scrna/sc-in-silico-perturbation/sc_in_silico_perturbation.py --input expression.h5ad --method sctenifoldknk --ko-gene TP53 --seed 0 --n-cores 1 --output results/tenifold

`--corr-threshold` is an inactive legacy argument; it never thresholded the correlation matrix. The API intentionally does not expose it.

Workflow

Preflight checks the target gene. `grn_ko` selects high-variance genes plus the target, computes Pearson correlations, zeros the target row/column and averages absolute changes by gene. The target's own score summarizes all its removed edges; other genes lose one edge. R uses the existing temporary CSV bridge and sets `set.seed` before fitting. No backend is silently substituted.

Matrix Contract

Reads raw_counts from `layers['counts']` when present, otherwise X. Inputs are unchanged by the API; returned table metadata records the chosen source. CLI `processed.h5ad` carries `omicsclaw_input_contract` and `omicsclaw_matrix_contract`. Use `sc-perturb` for an actual perturbation screen.

Inputs & Outputs

Input: expression `.h5ad` with `--ko-gene` in `var_names`. The CLI writes `processed.h5ad`, `tables/diff_regulation.csv`, `report.md`, `result.json`, `figures/top_perturbed_genes.png`, and figure/plot-data manifests. The default table has `gene`, `dr_score`, `wt_ko_corr`; only `perturbation_dr_score` is added to `var`. R additionally writes `tables/tenifold_diff_regulation.csv` and may produce a p-value histogram and statistical `var` columns. R-enhanced volcano plots require R statistical output; they are not made for correlation scores.

Gotchas

• `tables/diff_regulation.csv` no longer contains fabricated `p_value`, `p.adj`, `z_score` or an `FC` alias for the default method. Scores are sorted descending; they do not measure treatment effects.
• `result.json` → `summary.n_significant` exists only for R results with adjusted p-values. No significant-gene count is inferred from correlation scores.
• `--ko-gene G10` is a synthetic-demo default; the API raises when the chosen gene is absent.
• `tables/tenifold_diff_regulation.csv` is produced only if scTenifoldKnk succeeds. The R package is not installed by this skill.

API

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

`knockout_correlation(adata, *, ko_gene, n_top_genes=2000)`

Return descriptive edge-removal scores, not a causal knockout simulation.

Select the most variable genes plus ko_gene, compute Pearson correlations from layers['counts'] (or X), and average absolute changes after zeroing the target row and column. Returns gene, dr_score and wt_ko_corr, with no p-values. The target's own score includes all its removed edges and is not comparable to another gene's single removed edge. The input AnnData is unchanged.

`sctenifoldknk(adata, *, ko_gene, qc=False, qc_min_lib_size=0, qc_min_cells=10, n_net=2, n_cells=100, n_comp=3, q=0.8, td_k=2, ma_dim=2, n_cores=1, random_state=0)`

Return scTenifoldKnk diffRegulation through a temporary CSV bridge.

Uses layers['counts'] or X without changing the input. Requires Rscript and the scTenifoldKnk R package; missing packages and R failures propagate. random_state is passed to R set.seed before fitting the network.

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

Return method and interpretation; keep=False removes the table's run record.

`top_perturbed_genes(table, *, n_top=15)`

Return top correlation scores, or lowest adjusted p-values for scTenifoldKnk.

`perturbed_genes_figure(table, *, n_top=15)`

Return a Figure of descriptive edge scores or R differential-regulation FC.

<!-- api:end -->

Dependencies

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

The R method additionally requires the scTenifoldKnk R package.