Skip to content

Merging and obsoleting

Merging and Obsoleting Classes

Overview

  1. Mondo users need to be notified before we obsolete, merge or split a Mondo class.
  2. If there is a request to obsolete a Mondo class, Monarch Initiative to determine if the disease term is used for Monarch annotations. For example, discitis (see ticket here) does not have any annotations in Monarch. (This is something that we hope to automate in the future).
  3. If a term is to be obsoleted, in a new row in the ROBOT_ObsoleteTag spreadsheet template, add the following information for the term-to-be-obsoleted:
    1. ID for term to be obsoleted
    2. Label for term to be obsoleted
    3. seeAlso: GitHub ticket that describes the obsoletion request
    4. Consider: the replacement term that should be considered for use after the term is obsoleted. If there is no replacement, leave it blank.
    5. Obsoletion reason: chose from dropdown list.
    6. Comment: do not add free text here. Copy and paste the formula from the row above so the comment is consistently structured.
    7. Obsoletion candidate subset: This should always be http://purl.obolibrary.org/obo/mondo#obsoletion_candidate
    8. obsoletion date: should be a release date at the first of the month, at least two months from today. Please write in the format YYYY-MM-DD.
  4. If a term is to be merged, in a new row in the ROBOT_MergeTag spreadsheet template, add the information above, and in addition, add:
    1. Mondo ID for the term that will replace the obsoleted terms
    2. Label for the term that will replace the obsoleted terms

Monthly (before release)

  1. Run the pipeline to merge the ROBOT template and commit and merge the PR into mondo-edit.obo.
  2. Run the risky_obsoletion_check pipeline to check if external ontologies and databases (such as EFO and ClinGen) are using this Mondo term.
  3. if so, create a ticket on the EFO tracker and notify ClinGen users (for now, email Larry Babb).
  4. Perform a SPARQL query to identify all the obsoletion candidates (see instructions here). The command to run the query is: sh run.sh make report-query-obsoletioncandidates-withcomment. This will be the report that will be shared with Mondo users to inform them of upcoming obsoletions.
  5. Share the report on the Mondo users email list (include the file as an attachment) and/or share the report (tsv file) on GitHub here.
  6. Allow for at least one month after sending the report or contacting users before obsoleting the terms to allow users time to comment.

How to

There are 2 ways to merge classes:

  • Manually (not recommended)
  • Using owltools

To use owl tools will need to have Docker installed and running (see instructions here). This should be done in plain text, either csv or tsv. Two columns (or optionally 4 columns with labels):

  1. CURIE of class to be obsoleted
  2. CURIE of replacement class

These are then merged like this:

owltools mondo-edit.obo  --obsolete-replace MONDO:0000267 MONDO:0015264 --assert-inferred-subclass-axioms --markIsInferred --removeRedundant -o -f obo new.obo
diff mondo-edit.obo new.obo
mv new.obo mondo-edit.obo

Note this can frequently lead to cycles and equivalence between named class pairs, as many seemingly identical classes have different implicit semantics.

Note: if you add an obsoletion reason, make sure that the replaced class does not have an alt_id assertion. If so, remove that before committing.

Merge terms

Merge using owltools

  1. Create a branch and name it issue-### (for example issue-2864)
  2. Open Protege
  3. Prepare the owltools command: owltools --use-catalog mondo-edit.obo --obsolete-replace [CURIE 1] [CURIE 2] -o -f obo mondo-edit.obo

CURIE 1 = term to be obsoleted
CURIE 2 = replacement term (ie term to be merged with)

For example: If to merge MONDO:0023052 ectrodactyly polydactyly with MONDO:0009156 ectrodactyly-polydactyly syndrome, the command is:

owltools --use-catalog mondo-edit.obo --obsolete-replace MONDO:0023052 MONDO:0009156 -o -f obo mondo-edit.obo

Recommended: Use this template to track the terms to be mergd. There is a formula in column G, copy from the row above. Note: the Mondo ID in columns A and C must be in CURIE format (use a colon, not an underscore)

  1. In Terminal, navigate to ..mondo/src/ontology
  2. Run your owltools command
  3. Review diff: Check the output in GitHub Desktop. Note: you may see an unexpected addition at the top that starts with owl-axioms... This is because two IDs were added to replacement term. The instructions below note to remove the additional ID, and this will go away after you do that.
  4. The owltools command will move all of the dbxrefs to the new term. We can have proxy merges, ie two MONDO:equivalentTo xrefs from the same source. If this is the case, one dbxref should be marked as MONDO:preferredExternal (as a source annotation on the dbxref) in addition to the MONDO:equivalentTo source annotation.

