sc-grn

sc-grn

Use from a step

grn = load_skill("sc-grn")
adata = read_input("expression.h5ad")
edges = grn.infer_adjacencies(adata, tfs=["SPI1", "IRF8", "STAT1"],
                              method="correlation", n_top=50)
regulons = grn.regulons_from_adjacencies(edges)
scores = grn.score_regulons(adata, regulons, method="mean")
write_output(edges, "tables/adjacencies.csv")
write_output(scores, "tables/mean_target_expression.csv")

Functions do not annotate the input automatically. The PBMC example in examples/example_step.py uses caller-supplied TFs and explicitly labeled mean-expression scores.

API

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

infer_adjacencies(adata, *, tfs, method: str='grnboost2', layer: str | None=None, random_state: int=42, n_top: int=50, n_jobs: int=4) -> pd.DataFrame

Return TF, target and importance columns using the caller's TF list.

grnboost2 retains the CLI's fallback to absolute Spearman correlation when its backend fails or returns no edges. Correlation excludes supplied TFs from candidate targets and keeps n_top targets per TF. No motif validation occurs here; a warning and run_info report any fallback.

:param tfs: TF names; only names present in the selected matrix are used. :param method: grnboost2 (default) or correlation. :param layer: Explicit expression layer; None prefers counts, aligned raw, then X. :param random_state: GRNBoost2 seed, default 42. Correlation is deterministic. :param n_top: Correlation targets per TF, default 50. :param n_jobs: GRNBoost2 workers, default 4. :returns: A new DataFrame; input AnnData is not modified. :raises ValueError: The method or budget is invalid, or no TF overlaps.

run_info(adjacencies: pd.DataFrame, *, keep: bool=True) -> dict

Return an independent backend/fallback record; keep=False removes it from attrs.

prune_regulons(adjacencies: pd.DataFrame, *, database_glob: str, motif_annotations: str, n_top: int=50, rank_threshold: int=5000, auc_threshold: float=0.05, nes_threshold: float=3.0, n_jobs: int=4) -> list[dict]

Return motif-pruned regulon dictionaries using the existing cisTarget bridge.

Requires pySCENIC and caller-provided databases and motif annotations. Thresholds retain the CLI defaults: rank 5000, AUC 0.05, NES 3 and 50 targets. Backend and resource errors propagate; no data are downloaded.

regulons_from_adjacencies(adjacencies: pd.DataFrame, *, n_top: int=50) -> list[dict]

Group the strongest edges per TF without motif validation; default 50 targets.

score_regulons(adata, regulons: list[dict], *, method: str='aucell', random_state: int=42, n_jobs: int=4) -> pd.DataFrame

Return per-cell regulon scores without annotating the input.

aucell requires pySCENIC and ranks count-layer/aligned-raw/X expression. mean averages each regulon's targets in X, matching the old simplified CLI. It is not AUCell, an enrichment statistic, or motif validation.

:param method: aucell (default) or mean; no automatic scoring fallback. :param random_state: AUCell seed, default 42; mean is deterministic. :param n_jobs: AUCell workers, default 4. :returns: DataFrame indexed by cell; attrs names the scoring_method and is_aucell. :raises ValueError: The scoring method is unknown. :raises ImportError: AUCell's optional backend is unavailable.

regulon_heatmap_figure(scores: pd.DataFrame, *, groups: pd.Series | None=None)

Return a score heatmap, optionally averaged over aligned cell groups.

<!-- api:end -->

Methods and parameters

infer_adjacencies defaults to GRNBoost2, with random_state=42 and n_jobs=4. Its legacy fallback is absolute Spearman correlation, retaining n_top=50 targets per TF. run_info(edges) records the actual method and fallback reason, also emitted as a warning. method="correlation" runs directly without arboreto.

The simplified path now respects the caller's TF list. Correlation gives co-expression candidates, not validated regulatory edges. regulons_from_adjacencies only groups these candidates; prune_regulons needs pySCENIC, caller-provided cisTarget databases and motif annotations. It retains rank threshold 5000, AUC threshold 0.05 and NES threshold 3; it does not download resources.

score_regulons(method="aucell") requires pySCENIC and uses seed 42. method="mean" averages target expression in X, matching the old simplified CLI. Mean expression is not AUCell and has no enrichment p-value.

Gotchas

• Inference selects an explicit layer, else counts, aligned raw, then X. Mean scoring uses X; verify its normalization separately (_api.py:15, _api.py:98).
• run_info is stored in DataFrame attrs; CSV does not preserve attrs. Save the diagnostics separately when exporting edges (_api.py:61).
• GRNBoost2/backend failure can trigger correlation; inspect the record. The full pySCENIC path also needs external resources and was not validated merely by running the correlation example (_api.py:68).
• The CLI preserves legacy grn_auc_matrix.csv and regulon_<TF> names for compatibility even for mean scores. Check result.json["data"]["scoring_method"].
• Correlation targets exclude the TFs supplied in the same call. No TF overlap raises an error in the API (_api.py:15).

Inputs & Outputs

The API returns adjacency tables, regulon dictionaries, score tables and Figures. The CLI writes processed.h5ad, tables/grn_adjacencies.csv, tables/grn_regulons.csv, tables/grn_regulon_targets.csv, tables/grn_auc_matrix.csv, report.md and result.json. Plots and their figure-data manifests depend on available scores.

Key CLI

python skills/singlecell/scrna/sc-grn/sc_grn.py --demo --output /tmp/sc_grn_demo
python skills/singlecell/scrna/sc-grn/sc_grn.py --input expression.h5ad --tf-list tfs.txt --allow-simplified-grn --output results/
python skills/singlecell/scrna/sc-grn/sc_grn.py --input expression.h5ad --tf-list tfs.txt --db '/refs/*.feather' --motif motifs.tbl --output results/

Dependencies

anndata, arboreto, dask, matplotlib, networkx, numpy, pandas, pyscenic, scanpy, scikit-learn, scipy, seaborn