Skip to contents

Pathway databases, interaction provenance, and rebuilding graphs

Source: vignettes/Pathway_Database_Integration.Rmd
Pathway_Database_Integration.Rmd

Membership and topology are separate resources

SpaMTP combines identifiers and pathway memberships from NCATS RaMP-DB with network topology from graphite. The RAMP_* identifiers on graph nodes describe the common identifier system; the interaction labels are derived from graphite’s source graphs. They are not RaMP interaction IDs.

Resource Contents and origin
analyte, source_df RaMP entities and their source identifier cross-references
pathway, analytehaspathway Source-specific pathway descriptions and RaMP entity memberships
chem_props Pruned RaMP chemical properties used for metabolite annotation
RAMP_kegg Human KEGG topology from graphite
RAMP_Reactome Human Reactome topology from graphite
RAMP_wikipathway Human WikiPathways topology from graphite
RAMP_hmdb Human SMPDB topology from graphite, retained under its historical SpaMTP resource name

The RaMP 3.0.7 membership snapshot and the graph snapshot have separate dates. The currently supported topology correction uses graphite archive 19, dated 2022-11-01. Updating RaMP identifiers does not update the biological topology. SpaMTP does not construct a consensus of the four networks or treat equally named pathways as equivalent biological definitions. Membership tables retain their source identifiers. The network viewer selects a source graph; its legacy name-based selection can collapse identically named result rows, so filter results to a single database when comparing such pathways.

Identifier consolidation

data-raw/update_ramp_data.R extracts the required columns from RaMP’s SQLite analyte, source, analytehaspathway, pathway, and chem_props tables. It records RaMP and upstream database versions in ramp_db_metadata.

The original topology builder translated graphite namespaces, for example ENTREZID to entrez: and KEGGCOMP to kegg:, then matched those source IDs to RaMP identifiers. The historical builder selected the first RaMP match; unmapped endpoints remain missing and the network viewer excludes these edges. That historical mapping is reproduced by the correction recipe to preserve the existing nodes, rather than introducing new biological identifier choices.

data-raw/ramp_graph_utils.R migrates retired graph IDs to the current RaMP snapshot using the maximum number of shared stable source identifiers. Tied matches expand to multiple current entities. Two retired heme identifiers use explicit, validated replacements. The migration preserves interaction columns and deduplicates complete rows, keeping different interactions between the same pair of nodes distinct.

Interaction correction

The original graphite-to-SpaMTP conversion used code equivalent to:

ifelse(length(edge$type) == 0, NA, edge$type)

The test has length one, so the result contains only the first factor code. Creating the edge table recycled that value across all rows. The same issue affected direction. In addition, a factor code has meaning only within its source’s factor levels; Reactome, WikiPathways, and SMPDB use different levels from KEGG. Interpreting all four using KEGG’s numeric dictionary was incorrect.

The corrected conversion in data-raw/pathway_interaction_utils.R reads every source label and direction, maps labels to stable SpaMTP style codes, and retains the exact label in source_reaction_type. Code 4 still means inhibition. Generic biochemical processes are not relabelled as activation or inhibition. Undirected edges are displayed without an arrowhead. These are source annotations, not causal relationships inferred from expression data.

For KEGG Cell Cycle (hsa:04110), the repaired protein edge table has 1,009 rows and 11 interaction types, including 286 inhibition rows, 113 activation rows, 84 phosphorylation rows, and 224 binding rows. The original table incorrectly assigned all 1,009 rows to inhibition.

The correction covers all four topology collections. Restoring labels before ID migration also recovers parallel interactions that were incorrectly collapsed when their corrupted labels became identical. The network viewer draws parallel interactions on separate curves, including opposite-direction edges and self-loops. Hover over each curve to inspect its original source label; undirected interactions have no arrowhead.

Loading and inspecting corrected graphs

The stable main branch distributes corrected bundled graph objects. Both data() and pathway network workflows use the corrected data:

data("RAMP_kegg", package = "SpaMTP")
cell_cycle <- RAMP_kegg[["Cell cycle"]]
table(cell_cycle$protEdges$source_reaction_type)
attr(RAMP_kegg, "spamtp_interaction_repair")

The graph collections retain their existing object names and identifiers. The spamtp_interaction_repair attribute records the graphite archive, source checksum, and RaMP version used to reconstruct the corrected interactions.

The separate developmental branch obtains graphs through SpaMTPdb and applies an exact-fingerprint correction when SpaMTP loads the affected snapshot. The published SpaMTPdb RDS files themselves remain unchanged; reading those files directly bypasses the developmental loader’s correction. The stable branch’s bundled graph files contain the correction already.

The membership-based enrichment functions do not use these edge labels. This bug affects network interactions and any downstream analysis that directly uses those interactions, rather than changing RaMP pathway memberships.

Reproducing the correction

The maintainer recipe is data-raw/rebuild_pathway_interactions.R in the source checkout. Its input URLs and MD5 checksums are pinned in inst/extdata/pathway_interactions_provenance.csv. It requires digest plus base R; installing graphite is unnecessary because it reads archived data.

  1. Download the four graphite archive-19 graphs and the pinned original RaMP source mapping using the URLs and filenames in the provenance CSV.
  2. Stage the listed immutable SpaMTPdb 3.0.7 resources.
  3. From the source checkout, run:
Rscript data-raw/rebuild_pathway_interactions.R \
  /path/to/graphite-19 /path/to/initial-source_df.rda \
  /path/to/SpaMTPdb-resources/3.0.7

The recipe verifies input checksums, reproduces the old faulty conversion, and requires every reconstructed endpoint, direction, and code to match the stored input before generating corrections. It then reconverts from source labels, repeats the same ID migration, and writes the corrected collections to data/RAMP_*.rda, along with their repair provenance. It also updates the reaction-style lookup. No new endpoints are invented. inst/extdata/pathway_interactions_audit.csv records all pathways and edge tables checked; edge counts include historical all-missing empty-table sentinels. Regression tests check source-label and direction preservation, corrected bundled Cell Cycle data, and the four collections’ audit totals.

For a future graph release, build from labelled source edges before ID migration and publish the rebuilt data in a new package release. The external SpaMTPdb 3.0.7 input files and their checksums must remain unchanged.