Screen Shot 2022-02-08 at 11 00 00 AM

  1. Open a new version of mondo-edit.obo in Protege
  2. Obsoleted class: Search for the term that was obsoleted
  3. Add SeeAlso with a link to the GitHub issue that requested the obsoletion.
  4. Add an obsoletion reason: use the annotation property 'has obsolescence reason' and write 'terms merged' in the literal field.
  5. Any source annotations to MONDO:equivalentTo on a dbxref should be changed to MONDO:obsoleteEquivalent.
  6. Optional: Add an additional comment (rdfs:comment) explaning why the terms were merged.
  7. Replacement term: Search for the 'term replaced by' term
  8. Delete the old ID (if you check the diff after doing this and saving, you'll see the unexpected addition will disappear)
  9. Review the annotations to ensure there are no duplicate annotations. If there are, they should be combined. (Sometimes this is easier to review in the diff in GitHub Desktop, but they must be fixed in Protege.)
  10. Review the subClassOf assertions, and make sure there are no duplicates. If there are, they should be combined.
  11. Remove the annotations: 'in subset obsoletion candidate' and 'scheduled for obsoletion on or after'
  12. When reviewing the diff, make sure there is not an Alt ID. The diff should only show additions to the merged term and the obsoletion

Manual merge/obsolete

  1. If one class should be merged with another class, first obsolete the class that will be merged.
  2. Search for the class to be obsoleted
  3. Rename label to: obsolete [class name]
  4. Add annotation owl:deprecated and indicate true (in literal)
  5. Add annotation term replaced by and add ID of term which replaced it (in CURIE format, such as MONDO:0010684). If the disease term is being obsoleted and an HPO term should be used instead, do not use term replaced by, rather use the annotation consider. For example, see MONDO:0001445.
  6. Add an obsoletion reason: use the annotation property 'has obsolescence reason' and manually write in a reason as a string (usually 'out of scope'). Add a source annotation to the obolescence reason that comes from this list of exclusion reasons.
  7. Optional: Add an additional comment (rdfs:comment) explaning why the terms were merged.
  8. Add SeeAlso with a link to the GitHub issue that requested the obsoletion.
  9. Remove superclass axioms
  10. If the class has children, remove the superclass assertion for the children
  11. Example: Manual merge example 1
  12. Move all the synonyms to the new term.
  13. Retain all of the database_cross_references on the obsoleted term. Any annotations to MONDO:equivalentTo should be changed to MONDO:obsoleteEquivalent.
  14. If applicable, to mark the synonym as deprecated, add an annotation to the synonym: has_synonym_type ‘A synonym that is historic and discouraged’. See granulomatosis with polyangiitis for examples of deprecated syn axiom annotations.

Note: An obsolete Mondo class should not have an xref axiom tagged with "MONDO:equivalentTo". Instead use "MONDO:obsoleteEquivalent" to map between an obsolete MONDO class and a live entry in another resource (these serve as a kind of flag of a state of inconsistency).

Obsolete a class (without merging)

Obsolete a class (using Protege 'Make entity obsolete' function)

  1. Search for the class to be obsoleted.
  2. In the Protege edit menu-> Make entity obsolete
  3. Prepend the definition with OBSOLETE. For example, OBSOLETE. Chronic form of myeloproliferative neoplasm.
  4. Add an obsoletion reason: use the annotation property 'has obsolescence reason' and manually write in a reason as a string (usually 'out of scope'). Add a source annotation to the obolescence reason that comes from this list of exclusion reasons.
  5. Add SeeAlso with a link to the GitHub issue that requested the obsoletion.
  6. If the term has database_cross_reference annotations and the source is annotated as MONDO:equivalentTo, change the source to source MONDO:obsoleteEquivalent (in the literal tab). Obsolete terms should never be equivalent.
  7. Add annotation consider, add the CURIE for the term that should be considered as a replacement.
  8. Optional: Add an additional comment (rdfs:comment) explaning why the term was obsoleted.

Obsolete a class (manually)

  1. Search for the class to be obsoleted.
  2. Rename label to: obsolete [class name].
  3. Add annotation owl:deprecated and indicate true (in literal).
  4. Prepend the definition with OBSOLETE. For example, OBSOLETE. Chronic form of myeloproliferative neoplasm.
  5. Add an obsoletion reason: use the annotation property 'has obsolescence reason' and manually write in a reason as a string (usually 'out of scope'). Add a source annotation to the obolescence reason that comes from this list of exclusion reasons.
  6. Add SeeAlso with a link to the GitHub issue that requested the obsoletion.
  7. Remove superclass axioms.
  8. If the class has children, remove the superclass assertions for the children.
  9. If the term has database_cross_reference annotations and the source is annotated as MONDO:equivalentTo, change the source to source MONDO:obsoleteEquivalent (in the literal tab). Obsolete terms should never be equivalent.
  10. Optional: Add an additional comment (rdfs:comment) explaning why the term was obsoleted.

Simple mass obsoletion pipeline

If you only want to obsolete terms without taking another look, you can use the simple mass obsoletion pipeline:

  1. add all terms you wish to obsolete to config/obsolete_me.txt
  2. run sh run.sh make mass_obsolete2 -B
  3. Very carefully review the diff. More carefully then usual!

When to obsolete / merge

If a term is a candidate for obsoletion and/or merging, this should be reported on the GitHub issue tracker and labeled 'obsolete'. Click here for potential terms to be obsoleted.

Some examples of when to obsolete and/or merge a term are:

  • Duplicate terms (for example MONDO:0019055 mitochondrial disease was obsoleted and replaced by MONDO:0004069 'inborn mitochondrial metabolism disorder')
  • Out of scope- Terms that are not truly diseases, (ie phenotype terms, such as MONDO:0007348 Colchicine resistance). For another example, see see #503
  • obsoleted in source: for example, OMIM, Orphanet or GARD may retire or obsolete a term. For example, MONDO:0015173 obsolete autoimmune enteropathy type 2 is a phenotype and not a disease: for example, MONDO:0043606 'obsolete pathologic fracture'

Issues should remain open for at least two weeks to allow for the community to comment and bring up any objections. All obsoletions will be done via a pull request and reviewed by Mondo developers.

See GitHub Discussion on Obsoletions

by Nicole Vasilevsky and Sabrina Toro updated 2021-12-17