User Guide

This guide walks you through the complete mapping workflow, from selecting Key Events to submitting high-quality mappings.

Creating a New Mapping

Step 1: Select Key Event

Use the searchable dropdown to find a Key Event from AOP-Wiki. You can search by:

  • Key Event ID (e.g., "KE 55")
  • Key Event title or keywords

After selecting a KE, a details panel appears showing the KE description, biological level, and a link to measurement methods on AOP-Wiki. A context panel lists AOP membership and any existing WP / GO / Reactome mappings, and an inline AOP-context graph (Cytoscape) fans out from the chosen KE so you can see the upstream Molecular Initiating Event and downstream Adverse Outcome at a glance.

Step 2: Choose a target resource

A Key Event can be mapped to three resources, and they are peers, not a default plus two alternatives. Pick whichever describes the Key Event best, and map to more than one where more than one fits — the tabs, proposal queues and exports are independent.

  • WikiPathways and Reactome give curated pathway models. A mapping says this Key Event is realised by this pathway. Good for a Key Event that names a mechanism.
  • Gene Ontology gives biological processes and molecular functions, not pathways. A mapping names the process the Key Event is. Usually the better fit for a Key Event describing a single event, where a pathway diagram would be broader than the event itself.

Step 2a: Select a WikiPathways pathway — KE-WikiPathways Mapping

Choose a related pathway using the KE-WikiPathways Mapping tab. The system provides three sub-tabs:

  • Suggested - Pathways ranked by BioBERT semantic similarity to the KE description (v1.5, 2026-05-10). Each card shows a "Genes: N/M" overlap chip for context, but gene overlap does not influence the ranking.
  • Search - Search for pathways by name or keywords
  • Browse All - Browse all available WikiPathways

If the selected KE-WP pair already exists in the database, a duplicate warning is shown before submission.

Step 2b: Select a GO term — KE-GO Mapping

To map a KE to a Gene Ontology Biological Process term, use the KE-GO Mapping tab. The system provides two sub-tabs:

  • Suggested - GO BP term suggestions ranked by BioBERT semantic similarity (v1.5, 2026-05-10). Cards show GO term name, definition, matched genes (informational), term depth, and similarity score.
  • Search - Search for GO terms by name or GO ID (e.g. GO:0006915). Searches both Biological Process and Molecular Function; each result is labelled with its namespace.
Why the umbrella term sometimes ranks first. The suggestion list is filtered so that an ancestor GO term is dropped when a more specific descendant is also suggested — unless the ancestor is the term the Key Event actually names. For a generic KE such as "Cell death", cell death is the intended annotation and will not be evicted by programmed cell death scoring fractionally higher. Ranking itself is pure semantic similarity: there is no boost that favours deeper, more specific terms. Direction ("increased", "decreased") belongs in the Key Event's own annotation rather than the GO term, so directionally-signed labels such as positive regulation of… are excluded from the suggestion corpus.

Step 2c: Select a Reactome pathway — KE-Reactome Mapping

To map a KE to a Reactome pathway, use the KE-Reactome Mapping tab. Suggestions follow the same BioBERT pure-semantic ranker (v1.5) used for WP and GO; cards show the Reactome pathway name, the gene-overlap chip (informational), and a similarity score.

Active refinement: the Reactome tab carries a small "under development" notice. The proposal flow and exports are functional; suggestion thresholds are being calibrated.

Step 3: Confidence Assessment (4 Questions)

Answer four questions to evaluate mapping quality:

Question Options Purpose
1. Relationship Type Causative / Responsive / Bidirectional / Unclear Determines connection direction
2. Evidence Basis Known / Likely / Possible / Uncertain Your confidence level (0-3 points)
3. Pathway Specificity KE-specific / Includes KE / Loosely related Pathway scope evaluation (0-2 points)
4. KE Coverage Complete / Key steps / Minor aspects Pathway completeness (0-1.5 points)

Confidence Scoring

