Editing the ontology

There is a full tutorial in the obook website that covers the whole process, from installing, setup to the editing and pushing to GitHub. Here is a brief summary assuming you have already visited the wiki setup page

NOTE: If you are going to use a term from another ontology in a logical definition that is not included in any of the .txt files in src/ontology/imports (e.g. if you need a GO term that is not in src/ontology/imports/go_terms.txt) you will have to run a GitHub action before doing any editing. See refresh imports action.

• Create a new issue in the fypo repository that describes the change you want to make.
• In your local copy of the repository:
  • Make sure you are on the master branch: git branch
    • If not, git checkout master
  • Make sure you have the latest version: git pull origin master
  • Create a new branch with the number of your issue e.g. 123: git checkout -b issue_123
• Open it in Protege the file you have to edit: src/ontology/fypo-edit.owl.
• Make your edits in Protege, and save the file. More on this on Basic Editing.

• Check that the diffs make sense. A good way to do this is to use Github Desktop, to see the changes in the owl source code. Alternatively you can use the command line tool robot to produce more comprehensive diffs, see this section.
• Commit your changes and push to the branch you just created. In the commit message, include the issue number preceded by #. Assuming you are in src/ontology directory:

  git add fypo-edit.owl
  git commit -m 'addressed issue #123'
  git push origin issue_123

• Make a pull request:
  • Go to Pull requests in the fypo repo, and click on New pull request, select your branch (issue_123 in the example) as compare, leave base: master as default.
  • Wait for tests to pass.
  • Click "Squash & merge", then "Confirm squash & merge"
  • Wait for tests to pass in master branch.
  • Delete the merged branch (issue_123 in the example).
• Update your local master branch to match master in GitHub and delete the branch that is already merged:

  git chechout master
  git pull origin master
  git branch -D issue_123

Basic Editing

Editing an existing term

• Search by ID to locate parent [Double click]
• Mouseover term in Hierarchy
• [Annotations] of the ontology term (ontology term name/ID/ text def/corss refs/synonys/
• Can have cross-references directly on the term, or on other annotations on the term
• Every annotation type has a set of controls (eye=edit/ @=annotations)
• +add annotation and select annotations from a list (most are not relevant, all options are shown for everything)
• (SUGGEST SETTING SCOPE TO SHOW RELEVANT ONES)

Adding a new term

• Right-click on a term
• Options (Or sometimes duplicate class to copy and edit REMEMBER TO DELETE EXTRA TIME STAMP)
• Term appears with autogenerated ID
• Click annotation select definition, add definition
• Add database cross reference

Adding a logical definition

EXAMPLE Has part’ some (a little wrapper that goes around thing store cope with the types of phenotypes that (Quality and happens_during some ‘single-celled vegetative growth phase) And (characteristic of part of some ‘RNA processing’ And (qualifier some abnormal)

Equivalent to

but 'increased occurrence' goes in place of 'quality'; it's not a "modifier" as in "'has modifier' some abnormal", e.g.

'has part' some
    ('decreased occurrence'
     and ('characteristic of' some
        ('histone H2A phosphorylation'
         and ('happens during' some 'single-celled organism vegetative
growth phase'))))

Small things

• Escaping ' characters in logical definitions: When a GO term contains ' in its name (e.g. RNA-directed 5'-3' RNA polymerase activity), when you enter it in the logical definition window (even if you auto-complete with tab), Protege won't let you accept because you have introduced extra quotes. You can escape them with \. As in Protegé 5.5, the \ characters will show up in the logical definition, and when hovering over the term in the logical definition, you won't be able to click on it and be redirected to the right go term. However, when you save the relationship is saved correctly. You can double-check by going to the fypo-edit.owl file and seeing that the GO-term (or any term) is mentioned in a relationship.

More comprehensive diffs

NOTE: you need Docker installed to run this

More comprehensive diffs can be generated using robot. These show the differences between ontologies in a human-readable way instead of just displaying the changes in text files. To do that, go to the folder comprehensive_diff in the root folder of the project and run:

sh make_comprehensive_diff.sh

This will create two folders that are excluded from git:

• fypo-edit-old.owl (fypo-edit.owl prior to the changes)
• editdiff.html: html file with the comprehensive diff

Just open editdiff.html in your browser, and you should see the diff.

This downloads a docker image, so the first time you run it it may be slow, but subsequent calls should be faster (although the diff itself can take a couple of minutes).