ORB term request prototype

Introduction

The vision of this project is to develop an application that will allow data curators to use new ontology terms without creating a workflow bottleneck.

Background

There is a need for applications that will expedite the annotation of phenotypic characters using ontologies and also promote community participation in the expansion and refinement of ontologies. One particular need that has arisen within Phenoscape and other projects is for an Ontology Request Broker (ORB), an application that can launch new ontology term requests within existing data curation workflows, record term provenance and community discussion, enable temporary terms to be used in data annotation, and update temporary terms once a request has been resolved.

Scope

Here is a documentation of ORB term request service. ORB will be accessible via an online interface and programmatically through RESTful web-services.

ORB architecture overview

Use cases

Case:Place a term request within an ontology annotation application

Brief: One of the key challenges in ontological data annotation is placing a new term request.During annotation, a user normally has to switch from his/her annotation platform/application ( for examplePhenex) to a different URL (such as sourceforge based term tracker) to place a request. This poses a bottleneck to efficient data annotation especially in large-scale projects. An annotator working with an annotation application integrating ORB's submit term request service, can submit a new request and receive a temporary ID to work with before the requested term is assigned an official ontology ID.

Actor: annotator of data using ontology terms

Pre-condition: -The antology annotation application being used is integrated to ORB's submit term request service

Ideal path The process is initiated when the user initiates new term request within the annotation application

A GUI for term submission is generated
User completes the term submission fields
User clicks on the submit button
ORB validates the request
ORB informs the user of successful term submission and provides a temporary ID(referred to as ORB ID) assigned to the term
Adds the new request to the database

Invalid path : This occurs when the user submits an invalid request

ORB alerts the user that the request is invalid
ORB return the term submission GUI with the invalid field(s) highlighted

Case:Get term from the ontology annotation application

Brief: After placing a term request, a ontology annotator would like to find out if the term has been resolved (i.e assigned the correct name and ontology ID).

Actor: ontology annotator

Pre-condition -The antology annotation application being used is integrated to ORB's get term via orb ID service. Ideal path The process is initiated when the user initiates get term via ORB ID within the annotation application

A GUI for inserting the ORB ID is generated
User inserts the ID
User clicks on the submit button
ORB validates the request
ORB informs user that the term has been resolved and returns the resolved term's name, ontology ID, definition plus other related information

Alternative paths:

If the term is still pending

ORB informs the user that the term is still pending and returns the term's name, ORB ID plus any other updates relating to the term

If the term is obsoleted

ORB informs user that the term has been obsoleted and returns the suggested correct ontology term if one exists
ORB also returns any comments that may give a clue to the user why the term was obsoleted

If a term matching the ORB ID is not found

ORB informs user that no match was found
ORB suggests to the user to verify if the ORB ID provided was correct an if he/she wants to re-submit another ORB ID

Case:Register
Brief: This is a use case for creating an account in ORB

Actor:ORB user

Pre-condition: The user is at the ORB site

Ideal path The process is initiated when the user selects the registration link

ORB presents the registration page
User provides required fields(e-mail,name, password and country)
User submits his/her information
ORB verifies the request
ORB informs the user of successful registration and provides an activation link
ORB sends the registration information to the user's e-mail account

Alternative path Invalid request: This occurs when a user submits a request with missing required information

The steps 1 to 4 in the ideal path apply
ORB terminates the registration
ORB returns to the registration page with the missing field highlighted

Invalid e-mail address: This occurs when a user provides an invalid e-mail address

The steps 1 to 4 in the ideal path apply
ORB terminates the registration
ORB informs user the e-mail address is invalid
ORB returns the registration page

Case:SubmitTerm

Brief: This is a use case for submitting new ontology term requests.

Actor: TermRequester

Pre-conditions: The requester must be at the ORB website and has an account

Ideal path:

