General introduction

This document is under construction.

author: Dirk Derom

This document will guide you through the maze of OBI. It's intended for those not familiar with OBI and aims to be an easy read document giving you all the minimum information for a quick understanding of OBI.

OBI: short & simple
What? OBI is a Ontology for the description of biological and clinical investigations using BFO as its upper-ontology.
 * An Ontology captures the concepts used within a specific domain along with its relations for those concepts. It's a controlled (usually community driven) effort to create a shared vacabulary for the specific domain.
 * BFO is an upper-ontology, which describes the very general concepts of scientific research where various domain ontologies can reside.
 * OBI is such a domain specific ontology (cf. a more 'specific' ontology focussed on a specific domain), using BFO as its framework (cf. using the more general concepts) targeting biological and clinical investigations.

Scope? The ontology will represent the design of an investigation, the protocols and instrumentation used, the material used, the data generated and the type analysis performed on it. Its primary goals are:
 * to develop ontology for Biomedical Investigations in collaboration with groups representing different biological and technological domains involved in Biomedical Investigations
 * to make OBI compatible with other bio-ontologies
 * to develop of OBI using an open source approach
 * to create a valuable resource for the biomedical communities to provide a source of terms for consistent annotation of investigations

Who? OBI is being developed by individuals from different biological and technological domains involved in Biomedical Investigations.

OBI
The Ontology for Biomedical Investigations (OBI) addresses the need for controlled vocabularies to stimulate the integration of experimental data. OBI captures representation of designs, protocols, instrumentation, materials, processes, data and types of analysis in all areas of biological and biomedical investigations.

The need for data integration was originally identified in the transcriptomics domain by the Microarray Gene Expression Data Society (MGED), which developed the MGED Ontology as an annotation resource for microarray data. Following a mutual decision to collaborate, this effort later became a wider collaboration between groups such as MGED, PSI and MSI in response to the needs of areas such as transcriptomics, proteomics and metabolomics and the FuGO (Functional Genomics Investigation Ontology) was created. FUGO was later on extended with clinical and epidemiological research and biomedical imaging (=OBI). This later become OBI covering the wider scope of all biomedical investigations.

The Scope of OBI
The Ontology for Biomedical Investigations (OBI) project is developing an integrated ontology for the description of biological and clinical investigations. This ontology will support the consistent annotation of biomedical investigations, regardless of the particular field of study. This leads to the formulation of the following goals:
 * Develop an Ontology for Biomedical Investigations in collaboration with groups representing different biological and technological domains involved in Biomedical Investigations
 * Make OBI compatible with other bio-ontologies
 * Develop OBI using an open source approach
 * Create a valuable resource for the biomedical communities to provide a source of terms for consistent annotation of investigations

The ontology has the scope of modeling all biomedical investigations and as such contains ontology terms for aspects such as:
 * biological material - for example blood plasma
 * instrument (and parts of an instrument therein) - for example DNA microarray, centrifuge
 * information content - such as an image or a digital information entity such as an electronic medical record
 * design and execution of an investigation (and individual experiments therein) - for example study design, electrophoresis material separaition
 * data transformation (incorporating aspects such as data normalization and data analysis) - for example principal components analysis dimensionality reduction, mean calculation

Less 'concrete' aspects such as the role a given entity may play in a particular scenario (for example the role of a chemical compound in an experiment) and the function of an entity (for example the digestive function of the stomach to nutriate the body) are also covered in the ontology.

The OBI Consortium
As an international, cross-domain initiative, the OBI consortium draws upon a pool of experts from a variety of fields, not limited to biology. The current list of OBI consortium members is available at the OBI consortium website. The consortium is made up of a coordinating committee which is a combination of two subgroups, the Community Representative (those representing a particular biomedical community) and the Core Developers (ontology developers who may or may not be members of any single community). Separate to the coordinating committee is the Developers Working Group which consists of developers within the communities collaborating in the development of OBI at the discretion of current OBI Consortium members.

Editor role
It was decided to split the development process into branches. For each branch, groups of editors were assigned. The responsibilities of an editor is as follows,
 * request and vet MIO required information for all terms from the communities
 * Compare and resolve conflicts between terms, iteratively get buy-in from the communities
 * Place terms in hierarchy
 * Vetting of orthogonality to existing OBO foundry ontologies; Submit terms to other OBO ontologies that do not belong in OBI
 * Move terms not fit for a given branch to a more appropriate branch, and notify the editors of the branch they are moved to
 * Communicate to the OBI-Devel Group whenever
 * changes to the OBI-Core classes in other branches are deemed necessary
 * classes in the branch which were considered part of the OBI-Core are deleted

