clusterProfiler Documentation

The clusterProfiler mechanism interpretation workflow is a multi-stage process designed to transform enrichment analysis outputs into biological explanations. It follows this progression:

1. Mechanism Summary: A structured synthesis of enriched terms into higher-level biological themes. It explains what the results suggest without claiming causality.
2. Mechanism Hypothesis: A testable biological claim proposing directional relationships (e.g., between regulators, processes, or phenotypes). It must explicitly expose its supporting evidence and uncertainty.

Intermediate results are stored in a Module Summary object, which groups enriched terms into coherent themes and serves as the input for both reporting and mechanism inference.

To evaluate if your mechanism summaries and hypotheses are biologically useful (rather than just structurally valid), you can use Golden Cases. These are curated enrichment-analysis examples with expected biological interpretations.

clusterProfiler provides Package Golden Cases (such as DE_GSE8057 or gcSample) built from shipped data. These allow you to demonstrate and regression-test your workflows without needing external datasets.

The clusterProfiler interpretation engine is moving from simple LLM narration to a structured multi-layer model. This ensures that biological hypotheses are represented as data objects rather than just free-text strings.

• Module Summary: An abstraction that groups individual enriched terms into coherent biological themes.
• Mechanism Inference: A layer that converts module summaries and evidence into testable mechanism hypotheses.
• Mechanism Objects: The output of the inference layer. These are structured objects containing evidence, confidence components, and rationale. They are designed to be auditable and eventually testable, rather than existing solely within a text narrative.

Evidence Adapters are pluggable sources used to support biological interpretations. While the Offline Default Path (which uses only enrichment results and user context) is always available, you can opt-in to several adapters to strengthen your analysis:

• Statistical Evidence Adapter (Default): Derives support from enrichment fields like adjusted p-values, NES, gene ratios, term overlap, and direction consistency.
• Knowledge Hierarchy Adapter: Uses ontology or pathway structures (e.g., GO hierarchy, KEGG, WikiPathways) to support module grouping.
• PPI Network Adapter: Uses protein-protein or functional interaction networks to identify hubs, modules, or regulator-process relationships.
• PubMed Literature Adapter: An explicit opt-in adapter that retrieves and caches literature support (PMID, title, and abstract snippets) from PubMed.

While interpret() can accept direct enrichment results for backward compatibility, the recommended workflow for high-fidelity biological interpretation involves a three-step structured pipeline. This approach separates term grouping from hypothesis generation, allowing for more traceable and auditable results:

1. Summarize Terms: Use summarize_terms() to group enriched terms into coherent biological themes (Module Summaries).
2. Infer Mechanisms: Use infer_mechanisms() to transform those module summaries into testable mechanism hypotheses. You can optionally provide evidence adapters to enhance this step.
3. Interpret: Pass the resulting mechanism objects to interpret() to generate the final narrative report.

modules <- summarize_terms(x)
mechanisms <- infer_mechanisms(modules, evidence = ...)
interpret(mechanisms)