Merge Terms

Merge two MONDO terms

⚠️ Running ODK commands

Every step below uses ODK tools (owltools, robot, make NORM). Read the odk skill first for how to invoke them — sh run.sh <cmd> if you have a TTY, otherwise direct docker run ... -i obolibrary/odkfull:<tag> (the tag lives in src/ontology/run.sh).

The commands below show the body (what goes after sh run.sh or after the docker prefix). Pick the wrapper based on your environment.

Required inputs

• Term to obsolete (the duplicate / less-rich term)
• Replacement / surviving term (the term content gets transferred to)
• GitHub issue number (the issue requesting the merge)

If any are missing, ask before proceeding.

Step 1 — Run owltools merge

From src/ontology/:

owltools --use-catalog mondo-edit.obo \
  --obsolete-replace MONDO:XXXXXXX MONDO:YYYYYYY \
  -o -f obo mondo-edit.obo

Where MONDO:XXXXXXX = obsoleted, MONDO:YYYYYYY = surviving.

What owltools does:

• Renames the obsoleted term to obsolete <original name>
• Sets is_obsolete: true and replaced_by: MONDO:YYYYYYY on the obsoleted term
• Strips definition, comment, xrefs, synonyms, subsets, is_a, intersection_of, relationship, property_value from the obsoleted term
• Transfers xrefs, synonyms, subsets, is_a, relationships, property_values onto the surviving term — including stale "obsoletion-tracking" metadata (see Step 5)
• Adds the obsoleted term's name as a synonym on the surviving term, citing the obsoleted MONDO ID as evidence (must be fixed in Step 5)

Step 2 — Normalize immediately

make NORM

Then mv NORM mondo-edit.obo. This deduplicates source qualifiers on identical subset/xref/is_a lines and re-quotes property_value URIs that owltools mangles.

NORM does not dedupe synonyms across different scopes (e.g. an EXACT and a RELATED with the same text both stay) — handle in Step 5.

Step 3 — Checkout both terms

obo-checkout.pl src/ontology/mondo-edit.obo MONDO:XXXXXXX MONDO:YYYYYYY

Step 4 — Clean up the OBSOLETED term

The obsoleted stanza must contain ONLY the lines below. Delete anything else owltools left behind (def, comment, xref, synonym, subset, is_a, intersection_of, relationship, other property_value) — but only after verifying the content is on the surviving term.

Step 5 — Clean up the SURVIVING term

owltools transfers content but several things need manual attention:

1. Fix synonym evidence. owltools added a synonym like synonym: "<obsoleted name>" EXACT [MONDO:XXXXXXX]. Replace MONDO:XXXXXXX with one of the transferred xrefs (e.g. [Orphanet:NNNNNN]) — but only if that source actually uses the name. Picking any xref at random fabricates evidence. To confirm: either reuse a citation from the pre-merge obsolete stanza if the same synonym was already cited there, or open the xref at source (omim.org/entry/NNNNNN, orpha.net/en/disease/detail/NNNNNN, etc.) and check the name appears as a label or synonym. If no transferred xref carries the name, leave [] and flag in the Step 8 summary. If the obsoleted name duplicates an existing synonym with a different scope, reconcile manually — pick the correct scope, drop the duplicate.

2. Remove obsoletion-tracking metadata that came from the obsoleted term:

   • subset: obsoletion_candidate
   • subset: scheduled for obsoletion on or after (if present)
   • property_value: IAO:0006012 "<date>" xsd:string (scheduled-obsoletion date — would otherwise claim the surviving term is scheduled for obsoletion)

3. Decide which definition to keep. Default = whichever the issue says is correct. If the issue is silent, keep the surviving term's existing definition. If the surviving term had no definition and the obsoleted one did, use the obsoleted one's. State the choice in the final summary so the user can override.

4. Check for redundant is_a. If a transferred is_a is a superclass of another is_a already on the surviving term (e.g. MONDO:0000001 "disease" alongside a more specific class), remove the redundant one along with its source qualifiers.

5. Check for an unwanted alt_id. Some owltools versions add alt_id: MONDO:XXXXXXX to the surviving term. If present, remove it (Mondo policy: no alt_id for merges).

(Step 7.5 #8 will verify that all meaningful content from the obsolete stanza actually made it onto the surviving term — don't duplicate that check here.)

Step 6 — Rewire children of the obsoleted term

owltools usually rewires is_a children, but does not touch references in relationship:, intersection_of:, disjoint_from:, etc. Sweep for ANY remaining reference:

obo-grep.pl --noheader -r 'MONDO:XXXXXXX' src/ontology/mondo-edit.obo

For each hit outside the obsoleted stanza itself, checkout that term, repoint the axiom to MONDO:YYYYYYY, and check it back in.