fgsea-preranked-enrichment

name	fgsea-preranked-enrichment
description	Use this skill to run deterministic toy or local custom preranked gene-set enrichment with Bioconductor fgsea. Do not use it for remote annotation lookups or large cohort-scale pathway workflows.

Purpose

Run preranked enrichment with a local ranked-statistics table and local pathway definitions through Bioconductor fgsea.

When to use

• You already have a ranked gene statistics vector from a differential expression or scoring workflow.
• You want a deterministic enrichment example that depends only on local pathway definitions.

When not to use

• You need remote MSigDB, Reactome, or annotation downloads.
• You need large production enrichment workflows with reporting layers.

Inputs

• Ranked stats TSV with columns gene and score
• Pathway membership TSV with columns pathway and gene
• Optional local R library path and --install-missing

Outputs

• Compact JSON summary of fgsea results with ES, NES, p-values, adjusted p-values, and leading-edge genes

Requirements

• Rscript
• jsonlite
• Bioconductor fgsea for package-backed execution

Procedure

1. Inspect the toy files in examples/toy_ranked_stats.tsv and examples/toy_pathways.tsv.
2. Optionally prepare a temp Bioconductor library, then run Rscript skills/systems-biology/fgsea-preranked-enrichment/scripts/run_fgsea_preranked.R --lib-dir /tmp/bioc-skill-lib --install-missing --out fgsea_summary.json.
3. Review results for pathway, NES, padj, and leadingEdge.

Validation

• --describe-toy returns the expected toy gene and pathway counts.
• A package-backed run returns at least one enriched pathway for the bundled toy example.

Failure modes and fixes

• Missing fgsea: rerun with --install-missing --lib-dir <path>.
• Empty results: lower --min-size or inspect the ranked-statistics directionality.
• Non-deterministic values: keep the input files fixed and set --seed.

Safety and limits

• Uses only local custom pathways and local ranked statistics.
• Does not fetch or infer biological annotations from remote services.

Example

• Rscript skills/systems-biology/fgsea-preranked-enrichment/scripts/run_fgsea_preranked.R --describe-toy

Provenance

• Bioconductor fgsea package page: https://bioconductor.org/packages/fgsea
• fgsea tutorial: https://bioconductor.org/packages/release/bioc/vignettes/fgsea/inst/doc/fgsea-tutorial.html

Related skills

• reactome-identifiers-enrichment
• clusterprofiler-custom-enrichment