This use case is initiated when the requester clicks on the term submission tab
ORB presents the user login page for the requester to fill in the name and password
ORB verifies the requester
ORB displays the term submission page
Requester provides the required fields(i.e term's name, parent, textual definition,target ontology) plus any additional information related to the term (i.e other relations, references, database cross references, comments etc) and submits
ORB verifies the submission
ORB assigns a temporary ID to the term and presents it the requester
ORB sends the requested term's temporary ID and other details to requester's e-mail account
ORB returns to the term submission page

Alternative paths:

Invalid request: This occurs if the user submits a request without the required fields

Steps 1 to 6 as described in the ideal path will apply
ORB will the terminate the request
ORB will return to the term submission page with the missing required field highlighted

Matching term found: This occurs when the requested term already exists in the targetted ontology

Steps 1 to 6 as described in the ideal path will apply
ORB returns a message informing the requester that the term exists
ORB returns the matching term's id, name and parent to the requester

Case: EditTerm

Brief: This is a use case for editing requested term

Actor: TermRequester and OntologyGateKeeper

Pre-conditions

The term exists in ORB database
The term has not been resolved
The term editor is at the specific term's page

Ideal path: This case is initiated when the TermRequester/OntologyGateKeeper selects the "edit term" link

ORB presents the user login page
User provides their name and password
ORB verifies the user
ORB presents the term with the editable fields
User makes any changes and submits
ORB verifies the changes made
ORB updates changes
ORB informs user of successful update
ORB displays the term plus the new changes

Alternative paths:

User not registered

Steps 1 to 3 as described in the ideal path apply
ORB terminates the process
ORB informs the user that they are not registered or need to try again in case of misspelled login details
ORB presents the ORB registration page

User neither the requester of the term nor gatekeeper for the target ontology

Steps 1 to 3 as described in the ideal path apply
ORB terminates the process
ORB informs the user that they need to be the term's requester or ontology gatekeeper to edit the term
ORB returns to the term page

Case:ChangeTermStatus

Brief: This is a use case for changing the status a term submitted

Actor: OntologyGateKeeper

Pre-condition: The user is at the specific term page

Ideal path This case is initiated when the user,selects the "change term status" link

ORB presents the user login page
User provides their name and password
ORB verifies the user
ORB presents the term with the editable status fields
User selects the new status and submits
ORB updates changes
ORB informs user of successful update
ORB displays the term plus the updated status

Alternative paths

Invalid OntologyGateKeeper

Steps 1 to 3 as described in the ideal path will apply
ORB terminates the request
ORB informs the user that they aren't the ontology gatekeeper or they may try again in case of misspelled login information
ORB returns to term page

Resolved term status: This applies when a term has already been resolved and assigned a permanent ID

Steps 1 to 3 as described in the ideal path will apply
ORB terminates the request
ORB informs the user that the term has been resolved
ORB returns to the term page

Case:BrowseTerms

Actor: CasualUser

Brief:This is a case for user who is navigating the ORB site

Pre-Condition:

The user is online at the ORB site

Ideal path

The user selects the "browse terms" link
ORB displays the ORB browse term page
User selects whether to view all terms or based on status
ORB displays the terms name , ID , target ontology, status and a link to the terms page

Alternative paths:

Case: DownloadTerms

Brief: Use case for downloading terms

Steps 1 to 4 as described in the ideal path apply
User selects the terms to be downloaded
User selects the download tab
ORB generates a text file containing the terms in OBO format
ORB returns to the page displaying downloaded terms

Download a term: Applicable when user wants to download a single term

The steps 1 to 4 as described in the ideal path apply.
User selects the term page link
ORB displays the term page with all the term's information
User selects the term download tab
ORB generates a file containing the term in OBO format
ORB returns to the term's page

Case: SearchTerm Brief: A case for user to search for a term

Ideal path:

User selects the search term link
ORB displays the term search page
User provides the term name or id or parent
User selects the submit button
ORB returns a term with the name,synonyms or id matching the information provided in step 3

Alternative path:

No term matching the search

Steps 1 to 3 as described in the ideal path apply
ORB returns a term not found message

Case: Comment

Pre-condition: User is at the specific term's page

Ideal path

User selects the "comment on term" link
ORB provides a page for submitting a comment
User provides comment in the term comment field
User provides name and e-mail
ORB validates the user e-mail
User submits the comment
ORB generates a comment submission success message
ORB returns to the term page

Alternative path

User e-mail invalid

Steps 1 to 5 as described in the ideal path apply
ORB terminates the comment submission process
ORB informs user about the invalid e-mail address
ORB returns to the term comment submission page

Case: DevelopOrb

Actor: Developer

Brief: This is a case for users who have skills in application development and are interested in developing ORB further

Pre-conditions:

Ideal path:

Alternative paths:

Case:IntegrateOrb

Actor : Developer

Brief: This is a case for users who have skills in application development and are interested in integrating ORB into existing application e.g to form a workflow.

Pre-conditions:

Ideal path:

Alternative path:

Non-functional requirements

Accessibility

ORB will have a web interface for easy access via browsers
It will also have REST-style web service for programmatic access
The prototype will be integrated into Phenex as a demonstration of an interfaceable API.

Support

- A comprehensive documentation on ORB's functions(how to..),implementation and help pages
- Registration and extensive documentation at sourceforge, Biocatalogue and Phenoscape wiki
- Have a bug tracking and feature request mechanism

Activity

Installation

Download source code

-To obtain the complete and latest version of the applications source, visit the SVN link -Download the project all files

Build

-Run the ant based build file to generate the orbprototype.war file

Database

-Get the DDL scripts from the build step depending on the kind of DBMS your are using e.g. for PostgreSQL, use ddl_postgres.sql. -Create a database withing your DBMS with the parameters below:

     database name: ontologyrequestbroker
     password : orbprototype

-Run the DDL script chosen above within the SQL interface or on command line to create all the database tables and sequences.

Establish connection to the database

ORB database Entity-Relation(ER) diagram

Note: The {ontology_identifier}refers to either the name or prefix of an ontology e.g Teleost Anatomy Ontology (name) or TAO (prefix)

Output : All requested terms with the provided ontology as their target in html format

Example

GET /orbprototype/terms/ontology/TAO/?media=html HTTP/1.1

Get all terms from an ontology with an ontology_identifier in xml format

Type : xml

Type : html

Protocol : HTTP GET

URI :<BASE>terms/publication/{publication_identifier}/?media=html

Note: The publication_identifier can be a publication's DOI or title

Output :All requested terms with the provided publication as their reference in html format

Example

GET /orbprototype/terms/publication/test/?media=html HTTP/1.1

URI :<BASE>terms/top/?media=xml

GET /orbprototype/terms/ORB:5bfba0d4-de9b-47ce-adb7-9c9ebc2ae359/?media=html HTTP/1.1

Post term via a web form

URI : <BASE>/orbprototype/terms/?postterm=true
Input :
Web form containing all the term input fields as found in this pdf file [1]

Output : A term post success message in html format

Post term in XML format

URI : <BASE>/orbprototype/terms/?media=xml
Input :
Term in XML format adhering to the term(s) to post schema

Output : A term post success message in XML format

Samples of new term requests

1. New term request with required elements only

POST /orbprototype/terms/?media=xml HTTP/1.1 <xml> <terms>

<term>

<term_name>adult alar plate6</term_name>

<term_definition> <definition_text>Wing-shaped sclerotized plates for support of muscles controlling the action of the pharyngeal valve, Muscle bundles extendfrom the alae to the subcheliceral plate (epistome) and from the alar surfaces to the ventral side of the basis capituli. Dilator muscles of the pharynx also attach to the alar plates. Operation of the anterior pharyngeal valve is accomplished by the contractionof the dilator muscles inserted on the wing-like alae, thereby raising or lowering the v-shaped wedge. When the wedge is raised,fluid is taken up, when lowered, it projects down into the v-shaped valve, sealing it and prevents backflow.</definition_text> </term_definition>

<term_relationship> <relationship_type> <relationship_type_name>test relationship type name </relationship_type_name> <relationship_to> test relationship to property value</relationship_to> </relationship_type> </term_relationship>

<term_ontology> <ontology_name>Teleost Anatomy and Development</ontology_name> <ontology_prefix>TAO</ontology_prefix> </term_ontology>

<term_requester> <requester_name>test requester name </requester_name> <requester_email>username@ymail.com</requester_email> </term_requester>

</term> </terms> </xml>

2. New term request with all term elements

POST /orbprototype/terms/?media=xml HTTP/1.1 <xml> <terms> <term> <term_name>adult alar plate7</term_name>

<term_definition> <definition_text>Wing-shaped sclerotized plates for support of muscles controlling the action of the pharyngeal valve, Muscle bundles extendfrom the alae to the subcheliceral plate (epistome) and from the alar surfaces to the ventral side of the basis capituli. Dilator muscles of the pharynx also attach to the alar plates. Operation of the anterior pharyngeal valve is accomplished by the contractionof the dilator muscles inserted on the wing-like alae, thereby raising or lowering the v-shaped wedge. When the wedge is raised,fluid is taken up, when lowered, it projects down into the v-shaped valve, sealing it and prevents backflow.</definition_text> <definition_dbxref>ISBN:0-19-505910-7</definition_dbxref> </term_definition>

<term_relationship> <relationship_type> <relationship_type_name>test relationship type name </relationship_type_name> <relationship_to> test relationship to property value</relationship_to> </relationship_type> </term_relationship>

<term_ontology> <ontology_name>Teleost Anatomy and Development</ontology_name> <ontology_prefix>TAO</ontology_prefix> <ontology_domain>Anatomy and Development</ontology_domain> <ontology_gatekeeper> <gatekeeper_name>test gatekeeper name</gatekeeper_name> <gatekeeper_email>test gatekeeper@ymail.com</gatekeeper_email> </ontology_gatekeeper> </term_ontology>

<term_status>Pending</term_status>

<term_requester> <requester_name>test requester name </requester_name> <requester_email>test requester@ymail.com</requester_email> </term_requester>

<term_synonym> <synonym_text>test synonym</synonym_text> <synonym_scope>test synonym scope</synonym_scope> <synonym_type>test synonym type</synonym_type> <synonym_dbxref> <synonym_dbxref_name>test synonym dbxref name</synonym_dbxref_name> <synonym_dbxref_accession>test synonym dbxref accession</synonym_dbxref_accession> </synonym_dbxref> </term_synonym>

<term_comment>Fig. 7-5; Fig. 7-9; in Biology of Ticks ISBN:0-19-505910-7.</term_comment>

<term_publication> <publication_title>Test title</publication_title> <publication_doi>test doi</publication_doi> <publication_journal>test journal</publication_journal> </term_publication>

<term_dbxref> <dbxref_dbname>test term dbxref name</dbxref_dbname> <dbxref_accession>test term dbxref accession</dbxref_accession> </term_dbxref>

<term_xref_analog> <xref_analog_name>test xref analog name</xref_analog_name> <xref_accession>test xref accession</xref_accession> </term_xref_analog>

</term> </terms>

</xml>

Project plan

An agile approach will be used in ORB development. The sign √ indicates accomplished tasks while * indicates tasks which ought to have been implemented but haven't been

Week 1: 4 to 9 January, 2010 To review the ORB project, suggest any changes in light of existing technologies from literature review and input from the team and document the (including the changes).

Revise the ORB project plan and milestones√
Identify a suitable citation management tool and learn how to utilize it√
Perform a comprehensive literature search and read the relevant papers and add to the ORB literature review√

Week 2: 10 to 16 January, 2010 Complete literature review, document and discuss with project team

Perform further literature search, read and complete literature review√
Document the project requirements (technologies to be used, architecture, behavior) in the project wiki√
Hold an online meeting with NESCent team about progress and ORB implementation based on literature review and existing technologies√

Week 3: 17 to 23 January, 2010 Document ORB requirements and specification based on input from literature, discussion and research

Revise the ORB requirements, specification and document it to the wiki√

Week 4: 24 to 30 January, 2010 Revise, design and implement ORB data layer based on existing technologies, input from project team and implement the database.

Design and implement the ORB database
Document the ORB database schema

Week 5: 31st January to 6th February 2010 Design and implement ORB Application layer

Identify and document the role of each server application
Start implementing/coding the application layer

Week 6: 7 to 13 February, 2010 Continue implementing the application layer plus the unit test

Continue implementing the application layer and unit tests

Week 7: 14 to 20 February, 2010 Continue implementing the application layer plus the unit test

Continue implementing the application layer and unit tests

Week 8: 21 to 27 February, 2010 Continue implementing the application layer plus the unit test

Continue implementing the application layer and unit tests

Week 9: 28th February to 6th March 2010 Continue implementing the application layer plus the unit test

Continue implementing the application layer and unit tests

Week 10: 7th to 13th March 2010 Start working on the ORB user/client interface

Identify and describe the user/client interface
Begin implementing the user/client interface

Week 12: 21st to 27th March 2010

Continue working on the user/client interface

Week 13: 28th March to 3rd April 2010

Continue working on the user/client interface

Week 14: 4th to 10th April 2010

Continue working on the user/client interface

Week 15: 11th to 17th April, 2010

Continue working on the user/client interface

Week 16: 18th to 24th April, 2010

Continue working on the user/client interface

Week 17: 25th April to 1st May 2010 Complete the ORB application

Assemble all the ORB components and have a complete software
Refine the code implementation and fix any bugs

Week 18: 2nd to 8th May 2010 Refinement and fix bugs

Continue fixing bugs

Week 19: 9th to 15th May, 2010 Begin deployment

Deploy ORB to a publicly accessible server
Document ORB server

Week 20: 16th to 22nd May, 2010

*To be added

Week 21: 23rd to 29th May, 2010

 *To be added

Week 22: 30th to 31st May, 2010

Meetings

Jan 19, 2010 (notes by Mtakai)

Present

- Paula Mabee
- Hilmar Lapp
- Wasila Dahdul
- Jim Bahloff
- Peter Midford
- Mtakai Ngara

Agenda

- ORB requirements
- Working modalities

Minutes

- ORB will be accessible via browsers and programmatically as REST web services.
- Term requester and Ontology gatekeepers must create an account at the site.
- A function to allow for submission of a term to multiple ontologies would useful.
- Apart from term submission, definition revision, term obsoletion and graph placement should be implemented.
- The users are categorized as:requester, ontology gatekeeper,developers, casual user and the community at large. A casual user need not register at the site.Visit requirements section for details on each of the users' role(s).
- Function for uploading a file and downloading terms to be implemented
- Have a section within ORB site for updates on latest acivities
- Integrate ORB into phenex
- Host the ORB project at sourceforge on it's page
- Have a mechanism of checking if a term already exists in an ontology
- Communication via e-mail
- ORB meetings after each use case implementation
- Code will be shared via subversion repository for team review

Action items
- Contact the Berkley group (BBPO) on ORB trial
- Have screen shots of ORB uploaded in the wiki to demonstrate functionality

Links & Resources

Early and incomplete ORB implementation in Perl by Seth Carbon. This interfaces directly with the SourceForge tracker.

Ontology Lookup services

Contacts

Name: Mtakai Ngara

E-mail: ngaravald@gmail.com

ORB term request prototype

Contents

Introduction

Background

Scope

ORB architecture overview

Use cases

Non-functional requirements

Activity

Installation

Download source code

Build

Database

Establish connection to the database

ORB database Entity-Relation(ER) diagram

Services

Get all terms in html format

Example

Get all terms in xml format

Example

Get all obsoleted terms in htm format

Example

Get all obsoleted terms in xml format

Example

Get all terms from an ontology with an ontology_identifier in HTML format

Example

Get all terms from an ontology with an ontology_identifier in xml format

Example

Get all pending terms in html format

Example

Get all pending terms in xml format

Example

Get all terms in html format using publication_identifier

Example

Get all terms in xml format using publication_identifier(publication's DOI or title)

Example

Get all terms in HTML format requested by {requester_identifier}

Example

Get all terms in xml format requested by {requester_identifier}

Example

Get all resolved terms in html format

Example

Get all resolved terms in xml format

Example

Get top terms in html format

Get top terms in xml format

Get all trial terms in html format

Example

Get all trial terms in xml format

Example

Get Term in XML format

Example

Get Term in HTML format

Example

Post term via a web form

Post term in XML format

Samples of new term requests

1. New term request with required elements only

2. New term request with all term elements

Project plan

Meetings

Links & Resources

Contacts

Navigation menu

Search