Skip to content

Merging and obsoleting

Merging and Obsoleting Classes

Overview

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 the issue tagged with the label "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 "mitochondrial disease" (MONDO:0019055) was obsoleted and replaced by "inborn mitochondrial metabolism disorder" (MONDO:0004069)
  • Out of scope: some terms are excluded from Mondo based on certain criteria, which are outlined in the exclusion reason table. For example, terms that are not truly diseases, (i.e. phenotype terms, such as "Colchicine resistance" (MONDO:0007348). For another example, see see #503.
  • Obsoleted in source: external resources such as OMIM, Orphanet, or GARD may retire or obsolete a term. For example "obsolete Ehlers-Danlos syndrome with periventricular heterotopia" (MONDO:0019348).

Issues should remain open for at least two (2) months* 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.

*There is an exception to this rule if a term is not an actual disease, it can be obsoleted sooner. See this ticket for an example.

See GitHub Discussion on Obsoletions

Workflow

Tag Term for Obsolete/Merge

  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, check 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. 'term tracker item': 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 one of the reasons below. Note, the obsoletion reason code should be added in the IRI Editor.

      • OMO:0001000: out of scope
      • IAO:0000423: to be replaced with external ontology term
      • IAO:0000229: term split
      • MONDO:TermsMerged: http://purl.obolibrary.org/obo/MONDO_TermsMerged

    6. Comment:

    7. Do not add free text here. Copy and paste the formula from the row above so the comment is consistently structured.
    8. Manually check the term to be obsoleted for comment.
      1. If the term to be obsoleted already has a comment, manually add the structured obsoletion comment to the existing comment.
      2. If the term to be obsoleted does NOT has a comment, copy and paste the formula from the row above and add it in the "Comment to be automatically added" column
    9. Obsoletion candidate subset: This should always be http://purl.obolibrary.org/obo/mondo#obsoletion_candidate
    10. 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.
    11. 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:
    12. Mondo ID for the term that will replace the obsoleted terms
    13. Label for the term that will replace the obsoleted terms

    Video explanation of Workflow

    See video explanation here.

    Request new obsoletion reasons as needed

    Request new obsoletion reasons from the technical team: 1. amending the QC check 2. updating the imports/removeseed.txt file and 3. the omo_import.owl goal.

    Unfortunately, this complex process is necessary due to limitations with the OBO format, see https://github.com/owlcollab/oboformat/issues/139.

Monthly (before Mondo 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.
    1. if any terms are reported, create a ticket on the EFO tracker and notify ClinGen users (for now, email Larry Babb).
  3. 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.
  4. 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.
  5. Allow for at least one month after sending the report or contacting users before obsoleting the terms to allow users time to comment.

Obsolete and/or Merge the Class

Once the two month notification period has passed, the class can be obsoleted and/or merged. The section below describes how to make these changes in the ontology.

How to Obsolete and Merge the Class

There are 2 ways to merge classes:

  • Manually (not recommended)
  • Using owltools within the ODK Docker container (see instructions here)
  1. Confirm your Docker container with ODK is running
  2. Pull latest content from master branch
  3. Create an issue branch and name it issue-### (for example issue-2864) where the number is the GitHub ticket number for the merge/obsolete request
  4. Open Protege

  5. Prepare the owltools command: run.sh 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 (existing term to be merged with)

    Example: If the term "ectrodactyly polydactyly" (MONDO:0023052) is to be merged with "ectrodactyly-polydactyly syndrome" (MONDO:0009156), the command is:
    run.sh 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 merged. 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)

  6. In Terminal, navigate to YOUR-MONDO-GIT-DIRECTORY/mondo/src/ontology

  7. Run your owltools command

    📝 IMPORTANT
    Review the mondo-edit.obo diff file and manually make the changes listed below to finalize the merge/obsolete process.

  8. Check the output in GitHub Desktop
    Note: you may see an unexpected addition at the top that starts with "_owl-axioms: Prefix(owl:=http://www.w3.org/2002/07/owl#)\nPrefix..." This is because two IDs were added to replacement term (the ID from the term obsoleted and the ID for term it was merged into). The instructions below describe how to remove the additional ID and once that is done the "owl-axiomsPrefix(owl:=http://www.w3.org/2002/07/owl#)\nPrefix..._" addition in the file will go away after you do that.

  9. The owltools command will move all of the dbxrefs to the new term. We can have proxy merges, i.e. 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

  10. Open a new version of mondo-edit.obo in Protege

  11. Obsoleted class: Search for the term that was obsoleted
    1. Add "term tracker item" (type xsd:anyURI) annotation with a link to the GitHub issue (e.g. https://github.com/monarch-initiative/mondo/issues/YOUR-TICKET-NUMBER) that requested the obsoletion.
    2. Add an obsoletion reason: use the annotation property "has obsolescence reason" and add http://purl.obolibrary.org/obo/MONDO_TermsMerged in the IRI Editor field.
    3. Any source annotations to MONDO:equivalentTo on a dbxref should be changed to MONDO:obsoleteEquivalent.
    4. Optional: Add an additional comment (rdfs:comment) explaning why the terms were merged.

  12. Replacement term: Search for the 'term replaced by' term

    1. Delete the old ID (if you check the diff after doing this and saving, you'll see the unexpected addition will disappear)
    2. 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.)
    3. Review the subClassOf assertions, and make sure there are no duplicates. If there are, they should be combined. This can be done in a text editor by copying the "source" information from one subClassOf assertion to the other and deleting the duplicate subClassOf assertion. After saving the file, the updates will be visible in Protege.
    4. Remove the annotations:
      1. "in subset obsoletion candidate"
      2. "scheduled for obsoletion on or after"
    5. If there is a rare disease subset annotation from the obsolete term, it is ok to keep the rare subset annotation to the term kept (we will let the rare disease authorities know so that they can update the source of truth.
    6. When reviewing the diff, make sure there is not an Alt ID. The diff should only show additions to the merged term and the obsoleted class.

    Merge Terms in Mondo - Part 1


    Merge Terms in Mondo - Part 2

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 add OMO:0001000 in the IRI editor (OMO:0001000 = out of scope). Add a source annotation to the obsolescence reason that comes from this list of exclusion reasons. It should look something like: property_value: IAO:0000231 OMO:0001000 {source="MONDO:excludeObsoleteSource"}.
  7. Optional: Add an additional comment (rdfs:comment) explaning why the terms were merged.
  8. Add annotation 'term tracker item' (type xsd:anyURI) 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.
  15. remove all rare disease subset 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 add OMO:0001000 in the IRI editor (OMO:0001000 = out of scope). Add a source annotation to the obsolescence reason that comes from this list of exclusion reasons. It should look something like: property_value: IAO:0000231 OMO:0001000 {source="MONDO:excludeObsoleteSource"}.
  5. Add annotation 'term tracker item' (type xsd:anyURI) 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. Remove all rare disease subset annotations
  9. 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 add OMO:0001000 in the IRI editor (OMO:0001000 = out of scope). Add a source annotation to the obsolescence reason that comes from this list of exclusion reasons. It should look something like: property_value: IAO:0000231 OMO:0001000 {source="MONDO:excludeObsoleteSource"}.
  6. Add annotation 'term tracker item' (type xsd:anyURI) 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. Remove all rare disease subset annotations
  11. 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 (note, this file may need to be created and saved in this folder). The changes will not show up in the git diff.
  2. run sh run.sh make mass_obsolete2 -B
  3. Very carefully review the diff. More carefully then usual!

Note: The QC test obsolete_warning.sparql will give warnings for classes that do not have subset tags obsoletion_candidate.

Restoring an Obsolete Ontology Term

When to restore or reinstate an ontology term

There may be rare cases when we chose to reinstate or restore an obsolete class. For example, in this ticket (#4948) we decided to reinstate some Orphanet grouping classes because they were used in the classification scheme described by the authors of the paper.

Note: The Gene Ontology has instructions to restore an obsolete term, but in Mondo, we prefer to create a new term and mint a new ID, and point from the obsoleted term to the new term using the replaced_by annotation.

Restore an obsolete term (Add new term)

  1. Follow the usual instructions to create a new term in Mondo.
  2. More advanced: New terms can be added using the text file:
    1. Open mondo-edit.obo in a text editor, like Atom.
    2. Find the obsoleted term.
    3. Copy the stanzas for that term and paste as a new term in the file.
    4. Replace the ID with the new ID
    5. Remove the 'obsolete' from the label
    6. Remove the obsolescence annotations:
    7. property_value: IAO:0000231 "out of scope" xsd:string
    8. is_obsolete: true
    9. If applicable, change the source annotations from MONDO:obsoleteEquivalent to MONDO:equivalentTo
    10. Update the 'term tracker item' (type xsd:anyURI)annotation to point to the relevant ticket
  3. Find the obsolete term, and add (or replace) the annotation 'replaced_by' to point to the new ID.
  4. Note: A term cannot have both a consider annotation and a replaced_by annotation. Add only the replaced_by annotation that points to the new term you created.
  5. If edits were made in the text file, be sure to open the file in Protege and Save As -> mondo-edit.obo and replace existing failure
  6. Commit to your branch and create a pull request

Updated 2024-03-14