Branch Leader Role

 * be the principal contact for the branch
 * organize the branch calls and discussion
 * establish a wiki page for the branch where terms and notes are posted
 * negotiate with other branch leaders in cases of disputed terms or setting up joint discussions

Editor-in-Chief Role
It was decided at the March 14 Coordinators call that having an Editor-In-Chief for the OBI bracnches would be beneficial. The duties of this role are:
 * Moderate issues that arise between OBI branches. For example, if there is disagreement between branches such as to how to deal with terms important to those branches, the Editor-In-Chief will arbitrate the decision.
 * Help communities find the appropriate branches for their terms. For example, if terms important to a community are rejected by a branch as out of scope, the Editor-In-Chief will determine whether another branch is more appropriate or ask a bracnh to expand their scope to include those terms.
 * Monitor the discussion of the OBI branches for common issues that warrant general discussion. Bring these issues to the attention of the appropriate group (e.g, OBI developers list).
 * Monitor progress of the OBI branches. Check if they are meeting milestones and suggest steps to keep up with other branches.

Scoping Branch

 * Post composite use-cases for study design
 * Document efforts in scoping branches to be able to publish manuscript

Branches

 * independent_continuant
 * Biomaterial (Bjoern, Alan Tina, Helen, Susanna, Norman)
 * Instrument, Part of Instrument (Daniel, Melanie, Frank, Ryan)
 * Bio Repositories (Richard, Barry) --> NEEDS TO BE MOVED TO MILESTONES
 * Process
 * Protocolapplication (except datatransformation) (Allyson, Bjoern, Alan)
 * Data Transformation (Jeff, Tina, Ryan, Philippe, Richard, Helen)
 * Bio Repositories Process (Richard, Barry) --> NEEDS TO BE MOVED TO MILESTONES
 * Dependent continuants
 * Qualities (Biomaterial Characteristic, Phenotype) PATO (Chris M point of contact)
 * Roles (Reagent / Reporter / Variable) (Bill, Richard, Jennifer, Alan)
 * Function (Biological Function in FuGO) (GO, Bill, Suzi(advisor), Alan)
 * Generically Dependent Continuants - This is NOT a branch in itself. Needs to be added to BFO.
 * Sub-branch: Digital Entity and Non-realizable information entity (Data, Dimension, Measurement, Parameter, Value, capturing experimental conclusions) (Liju, Barry(adviser), Jennifer)
 * Sub-branch: Plan (old name: Study_design) (Susanna, Jennifer, Helen, Trish, Liju, Jeff, Philippe)
 * Relationships (Liju, Chris M, Alan, Daniel, Cristian)

Branch Implementation

 * Communication
 * Separate obi mailing lists for each group will be set up via sourceforge. You may sign up for any group's mailing list, even if you are not strictly part of that group
 * Separation of OBI.owl
 * Each branch will be restricted to only modifying their own branch through owl imports
 * A new owl file will be created for each branch
 * Liju suggests extracting each branch using Protege � she knows how
 * Use owl imports for all other OBI branches, thus rendering them read-only
 * To solve problems with shared imports like BFO and others, we should have a parent node owl file containing those things
 * we can delete this if we want to, once everything is merged back into OBI.owl: this is basically just a convenience method for branch development
 * Relations will be done after all the terms are finished, and the branches merged. They will be done by the relations branch group.
 * However, DON'T IGNORE RELATIONS � track them and write them down
 * Write them down in the definition and maybe in the group notes file,
 * Send your change to the obi relations branch group list to keep them informed.


 * Merging back into a single OBI.owl file will occur once all branches are complete, and will be done manually.
 * This methodology has raised several issues with Protege.
 * Keeping Notes
 * Each group should keep a file (also in subversion) recording what changes they are making to their branch (this is in addition to the subversion commit messages). This way other groups can easily scan through and see what you're up to, and it will also provide a useful record within the group.
 * Use of Subversion
 * There will be X .owl files made within SVN, where X the number of OBI branches we decided on
 * Initially, these will all be in the trunk directory of the OBI SVN repository. This means that any committed change made by a group will immediately be visible to all other groups as soon as they re-load Protege.
 * If any branch wants to try something that they feel may break things, they can request that an SVN branch be specially created for them to work in. These branches will never be re-integrated back into the trunk, so they don't have to worry if things go wrong.
 * Also, each time one of these volatile branches are finished (if any are made at all====), we may decide to tag that stage of the branch as closed or finished, so that people browsing the repository would know these branches were no longer in an active modification state.


 * Once all branches are complete, they will be manually concatenated back together again, and the finished file will be committed to the OBI.owl file living in the trunk of the SVN repository.
 * Deprecation of Terms
 * During OBI Branch work
 * We may consider deprecation now using owl: Deprecated Class, owl: Deprecated Property as long as Alan doesn't find any problem with doing this
 * It will be actually deleted before committing to obi.owl, again as long as everyone is happy with that at the time.
 * Once the OBI file is stable, will have to think very carefully about it
 * Deprecation should be done properly and permanently, as it's important for our users to see these deprecation histories once it is 'stable'.
 * When you deprecate, the smart thing to do (and is done in BIRN) is to take formal owl assertions to a place invisible to reasoners but which says things like 'my former parent is xyz'. That doesn't handle axioms, but would handle parents and children.
 * OBI Identifiers
 * Use community ID ranges for the branch ID ranges. This prevents different branches using the same ID without realizing it
 * The autoid plugin needs to know what the last assigned ID is, so it may be useful for each group to keep a file with the last assigned ID in it.
 * Recognition of Work
 * Each branch should decide on their branch leader, but ALL that do significant work should get credit for their work at a highly visible level, e.g. in the top-level of the obi file as well as in the Editor portion of the term.

