Skip to content

Editors' Guide

Jump to bottom
Leigh Carmody edited this page Mar 18, 2021 · 11 revisions

(Modified from Human Phenotype Ontology editors' guide)

SETTING UP

Editing environment

  1. Install Protege 5.2 or higher. Protege 5.5 is currently available and most editors are using this version now.
  2. Install any additional plugins from: http://wiki.geneontology.org/index.php/Ontology_editor_plugins
  3. Install the Elk plugin from https://github.com/liveontologies/elk-reasoner/wiki/GettingElk (Put the plugin into the Protege/plugins directory, see instructions below.)

Especially

  1. The Term Metadata editor plugin (Alpha), to be found at: http://wiki.geneontology.org/index.php/Ontology_editor_plugins
  2. The obsolescence plugin (see http://wiki.geneontology.org/index.php/Ontology_editor_plugins; note the plugin is called org.nescent.protege.obo-actions.jar). (Note--these plugins are not great and use is not mandatory)

PRE-EDIT CHECKLIST

Setting your ID ranges

Do you have an ID range in the idranges file (maxo-idranges.owl), in the src/ontology/directory)? If not, create a GitHub issue.

Ensure that you have Protege configured to generate new URIs in your own range. Note that if you edit multiple files, you need to check this every time to ensure that the proper settings are in place. MAXO URIs should look like this: http://purl.obolibrary.org/obo/MAXO_0000473 Do a test to ensure that the ID generator is working properly.

A word of caution about protege auto-id functionality. Protege will allow reuse of a URI in your range according to the numbering scheme. It will keep track of what you did during last session, but does not check for use of the URI before assigning it (doh!!). Therefore, if you switched between editing another ontology, or added any IDs in your range prior to the switch to OWL, Protege will not know not to start from the beginning. Some tips below to check to see where you are in your range. Note: if you only edit the HPO and do not edit other ontologies, you will only need to set this up once, Protege will remember your last ID between sessions.

  1. Open the file maxo-idranges.owl in src/ontology in a text editor (like TextEdit) and check your ID range (start and end).

  2. In Protege, go to the View menu, click "render by entity IRI short name (Id)". This will display classes as "MAXO_0030021" etc.

  3. Use the search box to search for classes starting within your range, such as "HP_04" for Melissa's range. Check the "show all results" box to see all of your results.

  4. Find the last used ID in your range, e.g. MAXO_0400008.

  5. Go to Protege->Preferences, and click the New Entities tab. Set Protege to the next unused ID in your range (e.g., "MAXO_00400009") rather than the beginning of the range.

  6. To do so (assuming you are using Protege 5), go to Protege->Preferences window and find the "New Entities" tab. The following settings are correct:

  • Start with "Specified URI": http://purl.obolibrary.org/obo/
  • Followed by "/"
  • End with "autogenerated ID"
  • Entity label "custom label": http://www.w3.org/2000/01/rdf-schema#label
  • Autogenerated ID "numeric", prefix "MAXO_", digit count "7", start (next unused ID in your range), end (last ID in your range)
  • Finally, tick the box "remember last ID between Protege sessions"

Note that you can use ctrl-U to see the IRI of the current entity. If you click on "show full IRI", you should see something like this: http://purl.obolibrary.org/obo/MAXO_0011531

  1. Finally, go to Protege->Preferences, “New Entities Metadata” tab and set "http://www.geneontology.org/formats/oboInOwl#created_by”. This will ensure that we are all using the same tag to get credit for making new terms.

Elk reasoner

Installing ELK:

  1. Go to the ELK pages
  2. Scroll down and click on Protege Plugin latest build
  3. When downloaded, unzip and copy puli and elk jars (two .jar files) in the unpacked directory.
  4. Paste these files in your Protege plugin directory. This is in one of two locations:
  • ~/.Protege/plugins (note this is usually hidden from finder, but you can see it in the terminal) or
  • Go to Protege in Applications (Finder), right-click, 'Show package contents' -> Java -> plugins

GETTING STARTED

Use pull requests to make changes:

  1. git pull

  2. Create a new branch

  3. Start editing

  4. Switch on the Elk reasoner (see how to get plugins above). If you are making changes, be sure to synchronize the reasoner.

Edit the ontology in Protege:

  1. Find parent term in Protege by searching in the search box (at top of the screen)
  2. Double-check that term is not already there
  3. Add subclass
  4. Add a label (URI should be auto-generated)
  5. Under annotations, add definition, click OK
  6. Annotation on the definition (see below)
  7. database_cross_reference
  8. dbxref: Your ORCID (if you do not have an ORCID, sign up here: https://orcid.org/)
  9. Under annotations, add synonyms, if necessary (has_exact_synonym, etc). If applicable, mark the synonyms as an abbreviation or layperson term.

OR... EDIT using ODK/DOSDP patterns

  1. To create a new pattern, go to this directory: MAXO/src/patterns/dosdp-patterns and create a new yaml file with proposed pattern.
  2. To create new terms to be generated, go to MAXO/src/patterns/data/manual/ and create a TSV file
  3. On the command line, navigate to MAXO/src/ontology/ and run sh run.sh make templates
  4. commit and save to your branch
  5. If no conflicts, merge to master.

Commit your changes

  1. Git
  git add -u .
  git commit -m "COMMIT MESSAGE" maxo-edit.owl
  git push
  1. Or you can use a Git GUI like Sourcetree or GitHub Desktop

CREATING NEW TERMS or EDITING (Checklist)

  • In general, the term should be announced on the GitHub tracker prior to the creation of the new term.

  • Make sure the Protege reasoner (Elk) is active to investigate any unforeseen and unintended logical inferences.

  • Most terms should have the following items added.

  • Label All lower case.

  • Definition Should be a complete English sentence. This should be extended by an XREF (e.g., PMID:123 to provide additional information. There is a strong preference for PMID reference, but can use other ontologies or books. Note, there should be no spaces in the PMID.)

  • Comment This is optional but can be used to provide additional information about the term such as diseases that are characterized by the feature or diagnostic methods that can be used to demonstrate the feature. Use rdfs:comment.

  • Cross-references or XREFs Indicate an item in another database that is equivalent, a source, or reference to this MAXO term. For instance, MeSH:D058529. We can add a label (e.g., "Single umbilical artery") by the "Annotations" button. Use database_cross_reference

  • Synonyms If possible, add relevant synonyms. Use "has_exact_synonym" for true synonyms (preferred). If needed, use "has broad synonym" or "has narrow synonym" for words/phrases that are not 100% identical in meaning but are likely to be confused with the main term.

  • Additional notes. Make sure there aren't additional spaces, especially after '.'. Also, make sure no special characters are introduced.

Closing Issues with Commit Messages

This is the preferred way to commit a new term.
See the GitHub help pages for this. To close and commit terms that relate to issue #608, for instance, create the terms and save them to file. git add -u . git commit -m "This added NT X. Close #608" git push (Or use SourceTree/Github Desktop to commit.)

SAVING and COMMITTING

Save and commit regularly. Always describe the changes you have made at a high level in the commit messages.

Currently not set up yet is the Error log through Travis. This will be implemented soon.

After a commit, Travis will check your changes to make sure they conform to guidelines and do not introduce any inconsistencies - an email will be sent to the editors' list.

You can check on the build here: https://travis-ci.org/monarch-initiative/MAxO/branches

Check for errors in the report, send an email to editors if you cannot determine what the error is.

RELEASE

Release Pipeline:

  1. Merge all open pull requests
  2. Pull changes from master to local repo
  3. Open cmd
  4. Cd MAxO/src/ontology
  5. Create new branch (git checkout -B newbranch)
  6. Just in case, update docker:
  • docker pull obolibrary/odkfull
  1. Sh run.sh make templates
  2. Sh run.sh make prepare_release -B (or for testing sh run.sh make IMP=false prepare_release -B )
  3. Commit all changed files to Github branch (nico will review pull request)
  4. Request a curator to review, then merge to master
  5. Click on code -> releases
  6. Make new release, https://github.com/monarch-initiative/MAxO/releases/new
  7. In Tag version: write v2019-10-13, everything else, write as you see fit. Hit: “Save”

Obsoletion and merging

  1. Open the MAxO/src/patterns/templates/ folder.
  2. To obsolete open obsolete.tsv, and add the IRI for a term you wish to obsolete, the new term label (eg. obsolete term label) and set depreciation to TRUE.
  3. Then delete everything associated with the term in protege, including logical definitions and 'subclass of'
  4. ONLY OBSOLETE when there is no other option to merge. Ex.
Ontology ID Label Obsolete
ID A rdfs:label AT owl:deprecated^^xsd:boolean
http://purl.obolibrary.org/obo/MAXO_0000273 obsolete gastrointestinal agents, other TRUE
  1. To merge, in the same folder, open replaced.tsv
  2. add term IRI, change label name to 'obsolete term label), set depreciation to TRUE, and add the IRI of the term you want to merge to.
  3. Add all info from this term to the term that it should be replaced to manually in protege. Include synonyms, comments, definitions, etc., as necessary.
  4. Then delete everything associated with the term in protege, including logical definitions and 'subclass of'
  5. Merging (or replacing) is the preferred method because it redirects users to the new term without losing the information. Ex.
Ontology ID Label Obsolete Replacement Term
ID A rdfs:label AT owl:deprecated^^xsd:boolean AI IAO:0100001
http://purl.obolibrary.org/obo/MAXO_0000156 obsolete antispastic agents TRUE http://purl.obolibrary.org/obo/MAXO_0000245
http://purl.obolibrary.org/obo/MAXO_0000204 obsolete other antibacterial agents TRUE http://purl.obolibrary.org/obo/MAXO_0000061

Importing a new ontology

  1. add imports to src/ontology/maxo-odk.yaml
  • i.e., open maxo-odk.yaml in a text editor and add the new ontology under 'import_group: products:' ex. - id: obi
  • Note: if the ontology is large, then should use this and increase docker memory mport_group: products:
    • id: pr use_gzipped: TRUE is_large: TRUE
  1. in terminal sh run.sh make update_repo
  2. open maxo-edit.owl in text editor add import statement
  1. open catalog-v001.xml in text editor and add import statement
  • Add at least the .owl statement. The obo file is not a requirement. ex.
  1. terminal sh run.sh make imports/obi_import.owl
  2. open maxo-edit.owl in protege and run reasoner to look for unsatisfiable classes
Clone this wiki locally