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: Select WikiPathway — KE-WP Mapping

Choose a related WikiPathway using the KE-WP 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 2 (alternative): Select 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), enriched with IC-based specificity boost and ancestor redundancy filtering. Cards show GO term name, definition, matched genes (informational), and similarity score.
  • Search - Search for GO terms by name or GO ID (e.g. GO:0006915)

Step 2 (alternative): Select 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

Proposing Changes

If you notice an issue with an existing mapping:

  1. Sign in with GitHub (or use a workshop guest access code)
  2. Click Propose Change on the mapping row
  3. Describe the change (delete, change confidence, change connection type)
  4. Submit for admin review

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.