Single-Cell GRN

Why This Exists

• Without it: regulon analysis requires several external resources and multi-step orchestration.
• With it: pySCENIC-style GRN outputs are standardized into one wrapper contract.
• Why OmicsClaw: tables, figures, and AnnData outputs are bundled together.

Core Capabilities

1. Implementation-aligned pySCENIC workflow: adjacency inference, motif pruning, and regulon scoring.
2. Explicit external-resource contract: TF list, cisTarget databases, and motif annotations are surfaced as real prerequisites.
3. Regulon-centric outputs: adjacency, regulon, target, and AUCell tables.
4. Direct figure exports: regulon activity UMAP, regulon heatmap, and network plot.
5. Downstream-ready export: writes adata_with_grn.h5ad, report, result JSON, README, and notebook artifacts.

Scope Boundary

This skill currently exposes one public workflow: pyscenic_workflow.

That workflow covers:

1. GRNBoost2 adjacency inference
2. motif-based pruning
3. AUCell regulon scoring

Input Formats

Format	Extension / form	Current wrapper support	Notes
AnnData	.h5ad	preferred	most realistic path for preprocessed scRNA-seq
Shared-loader formats	.h5, .loom, .csv, .tsv, 10x directory	technically loadable	usually still need preprocessing and external GRN resources
Demo	--demo	yes	bundled lightweight fallback

Input Expectations

• The current skill expects a preprocessed scRNA-seq object.
• Required external resources: TF list, cisTarget database files, and motif annotations.
• The wrapper does not automatically fetch pySCENIC resources for the user.

Workflow

1. Load preprocessed expression data.
2. Run adjacency inference.
3. Prune candidate targets with motif evidence.
4. Score regulon activity per cell.
5. Export adata_with_grn.h5ad, tables, figures, report.md, and result.json.

CLI Reference

python omicsclaw.py run sc-grn \
  --input <processed.h5ad> \
  --tf-list <tfs.txt> \
  --db '<db_glob>' \
  --motif <motif.tbl> \
  --output <dir>

Public Parameters

Parameter	Role	Notes
--tf-list	transcription-factor list	core prerequisite for adjacency inference
--db	cisTarget database selector	usually a glob or database path
--motif	motif annotation table	required for pruning
--n-top-targets	wrapper-level export cap	limits exported targets per regulon
--n-jobs	parallelism control	runtime knob for pySCENIC steps
--seed	reproducibility control	affects stochastic components

Algorithm / Methodology

Current OmicsClaw pyscenic_workflow runs:

1. GRNBoost2 adjacency inference from expression data
2. motif-based pruning using the supplied cisTarget and motif resources
3. AUCell regulon scoring per cell
4. export of regulon activity and target summaries back into the output AnnData

Important implementation notes:

• n_top_targets is a wrapper-level export control, not a full pySCENIC science knob.
• Resource availability matters more than fine parameter tuning for first-pass success.

Output Contract

Successful runs write:

• adata_with_grn.h5ad
• report.md
• result.json
• tables/grn_adjacencies.csv
• tables/grn_regulons.csv
• tables/grn_regulon_targets.csv
• tables/grn_auc_matrix.csv
• figures/

Visualization Contract

The current wrapper writes direct figure outputs rather than a recipe-driven gallery:

• figures/regulon_activity_umap.png
• figures/regulon_heatmap.png
• figures/regulon_network.png

What Users Should Inspect First

1. report.md
2. tables/grn_regulons.csv
3. figures/regulon_activity_umap.png
4. tables/grn_auc_matrix.csv
5. adata_with_grn.h5ad

Current Limitations

• This skill depends on external pySCENIC resources and does not download them automatically.
• This skill writes README.md and notebook-style reproducibility artifacts when notebook export dependencies are available.

Safety And Guardrails

• Verify the TF list, cisTarget databases, and motif annotations before promising a full run.
• Do not present n_top_targets as a full pySCENIC science parameter; it is a wrapper-level export control.
• For short execution guardrails, see knowledge_base/knowhows/KH-sc-grn-guardrails.md.
• For longer method and interpretation guidance, see knowledge_base/skill-guides/singlecell/sc-grn.md.

CLI Parameters

Flag	Type	Default	Description	Validation
--input	str	None	Input AnnData file (.h5ad)	Required unless --demo
--output	str	—	Output directory	Required
--demo	flag	off	Run with built-in demo data (GRNBoost2 only)	—
--tf-list	str	None	TF list file (one TF gene symbol per line)	Optional; required for full pySCENIC run
--db	str	None	cisTarget database glob pattern	Optional; required for motif pruning
--motif	str	None	Motif annotations file (.tbl)	Optional; required for motif pruning
--n-top-targets	int	50	Maximum targets exported per regulon	Wrapper-level cap, not a pySCENIC science knob
--n-jobs	int	4	Number of parallel jobs for pySCENIC steps	—
--seed	int	42	Random seed for reproducibility	—
--cluster-key	str	leiden	adata.obs column for cell grouping in figures	—
--allow-simplified-grn	flag	off	Accept correlation-based GRN fallback when no TF/database/motif files are provided	Enables demo_mode logic without --demo
--r-enhanced	flag	off	Generate R Enhanced plots (requires R + ggplot2)	—

R Enhanced Plots

Renderer	Output file	Description
plot_embedding_discrete	figures/r_enhanced/r_embedding_discrete.png	UMAP colored by discrete cluster labels
plot_embedding_feature	figures/r_enhanced/r_embedding_feature.png	UMAP colored by a continuous feature (AUC score)

Special Requirements

External pySCENIC Database Files

A full pySCENIC run with motif enrichment requires three external resource files that OmicsClaw does not download automatically:

Resource	Flag	Example download
TF list (one TF per line)	--tf-list	wget https://raw.githubusercontent.com/aertslab/pySCENIC/master/resources/hs_hgnc_tfs.txt
cisTarget database (.feather)	--db	See https://resources.aertslab.org/cistarget/
Motif annotations (.tbl)	--motif	wget https://resources.aertslab.org/cistarget/motif2tf/motifs-v9-nr.hgnc-m0.001-o0.0.tbl

Store downloaded files under examples/databases/motifs/ or provide explicit paths via the flags above.

Simplified / Fallback Mode

When --tf-list, --db, and --motif are all absent and --allow-simplified-grn is passed, the wrapper accepts a correlation-based fallback GRN (no motif pruning). This is useful for quick exploratory analysis or when pySCENIC databases are not yet available.

# Full pySCENIC run
python omicsclaw.py run sc-grn \
  --input processed.h5ad \
  --tf-list hs_hgnc_tfs.txt \
  --db 'databases/*.feather' \
  --motif motifs-v9-nr.hgnc-m0.001-o0.0.tbl \
  --output results/

# Simplified fallback (no external databases needed)
python omicsclaw.py run sc-grn \
  --input processed.h5ad \
  --allow-simplified-grn \
  --output results/

Workflow Position

Upstream: sc-clustering or sc-cell-annotation Downstream: Terminal analysis.