Organization Chart
The OBI project is an international, collaborative effort to build an ontology to be used for annotation of Biomedical Investigations. The OBI Consortium is the name under which the OBI project authors its work.

Digraph {

/* Node styles */ node [shape = square]; {node [color = grey, style = dashed]; "Upper-Level Ontology"; "Domain Specific Ontology"; }

{ node [color =grey] "NeuroCommons"; }

{ node [shape = plaintext] "...";	}

/* Subs */ /* Comments */ Subgraph cluster_comments { "Upper-Level Ontology"; "Domain Specific Ontology"; color = white; }

/* Relations */ BFO -> OBI; BFO -> "OBO Foundry"; "OBO Foundry" -> OBI; "OBO Foundry" -> "NeuroCommons" [color = grey]; "OBO Foundry" -> "..." [color = grey]; OBI -> Branches; "Upper-Level Ontology" -> BFO [style = dashed, color = grey]; "Domain Specific Ontology" -> OBI [style = dashed, color = grey]; }

The Developers

 * Community Representatives
 * Core Developers
 * Developers Working Group

Contribute
We have mailing lists for both users and developers. Join the users list to be notified of each OBI release. If you represent a Community that would like to collaborate in the development of OBI, contact the Coordination Committee.

OBI Term Submission Guidelines
http://sourceforge.net/tracker/?func=add&group_id=177891&atid=886178
 * Currently, term requests may be submitted through the "OBI Term" Sourceforge Tracker system available here:


 * In order to submit terms, you will need to have an account with Sourceforge and you will need to be logged in. You can create a Sourceforge account here: https://sourceforge.net/user/registration


 * When you submit a term, it must conform, at a minimum, to the OBI Minimal Metadata requirements. Practically this means a 'term' a 'definition' and preferably an 'example'. Optionally, you may also suggest which branch of OBI your term belongs in. Please see the current list of OBI Branches to help you in making your choice.


 * What happens next?


 * Submitted terms will be examined by Alan Ruttenberg/Helen Parkinson, and sent to the appropriate branch. Out of scope terms, for example those belonging to another ontology domain e.g. PATO will be flagged at the point of submission if possible. Branches will add terms and will be responsible for commenting in the tracker to inform the term submitter of progress


 * Batch submissions. If you have a large number of terms don't use the term tracker for all, instead create a spreadsheet of your terms with term and definition columns (this is the minimum) and attach to a single sf item


 * If you have any questions on the submission process or any other queries, please email the OBI developers at obi-devel at lists.sourceforge.net.

Deprecation Policy
- current release, QC and deprecation issues

Update 10 Oct 09, branch files are now merged into a single file therefore

 * you need only access one file to edit obi. http://obi.svn.sourceforge.net/svnroot/obi/trunk/src/ontology/branches - obi-edit.pprj
 * Email obi-devel to announce check out
 * Email on commit to announce check in

