Allen Institute Ontology

Focus

The focus of the AIO is to represent research and the results of research in a manner that is useful for scientists. It is a link between scientific knowledge gained through experimentation and the distribution/dissemination of that knowledge. The ontology development team's goal is to report areas that are in need of development in the ontology and to implement those changes in a predictable and consistent manner. The development team adheres, as much is as possible, to the standards of best practices in ontology development as outlined by the OBO Foundry. The team members are also responsible for reviewing changes in the ontology to be sure that they accurately reflect the best current understandings of brain science. The team works in conjunction with a team of software developers to ensure that the ontology and its applications are consistent and up-to-date.

Editing

The ontology is comprised of a few groups of terms. Generally speaking, there are three ways to edit or add to the ontology:

1. external terms (from other ontologies): Use OntoFox for importing terms from other ontologies. Edit the corresponding [file name] file.
2. template terms: Use ROBOT to convert spreadsheets to OWL. Edit the relevant [file name] file:

• [techniques] for techniques.
• [modalities] for modalities.
• [methods] for methods.
• [assays] for assays.
• [devices] for devices.
• [tools] for tools.

3. other terms: Edit [owlfile] in Protege.

Files

• README.md the document you are currently reading.
• [.owl] the latest release of the ontology.
• [Makefile] scripts for building the ontology.
• [views/] various specialized views of the ontology.
  • [.obo] the latest release of the ontology in .obo file format
  • [core.owl] the latest release of ontology core: ~100 key terms
• [src/]
  • [ontology/] source files for the ontology.
    • [.owl] the main OWL file
    • [core.txt] the list of core terms
    • [templates/] ROBOT template files for various branches of the ontology
    • [modules/] the results of the ROBOT templates
  • [sparql/] SPARQL queries for building and validating the ontology
  • [scripts/] utility scripts
  • [views/] configuration for views

Building

The [Makefile] contains scripts for building the ontology. On macOS or Linux, you should just be able to run make or one of the specific tasks below.

[edit these]

Development

We use git and GitHub to develop. There's a lot of good documentation on both:

• git website with files and documentation
• GitHub Help and Flow
• git command-line overview

Making Changes

Changes should be made in manageable pieces, e.g. add one term or edit a few related terms. Most changes should correspond to a single issue on the tracker.

Start from a local copy of the master branch of the repository. Make sure your local copy is up-to-date. Make your changes on a new branch. Please use the [TMO Term ID Reservations] sheet to manage new IDs.

When you're ready, push your branch to the repository and make a Pull Request (PR) on the GitHub website. Your PR is a request to merge your branch back into master. Your PR will be tested, discussed, adjusted if necessary, then merged. Then the cycle can repeat for the next change that you or another developer will make.

These are the steps with their CLI commands. When using a GUI application the steps will be the same.

1. git fetch make sure your local copy is up-to-date
2. git checkout master start on the master branch
3. git checkout -b your-branch-name create a new branch named for the change you're making
4. make your changes
5. make sort sort and normalize tables, for cleaner diffs
6. git status and git diff inspect your changes
7. git add --update src/ add all updated files in the src/ directory to staging
8. git commit --message "Description, issue #123" commit staged changes with a message; it's good to include an issue number
9. git push --set-upstream origin your-branch-name push your commit to GitHub
10. open in your browser and click the "Make Pull Request" button

Your Pull Request will be automatically tested. If there are problems, we will update your branch. When all tests have passed, your PR can be merged into master. Rinse and repeat!

Things next to Godliness

The easiest way to edit our src/ontology/template/ files is with Excel. Unfortunately Excel has some idiosyncratic rules for quoting cell values, and on macOS uses old line endings. Both these things make our diffs messy and confusing.

For clean diffs, we also like to keep out templates sorted by ID. The make sort command will fix line endings and sorting by running all the templates through a Python script.