clusterprofiler-custom-enrichment— agent skill

Purpose

Run a compact over-representation analysis with local query genes, local TERM2GENE, and local TERM2NAME tables through Bioconductor clusterProfiler.

When to use

• You want a deterministic enrichment example without online annotation services.
• You already have a short gene list and local term mappings.

When not to use

• You need GO, KEGG, Reactome, or remote annotation queries.
• You need large production enrichment workflows with plotting/reporting layers.

Inputs

• Query gene file with one gene per line
• TERM2GENE TSV with columns term and gene
• TERM2NAME TSV with columns term and name
• Optional local R library path and --install-missing

Outputs

• Compact JSON summary of enrichment results with p-values, adjusted p-values, gene ratios, and matched genes

Requirements

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

Procedure

1. Inspect the toy files in examples/toy_query_genes.txt, examples/toy_term2gene.tsv, and examples/toy_term2name.tsv.
2. Optionally prepare a temp Bioconductor library, then run Rscript skills/systems-biology/clusterprofiler-custom-enrichment/scripts/run_clusterprofiler_custom_enrichment.R --lib-dir /tmp/bioc-skill-lib --install-missing --out clusterprofiler_summary.json.
3. Review results for term, description, gene_ratio, p_adjust, and gene_ids.

Validation

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

Failure modes and fixes

• Missing clusterProfiler: rerun with --install-missing --lib-dir <path>.
• gdtools or ggiraph build failures: install Cairo and FreeType development headers before retrying the Bioconductor stack.
• Empty results: inspect the overlap between the query genes and TERM2GENE.
• Wrong term labels: confirm the TERM2NAME table keys match the TERM2GENE term IDs exactly.

Safety and limits

• Uses only local custom term mappings.
• Does not fetch remote annotations or make claims beyond the supplied toy or local input data.

Example

• Rscript skills/systems-biology/clusterprofiler-custom-enrichment/scripts/run_clusterprofiler_custom_enrichment.R --describe-toy

Provenance

• Bioconductor clusterProfiler package page: https://bioconductor.org/packages/clusterProfiler
• clusterProfiler manual: https://bioconductor.org/packages/release/bioc/manuals/clusterProfiler/man/clusterProfiler.pdf

Related skills

• fgsea-preranked-enrichment
• reactome-identifiers-enrichment