Structure of SVN - there are 4 projects set-up, each with their own trunk, branches and tags directory: web, ontology, and tools.
 * web - location for web related files, e.g. the OBI homepage
 * branchDevelopment - location for the branch owl files that are currently being worked on
 * ontology - location for release-ready .owl, .pprj and other files
 * tools - any application code that is of use for the project that is NOT available at another location. The autoid plugin to use with Protege is stored here as this was pointed to us from the Protege list and the code subsequently modified by Gilberto Fragoso.


 * see current README in the SVN project

Powerpoint presentation
Powerpoint Presentation on Subversion for OBI : given 21 November 2007 by Allyson, Daniel S., and Melanie at the obi-dev Telecon.

How to install and set up your local svn repository
First, read this svn section under http://sourceforge.net/docs/B01/en/#

SVN (Subversion) is a tool used by many software developers to manage changes within their source code tree. SVN provides the means to store not only the current version of a piece of source code, but a record of all changes (and who made those changes) that have occurred to that source code. Use of SVN is particularly common on projects with multiple developers, since SVN ensures changes made by one developer are not accidentally removed when another developer posts their changes to the source tree.

In order to access a Subversion repository, you must install a Subversion clientfor your operating system.

On windows, please download and install the TortoiseSVN client from http://tortoisesvn.net/downloads

After this configure the SVN client as described here: http://sourceforge.net/docs/F07/en/#config and here http://sourceforge.net/svn/?group_id=177891

but use the following obi parameter: URL: https://obi.svn.sourceforge.net/svnroot/obi

Then you can create a new folder where you want all the svn stuff to be put by the svn-'checkout'. right click on the new folder and select svn-checkout. You will be asked to do some settings and then you connect to the SF svn address and download (checkout) the present directory structure and files into your specified client-based folder. Later you will update this folder or files via 'svn update' before you commit your changes back to the common repository. You can use the repro browser (again for tortoise svn client all the options are available via rightclick on your checkout folder or specific files) to just have a look what's in svn without actually downloading/updating anything in your local folder.

You can do an anonymous download but not an upload. When you commit you'll be prompted for a commit comment e.g. added 5 new classes for x use case

How to use svn is described here: http://sourceforge.net/docs/E09/en/#top

How to Use SVN
online tutorial for SVN
 * command line based (UNIX/MAC):

using tortoise svn
 * windows Explorer plugin-based (PC):

to summarize:

EMAIL THE LIST THAT YOU ARE CHECKING OUT TO EDIT, EMAIL AGAIN ONCE COMPLETE

a - when you want to commit your changes, ALWAYS do svn update first (svn status -u can also predict conflicts)

If the svn update shows no conflict ("C" in front of the file name) then go ahead and svn commit

If the svn show conflicts:

- svn will create additional files in your working repository:

- filename.mine: This is your file as it existed in your working copy before you updated your working copy—that is, without conflict markers. This file has only your latest changes in it. (If Subversion considers the file to be unmergeable, then the .mine file isn't created, since it would be identical to the working file.)

- filename.rOLDREV: This is the file that was the BASE revision before you updated your working copy. That is, the file that you checked out before you made your latest edits.

- filename.rNEWREV: This is the file that your Subversion client just received from the server when you updated your working copy. This file corresponds to the HEAD revision of the repository.

- at this point you can't commit into svn (as long as these 3 files exists)

=> YOU NEED TO SOLVE THE CONFLICT FIRST

- you can decide to throw away your changes: svn revert or copy one of the temporary svn file over your copy

- you can merge the conflicts by hand (lines identified by ========= and >>>>> and <<<<<<<<)

Once the conflict is solved, run svn resolved to tell svn that you're now ok. NOTE: svn will trust you, and will not check that you actually solved the conflicts. At this point the .mine, .rOLDREV and .rNEWREV are deleted.

- you can now svn commit your files

Please check the README in the SVN project for the lock option

You can check using diff between a given revision (for instance the last one committed) and your local working copy - e.g.:
 * USEFUL COMMAND

svn diff -r 470 Biomaterial.owl

The above compares the revision 470 of the file Biomaterial.owl to your local copy.

svn diff -r 470 Biomaterial.owl > test.diff.001

The above compares the revision 470 of the file Biomaterial.owl to your local copy and write the result in a local file in your copy called test.diff.001. (Thanks to Bill for the tip!)


 * Unix/Mac - command-line or embedded GUI wrapper in Eclipse or Netbeans
 * PC - Tortoise Client