The system calculates confidence based on your answers:

  • High Confidence: ≥5.0 points (strong evidence + good coverage)
  • Medium Confidence: 2.5-4.9 points (moderate evidence or limitations)
  • Low Confidence: <2.5 points (weak evidence or poor coverage)
Biological Level Weighting: Molecular, cellular, and tissue-level KEs receive a +1 bonus point because they're closer to pathway mechanisms than organ/population-level KEs.
KE-GO Assessment: KE-GO mapping has its own confidence assessment with GO-specific connection types. The assessment evaluates the biological relevance of the KE-to-GO-term relationship.

Exploring Existing Mappings

Navigate to Explore to view all approved mappings in an interactive DataTable with:

  • Tabs for KE-WP, KE-GO and KE-Reactome mappings
  • Client-side search and column sorting; AOP and confidence-level filters round-trip to the API
  • Coverage Gaps tab — pick an AOP to see which of its Key Events have no approved KE-WP mapping yet. Useful for steering curation effort.
  • Inline WikiPathways embed viewer (click the eye icon to preview a pathway diagram)
  • Export to CSV, Excel and PDF
  • "Propose Change" on any row opens a proposal modal for admin review

Exploring AOPs on the graph

The AOP Explorer shows a whole Adverse Outcome Pathway as an interactive graph, so you can see where a Key Event sits between its Molecular Initiating Event and the Adverse Outcome before deciding what to curate.

  • Per-resource coverage dots — each KE node carries three dots, always in the order WikiPathways, GO, Reactome. A filled dot means the KE has at least one approved mapping in that resource; a hollow dashed dot means it has none. The node's border tells you at a glance whether it is mapped in any resource.
  • Gap filters — narrow the graph to unmapped KEs, or to gaps in one specific resource, to find where curation effort is still needed.
  • OECD development status — filter AOPs by their status in the OECD workplan, so you can prioritise AOPs that are endorsed or under review.
  • Gene-count badges — the number beside a node is how many genes that KE has via its existing mappings.
  • Clicking a node opens a side panel with the KE's details and a link straight into the mapping workflow.

Proposing Changes

If you notice an issue with an existing mapping, you can correct it through the review workflow rather than needing database access. This works on all three resources.

  1. Sign in with GitHub (or use a workshop guest access code)
  2. Click Propose Change on the mapping row
  3. Describe the change and submit it for admin review

What you can propose depends on the resource:

  • All three resources — propose a deletion, or a revision that answers the same assessment the mapping was created with. The confidence level is calculated from those answers rather than chosen directly, so a correction records the reasoning behind the tier it produces.
  • KE-WikiPathways and KE-Reactome ask the four questions (relationship, evidence basis, pathway specificity, KE coverage); KE-GO asks for a connection type and scores its three dimensions (connection, specificity, evidence). Each resource is asked the same instrument it was mapped with.
  • The form shows the mapping's current answers beside each question, so you can see what you are changing. A mapping curated before the assessment existed has none to show, and says so.

Downloads & exports

The /downloads page provides ready-to-consume exports of all approved mappings:

  • GMT — KE-centric gene sets for fgsea / clusterProfiler, with one file per resource and confidence tier
  • RDF / TTL — Turtle exports for SPARQL federation
  • CSV / JSON — flat tables for spreadsheets and notebooks

For programmatic access, prefer the public REST API — it supports pagination, filtering, and JSON / CSV output without needing to download a snapshot file.

Citing the data. The download endpoints always serve the current state of the database, which is what you want for analysis but not for a methods section. For a frozen, citable snapshot use the Zenodo deposit: concept DOI 10.5281/zenodo.20184643 always resolves to the latest version, and each version bundles GMT files split by confidence tier plus Turtle with full curation provenance. Released under CC0 — no permission needed to reuse, though a citation is appreciated.

Provenance & privacy

The footer of every page records which upstream releases the current data came from (AOP-Wiki, WikiPathways, GO, Reactome), so a result can be traced back to the source versions that produced it.

Every approved mapping also records who proposed it and who approved it. What that means for your personal data, and how long it is kept, is set out in the privacy notice.