This page documents BioPortal Web Service signatures. The list below contains commonly accessed BioPortal Web services and is not intended to be an exhaustive list. If a feature you are interested in is not in the list below, please contact [mailto:support@bioontology.org BioPortal Support] to request the service or ask for more details on the full list of services.

The '''prefix''' for all production service URLs in the table below is http://rest.bioontology.org/bioportal/

* '''Note''': All NCBO REST web service calls MUST append a user identification query parameter with the pattern of "email=UserEmail" (note some clients may need to use URL encoding). For example, email=example@example.org or email=example%40example.org as an encoded email. Please start adding the user identification URL parameter to all your web service invocations. Later in 2009, we may start challenging REST service calls that do not have this parameter.

* '''Note''': ''Signatures for BioPortal services have changed in BioPortal 2.0.4 release on January 13th, 2009. This page has the new service URLs. If you have any questions, please contact [mailto:support@bioontology.org BioPortal Support].''

= Overview - Using NCBO Technology in Your Project =
See [http://www.bioontology.org/wiki/index.php/Using_NCBO_Technology_In_Your_Project Using NCBO Technology in your Project] for general information and widgets available for use.

= Code Examples =
*Code examples for the ontology web services, developed in FlexViz, is available at: https://bmir-gforge.stanford.edu/gf/project/flexviz/frs/?action=index. To see the code in action, visit the [http://keg.cs.uvic.ca/ncbo/restservicestest/TestUI.html Test User Interface] that has been set-up using the FlexViz code.

*Code examples for the [http://bioontology.org/wiki/index.php/Annotator_Web_service Annotator] and Resource Index can be found on pages specific for those tools.

= BioPortal Announce Mailing List =
To receive notices of new BioPortal releases, changes to web services, or planned downtime subscribe to the [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-annouce] list.

= Services to access ontologies and ontology versions =

== List all the latest version of ontologies ==

* '''Signature''': ./ontologies?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies?email=example@example.org

== Get a specific ontology based on a version id ==
* '''Signature''': ./ontologies/{ontology version id}?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/39002?email=example@example.org

== Download an ontology file ==
* '''Description''': Download the file (.obo, .owl) corresponding to the given ontology version id.
* '''Signature''': ./ontologies/download/{ontology version id}?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/download/39002?email=example@example.org

== Download the latest ontology file ==
* '''Description''': Download the file (.obo, .owl) corresponding to the given virtual ontology id.
* '''Signature''': ./virtual/download/{ontology id}?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/download/1090?email=example@example.org

== Get all versions of an ontology from a virtual ontology id ==
* '''Signature''': ./ontologies/versions/{ontology id}?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/versions/1104?email=example@example.org

== Get latest version of an ontology id ==
* '''Signature''': ./virtual/ontology/{ontology_id}?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1104?email=example@example.org

== List all ontology categories ==
'''NOTE''': ''To be released in BioPortal version 2.2''
* '''Signature''': ./categories?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/categories

== List all ontology groups ==
'''NOTE''': ''To be released in BioPortal version 2.2''
* '''Signature''': ./groups?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/groups

= Services to access ontology views and ontology view versions =

Since all the views on ontologies are ontologies themselves all the services that work on ontologies do
work for ontology views also with the same signature.

For example to get a specific ontology view based on a version id would be possible by using the signature:

'''./ontologies/download/{view version id}?email={email_address}'''

or for getting all view versions of a virtual view can be achieved called using the signature:

'''./ontologies/versions/{view id}?email={email_address}'''

However, there are a couple of services that are special for views:

== List all the latest version of views ==
'''NOTE''': ''To be released in BioPortal version 2.2''
* '''Signature''': ./views?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/views?email=example@example.org

== Get all versions of views from a virtual ontology id ==
'''NOTE''': ''To be released in BioPortal version 2.2''
* '''Description''': Returns all versions of views defined on the latest version a virtual ontology, grouped by virtual view ids.
* '''Signature''': ./views/versions/{ontology id}?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/views/versions/1104?email=example@example.org

= Search services =

== Search BioPortal ==
* '''Signature''': ./search/{query}[?{optional args}]&email={email_address}
* '''Alt Signature''': ./search/?query={uri-encoded query}[&{optional args}]&email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/search/Gene?email=example@example.org
* You can use multiple query terms, separated by a space, for example: [http://rest.bioontology.org/bioportal/search/lung%20disease http://rest.bioontology.org/bioportal/search/lung disease?email=example@example.org]
* '''Optional arguments:'''
** ontologyids=<ontologyid>,<ontologyid>… - limits the search to specific ontologies (default: all ontologies)
** isexactmatch=[1/0] – match the entire concept name (default: 0)
** includeproperties=[1/0] – include attributes in the search (default: 0)
** pagesize=<pagesize> - the number of results to display in a single request (default: all)
** pagenum=<pagenum> - the page number to display (pages are calculated using <total results>/<pagesize>) (default: 1)
** maxnumhits=<maxnumhits> - the maximum number of top matching results to return (default: 1000)
** subtreerootconceptid=<uri-encoded conceptid> - narrow the search to concepts residing in a sub-tree, where the "subtreerootconceptid" is the root node. This feature requires a SINGLE <ontologyid> passed in using the "onotlogyids" parameter.
* '''Description:'''
The search attempts to match both partial and exact queries, giving more weight to exact matches. In single-word searches, the wildcard character (*) is automatically appended to the end of the word. For example, searching for "lun" would return all concepts whose name contains a word that begins with "lun" (i.e. "Lung", "Murine Lunate Bone", "Base of the Lung", etc).

In phrase searches (multiple words), the wildcard character is appended to the end of each word. For example, searching for "cut mela" would return all concepts whose name contains a word starting with "cut", followed by any word that begins with "mela" (i.e. "Cutaneous Melanoma", "Metastatic Non-Cutaneous Melanoma", "Cutaneous Melanoma Clinical TNM Finding", etc).

* '''Example''': http://rest.bioontology.org/bioportal/search/software/?ontologyids=1104&isexactmatch=1&email=example@example.org
* '''Sample Output''':
<pre>
<?xml version="1.0" encoding="UTF-8" ?>
<success>
<accessedResource>
/bioportal/search/cutaneous%20mela
</accessedResource>
<accessDate>2009-05-07 16:17:46.182 PDT</accessDate>
<data>
<page>
<pageNum>1</pageNum>
<numPages>1</numPages>
<pageSize>3</pageSize>
<numResultsPage>3</numResultsPage>
<numResultsTotal>3</numResultsTotal>
<contents
class="org.ncbo.stanford.bean.search.SearchResultListBean">
<searchResultList>
<searchBean>
<ontologyVersionId>39715</ontologyVersionId>
<ontologyId>1136</ontologyId>
<ontologyDisplayLabel>
Experimental Factor Ontology
</ontologyDisplayLabel>
<recordType>
RECORD_TYPE_PREFERRED_NAME
</recordType>
<conceptId>
http://www.ebi.ac.uk/efo/EFO_0000389
</conceptId>
<conceptIdShort>EFO_0000389</conceptIdShort>
<preferredName>
cutaneous melanoma
</preferredName>
<contents>cutaneous melanoma</contents>
</searchBean>
<searchBean>
<ontologyVersionId>39478</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>
NCI Thesaurus
</ontologyDisplayLabel>
<recordType>
RECORD_TYPE_PREFERRED_NAME
</recordType>
<conceptId>
http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Cutaneous_Melanoma
</conceptId>
<conceptIdShort>
Cutaneous_Melanoma
</conceptIdShort>
<preferredName>
Cutaneous Melanoma
</preferredName>
<contents>Cutaneous Melanoma</contents>
</searchBean>
<searchBean>
<ontologyVersionId>39833</ontologyVersionId>
<ontologyId>1009</ontologyId>
<ontologyDisplayLabel>
Human disease
</ontologyDisplayLabel>
<recordType>
RECORD_TYPE_PREFERRED_NAME
</recordType>
<conceptId>DOID:2418</conceptId>
<conceptIdShort>DOID:2418</conceptIdShort>
<preferredName>
Cutaneous Melanocytic Neoplasm
</preferredName>
<contents>
Cutaneous Melanocytic Neoplasm
</contents>
</searchBean>
</searchResultList>
<ontologyHitList>
<ontologyHitBean>
<ontologyVersionId>39715</ontologyVersionId>
<ontologyId>1136</ontologyId>
<ontologyDisplayLabel>
Experimental Factor Ontology
</ontologyDisplayLabel>
<numHits>1</numHits>
</ontologyHitBean>
<ontologyHitBean>
<ontologyVersionId>39833</ontologyVersionId>
<ontologyId>1009</ontologyId>
<ontologyDisplayLabel>
Human disease
</ontologyDisplayLabel>
<numHits>1</numHits>
</ontologyHitBean>
<ontologyHitBean>
<ontologyVersionId>39478</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>
NCI Thesaurus
</ontologyDisplayLabel>
<numHits>1</numHits>
</ontologyHitBean>
</ontologyHitList>
</contents>
</page>
</data>
</success>
</pre>

= Term services =
(formerly referred to as Concept services)

== Get term ==
* '''Signature''': ./concepts/{ontology version id}/{concept id}?email={email_address}
* '''Alt Signature''': ./concepts/{ontology version id}?conceptid={uri-encoded concept id}&email={email_address}
* '''Optional arguments:'''
** light=[1/0] - when set to 1, returns the "light" version of XML with only a basic info for the concept and its immediate children
** norelations=[1/0] - when set to 1, returns only the requested term information (id, label, fullid, type, synonyms, definitions) without the "relations" map. This is useful when you need to quickly retrieve just the base information about a term.
* '''Examples''':
http://rest.bioontology.org/bioportal/concepts/39002/BRO:Resource?email=example@example.org 
http://rest.bioontology.org/bioportal/concepts/41009?conceptid=http%3A%2F%2Fihtsdo.owl%2Fsnomedct%2Fanatomy%23302509004&light=0&email=example@example.org 
http://rest.bioontology.org/bioportal/concepts/41009?conceptid=http%3A%2F%2Fihtsdo.owl%2Fsnomedct%2Fanatomy%23302509004&norelations=1&email=example@example.org
* '''Sample Output''':
<pre>
<?xml version="1.0" encoding="UTF-8" ?>
<success>
<accessedResource>/bioportal/concepts/40644/</accessedResource>
<accessDate>2009-12-16 10:06:10.727 PST</accessDate>
<data>
<classBean>
<id>Melanoma</id>
<fullId>http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Melanoma</fullId>
<label>Melanoma</label>
<type>Class</type>
<synonyms>
<string>Malignant Melanoma</string>
<string>Melanoma</string>
<string>melanoma</string>
</synonyms>
<definitions>
<string>A malignant, usually aggressive tumor composed of atypical,
neoplastic melanocytes.</string>
</definitions>
<relations>
<entry>
<string>UMLS_CUI</string>
<list>
<string>C0025202</string>
</list>
</entry>
<entry>
<string>owl:equivalentClass</string>
<list>
<string>'Common Neoplasm' and 'Melanocytic Neoplasm' and
(Disease_Has_Abnormal_Cell only 'Melanoma Cell')</string>
</list>
</entry>
<entry>
<string>ALT_DEFINITION</string>
<list>
<string>
<def-source>NCI-GLOSS</def-source>
<def-definition>A form of skin cancer that arises in
melanocytes, the cells that produce pigment.</def-definition>
</string>
</list>
</entry>
<entry>
<string>ICD-O-3_Code</string>
<list>
<string>8720/3</string>
</list>
</entry>
<entry>
<string>Semantic_Type</string>
<list>
<string>Neoplastic Process</string>
</list>
</entry>
<entry>
<string>SubClass</string>
<list>
<classBean>
<id>Non-Cutaneous_Melanoma</id>
<fullId>http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Non-Cutaneous_Melanoma</fullId>
<label>Non-Cutaneous Melanoma</label>
<type>Class</type>
<synonyms>
<string>Extracutaneous Melanoma</string>
<string>Non-Cutaneous Melanoma</string>
</synonyms>
<definitions>
<string>Melanoma is a malignant tumor of melanocytes,
cells that are derived from the neural crest.</string>
</definitions>
<relations>
<entry>
<string>code</string>
<list>
<string>C8711</string>
</list>
</entry>
</relations>
</classBean>
</list>
</entry>
</relations>
</classBean>
</data>
</success>
</pre>

== Get all root terms for an ontology version id ==
* '''Signature''': ./concepts/{ontology version id}/root?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/concepts/39002/root?email=example@example.org

== Get term for latest ontology version id ==
'''NOTE''': ''This signature will change in BioPortal release 2.2''
* '''New Signature''': ./virtual/ontology/{ontology id}/{concept id}?email={email_address}
* '''New Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1104/BRO:Resource?email=example@example.org

* '''Signature''': ./virtual/{ontology id}/{concept id}?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/1104/BRO:Resource?email=example@example.org

== Get all terms using the specific ontology version id ==

'''NOTE:''' 'Get all terms' service has changed. The new signature and examples are reflected below. See [[#Changes_to_the_Get_all_terms_service]] for more information.

* '''Signature''': ./concepts/{ontology version id}/all?pagesize={pagesize}&pagenum={pagenum}&email={email_address}
* '''Examples''': A preview of the new service can be seen on the NCBO staging site:
** http://rest.bioontology.org/bioportal/concepts/40644/all?pagesize=50&pagenum=1&email=example@example.org
** http://rest.bioontology.org/bioportal/concepts/42431/all?pagesize=50&pagenum=500&email=example@example.org
* '''Arguments:'''
** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
** '''pagenum:''' An integer indicating which page of results to return.

== Get all terms using the virtual ontology id ==

'''NOTE:''' 'Get all terms' service has changed. The new signature and examples are reflected below. See [[#Changes_to_the_Get_all_terms_service]] for more information.

* '''Signature''': ./virtual/ontology/{ontology id}/all?pagesize={pagesize}&pagenum={pagenum}&email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1104/all?&pagesize=50&pagenum=1&email=example@example.org
* '''Arguments:'''
** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
** '''pagenum:''' An integer indicating which page of results to return.

== Changes to the Get all terms service ==

Starting in BioPortal 2.3.1 (released March 15, 2010), the 'Get all terms' service has changed to support speedier and more complete term retrieval. To support this, several changes to the response XML and service signature are being made. Please see the following notes to update your existing applications to support these changes.

* '''Examples''': A preview of the new service can be seen on the NCBO staging site:
** http://rest.bioontology.org/bioportal/concepts/40644/all?pagesize=50&pagenum=1
** http://rest.bioontology.org/bioportal/concepts/42431/all?pagesize=50&pagenum=500

* '''Signature'''
** '''New parameters:''' Previously, offset and limit were used to control pagination of results. These parameters have been replaced as follows:
*** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
*** '''pagenum:''' An integer indicating which page of results to return.

* '''Response''': The structure of the new 'Get all terms' response XML has been brought into line with other BioPortal REST term services. In addition, to assist in paging through result sets, 'page' metadata is provided. A list of classBeans is provided in the classBeanResultList element, which includes each classes' set of relations (examples of relations include SuperClass, SubClass, and rdfs:label). Please see the example below for a full demonstration of the new response.

= Instance Services =

== Get all direct instances for a given term ==
* '''Signature''': ./concepts/instances/{ontlogyVersionId}[?conceptid={uri-encoded concept id}[&{optional args}]&email={email_address}
* '''Optional arguments:'''
** pagesize=<pagesize> - the number of results to display in a single request (default: all)
** pagenum=<pagenum> - the page number to display (pages are calculated using <total results>/<pagesize>) (default: 1)

* '''Example''': http://rest.bioontology.org/bioportal/concepts/instances/38801?conceptid=SubstrateType&pagesize=1&pagenum=1&email=example@example.org
* '''Description''': returns all direct instances for a given term.
* '''Sample Output:'''
<pre>
<?xml version="1.0" encoding="UTF8" ?>
<success>
<accessedResource>/bioportal/concepts/instances/38801
</accessedResource>
<accessDate>20100408 18:17:21.226 PDT</accessDate>
<data>
<page>
<pageNum>1</pageNum>
<numPages>5</numPages>
<pageSize>1</pageSize>
<numResultsPage>1</numResultsPage>
<numResultsTotal>5</numResultsTotal>
<contents class="org.ncbo.stanford.bean.concept.InstanceBeanResultListBean">
<list>
<instanceBean>
<id>unknown_substrate_type</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unknown_substrate_type
</fullId>
<label>unknown_substrate_type</label>
<relations>
<entry>
<propertyBean>
<id>rdf:type</id>
<fullId>http://www.w3.org/1999/02/22rdfsyntaxns#type
</fullId>
<label>rdf:type</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>:NAME</id>
<fullId>:NAME</fullId>
<label>:NAME</label>
<relations />
</propertyBean>
<list>
<string>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unknown_substrate_type
</string>
</list>
</entry>
<entry>
<propertyBean>
<id>unique_identifier</id>

<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unique_identifier
</fullId>
<label>unique_identifier</label>
<relations />
</propertyBean>
<list>
<string>MO_484</string>
</list>
</entry>
<entry>
<propertyBean>
<id>:DIRECTTYPE</id>
<fullId>:DIRECTTYPE</fullId>
<label>:DIRECTTYPE</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>rdfs:comment</id>
<fullId>http://www.w3.org/2000/01/rdfschema#comment
</fullId>
<label>rdfs:comment</label>
<relations />
</propertyBean>

<list>
<string>SubstrateType of unknown type.</string>
</list>
</entry>
</relations>
<instanceType>
<list>
<classBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</contents>
</page>
</data>
</success>
</pre>

== Get an instance and its property/value pairs ==
* '''Signature''': ./instance/{ontlogyVersionId}[?instanceid={instanceid}&email={email_address}]

* '''Example''': http://rest.bioontology.org/bioportal/instance/38801?instanceid=glass&email=example@example.org
* '''Description''': returns information about an instance and a list of property/value pairs.
* '''Sample Output:'''
<pre>
<?xml version="1.0" encoding="UTF8" ?>
<success>
<accessedResource>/bioportal/instance/38801
</accessedResource>
<accessDate>20100408 18:10:48.760 PDT</accessDate>
<data>
<instanceBean>
<id>glass</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#glass
</fullId>
<label>glass</label>
<relations>
<entry>
<propertyBean>
<id>:NAME</id>
<fullId>:NAME</fullId>
<label>:NAME</label>
<relations />
</propertyBean>
<list>
<string>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#glass
</string>
</list>
</entry>
<entry>
<propertyBean>
<id>unique_identifier</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unique_identifier
</fullId>
<label>unique_identifier</label>
<relations />
</propertyBean>
<list>
<string>MO_742</string>
</list>
</entry>
<entry>
<propertyBean>
<id>rdfs:comment</id>
<fullId>http://www.w3.org/2000/01/rdfschema#comment
</fullId>
<label>rdfs:comment</label>
<relations />
</propertyBean>
<list>
<string>The array is made on a glass slide.</string>
</list>
</entry>
<entry>
<propertyBean>
<id>:DIRECTTYPE</id>
<fullId>:DIRECTTYPE</fullId>
<label>:DIRECTTYPE</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>rdf:type</id>
<fullId>http://www.w3.org/1999/02/22rdfsyntaxns#type
</fullId>
<label>rdf:type</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
</relations>
<instanceType>
<list>
<classBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</data>
</success>
</pre>

= Hierarchy Services =

'''NOTE: To see which ontology versions have been processed for use with the Hierarchy services, see http://rest.bioontology.org/obs/ontologies'''

== Get parents/children of a given concept in a specific ontology version ==
* '''Signature''': ./concepts/[parents|children]/{ontlogyVersionId}/{conceptId}[?email={email_address}&{optional args}]

* '''Example''': http://rest.bioontology.org/bioportal/concepts/parents/42331/Melanoma?email=example@example.org
* '''Example''': http://rest.bioontology.org/bioportal/concepts/children/42331/Melanoma?email=example@example.org
* '''Optional arguments:'''
** level=<integer> - limits results to a given level in the hierarchy
** offset=<integer> – results offset (used for pagination)
** limit=<integer> – limits the number of results
** '''Example''': http://rest.bioontology.org/bioportal/concepts/parents/42331/Melanoma?level=1&offset=1&limit=10&email=example@example.org
* '''Description''': returns all parents of the concept, with the level indicating how far away the parent is from the concept. For instance, direct parents have level 1; their direct parents have level 2, etc. If no level is specified, the service returns all the levels up to the root. If the level is specified, the service returns only the parents at that level.
* '''Sample Output:'''
<pre>
<?xml version="1.0" encoding="UTF8" ?>
<success>
<accessedResource>/bioportal/concepts/parents/42331/Melanoma
</accessedResource>
<accessDate>20100408 17:58:14.230 PDT</accessDate>
<data>
<list>
<classBean>
<ontologyVersionId>42331</ontologyVersionId>
<id>Common_Neoplasm</id>
<fullId>
http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Common_Neoplasm
</fullId>
<label>Common Neoplasm</label>
<synonyms>
<string>Common Tumor</string>
<string>Common Neoplasm</string>
</synonyms>
<relations>
<entry>
<string>Level</string>
<int>1</int>
</entry>
</relations>
</classBean>
<classBean>
<ontologyVersionId>42331</ontologyVersionId>
<id>Melanocytic_Neoplasm</id>
<fullId>
http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Melanocytic_Neoplasm
</fullId>
<label>Melanocytic Neoplasm</label>
<synonyms>
<string>Melanocytic Neoplasm</string>
</synonyms>
<relations>
<entry>
<string>Level</string>
<int>1</int>
</entry>
</relations>
</classBean>
</list>
</data>
</success>
</pre>

== Get parents/children of a given concept in the latest version of a given ontology ==
* '''Signature''': ./virtual/[parents|children]/{ontlogyId}/{conceptId}[?email={email_address}&{optional args}]
* '''Example''': http://rest.bioontology.org/bioportal/virtual/parents/1032/Melanoma?email=example@example.org
* '''Example''': http://rest.bioontology.org/bioportal/virtual/children/1032/Melanoma?email=example@example.org
* '''Optional arguments:'''
** level=<integer> - limits results to a given level in the hierarchy
** offset=<integer> – results offset (used for pagination)
** limit=<integer> – limits the number of results
** '''Example''': http://rest.bioontology.org/bioportal/virtual/parents/1032/Melanoma?level=1&offset=1&limit=3&email=example@example.org
* '''Description''': The same as the previous services, but takes an ontology id and returns parents from the latest version of that ontology.

== Get paths to roots/leaves from a concept in a specific ontology version ==
* '''Signature''': ./concepts/[rootpath|leafpath]/{ontologyVersionId}/{conceptId}[?email={email_address}&{optional args}]
**NOTE: To see which ontology versions have been processed for use with the Hierarchy services, see http://rest.bioontology.org/obs/ontologies
* '''Example''': http://rest.bioontology.org/bioportal/concepts/rootpath/42331/Melanoma?email=example@example.org
* '''Example''': http://rest.bioontology.org/bioportal/concepts/leafpath/42331/Melanoma?email=example@example.org
* '''Optional arguments:'''
** offset=<integer> – results offset (used for pagination)
** limit=<integer> – limits the number of results
* '''Description''': return a set of path to the roots (resp. leaves) for a given concept in a specific ontology version. Paths are represented as a list of conceptIds, separated by periods (.) The first one in the list is a root (resp. leaf) in the hierarchy; the last one in the list is the direct parent (resp. direct child) of the concept.
* '''Sample Output:'''
<pre>
<?xml version="1.0" encoding="UTF-8" ?>
<success>
<accessedResource>
/bioportal/concepts/rootpath/40644/Melanoma
</accessedResource>
<accessDate>2009-04-21 11:06:23.439 PDT</accessDate>
<data>
<list>
<classBean>
<ontologyVersionId>40644</ontologyVersionId>
<id>Melanoma</id>
<relations>
<entry>
<string>Path</string>
<string>
Getings_and_Disorders_Kind.Diseases_Disorders_and_Getings.Diseases_and_Disorders.Neoplasm.Neoplasm_by_Morphology.Melanocytic_Neoplasm
</string>
</entry>
</relations>
</classBean>
<classBean>
<ontologyVersionId>40644</ontologyVersionId>
<id>Melanoma</id>
<relations>
<entry>
<string>Path</string>
<string>
Getings_and_Disorders_Kind.Diseases_Disorders_and_Getings.Diseases_and_Disorders.Neoplasm.Neoplasm_by_Special_Category.Common_Neoplasm
</string>
</entry>
</relations>
</classBean>
</list>
</data>
</success>
</pre>

== Get paths to root/leaves from a concept in the latest version of a given ontology ==
* '''Signature''': ./virtual/[rootpath|leafpath]/{ontologyId}/{conceptId}[?email={email_address}&{optional args}]
* '''Example''': http://rest.bioontology.org/bioportal/virtual/rootpath/1032/Melanoma?email=example@example.org
* '''Example''': http://rest.bioontology.org/bioportal/virtual/leafpath/1032/Melanoma?email=example@example.org
* '''Optional arguments:'''
** offset=<integer> – results offset (used for pagination)
** limit=<integer> – limits the number of results
* '''Description''': The same as the previous services, but takes an ontology id and returns parents from the latest version of that ontology.

== Get siblings of a given concept in a specific ontology version ==
* '''Signature''': ./concepts/siblings/{ontlogyVersionId}/{conceptId}?level=<level>&email={email_address}&[&{optional args}]
**NOTE: To see which ontology versions have been processed for use with the Hierarchy services, see http://rest.bioontology.org/obs/ontologies
* '''Example''': http://rest.bioontology.org/bioportal/concepts/siblings/42331/Melanoma?level=1&email=example@example.org
* '''Required arguments:'''
** level=<integer> - limits results to a given level in the hierarchy
* '''Optional arguments:'''
** offset=<integer> – results offset (used for pagination)
* '''Description''': returns the set of sibling concepts at the given level (i.e., siblings that have the same direct (level=1), grand-parents (level=2), etc.) for a given concept.
* '''Sample Output:'''
<pre>
<?xml version="1.0" encoding="UTF8" ?>
<success>
<accessedResource>/bioportal/concepts/siblings/42331/Melanoma
</accessedResource>
<accessDate>20100408 18:06:16.868 PDT</accessDate>
<data>
<list>
<classBean>
<ontologyVersionId>42331</ontologyVersionId>
<id>Common_Germ_Cell_Neoplasm</id>
<fullId>
http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Common_Germ_Cell_Neoplasm
</fullId>
<label>Common Germ Cell Tumor</label>
<synonyms>
<string>Common Germ Cell Tumor</string>
<string>Common Germ Cell Neoplasm</string>
</synonyms>
<relations>
<entry>
<string>Level</string>
<int>1</int>
</entry>
</relations>
</classBean>
<classBean>
<ontologyVersionId>42331</ontologyVersionId>
<id>Common_Hematopoietic_Neoplasm</id>
<fullId>
http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Common_Hematopoietic_Neoplasm
</fullId>
<label>Common Hematopoietic Neoplasm</label>
<synonyms>
<string>Common Hematopoietic Neoplasm</string>
<string>Common Hematopoietic Tumor</string>
</synonyms>
<relations>
<entry>
<string>Level</string>
<int>1</int>
</entry>
</relations>
</classBean>
</list>
</data>
</success>
</pre>

== Get siblings of a given concept in the latest version of a given ontology ==
* '''Signature''': ./virtual/siblings/{ontlogyId}/{conceptId}?level=<level>&email={email_address}&[&{optional args}]
* '''Example''': http://rest.bioontology.org/bioportal/virtual/siblings/1032/Melanoma?level=1&email=example@example.org
* '''Required arguments:'''
** level=<integer> - limits results to a given level in the hierarchy
* '''Optional arguments:'''
** offset=<integer> – results offset (used for pagination)
* '''Description''': The same as the previous service, but takes an ontology id and returns parents from the latest version of that ontology.

= RDF Dump Service =

This service allows you to output a given ontology from BioPortal in the form of a N3 RDF file. This RDF dump will preserve original ontology names space and term URIs.

Coming soon ...

= Bio2RDF Dump Service =

This service allows you to output a given ontology from BioPortal in the form of a N3 RDF file conforming to the requirements for integrating into the [http://sourceforge.net/projects/bio2rdf/ Bio2RDF] collection.

* '''Signature''': ./ontology/dump_n3/{ontlogyVersionId}?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/ontology/dump_n3/40865?email=example@example.org

= Annotator Service =

The NCBO Annotator is a Web service that can be used to annotate text metadata with biomedical ontology concepts. The concepts are from ontologies in BioPortal and includes the Unified Medical Language System (UMLS) Metathesaurus, OBO Foundry candidate ontologies and many others.

The Annotator can be tested via a Web interface available through [http://bioportal.bioontology.org/annotate BioPortal]. For more information on using the Annotator Web service, see: http://bioontology.org/wiki/index.php/Annotator_Web_service.

= Resource Index Service =

The Resource Index provides a mechanism to search for biomedical data based on ontology concepts. For more information on using the Resource Index service, see http://www.bioontology.org/wiki/index.php/Resource_Index.

= Prototypes =

== Notes Service ==
* '''Signature''': ./notes/ont/{ontology_id}
* '''Example''': http://bioportal.bioontology.org/notes/ont/1104
* '''Required arguments:'''
** ontology_id
* '''Description''': returns BioPortal Notes as XML. This is a prototype web service, for updates subscribe to [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-announce]
* '''Sample Output:'''
<pre>
<records type="array">
<record>
<comment>
I note that clinical data is specifically defined not to include clinical trial data. So is anyone already thinking about where at a high level subtrees might be added to deal with clinical trial data and clinical trial management systems? Or is it premature to do that? This is for the CTSAs.
</comment>
<created-at>2008-08-07 11:21:00</created-at>
<ontology-id>1104</ontology-id>
<updated-at>2008-08-07 11:21:00</updated-at>
<mapping-id nil="true"/>
<subject>Including clinical trial data as clinical data</subject>
<id>75</id>
<user-id>38143</user-id>
<parent-id nil="true"/>
<ontology-version-id>38407</ontology-version-id>
<concept-id>BRO:Clinical_Data</concept-id>
<note-type>Question</note-type>
</record>
<record>
<comment> Not sure I follow the argument here.  Clinical trial data is covered under PHI so no distinction there.  Data generated in the course of delivering routine standard of care may be needed in the course of a clinical trial.  Does this make clinical trial data an overlapping superset of clinical data?
</comment>
<created-at>2008-08-07 11:24:04</created-at>
<ontology-id>1104</ontology-id>
<updated-at>2008-08-07 11:24:04</updated-at>
<mapping-id nil="true"/>
<subject>RE:Including clinical trial data as clinical data</subject>
<id>76</id>
<user-id>38144</user-id>
<parent-id>75</parent-id>
<ontology-version-id>38407</ontology-version-id>
<concept-id>BRO:Clinical_Data</concept-id>
<note-type>Comment</note-type>
</record>
</records>
</pre>

== Mapping Service ==
* '''Signature''': ./mappings/service/{ontology_id}/{concept_id}
* '''Example''': http://bioportal.bioontology.org/mappings/service/1083/
* '''Required arguments:'''
** ontology_id
* '''Optional arguments:'''
** concept_id=if concept_id is included, the service will return all mappings to and from the given concept
* '''Description''': returns BioPortal Mappings as XML. This is a prototype web service, for updates subscribe to [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-announce]
* '''Sample Output:'''
<pre>
<hash>
<mapping-from type="array">
<mapping-from>
<comment nil="true"></comment>
<map-type>Human</map-type>
<created-at>2008-05-09 08:25:23</created-at>
<updated-at>2008-08-05 17:26:06</updated-at>

<source-name>Carbon</source-name>
<source-ont-name>NanoParticle Ontology (NPO)</source-ont-name>
<destination-id>CHEBI:27594</destination-id>
<id>98216</id>
<user-id>38139</user-id>
<relationship-type nil="true"></relationship-type>

<destination-ont-name>Chemical entities of biological interest</destination-ont-name>
<destination-name>Carbon</destination-name>
<map-source nil="true"></map-source>
<destination-ont>1007</destination-ont>
<source-id>Carbon</source-id>
<destination-version-id>38377</destination-version-id>

<source-version-id>29531</source-version-id>
<source-ont>1083</source-ont>
</mapping-from>
<mapping-from>
<comment nil="true"></comment>
<map-type>Human</map-type>
<created-at>2008-05-09 08:27:05</created-at>

<updated-at>2008-08-05 17:26:06</updated-at>
<source-name>Gold</source-name>
<source-ont-name>NanoParticle Ontology (NPO)</source-ont-name>
<destination-id>CHEBI:29287</destination-id>
<id>98218</id>
<user-id>38139</user-id>

<relationship-type nil="true"></relationship-type>
<destination-ont-name>Chemical entities of biological interest</destination-ont-name>
<destination-name>Gold</destination-name>
<map-source nil="true"></map-source>
<destination-ont>1007</destination-ont>
<source-id>Gold</source-id>
<destination-version-id>38377</destination-version-id>

<source-version-id>29531</source-version-id>
<source-ont>1083</source-ont>
</mapping-from>
</mapping-from>
<mapping-to type="array">
<mapping-to>
<comment nil="true"></comment>
<map-type>Human</map-type>

<created-at>2008-05-09 08:35:27</created-at>
<updated-at>2008-08-05 17:26:06</updated-at>
<source-name>Carbohydrate</source-name>
<source-ont-name>NanoParticle Ontology (NPO)</source-ont-name>
<destination-id>Carbohydrate</destination-id>
<id>98219</id>

<user-id>38139</user-id>
<relationship-type nil="true"></relationship-type>
<destination-ont-name>NanoParticle Ontology (NPO)</destination-ont-name>
<destination-name>Carbohydrate</destination-name>
<map-source nil="true"></map-source>
<destination-ont>1083</destination-ont>
<source-id>Carbohydrate</source-id>

<destination-version-id>29531</destination-version-id>
<source-version-id>29531</source-version-id>
<source-ont>1083</source-ont>
</mapping-to>
</mapping-to>
</hash>

</pre>



= XML Schema Definitions for the REST services =

XML Schema for [[#Term_services|concept]] and [[#Hierarchy_Services|hierarchy]] services is [[Media:ClassBean.xsd.zip|available]] (courtesy Eamonn Maguire).

2009-10-22T00:51:40Z

Noy: /* Representing marginal notes and reviews */

This document is part of [[BioPortal_Metadata|a series of documents describing the representation of metadata in BioPortal]]

----

= The General Architecture For Representing Metadata in BioPortal =

[[image:Ontology-knowledgebase.jpg|frame|'''The general architecture of the metadata representation in BioPortal.''' There are two main components: (1) the
[http://protege.stanford.edu/ontologies/metadata/BioPortalMetadata.owl BioPortal Metadata ontology] defines the types of metadata that BioPortal represents; (2) The [http://protege.stanford.edu/ontologies/metadata/BioPortalMetadataKnowledgeBase.owl BioPortal Metadata knowledge base] imports the BioPortal Metadata ontology and contains the instances of its classes corresponding to the specific metadata values.]]
[[image:Ontologies.jpg|frame|'''The set of ontologies and key classes for representing metadata in Bioportal'''. The BioPortal Metadata ontology is just another ontology in BioPortal. It imports the OMV ontology, the Protege changes ontology, and the Protege mappings ontology. The figure shows some key classes in the Bioportal Metadata ontology in the ones it imports, as well as some key relations between them.]]
[[image:Instances.jpg|frame|'''Example of Metadata instances.''' Metadata instances describing two versions of the FMA and a view of the FMA]]

We describe the types of metadata that BioPortal has and the representation of this metadata in the [http://protege.stanford.edu/ontologies/metadata/BioPortalMetadata.owl '''BioPortal Metadata ontology''']. This ontology contains classes corresponding to the description of ontology metadata, mappings, reviews, marginal notes, projects, and users. The classes define specific properties for each type of metadata and the links between them.

The concrete metadata that users contribute to BioPortal is represented in the [http://protege.stanford.edu/ontologies/metadata/BioPortalMetadataKnowledgeBase.owl '''BioPortal Metadata Knowledge Base'''] (see the [[#instances|example in the figure]]). This knowledge base does not define any classes, it simply imports the BioPortal Metadata Ontology (the [[#architecture|Architecture figure shows the overall architecture]]). The knowledge base contains instances of the classes defined in that ontology.
When a service or another API call requests metadata information, the implementation queries the BioPortal Metadata Knowledge Base for the corresponding instance information.

We process the BioPortal Metadata ontology in exactly the same way as we process all other ontologies in BioPortal: it is represented in the BioPortal index, users can comment on it and reference it. The BioPortal Metadata Knowledge Base is also an OWL ontology, but it has a special status and BioPortal user interface does not directly display it in Bioportal. Instead, it queries it whenever it needs to access any metadata

The BioPortal Metadata Ontology ontology imports three other OWL ontologies:
# The '''Ontology Metadata Vocabulary (OMV)''' describes most of the metadata for ontologies themselves (e.g., domain, author, version number, ontology language, etc.)
# The '''Protégé Changes ontology''' provides the definitions for generic annotations (the <tt>Annotation</tt> class) and ontology components that they annotate.
# The '''Mappings ontology''' provides vocabulary for describing one-to-one mappings between concepts and corresponding metadata

The BioPortal Metadata ontology, by importing these three ontologies, can use all the classes and definitions from there and extend these definitions. The specific metadata is represented as instances of corresponding classes.

= The BioPortal Metadata Ontology =

The following ontologies are available for download and direct access at the Protege web site:
* '''[http://protege.stanford.edu/ontologies/metadata/BioPortalMetadata.owl The BioPortal Metadata ontology]'''
* '''[http://protege.stanford.edu/ontologies/ChAO/changes.rdfs The Changes ontology]'''
* '''[http://protege.stanford.edu/ontologies/mappings/mappings.rdfs The Mappings ontology]'''

= Classes and properties in the BioPortal Metadata ontology =
We will now describe some key classes used to represent metadata.

== Representing ontology metadata and provenance information ==

The metadata about ontologies themselves is represented mostly using the OMV vocabulary (namespace prefix “OMV”). OMV is the ontology developed jointly with the NeON consortium and accounts for much of the ontology metadata, including provenance information, static values (number of classes, etc.), licensing information, and so on.

=== The class <tt>OMV:Ontology</tt> ===
The main class in OMV is <tt>'''OMV:Ontology'''</tt>. It contains a set of metadata for a particular version of the ontology. Some properties of interest, among others, are:

* <tt>name</tt>
* <tt>acronym </tt>
* <tt>creationDate</tt>
* <tt>description</tt> (range: <tt>String</tt>)
* <tt>documentation</tt> (range: <tt>URL</tt>)
* <tt>endorsedBy</tt> (range: <tt>OMV:Party</tt>)
** one of the instances to fill in this value is OBOFoundry, an instance of <tt>OMV:Organisation</tt>
* <tt>domain</tt>
* <tt>ontologyLanguage</tt>
* <tt>keyClasses</tt>
* <tt>keywords</tt>
* <tt>...</tt>

We also add some instances for ontology engineering tools and methodologies to account for OBO ontologies (OBO-Edit tool and the DAG ontology structure) and to include the OBO Foundry, caBIG, and others as endorsing organizations.

=== The class <tt>VirtualOntology</tt> ===
A class <tt>'''VirtualOntology'''</tt> collects the information about each virtual ontology in the repository, all its versions and views. There is one instance of the <tt>VirtualOntology</tt> class for each virtual ontology in BioPortal. Each such instance has the following properties:
* <tt>currentVersion</tt> (range: <tt>OMV:Ontology</tt>) is a pointer to the metadata describing the current version of the ontology;
* <tt>ontologyName</tt> (range: <tt>String</tt>) provides a name for the ontology (e.g., “NCI Thesaurus"); we don’t technically have to have it as we can get it from the current version, but it may be useful to have it here for convenience (but need to remember to update it)
* <tt>virtualURI</tt> (range: <tt>URI</tt>) provide a virtual URI for this ontology; it could also be an ontology ID, as used in BioPortal now
* <tt>hasView</tt> (range <tt>OMV:Ontology</tt>) provides a collection of instances of the <tt>OMV:Ontology</tt> class corresponding to the views of this virtual ontology
* <tt>hasVersion</tt> (range <tt>OMV:Ontology</tt>) provides a collection of instances of the <tt>OMV:Ontology</tt> class corresponding to the versions of this virtual ontology

=== The class <tt> Project </tt>===
A class <tt>'''Project'''</tt> contains the information about each project. This information is represented as instances of the <tt> Project </tt> class. Each project has the following properties:
* <tt>projectName</tt> (range: <tt>String</tt>)
* <tt>description</tt> (range: <tt>String</tt>)
* <tt>institution</tt> (range: <tt>String</tt>)
* <tt>homepage</tt> (range: <tt>URL</tt>)
* <tt>administrator</tt> (range: <tt>User</tt>)
* <tt>hasContactInformation</tt> (range: <tt>String</tt>)
* <tt>usesOntologies</tt> (range: <tt>VirtualOntology</tt>)

=== The class <tt>BioPortalUser</tt> ===

A class <tt>BioPortalUser</tt> extends the class <tt>OMV:Person</tt> and <tt>foaf:Person</tt>. In addition, each user has the following properties:
* <tt>userName</tt> (range: <tt>String</tt>)
* <tt>createdReviews</tt> (range: <tt>Review</tt>)
* <tt>createdMarginalNotes</tt> (range: <tt>changes:Annotation</tt>)
* <tt>createdMappings</tt> (range: <tt>mappings:Mapping</tt>)

== Representing marginal notes ==

'''Marginal notes and ontology reviews''' instances contain the content of the notes and reviews, their types, and the provenance information for them. The '''Protégé Changes ontology''' provides several key classes for representing ontology components and annotations and we extend these classes with several classes and properties relevant to BioPortal:

[[image:Change-classes.jpg|frame|'''Classes for annotations and objects that can be annotated.''' Classes in white boxes are imported from the Protégé changes ontology. Classes in grey boxes are added in the BioPortal Metadata ontology.]]

The classes and properties below describe annotations

=== The class <tt>changes:AnnotatableThing</tt> ===

The class <tt>changes:AnnotatableThing</tt> represents anything that can be annotated, including ontology components, ontologies themselves, mappings, other annotations, etc. This class has the following key property:
* <tt>changes:associatedAnnotations</tt> (range: <tt>changes:Annotation</tt>) links to all annotations that are associates with this object

The subclasses of <tt>changes:AnnotatableThing</tt>:
* <tt>changes:OntologyComponent</tt> (represents classes and properties; we will use this class to encapsulate how we address individual classes and properties)
* the class <tt>Ontology</tt> added in the BioPortal Metadata ontology to represent ontology as a whole as a target of a review
* <tt>changes:Annotation</tt>, includes marginal notes and reviews.

=== The class <tt>changes:Annotation</tt> ===
Instances of the class <tt>changes:Annotation</tt> represent reviews and marginal notes, as well as notes on mappings and other reviews. For now, marginal notes will be direct instances of <tt>Annotation</tt> because we do not distinguish between different types of marginal notes, such as questions or proposals. This class has the following key properties:
* <tt>changes:annotates</tt>, which is the inverse of the property <tt>changes:associatedAnnotations</tt>. This property has instances of <tt>changes:AnnotatableThing</tt> as its value. Thus, it refers to the exact version of a concept or an ontology for which annotation has been created.
* <tt>annotatesByVirtualID</tt> contains the virtual id for the ontology or the concept that this annotation annotates. We need this property for efficient retrieval so that we can query by the id.

The only subclass of the class <tt>Annotation</tt> that we will currently use is the class <tt>Review</tt> that represents the reviews of the ontologies (see below).

== Representing reviews ==

=== The class <tt>bpMetadata:Review </tt> ===
[[image:EvaluationDimension.jpg|frame|'''Representing a single ontology review with several dimensions''' ]]

A class <tt>bpMetadata:Review</tt> is a subclass of <tt>changes:Annotation</tt>. This class represents reviews of an ontology as a whole. Each review contains ratings and comments along each of the dimensions specified as the evaluation dimensions (class <tt>EvaluationDimension</tt>, with two properties: <tt>numericRating</tt>, <tt>textualReview</tt>). It has the following properties, in addition to the provenance ones inherited from the <tt>Annotation</tt> class:

* <tt>inTheContextOfProject</tt> (range: <tt>Project</tt>; inverse property:<tt> ontologyReviews</tt>) indicates that a review was created in the context of a particular project
* the range for the property <tt>annotates</tt> is restricted to <tt>OMV:Ontology</tt>
*A property for each of the review dimensions. These properties are all subproperties of the property reviewOnDimension (range: <tt>EvaluationDimension</tt> (see [[#review| figure]])):
** <tt>digreeOfFormalityReview</tt>
** <tt>documentationAndSupportReview</tt>
** <tt>usabilityReview</tt>
** <tt>domainCoverageReview</tt>
** <tt>correctnessReview</tt>
** <tt>qualityOfContentReview</tt>

This list of properties can be changed or extended, and, thus, other implementations can custom-tailor the dimensions. Each property has an annotation property <tt>rdfs:label</tt> that contains a string that will be displayed for this dimension (e.g., "Domain coverage"). If the order in which these dimensions appear is important, the developers will need to update the Constant <tt>Names.DIMENSIONS</tt> in the code.

== Representing Mappings ==
The '''Mappings ontology''' represents different types of mappings and the corresponding metadata. More details on the mapping metadata in a separate document. We define the mapping ontology for BioPortal to represent one-to-one mappings.
This ontology has the key classes described below.
[[image:MappingOntologyAndInstances.jpg|frame|'''Mappings and the mapping metadata.''' Note that we may choose to represent the source and target of mapping as an instance of <tt>changes:Ontology_Component</tt> to factor out the way that we use to refer to specific versions of concepts ]]

=== The class <tt>mappings:One_to_one_mapping</tt> ===
A class <tt>'''mappings:One_to_one_mapping'''</tt> represents a mapping between any two concepts (usually, from different ontologies) It has the following properties (all in the <tt>mappings</tt> namespace:
* <tt>source</tt> (range: <tt>URL</tt>)
* <tt>target</tt> (range: <tt>URL</tt>)
* <tt>relation</tt> (range: <tt>URL</tt>)
* <tt>mapping_metadat</tt>a (range: <tt>Mapping_Metadata</tt>)

=== The class <tt>mappings:Mapping_Metadata</tt> ===
A class <tt>'''mappings:Mapping_Metadata'''</tt> represents the metadata about each mapping:
* <tt>applicationContext</tt> (range: String)
* <tt>authority</tt> (range: <tt>Authority</tt>, a class with two subclasses <tt>Authority_Algorithm</tt> and <tt>Authority_Manual</tt>; the former contains the details of the algorithm)
* <tt>comment</tt> (range: <tt>String</tt>)
* <tt>date</tt> (range: <tt>date</tt>)
* <tt>dependency</tt> (range: <tt>One_to_one_mapping</tt>)
* <tt>externalReferences</tt> (range: <tt>String</tt>)
* <tt>submittedBy</tt> (range: ''undefined'')
* <tt>verified</tt> (range: ''undefined'')
Note that we change the range for <tt>mappings:source</tt> and <tt>mappings:target</tt> to be <tt> changes:Ontology_Component</tt>. Thus, we will re-use whatever solution we choose to represent targets of annotations.
Because one can also add comments to mappings, we add <tt>changes:AnnotatableThing</tt> as another superclass of the class <tt>One_To_One_Mapping</tt>. Thus, <tt>One_To_One_Mapping</tt> now has <tt>changes:associatedAnnotations</tt> as one of its properties.

== Representing Metrics ==
''Please refer to the [[Ontology Metrics]] page for the details of metrics representation in BioPortal.''

== Representing Views ==

We treat a view as an ontology and therefore the representation of views parallels the representation of ontologies themselves.
[[image:ViewClasses.jpg|frame|'''Classes representing views and their versions.''' The classes for representing views are subclasses of the ontology classes. Inherited properties are represented as dotted lines.]]
The representation described here is flexible enough to address all
[http://www.bioontology.org/wiki/index.php/Requirements#Views the requirements] that we identified. While the representation is somewhat complex to allow the full flexibility (views on views, versions of views, etc.), the user interface will hide most of the complexity.

Just as we have a [http://www.bioontology.org/wiki/index.php/Architecture#The__class_VirtualOntology <tt>VirtualOntology</tt> class] as a container for all versions of a particular ontology, we have a class '''<tt>VirtualView</tt>''' to represent a container of all versions of a particular view. For example, we can have a "Liver" view of the FMA. The instance of the <tt>VirtualView</tt> class will point to all specific versions of the view. These specific versions are instances of the class '''<tt>OntologyView</tt>''', which is a subclass of the [http://www.bioontology.org/wiki/index.php/Architecture#The_class_OMV:Ontology <tt>OMV:Ontology</tt> class]. Each instance of <tt>OntologyView</tt> (i.e., a specific version of the view), points to the specific version of the "base" ontology that was used to create this view.

The two figures to the right show [#viewClasses|the key classes] in representing the views, and an example of [#viewInstances|a set of instances] that instantiate these classes. The color of the box for the instance in the second figure is the same as the color of its class in the first figure.
[[image:ViewInstances.jpg|frame|'''Instances representing a "Liver" view and its versions.''' ]] There is a <tt>VirtualView</tt> instance that contains the collections of all the versions of this view. Some of the versions of the view were created using v.1.0 of the FMA. One version of the Liver view was created using v2.0 of the FMA.

=== The class <tt>OntologyView</tt> ===

The class <tt>OntologyView</tt> is the main class that represents the metadata about a specific version of the view.
This class is a subclass of the class [http://www.bioontology.org/wiki/index.php/Architecture#The_class_OMV:Ontology <tt>OMV:Ontology</tt>], which represents the metadata about a specific version of an ontology. Any specific version of a view is fundamentally just an ontology; thus it inherits all the metadata properties of the <tt>OMV:Ontology</tt> class (copied below for convenience):

* <tt>name</tt>
* <tt>acronym </tt>
* <tt>creationDate</tt>
* <tt>description</tt> (range: <tt>String</tt>)
* <tt>documentation</tt> (range: <tt>URL</tt>)
* <tt>endorsedBy</tt> (range: <tt>OMV:Party</tt>)
** one of the instances to fill in this value is OBOFoundry, an instance of <tt>OMV:Organisation</tt>
* <tt>domain</tt>
* <tt>ontologyLanguage</tt>
* <tt>keyClasses</tt>
* <tt>keywords</tt>

In addition to inheriting all the metadata properties from that describe all BioPortal ontologies, we need to provide additional metadata for each version of a view:

* <tt>viewDefinition</tt> (range <tt>String</tt>) has the textual representation of the view definition. This definition can be a query that was used to create the view, a set of traversal directive (as in Prompt), or any other way that specifies how the view was extracted. (''Question:'' is the type <tt>String</tt> sufficient here or will we need something more structured?)
* <tt>viewDefinitionLanguage</tt> (range: <tt>ViewDefinitionLanguage</tt>) defines the language that was used to define the view (e.g., the query language, such as SPARQL, for a view that was generated by a query). The instance of the class <tt> ViewDefinitionLanguage </tt> will have all the pertinent attribute of the language (name, creator, url) as well as the specific version that was used for the view.
* <tt>viewGenerationEngine</tt> (range: <tt>ViewGenerationEngine</tt>) defines the engine that was used to compute the view. The instance of the class <tt> ViewGenerationEngine </tt> will have all the pertinent attribute of the engine (name, creator, url) as well as the specific version that was used to generate the view.

=== The class <tt>VirtualView</tt> ===

The class <tt>VirtualView</tt> collects the information about all the versions of a particular view. This class is a subclass of the [http://www.bioontology.org/wiki/index.php/Architecture#The__class_VirtualOntology <tt>VirtualOntology</tt> class]. Thus, it inherits all of its properties. However, we restrict the range of values for the properties <tt>currentVersion</tt>, <tt>hasView</tt> and <tt>hasVersion</tt> to instances of the <tt>OntologyView</tt> class. Here is the summary of the inherited properties for the class <tt>VirtualView</tt>, with the corresponding restrictions:
* <tt>currentVersion</tt> (range: <tt>OntologyView</tt>) is a pointer to the metadata describing the current version of the view;
* <tt>ontologyName</tt> (range: <tt>String</tt>) provides a name for the view (e.g., “Liver view for radiology")
* <tt>virtualURI</tt> (range: <tt>URI</tt>) provide a virtual URI for this view; it could also be an ontology ID, as used in BioPortal now
* <tt>hasView</tt> (range <tt>OntologyView</tt>) provides a collection of instances of the <tt>OntologyView</tt> class corresponding to the views of this view (i.e., views on views)
* <tt>hasVersion</tt> (range <tt>OntologyView</tt>) provides a collection of instances of the <tt>OntologyView</tt> class corresponding to the versions of this virtual view

There is also one additional property defined for the class <tt>VirtualView</tt>:
* <tt>isVirtualViewOf</tt> (range: <tt>VirtualOntology</tt>) is a pointer to the "base" ontology or ontologies from which the view is created (e.g., FMA). Note that we may later decide not to use this property as there may be a situation as the set of "base" ontologies is different for different versions of the view. For instance, one version is a view on FMA; but then we extend this version and join it with some classes from NCI Thesaurus. If we want to allow for such evolution, then we don't want to store the "base" ontology (or ontologies) at the level of the <tt>VirtualView</tt>. We can always infer this information from the specific versions that we access through the property <tt>hasVersion</tt>.

Requirements

2009-10-22T00:50:30Z

Noy: /* Marginal notes */

This document is part of [[BioPortal_Metadata|a series of documents describing the representation of metadata in BioPortal]]

----

We discuss two types of requirements for handling metadata in BioPortal:
# the '''functional requirements''' are the set of calls from the user-interface (and web services) that metadata must support;
# the '''architectural requirements''' address the structure and evolution of metadata.

Functional requirements include support for all the current functionality for the metadata use in BioPortal and the future use that we are envisioning in various scenarios and use cases. Specific details on functional requirements are outlined here.

The following are the architectural requirements:
* Represent metadata as ontology instances
* Download metadata (and its various subsets) in RDF
* Be able to update the metadata ontologies “on the fly”
** Incremental updates, such as adding new properties, should be a simple “swap” of the metadata schema (the metadata ontology), without having to change any of the instances
* Be flexible about which properties show up on the ontology metadata page and on the columns in the table on the “Browse” page (The metadata ontology itself will define the set of these metadata features. Thus, other groups that wish to install BioPortal locally will need to customize only the metadata ontology in order to custom-tailor their installations.)

= Types of metadata in BioPortal =

We represent the following types of metadata in BioPortal:
# '''Ontology metadata''' (e.g., the ontology domain and coverage, provenance information, version information, additional references);
# '''Ontology metrics''' (mostly computable metrics such as the number of classes, etc.)
# '''Mappings''' between concepts in different ontologies;
# '''Ontology reviews''' along different review dimensions (e.g., domain coverage, usability, quality of content, etc.);
# '''Marginal notes''' on concepts and mappings in the ontologies containing users’ comments, questions, and discussions;
# '''Projects''' that use ontologies in BioPortal
# BioPortal '''Users'''

These different types of metadata are inter-linked. For example, each user is characterized by the metadata that they contribute; reviews can be created in the context of a particular projects; marginal notes can be attached to mappings.

= Glossary =
'''Virtual ontologies''': the list of ontologies in the repository, with one entry per each “logical” ontology. Basically, the list that appears on the “Browse” page in BioPortal (see [[#browse_page_figure|Figure]]).

'''Core metadata properties''': metadata properties that appear on the [[#ontology_metadata_page_figure|"Ontology metadata” page]]. Not all properties associated with the ontology will generally appear there, as there are many minor ones that we don’t always want to display. Perhaps there can be a “more details” page that shows those.

'''Summary metadata properties''': metadata properties that appear in the columns of the table on the “Browse” page and in the columns for versions and views on the metadata page for each ontology

----

[[image:BrowsePage.jpg|thumb|right|The "Browse" page in Bioportal]]
[[image:OntologyMetadataPage.jpg|thumb|right|The "Ontology metadata" page in Bioportal]]
[[image:ReviewsPage.jpg|thumb|right|The "Project and reviews" page in Bioportal]]

----

= Functional Requirements =

Metadata drives much of the BioPortal user interface, with the exception of the display of the ontologies themselves. The list below is not exhaustive and we expect it to grow. However, it does cover major categories of requirements and some details on each. In the section on [[Implementation Details]], we provide details on the implementation for all these calls.

== Browse ontologies (as in [[#browse_page_figure|the “Browse” tab of BioPorta]]) ==
* get all virtual ontologies
* for each virtual ontology, get the summary properties to fill in the rest of the table:
** name
** version
** author
** uploaded on
** url

== Ontology metadata ([[#ontology_metadata_page_figure|in ontology metadata page]]) ==
* display property-value pairs for the core metadata properties
* get a list of all views for the ontology
** for each view, get the summary properties, such as description, version number, status, url
* get a list of all versions for the ontology
** for each version, get the summary properties, such as description, version number, status, url

== Submitting a new version of an ontology ==
* get a list of core properties and their ranges (the range determines the UI widget)
** in order
* create a new metadata instance describing this ontology version
** and set property values

== Submitting a new ontology ==
* get a list of core properties and their ranges (the range determines the widget)
** in order
* create a new metadata instance describing this ontology version
** and set property values

== Accessing the metrics of an ontology version ==
* get all available metrics for a specific ontology version
* the metrics should be computed when the ontology is loaded into BioPortal
** Specific metrics are described on the [[Ontology Metrics]] page

== Search ==
* get a list of virtual ontologies to provide filters for search

== Recent items ==
* provide the list of recent ontology uploads
* provide the list of recent marginal notes, mappings, reviews, projects

== Reviews ==
* get all reviews for an ontology, indicating which reviews where created for a current version, and which were created for old versions
* when presenting a review, show ratings and text along different dimensions (Figure 1)
* create a review for an ontology
** in the context of a particular project
** without a project context
* determine which ontology has the highest ratings for a particular dimension

== Marginal notes ==
* for each concept, given its URL (real or virtual?), get all marginal notes associated with this concept:
** marginal notes attached directly to the current version of this concept
** marginal notes attached to earlier versions
* the number of marginal notes for an ontology
** over a period of time?
* the marginal notes created by a particular user
* the marginal notes of a particular type (e.g., new term proposals)
* any combination of the above (e.g., ''new term proposals from a user X'')
* Create a marginal note and associate it with a version of a concept

== All mappings ==
* for each virtual ontology, get the number of mappings to and from that ontology
* for each ontology, get all the mappings (grouped by target ontology)

== Mappings for a concept ==
* for each concept, given its URL (real or virtual?), get all mappings associated with this concept:
** mappings attached directly to the current version of this concept
** mappings attached to earlier versions
* create a new mapping and attach it to the current version of the concept

== Views ==

* each view is itself an ontology and can have metadata, be explorable, etc.
* a view is defined on a specific ''version'' of an ontology
* there is a notion of a "virtual view" (cf. "virtual ontology"): for example, a view of Liver-related concepts in FMA created for a particular purpose
** each virtual view will have at least one version, but can have several
** a virtual view has some metadata attached to it (name, contact, etc.)
** each version of the view also has its own metadata (inherited from ontology metadata, but with additional fields)
* we must be able to represent views on views
* we must be able to represent views that include more than one ontology

== Projects ==
* get a list of projects
* for each project, get the property-value pairs:
** name
** description
** people
** institution
** homepage
* project-specific page

2009-10-16T00:48:54Z

Noy: /* Generating metrics */

= Ontology Metrics in BioPortal =

This page describes the metrics that BioPortal calculates for the ontologies in its repository. In general, BioPortal will calculate the metrics when the ontology is uploaded and will store it as part of the [http://www.bioontology.org/wiki/index.php/BioPortal_Metadata Ontology Metadata]. There are two groups of metrics:
* '''Statistical''' metrics
* '''Quality-control''' and '''quality-assurance''' metrics

Each ontology may have all, some, or no values filled in for its metrics. Some metrics are meaningful only for ontologies in a specific representation language (e.g., number of axioms matters only for OWL ontologies; there are no individuals to count in the ontologies in OBO format).

== Statistical Metrics ==
We calculate the following statistics on each ontology in BioPortal:

* '''number of classes''': the number of classes in the ontology. For OWL ontologies
** does not include imported classes
** includes only named classes (no anonymous classes in this count)
* '''number of properties:''' the number of properties or slots in the ontology.
* '''number of individuals:''' the number of individuals in the ontology. Note:
** Individuals exist only in OWL and Protege ontologies.
** An individual in OWL is a resource that is neither a class, nor a property.
* '''number of axioms:''' the number of axioms in an OWL ontology.
* '''maximum depth:''' the maximum depth of the hierarchy tree.
** For OWL, RDFS, Protege, and RRF ontologies, we consider only the ''is-a'' relationship as a hierarchical relationship
** For OBO format ontologies, we consider the following relationships as hierarchical relationships: ''is-a'', ''has-part'', inverse of ''develops-from''
* '''average number of siblings:''' the average number of siblings at one level in the tree.
* '''maximum number of siblings:''' the maximum number of siblings in the ontology.

== Quality-Control and Quality-Assurance Metrics ==
We calculate the following metrics that may give some indication of the quality of the ontology and help ontology authors improve the quality.

* '''classes with only one subclass''': a list of classes that have only one subclass in the ''is-a'' hierarchy. While technically there is no problem in having only one subclass, this situation often indicates that either the hierarchy is under-specified, or the distinction between the class and the subclass is not appropriate.
* '''classes with too many subclasses''': a list of classes that have more direct subclasses than a certain threshold. The specific threshold is an internal parameter in BioPortal (currently set to 25). This situation may be an indication that additional distinctions and categorization are needed.
* '''classes with no definition''': a list of classes that have no value for the definition property. For ontologies in OBO and RRF formats, the property for definition is part of the language. For OWL ontologies, the authors specify this property as part of the ontology metadata (the default is <tt>skos:definition</tt>). If the ontology author has not specified any property as a definition property, we do not fill out this value.
* '''univocality''': the consistency of expression of concepts in an ontology (developed by Karin Verspoor∗, Daniel Dvorkin, K. Bretonnel Cohen, and Lawrence E. Hunter, University of Colorado)

== Auditing and other information ==
* '''auditing information''': a set of <author, classes> pairs that indicates which lists the classes that each author contributed to the ontology. We use the property that the ontology developers specify in their metadata to determine who is the author of the class. If the ontology author has not specified any property as a definition property, we do not fill out this value.

Please, contact us at [mailto:support@bioontology.org support@bioontology.org], if there are additional metrics of any kind that you would like to see.

= Generating metrics =

At the moment, we do not generate metrics as part of the ontology load process, but we will shortly. The process will be as follows: When BioPortal loads and parses a version of an ontology, it then starts a process that calculates the metrics and stores the values as part of the metadata about that ontology version.

== Metrics computation and ontology metadata ==

Metric generation relies on the following information being specified in the ontology metadata:

'''For OBO and RRF ontologies:'''
* property used to specify the authors of a class

'''For OWL ontologies:'''
* property used to specify preferred name (default <tt>rdfs:label</tt>, and if not specified, then <tt>rdf:ID</tt>)
* property used to specify synonyms (default <tt>skos:altLabel</tt>)
* property used to specify the definition of a class (default <tt>skos:definition</tt>)
* property used to specify the author of a class (default <tt>dc:creator</tt>)

= Storing metrics in BioPortal =

The metrics in BioPortal are stored as part of the ontology metadata. Specifically, each instance of the <tt>OMV:Ontology</tt> class, which describes the metadata about a single ontology version, has a number of properties that store the metrics. Some of these properties are imported from the Ontology Metadata Vocabulary, OMV (the <tt>omv:</tt> prefix) and the rest are defined locally in the BioPortal Metadata Ontology (the <tt>metrics:</tt> prefix). These properties include:
*<tt>OMV:numberOfClasses</tt>
*<tt>OMV:numberOfProperties</tt>
*<tt>OMV:numberOfAxioms</tt>
*<tt>OMV:numberOfIndividuals</tt>
* <tt>metrics:averageNumberOfSiblings</tt>
* <tt>metrics:maximumNumberOfSiblings</tt>
* <tt>metrics:classesWithNoDocumentation</tt>
* <tt>metrics:maximumDepth</tt>
* <tt>metrics:preferredMaximumSubclassLimit</tt>
* <tt>metrics:classesWithSingleSubclass</tt>
* <tt>metrics:classesWithNoAuthor</tt>
* <tt>metrics:classesWithMoreThanXSubclasses</tt>
* <tt>metrics:classesWithMoreThanOnePropertyValueForPropertyWithUniqueValue</tt>

= Accessing metrics in BioPortal =

BioPortal users will be able to access ontology metrics in two ways:
* through the BioPortal user interface, as part of the Ontology Details tab (not implemented yet)
* through a dedicated REST service that returns a <tt>MetricsBean</tt>

== REST service access ==

Applications can use the following REST service to access metrics information for a specific ontology version.
''Note: there is no version of this service that uses virtual ontology id yet.''

* '''Signature''': ./ontologies/metrics/{ontologyVersionId}?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/metrics/40616?email=example@example.org

The service returns a <tt>ontologyMetricsBean</tt> that contains the version id for the ontology and the values for the metrics that have some values computed for them:

<pre>
<success>
<accessedResource>/bioportal/ontologies/metrics/40616</accessedResource>
<accessDate>2009-10-15 17:43:25.978 PDT</accessDate>
<data>
<ontologyMetricsBean>
<id>40616</id>
<numberOfClasses>1577</numberOfClasses>
<numberOfIndividuals>74</numberOfIndividuals>
<numberOfProperties>72</numberOfProperties>
</ontologyMetricsBean>
</data>
</success>
</pre>

Ontology Metrics

2009-10-16T00:48:27Z

Noy: /* REST service access */

= Ontology Metrics in BioPortal =

This page describes the metrics that BioPortal calculates for the ontologies in its repository. In general, BioPortal will calculate the metrics when the ontology is uploaded and will store it as part of the [http://www.bioontology.org/wiki/index.php/BioPortal_Metadata Ontology Metadata]. There are two groups of metrics:
* '''Statistical''' metrics
* '''Quality-control''' and '''quality-assurance''' metrics

Each ontology may have all, some, or no values filled in for its metrics. Some metrics are meaningful only for ontologies in a specific representation language (e.g., number of axioms matters only for OWL ontologies; there are no individuals to count in the ontologies in OBO format).

== Statistical Metrics ==
We calculate the following statistics on each ontology in BioPortal:

* '''number of classes''': the number of classes in the ontology. For OWL ontologies
** does not include imported classes
** includes only named classes (no anonymous classes in this count)
* '''number of properties:''' the number of properties or slots in the ontology.
* '''number of individuals:''' the number of individuals in the ontology. Note:
** Individuals exist only in OWL and Protege ontologies.
** An individual in OWL is a resource that is neither a class, nor a property.
* '''number of axioms:''' the number of axioms in an OWL ontology.
* '''maximum depth:''' the maximum depth of the hierarchy tree.
** For OWL, RDFS, Protege, and RRF ontologies, we consider only the ''is-a'' relationship as a hierarchical relationship
** For OBO format ontologies, we consider the following relationships as hierarchical relationships: ''is-a'', ''has-part'', inverse of ''develops-from''
* '''average number of siblings:''' the average number of siblings at one level in the tree.
* '''maximum number of siblings:''' the maximum number of siblings in the ontology.

== Quality-Control and Quality-Assurance Metrics ==
We calculate the following metrics that may give some indication of the quality of the ontology and help ontology authors improve the quality.

* '''classes with only one subclass''': a list of classes that have only one subclass in the ''is-a'' hierarchy. While technically there is no problem in having only one subclass, this situation often indicates that either the hierarchy is under-specified, or the distinction between the class and the subclass is not appropriate.
* '''classes with too many subclasses''': a list of classes that have more direct subclasses than a certain threshold. The specific threshold is an internal parameter in BioPortal (currently set to 25). This situation may be an indication that additional distinctions and categorization are needed.
* '''classes with no definition''': a list of classes that have no value for the definition property. For ontologies in OBO and RRF formats, the property for definition is part of the language. For OWL ontologies, the authors specify this property as part of the ontology metadata (the default is <tt>skos:definition</tt>). If the ontology author has not specified any property as a definition property, we do not fill out this value.
* '''univocality''': the consistency of expression of concepts in an ontology (developed by Karin Verspoor∗, Daniel Dvorkin, K. Bretonnel Cohen, and Lawrence E. Hunter, University of Colorado)

== Auditing and other information ==
* '''auditing information''': a set of <author, classes> pairs that indicates which lists the classes that each author contributed to the ontology. We use the property that the ontology developers specify in their metadata to determine who is the author of the class. If the ontology author has not specified any property as a definition property, we do not fill out this value.

Please, contact us at [mailto:support@bioontology.org support@bioontology.org], if there are additional metrics of any kind that you would like to see.

= Generating metrics =

At the moment, we do not generate metrics as part of the ontology load process, but we will shortly. The process will be as follows: When BioPortal loads and parses a version of an ontology, it then starts a process that calculates the metrics and stores the values as part of the metadata about that ontology version.

Metric generation relies on the following information being specified in the ontology metadata:

'''For OBO and RRF ontologies:'''
* property used to specify the authors of a class

'''For OWL ontologies:'''
* property used to specify preferred name (default <tt>rdfs:label</tt>, and if not specified, then <tt>rdf:ID</tt>)
* property used to specify synonyms (default <tt>skos:altLabel</tt>)
* property used to specify the definition of a class (default <tt>skos:definition</tt>)
* property used to specify the author of a class (default <tt>dc:creator</tt>)

= Storing metrics in BioPortal =

The metrics in BioPortal are stored as part of the ontology metadata. Specifically, each instance of the <tt>OMV:Ontology</tt> class, which describes the metadata about a single ontology version, has a number of properties that store the metrics. Some of these properties are imported from the Ontology Metadata Vocabulary, OMV (the <tt>omv:</tt> prefix) and the rest are defined locally in the BioPortal Metadata Ontology (the <tt>metrics:</tt> prefix). These properties include:
*<tt>OMV:numberOfClasses</tt>
*<tt>OMV:numberOfProperties</tt>
*<tt>OMV:numberOfAxioms</tt>
*<tt>OMV:numberOfIndividuals</tt>
* <tt>metrics:averageNumberOfSiblings</tt>
* <tt>metrics:maximumNumberOfSiblings</tt>
* <tt>metrics:classesWithNoDocumentation</tt>
* <tt>metrics:maximumDepth</tt>
* <tt>metrics:preferredMaximumSubclassLimit</tt>
* <tt>metrics:classesWithSingleSubclass</tt>
* <tt>metrics:classesWithNoAuthor</tt>
* <tt>metrics:classesWithMoreThanXSubclasses</tt>
* <tt>metrics:classesWithMoreThanOnePropertyValueForPropertyWithUniqueValue</tt>

= Accessing metrics in BioPortal =

BioPortal users will be able to access ontology metrics in two ways:
* through the BioPortal user interface, as part of the Ontology Details tab (not implemented yet)
* through a dedicated REST service that returns a <tt>MetricsBean</tt>

== REST service access ==

Applications can use the following REST service to access metrics information for a specific ontology version.
''Note: there is no version of this service that uses virtual ontology id yet.''

* '''Signature''': ./ontologies/metrics/{ontologyVersionId}?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/metrics/40616?email=example@example.org

The service returns a <tt>ontologyMetricsBean</tt> that contains the version id for the ontology and the values for the metrics that have some values computed for them:

<pre>
<success>
<accessedResource>/bioportal/ontologies/metrics/40616</accessedResource>
<accessDate>2009-10-15 17:43:25.978 PDT</accessDate>
<data>
<ontologyMetricsBean>
<id>40616</id>
<numberOfClasses>1577</numberOfClasses>
<numberOfIndividuals>74</numberOfIndividuals>
<numberOfProperties>72</numberOfProperties>
</ontologyMetricsBean>
</data>
</success>
</pre>

Ontology Metrics

2009-10-16T00:48:12Z

Noy: /* REST service access */

= Ontology Metrics in BioPortal =

This page describes the metrics that BioPortal calculates for the ontologies in its repository. In general, BioPortal will calculate the metrics when the ontology is uploaded and will store it as part of the [http://www.bioontology.org/wiki/index.php/BioPortal_Metadata Ontology Metadata]. There are two groups of metrics:
* '''Statistical''' metrics
* '''Quality-control''' and '''quality-assurance''' metrics

Each ontology may have all, some, or no values filled in for its metrics. Some metrics are meaningful only for ontologies in a specific representation language (e.g., number of axioms matters only for OWL ontologies; there are no individuals to count in the ontologies in OBO format).

== Statistical Metrics ==
We calculate the following statistics on each ontology in BioPortal:

* '''number of classes''': the number of classes in the ontology. For OWL ontologies
** does not include imported classes
** includes only named classes (no anonymous classes in this count)
* '''number of properties:''' the number of properties or slots in the ontology.
* '''number of individuals:''' the number of individuals in the ontology. Note:
** Individuals exist only in OWL and Protege ontologies.
** An individual in OWL is a resource that is neither a class, nor a property.
* '''number of axioms:''' the number of axioms in an OWL ontology.
* '''maximum depth:''' the maximum depth of the hierarchy tree.
** For OWL, RDFS, Protege, and RRF ontologies, we consider only the ''is-a'' relationship as a hierarchical relationship
** For OBO format ontologies, we consider the following relationships as hierarchical relationships: ''is-a'', ''has-part'', inverse of ''develops-from''
* '''average number of siblings:''' the average number of siblings at one level in the tree.
* '''maximum number of siblings:''' the maximum number of siblings in the ontology.

== Quality-Control and Quality-Assurance Metrics ==
We calculate the following metrics that may give some indication of the quality of the ontology and help ontology authors improve the quality.

* '''classes with only one subclass''': a list of classes that have only one subclass in the ''is-a'' hierarchy. While technically there is no problem in having only one subclass, this situation often indicates that either the hierarchy is under-specified, or the distinction between the class and the subclass is not appropriate.
* '''classes with too many subclasses''': a list of classes that have more direct subclasses than a certain threshold. The specific threshold is an internal parameter in BioPortal (currently set to 25). This situation may be an indication that additional distinctions and categorization are needed.
* '''classes with no definition''': a list of classes that have no value for the definition property. For ontologies in OBO and RRF formats, the property for definition is part of the language. For OWL ontologies, the authors specify this property as part of the ontology metadata (the default is <tt>skos:definition</tt>). If the ontology author has not specified any property as a definition property, we do not fill out this value.
* '''univocality''': the consistency of expression of concepts in an ontology (developed by Karin Verspoor∗, Daniel Dvorkin, K. Bretonnel Cohen, and Lawrence E. Hunter, University of Colorado)

== Auditing and other information ==
* '''auditing information''': a set of <author, classes> pairs that indicates which lists the classes that each author contributed to the ontology. We use the property that the ontology developers specify in their metadata to determine who is the author of the class. If the ontology author has not specified any property as a definition property, we do not fill out this value.

Please, contact us at [mailto:support@bioontology.org support@bioontology.org], if there are additional metrics of any kind that you would like to see.

= Generating metrics =

At the moment, we do not generate metrics as part of the ontology load process, but we will shortly. The process will be as follows: When BioPortal loads and parses a version of an ontology, it then starts a process that calculates the metrics and stores the values as part of the metadata about that ontology version.

Metric generation relies on the following information being specified in the ontology metadata:

'''For OBO and RRF ontologies:'''
* property used to specify the authors of a class

'''For OWL ontologies:'''
* property used to specify preferred name (default <tt>rdfs:label</tt>, and if not specified, then <tt>rdf:ID</tt>)
* property used to specify synonyms (default <tt>skos:altLabel</tt>)
* property used to specify the definition of a class (default <tt>skos:definition</tt>)
* property used to specify the author of a class (default <tt>dc:creator</tt>)

= Storing metrics in BioPortal =

The metrics in BioPortal are stored as part of the ontology metadata. Specifically, each instance of the <tt>OMV:Ontology</tt> class, which describes the metadata about a single ontology version, has a number of properties that store the metrics. Some of these properties are imported from the Ontology Metadata Vocabulary, OMV (the <tt>omv:</tt> prefix) and the rest are defined locally in the BioPortal Metadata Ontology (the <tt>metrics:</tt> prefix). These properties include:
*<tt>OMV:numberOfClasses</tt>
*<tt>OMV:numberOfProperties</tt>
*<tt>OMV:numberOfAxioms</tt>
*<tt>OMV:numberOfIndividuals</tt>
* <tt>metrics:averageNumberOfSiblings</tt>
* <tt>metrics:maximumNumberOfSiblings</tt>
* <tt>metrics:classesWithNoDocumentation</tt>
* <tt>metrics:maximumDepth</tt>
* <tt>metrics:preferredMaximumSubclassLimit</tt>
* <tt>metrics:classesWithSingleSubclass</tt>
* <tt>metrics:classesWithNoAuthor</tt>
* <tt>metrics:classesWithMoreThanXSubclasses</tt>
* <tt>metrics:classesWithMoreThanOnePropertyValueForPropertyWithUniqueValue</tt>

= Accessing metrics in BioPortal =

BioPortal users will be able to access ontology metrics in two ways:
* through the BioPortal user interface, as part of the Ontology Details tab (not implemented yet)
* through a dedicated REST service that returns a <tt>MetricsBean</tt>

== REST service access ==

Applications can use the following REST service to access metrics information for a specific ontology version.
''Note: there is no version of this service that uses virtual ontology id yet.''

* '''Signature''': ./ontologies/metrics/{ontologyVersionId}?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/metrics/40616?email=example@example.org

The service returns a <tt>ontologyMetricsBean</tt> that contains the version id for the ontology and the values for the metrics that have some values computed for them:

<pre>
<success>
<accessedResource>/bioportal/ontologies/metrics/40616</accessedResource>
<accessDate>2009-10-15 17:43:25.978 PDT</accessDate>
<data>
<ontologyMetricsBean>
<id>40616</id>
<numberOfClasses>1577</numberOfClasses>
<numberOfIndividuals>74</numberOfIndividuals>
<numberOfProperties>72</numberOfProperties>
</ontologyMetricsBean>
</data>
</success>
</pre>