NCBO Wiki - User contributions [en]

SKOSSupport

2017-12-03T18:34:23Z

Jonquet:

[[File:Plos_thesaurus_class_tree.png|thumb|400px|PLOS Thesaurus concept tree in BioPortal]]

__TOC__

=== Support for SKOS vocabularies in BioPortal ===

BioPortal is a web-based portal for accessing and sharing ontologies. The application accepts ontology submissions in OWL and OBO format, and SKOS vocabularies that contain particular constructs.

This wiki page documents the minimum set of SKOS constructs that must be present in a SKOS vocabulary for BioPortal to accept and handle the submission properly.

Please note that the SKOS constructs described here are handled only for vocabularies that are identified as SKOS when they are submitted to BioPortal. Vocabularies submitted as OWL or OBO formats are not examined for SKOS constructs.

==== Required SKOS constructs ====

===== skos:Concept =====

''Concepts'' are the fundamental elements of SKOS vocabularies and are asserted using the skos:Concept class, e.g.:

<nowiki><http://www.example.com/animals></nowiki> rdf:type skos:Concept

In SKOS vocabularies, BioPortal only treats the SKOS concept assertions as concepts to be displayed. If the vocabulary contains other assertions about other types of concepts, BioPortal will not treat these as concepts in any of its displays or features. See the W3C's SKOS System Primer and SKOS Reference for concept documentation and examples:

https://www.w3.org/TR/2009/NOTE-skos-primer-20090818/#secconcept
https://www.w3.org/TR/skos-reference/#concepts

If you declare the skos name space only for the purpose of using SKOS properties for label or mapping, it is not needed to select the SKOS format when uploading your ontology. Use the normal OWL format instead.

===== skos:ConceptScheme & skos:hasTopConcept =====

For every ontology entry in BioPortal, the application provides a tabbed interface with various views of the ontology data, e.g., a "Classes" tab with a tree structure to graphically depict the hierarchical collection of ontology classes.

In the case of SKOS vocabularies, BioPortal determines which concepts to display as roots in the concept tree by querying vocabulary content for occurrences of skos:hasTopConcept property assertions. Top concepts are the most general concepts contained in SKOS concept schemes (an aggregation of one or more SKOS concepts).

The following example, taken from the SKOS System Primer, shows how to define a concept scheme and link it to the most general concepts it contains:

@prefix skos: <nowiki><http://www.w3.org/2004/02/skos/core#></nowiki> .
@prefix rdf: <nowiki><http://www.w3.org/1999/02/22-rdf-syntax-ns#></nowiki> .
@prefix ex: <nowiki><http://www.example.com/></nowiki> .

ex:animalThesaurus rdf:type skos:ConceptScheme;
skos:hasTopConcept ex:mammals;
skos:hasTopConcept ex:fish.

SKOS vocabularies submitted to BioPortal must contain a minimum of one concept scheme and top concept assertion. See the the SKOS System Primer and SKOS Reference for more documentation of concept schemes and top concepts:

https://www.w3.org/TR/2009/NOTE-skos-primer-20090818/#secscheme

https://www.w3.org/TR/skos-reference/#schemes

Note that if your vocabulary declares more than one skos:ConceptScheme, all the skos:hasTopConcept instances will be aggregated and consider the roots of your vocabulary.
BioPortal does not handle the notion of Scheme persé. It is recommended to declare a owl:Ontology, especially for metadata annotations.

===== skos:broader hierachy =====

For the hierarchy to be handle and display properly by BioPortal, hierarchical relations between skos:Concept need to defined by the skos:broader.
If another property is used (narrower, transitive), it is not an issue, but BioPortal will display hierarchies on based on skos:broader properties.

ex:zebra rdf:type skos:Concept;
skos:inScheme ex:animalThesaurus;
skos:prefLabel "Plains zebra";
skos:altLabel "Equus quagga";
skos:broader ex:mammals.

==== Note on metrics ====

[[File:Metrics.png|thumb|400px|PLOS Thesaurus metrics in BioPortal]]

Because BioPortal's metrics are mostly being computed by the OWL-API, a SKOS vocabulary will be then treated like any RDF file with classes and instances. According to the SKOS specification, because skos:Concept are instances, they will be counted as "individuals" (not class).
Therefore, when looking a the metrics, one shall consider that the number of individuals reports the number of concepts in the vocabulary and not the number of classes like this is the case with OWL format ontologies.

==== Note on SKOS-XL ====

SKOS-XL extension of the SKOS format is currently not supported by BioPortal.
It is advised to dump the value of labels (i.e., skosxl:literalForm of skosxl:*Label instances) into the corresponding skos:*Label property.

==== Note on mapping properties ====

As of now, skos:*Match properties are parsed as any properties, but will not be used to populated BioPortal's mapping repository.
One-to-one mappings between concepts need to be uploaded aside using the REST API.

SKOSSupport

2017-12-03T18:24:53Z

Jonquet:

[[File:Plos_thesaurus_class_tree.png|thumb|400px|PLOS Thesaurus concept tree in BioPortal]]

__TOC__

=== Support for SKOS vocabularies in BioPortal ===

BioPortal is a web-based portal for accessing and sharing ontologies. The application accepts ontology submissions in OWL and OBO format, and SKOS vocabularies that contain particular constructs.

This wiki page documents the minimum set of SKOS constructs that must be present in a SKOS vocabulary for BioPortal to accept and handle the submission properly.

Please note that the SKOS constructs described here are handled only for vocabularies that are identified as SKOS when they are submitted to BioPortal. Vocabularies submitted as OWL or OBO formats are not examined for SKOS constructs.

==== Required SKOS constructs ====

===== skos:Concept =====

''Concepts'' are the fundamental elements of SKOS vocabularies and are asserted using the skos:Concept class, e.g.:

<nowiki><http://www.example.com/animals></nowiki> rdf:type skos:Concept

In SKOS vocabularies, BioPortal only treats the SKOS concept assertions as concepts to be displayed. If the vocabulary contains other assertions about other types of concepts, BioPortal will not treat these as concepts in any of its displays or features. See the W3C's SKOS System Primer and SKOS Reference for concept documentation and examples:

https://www.w3.org/TR/2009/NOTE-skos-primer-20090818/#secconcept
https://www.w3.org/TR/skos-reference/#concepts

If you declare the skos name space only for the purpose of using SKOS properties for label or mapping, it is not needed to select the SKOS format when uploading your ontology. Use the normal OWL format instead.

===== skos:ConceptScheme & skos:hasTopConcept =====

For every ontology entry in BioPortal, the application provides a tabbed interface with various views of the ontology data, e.g., a "Classes" tab with a tree structure to graphically depict the hierarchical collection of ontology classes.

In the case of SKOS vocabularies, BioPortal determines which concepts to display as roots in the concept tree by querying vocabulary content for occurrences of skos:hasTopConcept property assertions. Top concepts are the most general concepts contained in SKOS concept schemes (an aggregation of one or more SKOS concepts).

The following example, taken from the SKOS System Primer, shows how to define a concept scheme and link it to the most general concepts it contains:

@prefix skos: <nowiki><http://www.w3.org/2004/02/skos/core#></nowiki> .
@prefix rdf: <nowiki><http://www.w3.org/1999/02/22-rdf-syntax-ns#></nowiki> .
@prefix ex: <nowiki><http://www.example.com/></nowiki> .

ex:animalThesaurus rdf:type skos:ConceptScheme;
skos:hasTopConcept ex:mammals;
skos:hasTopConcept ex:fish.

SKOS vocabularies submitted to BioPortal must contain a minimum of one concept scheme and top concept assertion. See the the SKOS System Primer and SKOS Reference for more documentation of concept schemes and top concepts:

https://www.w3.org/TR/2009/NOTE-skos-primer-20090818/#secscheme

https://www.w3.org/TR/skos-reference/#schemes

===== skos:broader hierachy =====

For the hierarchy to be handle and display properly by BioPortal, hierarchical relations between skos:Concept need to defined by the skos:broader.
If another property is used (narrower, transitive), it is not an issue, but BioPortal will display hierarchies on based on skos:broader properties.

ex:zebra rdf:type skos:Concept;
skos:inScheme ex:animalThesaurus;
skos:prefLabel "Plains zebra";
skos:altLabel "Equus quagga";
skos:broader ex:mammals.

==== Note on metrics ====

[[File:Metrics.png|thumb|400px|PLOS Thesaurus metrics in BioPortal]]

Because BioPortal's metrics are mostly being computed by the OWL-API, a SKOS vocabulary will be then treated like any RDF file with classes and instances. According to the SKOS specification, because skos:Concept are instances, they will be counted as "individuals" (not class).
Therefore, when looking a the metrics, one shall consider that the number of individuals reports the number of concepts in the vocabulary and not the number of classes like this is the case with OWL format ontologies.

==== Note on SKOS-XL ====

SKOS-XL extension of the SKOS format is currently not supported by BioPortal.
It is advised to dump the value of labels (i.e., skosxl:literalForm of skosxl:*Label instances) into the corresponding skos:*Label property.

SKOSSupport

2017-12-03T18:18:56Z

Jonquet: /* Note on metrics */

[[File:Plos_thesaurus_class_tree.png|thumb|400px|PLOS Thesaurus concept tree in BioPortal]]

__TOC__

=== Support for SKOS vocabularies in BioPortal ===

BioPortal is a web-based portal for accessing and sharing ontologies. The application accepts ontology submissions in OWL and OBO format, and SKOS vocabularies that contain particular constructs.

This wiki page documents the minimum set of SKOS constructs that must be present in a SKOS vocabulary for BioPortal to accept and handle the submission properly.

Please note that the SKOS constructs described here are handled only for vocabularies that are identified as SKOS when they are submitted to BioPortal. Vocabularies submitted as OWL or OBO formats are not examined for SKOS constructs.

==== Required SKOS constructs ====

===== skos:Concept =====

''Concepts'' are the fundamental elements of SKOS vocabularies and are asserted using the skos:Concept class, e.g.:

<nowiki><http://www.example.com/animals></nowiki> rdf:type skos:Concept

In SKOS vocabularies, BioPortal only treats the SKOS concept assertions as concepts to be displayed. If the vocabulary contains other assertions about other types of concepts, BioPortal will not treat these as concepts in any of its displays or features. See the W3C's SKOS System Primer and SKOS Reference for concept documentation and examples:

https://www.w3.org/TR/2009/NOTE-skos-primer-20090818/#secconcept

https://www.w3.org/TR/skos-reference/#concepts

===== skos:ConceptScheme & skos:hasTopConcept =====

For every ontology entry in BioPortal, the application provides a tabbed interface with various views of the ontology data, e.g., a "Classes" tab with a tree structure to graphically depict the hierarchical collection of ontology classes.

In the case of SKOS vocabularies, BioPortal determines which concepts to display as roots in the concept tree by querying vocabulary content for occurrences of skos:hasTopConcept property assertions. Top concepts are the most general concepts contained in SKOS concept schemes (an aggregation of one or more SKOS concepts).

The following example, taken from the SKOS System Primer, shows how to define a concept scheme and link it to the most general concepts it contains:

@prefix skos: <nowiki><http://www.w3.org/2004/02/skos/core#></nowiki> .
@prefix rdf: <nowiki><http://www.w3.org/1999/02/22-rdf-syntax-ns#></nowiki> .
@prefix ex: <nowiki><http://www.example.com/></nowiki> .

ex:animalThesaurus rdf:type skos:ConceptScheme;
skos:hasTopConcept ex:mammals;
skos:hasTopConcept ex:fish.

SKOS vocabularies submitted to BioPortal must contain a minimum of one concept scheme and top concept assertion. See the the SKOS System Primer and SKOS Reference for more documentation of concept schemes and top concepts:

https://www.w3.org/TR/2009/NOTE-skos-primer-20090818/#secscheme

https://www.w3.org/TR/skos-reference/#schemes

===== skos:broader hierachy =====

For the hierarchy to be handle and display properly by BioPortal, hierarchical relations between skos:Concept need to defined by the skos:broader.
If another property is used (narrower, transitive), it is not an issue, but BioPortal will display hierarchies on based on skos:broader properties.

ex:zebra rdf:type skos:Concept;
skos:inScheme ex:animalThesaurus;
skos:prefLabel "Plains zebra";
skos:altLabel "Equus quagga";
skos:broader ex:mammals.

==== Note on metrics ====

[[File:Metrics.png|thumb|400px|PLOS Thesaurus metrics in BioPortal]]

Because BioPortal's metrics are mostly being computed by the OWL-API, a SKOS format ontology will be then treated like any RDF file with classes and instances. According to the SKOS specification, because skos:Concept are instances, they will be counted as "individuals" (not class).
Therefore, when looking a the metrics, one shall consider that the number of individuals reports the number of concepts in the ontology and not the number of classes like this is the case with OWL format ontologies.

==== Note on SKOS-XL ====

SKOS-XL extension of the SKOS format is currently not supported by BioPortal.
It is advised to dump the value of labels (i.e., skosxl:literalForm of skosxl:*Label instances) into the corresponding skos:*Label property.

SKOSSupport

2017-12-03T18:08:42Z

2010-08-11T21:11:33Z

Jonquet: /* Headline text */

This wiki page describes the status of the OBR index.

= Execution of the OBR worklow =

== Technical documentation ==
[[Image:PopulationOBRtables.png|thumb|Population of the OBR tables]]
* '''Population And Maintenance Of The OBR Index'''
Population of OBR and OBS tables is described in document [http://www.bioontology.org/wiki/images/5/5f/Population_And_Maintenance_Of_The_OBR_Index.doc Population_And_Maintenance_Of_The_OBR_Index]

* '''Technical Instructions for Configuring OBR Workflow'''
Population of OBR and OBS tables using properties files and shell script is described in document [http://www.bioontology.org/wiki/images/4/47/Technical_Instructions_for_Configuring_OBR_Workflow.doc Technical_Instructions_for_Configuring_OBR_Workflow]

RAT Start Date End Date Database Type of workflow execution
PCM Sunday, Oct 04, 2009 10:47 PM
Monday, Oct 05, 2009 06:11 PM
Obsdb1.obs_stage Resource update + OBR execution with full dictionary of the new delta of resources

== Resource Index v2.0 execution history ==

Please refer to: http://rest.bioontology.org/resource_index/executions/list/

== OBR workflow execution history ==

{| class="wikitable" border="1" cellspacing="0" cellpadding="1" width="150%"
|-
! RAT
! Date first processed
! Date last processed
! Database/schema
! Executed by
! Type of work flow execution
|-
| valign="top" width="5%" |BSM
| valign="top" width="25%" |Tuesday Dec 01, 2009 11:23 PM
| valign="top" width="25%" |Tuesday Dec 01, 2009 11:38 PM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Resource update + OBR execution with full dictionary of the new delta of resources
|-
| valign="top" width="5%" |MICAD
| valign="top" width="25%" |Monday Nov 09, 2009 05:29 AM
| valign="top" width="25%" |Monday Nov 09, 2009 04:08 PM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Resource update + OBR execution with full dictionary of the new delta of resources
|-
| valign="top" width="5%" |SMD
| valign="top" width="25%" |Thursday Nov 05, 2009 03:26 AM
| valign="top" width="25%" |Thursday Nov 05, 2009 04:14 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources
|-
| valign="top" width="5%" |GM
| valign="top" width="25%" |Thursday Nov 05, 2009 03:23 AM
| valign="top" width="25%" |Thursday Nov 05, 2009 03:26 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources
|-
| valign="top" width="5%" |REAC
| valign="top" width="25%" |Thursday Nov 05, 2009 02:01 AM
| valign="top" width="25%" |Thursday Nov 05, 2009 03:23 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources
|-
| valign="top" width="5%" |DBK
| valign="top" width="25%" |Thursday Nov 05, 2009 01:59 AM
| valign="top" width="25%" |Thursday Nov 05, 2009 02:01 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources
|-
| valign="top" width="5%" |PCM
| valign="top" width="25%" |Thursday Nov 05, 2009 01:45 AM
| valign="top" width="25%" |Thursday Nov 05, 2009 01:59 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" |BSM
| valign="top" width="25%" |Thursday Nov 05, 2009 01:39 AM
| valign="top" width="25%" |Thursday Nov 05, 2009 01:45 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources
|-
| valign="top" width="5%" |AE
| valign="top" width="25%" |Thursday Nov 05, 2009 00:23 AM
| valign="top" width="25%" |Thursday Nov 05, 2009 01:39 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources
|-
| valign="top" width="5%" |PC
| valign="top" width="25%" |Thursday Nov 05, 2009 00:19 AM
| valign="top" width="25%" |Thursday Nov 05, 2009 00:23 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources
|-
| valign="top" width="5%" |GAP
| valign="top" width="25%" |Thursday Nov 05, 2009 00:17 AM
| valign="top" width="25%" |Thursday Nov 05, 2009 00:19 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources
|-
| valign="top" width="5%" |WP
| valign="top" width="25%" |Thursday Nov 05, 2009 00:15 AM
| valign="top" width="25%" |Thursday Nov 05, 2009 00:17 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" |GEO
| valign="top" width="25%" |Wednesday Nov 04, 2009 10:38 PM
| valign="top" width="25%" |Thursday Nov 05, 2009 00:15 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources
|-
| valign="top" width="5%" |PGGE
| valign="top" width="25%" |Wednesday Nov 04, 2009 10:34 PM
| valign="top" width="25%" |Wednesday Nov 04, 2009 10:38 PM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources
|-
| valign="top" width="5%" |PGDI
| valign="top" width="25%" |Tuesday Nov 03, 2009 01:13 AM
| valign="top" width="25%" |Tuesday Nov 03, 2009 01:19 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources
|-
| valign="top" width="5%" |UPKB
| valign="top" width="25%" |Tuesday Nov 03, 2009 01:09 AM
| valign="top" width="25%" |Tuesday Nov 03, 2009 01:13 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources
|-
| valign="top" width="5%" |CDD
| valign="top" width="25%" |Tuesday Nov 03, 2009 00:56 AM
| valign="top" width="25%" |Tuesday Nov 03, 2009 01:09 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources
|-
| valign="top" width="5%" |PGDR
| valign="top" width="25%" |Tuesday Nov 03, 2009 00:52 AM
| valign="top" width="25%" |Tuesday Nov 03, 2009 00:56 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources
|-
| valign="top" width="5%" |OMIM
| valign="top" width="25%" |Tuesday Nov 03, 2009 00:39 AM
| valign="top" width="25%" |Tuesday Nov 03, 2009 00:52 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" |GM
| valign="top" width="25%" |Tuesday Oct 27, 2009 04:07 AM
| valign="top" width="25%" |Tuesday Oct 27, 2009 05:11 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" |REAC
| valign="top" width="25%" |Tuesday Oct 27, 2009 02:15 AM
| valign="top" width="25%" |Tuesday Oct 27, 2009 04:07 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" |BSM
| valign="top" width="25%" |Tuesday Oct 27, 2009 02:08 AM
| valign="top" width="25%" |Tuesday Oct 27, 2009 02:15 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" |WP
| valign="top" width="25%" |Tuesday Oct 27, 2009 02:06 AM
| valign="top" width="25%" |Tuesday Oct 27, 2009 02:08 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" |PGGE
| valign="top" width="25%" |Tuesday Oct 27, 2009 01:52 AM
| valign="top" width="25%" |Tuesday Oct 27, 2009 02:06 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" |PGDI
| valign="top" width="25%" |Tuesday Oct 27, 2009 01:35 AM
| valign="top" width="25%" |Tuesday Oct 27, 2009 01:52 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" |UPKB
| valign="top" width="25%" |Monday Oct 26, 2009 10:56 PM
| valign="top" width="25%" |Tuesday Oct 27, 2009 01:35 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" |CDD
| valign="top" width="25%" |Monday Oct 26, 2009 08:07 AM
| valign="top" width="25%" |Monday Oct 26, 2009 10:56 PM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" |PGDR
| valign="top" width="25%" |Monday Oct 26, 2009 07:46 AM
| valign="top" width="25%" |Monday Oct 26, 2009 08:07 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" |OMIM
| valign="top" width="25%" |Monday Oct 26, 2009 05:24 AM
| valign="top" width="25%" |Monday Oct 26, 2009 07:46 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" |PC
| valign="top" width="25%" |Wednesday Oct 14, 2009 10:47 PM
| valign="top" width="25%" |Wednesday Oct 14, 2009 11:00 PM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Resource update + OBR execution with full dictionary of the new delta of resources

|-
| valign="top" width="5%" |SMD
| valign="top" width="25%" |Monday Oct 12, 2009 02:31 AM
| valign="top" width="25%" |Monday Oct 12, 2009 08:06 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" |GM
| valign="top" width="25%" |Monday Oct 12, 2009 02:23 AM
| valign="top" width="25%" |Monday Oct 12, 2009 02:31 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" |REAC
| valign="top" width="25%" |Monday Oct 12, 2009 02:11 AM
| valign="top" width="25%" |Monday Oct 12, 2009 02:23 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" |RXRD
| valign="top" width="25%" |Tuesday Oct 06, 2009 05:52 PM
| valign="top" width="25%" |Monday Oct 12, 2009 02:11 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" | DBK
| valign="top" width="25%" |Tuesday Oct 06, 2009 05:29 PM
| valign="top" width="25%" |Tuesday Oct 06, 2009 05:52 PM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" | CT
| valign="top" width="25%" |Tuesday Oct 06, 2009 04:39 AM
| valign="top" width="25%" |Tuesday Oct 06, 2009 05:29 PM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" | BSM
| valign="top" width="25%" |Tuesday Oct 06, 2009 04:37 AM
| valign="top" width="25%" |Tuesday Oct 06, 2009 04:39 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" | AE
| valign="top" width="25%" |Tuesday Oct 06, 2009 00:55 AM
| valign="top" width="25%" |Tuesday Oct 06, 2009 04:37 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" | GAP
| valign="top" width="25%" |Tuesday Oct 06, 2009 00:54 AM
| valign="top" width="25%" |Tuesday Oct 06, 2009 00:55 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" | WP
| valign="top" width="25%" |Tuesday Oct 06, 2009 00:53 AM
| valign="top" width="25%" |Tuesday Oct 06, 2009 00:54 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" | GEO
| valign="top" width="25%" |Monday Oct 05, 2009 11:47 PM
| valign="top" width="25%" |Tuesday Oct 06, 2009 00:53 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" | PGGE
| valign="top" width="25%" |Monday Oct 05, 2009 11:46 PM
| valign="top" width="25%" |Monday Oct 05, 2009 11:47 PM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" | PGDI
| valign="top" width="25%" |Monday Oct 05, 2009 11:44 PM
| valign="top" width="25%" |Monday Oct 05, 2009 11:46 PM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" | CDD
| valign="top" width="25%" | Monday Oct 05, 2009 10:47 PM
| valign="top" width="25%" | Monday Oct 05, 2009 11:27 PM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources
|-
| valign="top" width="5%" | UPKB
| valign="top" width="25%" | Monday Oct 05, 2009 11:27 PM
| valign="top" width="25%" | Monday Oct 05, 2009 11:44 PM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources

|-
| valign="top" width="5%" | PGDR
| valign="top" width="25%" | Monday Oct 05, 2009 10:45 PM
| valign="top" width="25%" | Monday Oct 05, 2009 10:47 PM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources
|-
| valign="top" width="5%" | OMIM
| valign="top" width="25%" | Monday Oct 05, 2009 10:32 PM
| valign="top" width="25%" | Monday Oct 05, 2009 10:45 PM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Ontology update + OBR execution with new delta dictionary of all the resources
|-
| valign="top" width="5%" | PCM
| valign="top" width="25%" | Sunday, Oct 04, 2009 10:47 PM
| valign="top" width="25%" | Monday, Oct 05, 2009 06:11 PM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" | Resource update + OBR execution with full dictionary of the new delta of resources
|-
| valign="top" width="5%" |GAP
| valign="top" width="25%" | Sunday, Aug 23, 2009 10:44 PM
| valign="top" width="25%" | Monday, Aug 24, 2009 04:40 AM
| valign="top" width="10%" |obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Resource update + OBR execution with full dictionary of the new delta of resources
|-
| valign="top" width="5%" |SMD, DBK
| valign="top" width="25%" | Monday, Aug 03, 2009 11:28 PM
| valign="top" width="25%" | Tuesday, Aug 04, 2009 02:12 PM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Resource update + OBR execution with full dictionary of the new delta of resources
|-
| valign="top" width="5%" | AE
| valign="top" width="25%" | Monday, July 27, 2009 11:19 PM
| valign="top" width="25%" | Wednesday, July 29, 2009 02:42 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Palani
| valign="top" |Resource update + OBR execution with full dictionary of the new delta of resources
|-
| valign="top" width="5%" | (All)
| valign="top" width="25%" | Monday, July 13, 2009 02:45 AM
| valign="top" width="25%" | Tuesday, July 21, 2009 03:46 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Kuladip/Palani
| valign="top" |Resource update + OBR execution with full dictionary of the new delta of resources
|-
| valign="top" width="5%" | AE
| valign="top" width="25%" | Wednesday, June 17, 2009 3:45 AM
| valign="top" width="25%" | Wednesday, June 17, 2009 10:04 AM
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Kuladip
| valign="top" |Contexts Populated : name, description, species
|-
| valign="top" width="5%" | (All)
| valign="top" width="25%" |
| valign="top" width="25%" | June 8, 2009
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Clement
| valign="top" |End of execution of the OBR workflow & switch of OBR API to the obsdb1.obs_stage schema
|-
| valign="top" width="5%" | (All)
| valign="top" width="25%" |
| valign="top" width="25%" | May 22, 2009
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Clement
| valign="top" |OBR workflow run (from scratch) on the new schema obsdb1.obs_stage for all resources
|-
| valign="top" width="5%" | RXRD
| valign="top" width="25%" |
| valign="top" width="25%" | May 2009
| valign="top" width="10%" | obsdb1.obs_stage
| valign="top" width="10%" |Adrien
| valign="top" |Execution of the OBR index on RXRD independently
|-
| valign="top" width="5%" | (All)
| valign="top" width="25%" |
| valign="top" width="25%" | March 2009
| valign="top" width="10%" |
| valign="top" width="10%" |Clement
| valign="top" |DB schema use right now: ncbodb2.obs
|}

== Resources logs ==
* '''Execution of the OBR workflow log files'''
Log files are available here : [https://bmir-gforge.stanford.edu/gf/project/obs/docman/?subdir=58 /project/obs/docman/logs]

= Resources Access Tools =

This page is for keeping track of Resources Access Tools (RATs) developement.

=== How to write Resources Access Tools ===
How to write a resource access tool is described in this [http://www.stanford.edu/~coulet/obr_tutorial_to_add_new_resources.pdf tutorial] by Adrien Coulet.

=== Available resources ===

Resources fully functional and available in the OBR index are available here: [http://ncbolabs-dev2.stanford.edu:8080/OBS_v1/obr/resources /obr/resources]

=== On development resources ===
* PubMed (PM)
* Stanford Microarray Database (SMD)
* Pathway Commons
* CaNanoLab

Others in queue

* ChemSpider
* Human Gene Mutation Database

=== Development history ===

1. Resource: Clinicaltrials.gov
*Person responsible: Kuladip Yadav(Optra),Sanjay Jadhav(Optra).
*Notes: Fixed issue of authentication, fixed other xml related issues.
*Status:
Changes done as per suggestions :
1. Decrease request delay from 1000 ms to 800ms.
2. Implement log4j logger mechanism.

2. Resource: GEO
*Person responsible: Kuladip Yadav(Optra), Sanjay Jadhav(Optra).
*Notes:Modified GEO resource access tool to get data from both GSE and GDS database.
*Status:
Changes done as per suggestions :
1. Implement log4j logger mechanism.

3. Resource: Pubmed
*Person responsible: Kuladip Yadav(Optra), Sanjay Jadhav(Optra).
*Notes:Built a new resource access tool from existing PubMedAccessTool to populate data from eutils and pubmed xml files .
*Status:
Changes done as per suggestions :
1. Remove direct database call from PubMed RAT.
2. Implement mapStringsToLocalConceptIDs method into ObsOntologiesAccessTool and TermTable.
3. Implement log4j logger in related classes.
4. Code changes pushed in SVN.

= Migration to a production workflow =

No yet started

Resource Index REST Web Service User Guide

2010-07-29T18:27:57Z

Jonquet: /* Parameters */

===Introduction===
The Resource Index API is available through a REST web services interface.

This documentation describes the current version of the API. Some changes may append in the future.

The Resource index API is based on the web service that returns annotations from the Resource Index (called via a REST post). Additionally some simplified REST get services returned simplified results.

'''Attention, this documentation is not currently in sync with the deployed version... we plan to release pretty soon the new API (that goes with this documentation). Please refer to the history of this wiki page for [http://www.bioontology.org/wiki/index.php?title=Resource_Index_REST_Web_Service_User_Guide&oldid=10015, old documentation].'''

----

===Sample HTTP Client for the Resource Index REST Web Service===

* Test HTML Page : http://rest.bioontology.org/resource_index/test

* Test HTML Page ('''element per concept(s)''') : http://rest.bioontology.org/resource_index/test/search

* Resources Page : http://rest.bioontology.org/resource_index/resources/list/

===Service endpoints===
* To retrieve "annotations" either per element or per concept(s) : http://rest.bioontology.org/resource_index/

* To retrieve "element" per concept(s) : http://rest.bioontology.org/resource_index/search

=== POST calls ===

POST your requests at the service endpoints.

====Parameters====

The Resource Index web service offers a set of parameters that allows a user to customize the annotations returned according to his specific requirements. For example, the annotations returned can be limited to a specific set of ontology and a specific set of semantic types. Plus, the expanded annotations can be filtered.

Please see below for the list of parameters and the possible values.

'''Note** :''' ''Parameter '''email''' and '''applicationid''' applies to all POST and GET calls.''

{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''email**'''
|width="10%"|{email id}
|width="10%"|default: null
|width="70%"|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.

|-valign="top"
|width="10%"|'''applicationid**'''
|width="10%"|{aplicationid}
|width="10%"|default: null
|width="70%"|Identifies the application calling the REST service.

|-valign="top"
|width="10%"|'''ontologiesToKeepInResult'''
|width="10%"|{localOntology1,...,localOntologyN}
|width="10%"|default: empty (i.e. all ontologies)
|width="70%"|Specifies the list of ontologies you want to filter in the result from the annotation process. The list of ontologies that can be used is available in the sample HTML page. The values are separated with comma (without spaces)
* For example, 42789,42838,42142.

|-valign="top"
|width="10%"|'''semanticTypes'''
|width="10%"|{semanticType1,...,semanticTypeN}
|width="10%"|default: empty (i.e. all semanticTypes)
|width="70%"|Specifies the list of UMLS semantic types to use in the annotation process. The list of semantic types that can be used is available at the /obs/semanticTypes URL. Note that the restriction to semantic types is also applied during the semantic expansion steps.
* For example, T047,T048,T191.

|-valign="top"
|width="10%"|'''levelMax'''
|width="10%"|{integer}
|width="10%"|default: 0
|width="70%"|Specifies the maximum level a parent concept must have to be considered for the is_a semantic closure expansion step.
* For example, an annotation done with levelMax=3 will expand a direct annotations done with a concept up to the 3rd level parent in the is_a hierarchy for this concept. An annotation done with levelMax=0 is equivalent to disable the is_a transitive closure expansion step.

|-valign="top"
|width="10%"|'''mappingTypes'''
|width="10%"|{null,mappingType1,...,mappingTypeN}
|width="10%"|default: empty (i.e. all mappingTypes)
|width="70%"|Specifies the list of mapping types to use during the mapping expansion step. The list of rmapping types that can be used is available at the /obs/mappingTypes URL. The current list is described in section Mapping types.
* For example, Automatic,Manual.
* Note that the use of the key word "'''null'''" in the mappingTypes list disables the mapping expansion component.

|-valign="top"
|width="10%"|'''filterNumber'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies whether the concept recognition step to filter numbers or not.

|-valign="top"
|width="10%"|'''minTermSize'''
|width="10%"|{integer}
|width="10%"|default: 0
|width="70%"|Specifies the minimum length of the term to be included in the annotations.

|-valign="top"
|width="10%"|'''withSynonyms'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies either or not the direct annotations are done with or without Synonyms. By default it includes all the synonyms and preferred name. If 'false' is selected, the direct annotations are done with only preferred name.

|-valign="top"
|width="10%"|'''additionalStopWords'''
|width="10%"|{stopWord1,...,stopWordN}
|width="10%"|default: empty (i.e. none)
|width="70%"|Specifies the list of additional stop words to use. Already used stop words are available here: [[http://rest.bioontology.org/obs/stopwords]]

|-valign="top"
|width="10%"|'''isStopWordsCaseSenstive '''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies whether stopwords are case-sensitive or not.

|-valign="top"
|width="10%"|'''conceptids'''
|width="10%"|{conceptid1,...,conceptidn}
|width="10%"|default: empty (i.e. all concepts)
|width="70%"|Specifies the list of concept to use to query the Resource index (i.e., get the annotations done with this list). This parameter must be jointly specified with the mode parameter. If conceptids contains only one element then the mode parameter can be ignored. The values are separated with comma (without spaces).
* For example, 40401/D008545,4513/Virtual_surface.

|-valign="top"
|width="10%"|'''isVirtualOntologyId'''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies the if the list of ontologies are all BioPortal virtual ontology IDs. This parameter applies to both conceptids and ontologiesToKeepInResult parameters.

|-valign="top"
|width="10%"|'''mode'''
|width="10%"|{union, intersection}
|width="10%"|default: union
|width="70%"|Specifies the mode to use when querying the resource index with several concept (parameter conceptids ). The union mode returns the union of all the annotations (filtered eventually with other parameters) done with each specified conceptid. The intersection mode returns the intersection.

|-valign="top"
|width="10%"|'''elementid'''
|width="10%"|
|width="10%"|default: all
|width="70%"|Specifies the identifier of the resource element for which annotations are requested. The elementid is defined by the original resource e.g., PMID for PubMed, NCT for ClinicalTrials. The full list of the elementid type is defined in Section Local element ID used.
* For example, NCT00001589 or GDS2735.

|-valign="top"
|width="10%"|'''resourceid'''
|width="10%"|
|width="10%"|default: all
|width="70%"|Specifies the resource to filter the annotations with. The resourceid identifies a resource in the Resource Index. They are defined in section Resource identifiers. The list of resourceid can be used is available at the /obs/resources URL.
* For example, GEO,CT,AE.

|-valign="top"
|width="10%"|'''elementDetails'''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies the if the returned resource elements to be detailed or not.

|-valign="top"
|width="10%"|'''withContext'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies whether the annotations context information to be available or not. If turn to false, the set of annotations returned will be simplified and will not detail the context information for an annotation. Only the score will be returned.

|-valign="top"
|width="10%"|'''offset and limit'''
|width="10%"|{integer}
|width="10%"|default: 0/10 respectively
|width="70%"|Specifies an offset and limits the number of annotation results.

|-valign="top"
|width="10%"|'''format'''
|width="10%"|{text, tabDelimited, owl, rdf, xml}
|width="10%"|default: xml
|width="70%"|Specifies the desired format of the response. RDF and OWL outputs are defined according to a RDFS schema and OWL ontology respectively available here: http://obs.bioontology.org/ontologies/BioPortalAnnotation.rdfs and http://obs.bioontology.org/ontologies/NCBO_OBS_ontology.owl

|}

===Web Service Response===

'''Response Format'''
{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''text'''
|width="90%"| Returns plain text representation of the ObrResultBean(Detailled).

|-valign="top"
|width="10%"|'''tabDelimited'''
|width="90%"| Shorter version of "Text" format, returns not the full result content but the annotations only (no statistics, etc.). The format of the tab delimited file is: score \t conceptId \t preferredName \t synonyms (separated by ' /// ') \t semanticType (separated by ' /// ') \t contextName \t isDirect \t other context information (e.g., childConceptId, mappedConceptId, level, mappingType) (separated by ' /// ').

|-valign="top"
|width="10%"|'''xml'''
|width="90%"| Returns XML representation of the ObrResultBean(Detailled).

|-valign="top"
|width="10%"|'''owl'''
|width="90%"| Returns OWL representation of the ObrResultBean(Detailled). The elementsof the result (dictionary, parameters, annotations, etc) are described as instances in the following ontology: http://obs.bioontology.org/ontologies/NCBO_OBS_ontology.owl

|-valign="top"
|width="10%"|'''rdf'''
|width="90%"| Returns RDF representation of the annotations in ObrResultBean(Detailled). The elements of the result are described as instances in the following ontology: http://obs.bioontology.org/ontologies/BioPortalAnnotation.rdfs
|}

'''Note :''' ''if request parameter withContext is true, then returns representation of the ObrResultBeanDetailled and if request parameter withContext is false, then returns representation of the ObrResultBean.''

'''Response Content: ObrResultBeanDetailled'''

Response ObrResultBeanDetailled contains all the contents of ObrResultBean. Those contents are described in section Response Content: ObrResultBean.

Following are remaining contents for ObrResultBeanDetailled :

{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''directAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|-valign="top"
|width="10%"|'''isaAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|-valign="top"
|width="10%"|'''mappingAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|}

'''Note :''' ''Response contents of the ObrAnnotationBean are described in section ObrResultBean annotations''

'''Response Content: ObrResultBean'''
{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''resultID'''
|width="90%"|
|-valign="top"
|width="10%"|'''dictionary'''
|width="90%"| Dictionary contains the metadata (not the content) of the dictionary used for a result. dictionaryId, dictionaryName, and dictionaryDate identify the dictionary on the server side and give information about its content. Dictionary versioning is strongly linked to the evolution of the ontologies used. Each time ontologies change, the dictionary is updated. All the dictionary information may be useful for comparing results of the Annotator Restlet service on time.
|-valign="top"
|width="10%"|'''statistics'''
|width="90%"| Statistics contains information on the number of annotations done for a given context. The contextName keyword identifies the type of context and nbAnnotation is the number of annotations of this type.
|-valign="top"
|width="10%"|'''parameters'''
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Annotator Restlet service. Those parameters are described in section Service parameters
|-valign="top"
|width="10%"|'''ontologies'''
|width="90%"| To keep the model simple, we provide only the global ontology identifier, localOntologyId the name (ontologyName) and version (ontologyVersion). This information come from the original repositories (UMLS/BioPortal) and might help the user to select the right ontology to use. When an ontology is used in the annotation, a result has a set of OntologyUsed which specify 2 other properties: nbAnnotation, the number of annotation that have been made with concepts from this ontology. score, the sum of all the scores of the annotations done with concepts from this ontology (if parameter scored=true). Therefore, score represents the most accurate ontology to annotate the given text.
|-valign="top"
|width="10%"|'''annotations'''
|width="90%"| ObrAnnotationBean/ObrAnnotationBeanDetailled is a representation of one annotation. If ''elementDetails'' parameter is true the service return response of type ObrAnnotationBean ,otherwise ObrAnnotationBeanDetailled. An annotation has a score which represents the accuracy of the annotation computed by the scoring algorithm (if the scored=true parameter was chosen, otherwise score=-1). An annotation is done with a concept in a context.

'''Response Content: ObrAnnotationBeanDetailled'''

Response ObrAnnotationBeanDetailled contains all the contents of ObrAnnotationBean. Those contents are described in section Response Content: ObrAnnotationBean.

Following are remaining contents for ObrAnnotationBeanDetailled :

{| border="2" 

|-valign="top"
|width="10%"|'''element'''
|width="90%"|
* ''localElementID'' - Global identifier for the resource element.
* ''elementStructure'' - Represents Structure of an element for a given resource.

'''Response Content: Structure'''

{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|resource identifier for Resource.

|-valign="top"
|width="10%"|'''contexts'''
|width="90%"|list of context for resource.

|-valign="top"
|width="10%"|'''itemKeys'''
|width="90%"|list of itemKeys for resource.

|-valign="top"
|width="10%"|'''weights'''
|width="90%"|map contain weights (as double) for each context (as String).

|-valign="top"
|width="10%"|'''ontoIDs'''
|width="90%"|map contain ontologyIDs for each context (as String).
|}

|}

'''Response Content: ObrAnnotationBean'''

{| border="2" 
|-valign="top"
|width="10%"|'''localElementID'''
|width="90%"| Identifier for resource element.
|-valign="top"
|width="10%"|'''score'''
|width="90%"|
|-valign="top"
|width="10%"|'''concept'''
|width="90%"|
* ''localConceptId'' - global identifier for the concept in its original repository.
* ''localOntologyId'' - identifier for the ontology in which the concept is defined.
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology.
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository).
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred.
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999).
|-valign="top"
|width="10%"|'''context'''
|width="90%"| Context specifies if it is a direct or expanded annotation and give precision about the origin of the annotation. ''contextName'' identifies the type of context. The context properties vary with the type of concept. There are 3 possible contexts identified by their contextName:
{| border="2" style="background:#ABCDEF;" 
|-valign="top"
|width="10%"|'''MGREP'''
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A Mgrep context has 3 properties:
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression. Attention, those values are in number of bytes, not characters e.g., ½ is a two-byte character, thus will count for 2 characters.
|-valign="top"
|width="10%"|'''ISA_CLOSURE'''
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:
* ''childConceptId'' - the concept from which the annotation was derived.
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.
* For example, if a direct annotation with NCI/C0025202 (melanoma) was done, the is_a transitive closure component may expand it to another annotation with NCI/C1302746 (Melanocytic Neoplasm) because the latter is a direct parent (i.e., level 1) concept of the former. The ISA_CLOSURE annotation generated will have the following properties {NCI/C0025202, 1}.
|-valign="top"
|width="10%"|'''MAPPING'''
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties:
* mappedConceptId identifies the concept from which the annotation was derived.
* mappingType specifies the type of mapping.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.
|}
|}

|-valign="top"
|width="10%"|'''localElementID localConceptIDs mode withContext elementDetails counts offsetStart offsetMax'''
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Resource Index Restlet service. Those parameters are described in section Service parameters

|}

===GET calls===
Following section describes all other simplified GET services available in Resource_Index_API.

====Annotation by Concept Service====
Returns the set of annotations done with a given localConceptID.

*GET Request Format : '''/byconcept/{ontologyid}/{withContext}/{counts}/{offset}/{limit}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/42693/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/{ontologyID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/{ontologyID}/{conceptID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled. If request parameter withContext is true, then returns representation of the ObrResultBeanDetailled and if request parameter withContext is false, then returns representation of the ObrResultBean.

====Annotation for BioPortal virtual ontology Concept Service ====
Returns the set of all annotations done with a given localConceptID using BioPortal virtual ontology ID.

*GET Request Format : '''/byconcept/virtual/{virtualOntologyID}/{withContext}/{counts}/{offset}/{limit}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/virtual/1032/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/virtual/{virtualOntologyID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/virtual/{virtualOntologyID}/{conceptID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation By Concept And Resource Service ====
Returns the set of all annotations done with a given localConceptID for given resourceID.

*GET Request Format : '''/byconcept/{ontologyid}/{resourceid}/{withContext}/{counts}/{offset}/{limit}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/42693/AE/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/{ontologyID}/{resourceID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/{ontologyID}/{conceptID}/{resourceID}/{withContext}/{counts}/{from}/{number}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation for BioPortal virtual ontology Concept And Resource Service ====
Returns the set of all annotations done with a given localConceptID using BioPortal virtual ontology ID and using particular resourceID.

*GET Request Format : '''/byconcept/virtual/{virtualOntologyID}/{resourceid}/{withContext}/{counts}/{offset}/{limit}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/virtual/1032/AE/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/virtual/{virtualOntologyID}/{resourceID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/virtual/{virtualOntologyID}/{conceptID}/{resourceID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation By Resource Element Service ====
Returns the set of all annotations done with a given resource element localElementID for all the concepts.

*GET Request Format : '''/byelement/{resourceid}/{elementDetails}{withContext}/{counts}/{offset}/{limit}?elementid={elementid}'''
*Example 1 : http://rest.bioontology.org/resource_index/byelement/AE/false/true/false/0/10?elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Example 1 : http://rest.bioontology.org/resource_index/byelement/AE/true/true/false/0/10?elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest

*Old Request Format* :
**/byelement/{resourceID}/{withContext}/{counts}/{from}/{number}?elementID={localElementID}
**/byelement/{resourceID}/{localElementID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation Details By Resource Element Service ====
Returns the set of all annotations details with a given resource element localElementID for given conceptID

*GET Request Format : '''/details/{elementDetails}/concept/{ontologyid}/resource/{resourceid}?conceptid={conceptid}&elementid={elementid}'''
*Example1 : http://rest.bioontology.org/resource_index/details/true/concept/42693/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Example2 : http://rest.bioontology.org/resource_index/details/false/concept/42693/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/details/{elementDetails}/concept/{ontologyID}/resource/{resourceID}?conceptID={conceptID}&elementID={localElementID}
**/details/{elementDetails}/concept/{ontologyID}/{conceptID}/resource/{resourceID}/element/{localElementID}

*Response Content : ObrAnnotationBeanDetailled if elementDetails is true otherwise ObrAnnotationBean

====Annotation Details By Resource Element Service for BioPortal Virtual OntologyID====
Returns the set of all annotations details with a given resource element localElementID for given conceptID of BioPortal virtual ontologyID

*GET Request Format : '''/details/{elementDetails}/virtual/concept/{virtualOntologyID}/resource/{resourceid}?conceptid={conceptid}&elementid={elementid}'''
*Example1 : http://rest.bioontology.org/resource_index/details/true/virtual/concept/1032/Melanoma/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Example2 : http://rest.bioontology.org/resource_index/details/false/virtual/concept/1032/npo:Nanoparticle/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/details/{elementDetails}/virtual/concept/{virtualOntologyID}/resource/{resourceID}?conceptID={conceptID}&elementID={localElementID}
**/details/{elementDetails}/virtual/concept/{virtualOntologyID}/{conceptID}/resource/{resourceID}/element/{localElementID}

*Response Content : ObrAnnotationBeanDetailled if elementDetails is true otherwise ObrAnnotationBean.

====Resources Service ====
Returns the set of all resources available in resource index and information related to it.

*GET Request Format : ''/resources''
*Example: http://rest.bioontology.org/resource_index/resources?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource is a representation of one resource
'''Response Content: Resource'''

{| border="2" 
|-valign="top"
|width="10%"|'''resourceName'''
|width="90%"| Name of the particular resource.

|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"| Identifier of the resource.

|-valign="top"
|width="10%"|'''mainContext'''
|width="90%"| Main context string for the resource.

|-valign="top"
|width="10%"|'''resourceURL'''
|width="90%"| Website URL for the resource

|-valign="top"
|width="10%"|'''resourceElementURL'''
|width="90%"| Base URL for getting elements for resource.

|-valign="top"
|width="10%"|'''resourceDescription'''
|width="90%"| Description of the resource.

|-valign="top"
|width="10%"|'''resourceLogo'''
|width="90%"| URL of logo image for the resource.

|-valign="top"
|width="10%"|'''resourceStructure'''
|width="90%"| Represents Structure of an element for the resource.

'''Response Content: Structure'''

{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|resource identifier for Resource.

|-valign="top"
|width="10%"|'''contexts'''
|width="90%"|list of context for resource.

|-valign="top"
|width="10%"|'''itemKeys'''
|width="90%"|list of itemKeys for resource.

|-valign="top"
|width="10%"|'''weights'''
|width="90%"|map contain weights (as double) for each context (as String).

|-valign="top"
|width="10%"|'''ontoIDs'''
|width="90%"|map contain ontologyIDs for each context (as String).
|}

|}

====Resource Service ====
Returns the resource in resource index for given resourceID and information related to it.

*GET Request Format : ''/resources/{resourceid}''
*Example: http://rest.bioontology.org/resource_index/resources/AE?email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /resources/{resourceID}
*Response Content : Resource.

====Resource Element Service ====
Service returns elementURL for given localElementID and redirect it to get resource element on the web.

*GET Request Format : ''/element/{resourceid}?elementid={elementid}''
*Example: http://rest.bioontology.org/resource_index/element/AE?elementid=E-GEOD-9118&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /element/{resourceID}?element={localElementID}
*Response Content : Web page containing details of the element.

====Element details service by elementid ====
Returns detail for given element using resource id and element id

*GET Request Format : ''/elementDetails/{resourceid}?elementid={elementid}''
*Example: http://rest.bioontology.org/resource_index/elementDetails/AE?elementid=E-GEOD-9118&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : element

====Elements detail service by chronology ====
Retruns elements details for given resource id cronologically

*GET Request Format : ''/elements/{resourceid}?method={method}&offset={offset}&limit={limit}''
*Example: http://rest.bioontology.org/resource_index/elements/AE?method=chronology&offset=0&limit=10&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Element is a representation of one element.

====Resources Service with ontologies used for indexing ====
Returns the set of all resources available in resource index and list of onotolgies used for indexing them.

*GET Request Format : ''/resources?withontologies=true''
*Example: http://rest.bioontology.org/resource_index/resources?withontologies=true&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /resources?withOntologies=true
*Response Content : ObrResourceBean is a representation of one resource with ontologies
'''Response Content: ObrResourceBean'''

Response ObrResourceBean contains all the contents of Resource. Those contents are described in section ''Response Content: Resource''.

Following are remaining contents for ObrResourceBean :

{| border="2" 
|-valign="top"
|width="10%"|'''ontologiesUsed'''
|width="90%"| Presents list of ontologies used for indexing. Each ontology of type OntologyBean.
'''Response Content: OntologyBean'''
{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''localOntologyID'''
|width="90%"|Local onotology id for Ontology.

|-valign="top"
|width="10%"|'''ontologyName'''
|width="90%"|name of the resource.

|-valign="top"
|width="10%"|'''ontologyVersion'''
|width="90%"|version number for resource.

|-valign="top"
|width="10%"|'''virtualOntologyID'''
|width="90%"|virtual ontology id for ontology.
|}
|}

====Resource Service with ontologies used for indexing ====
Returns the information about resources and list of onotolgies used for indexing it.

*GET Request Format : ''/resources/{resourceid}?withontologies=true''
*Example: http://rest.bioontology.org/resource_index/resources/AE?withOntologies=true&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format : /resources/{resourceID}?withOntologies=true
*Response Content : Resource is represented by ObrResourceBean.

====Ontologies Service with resources indexed ====
Returns the set of all ontologies used in resource index with list of resources indexed by given ontology.

*GET Request Format : ''/ontologies?withresources=true''
*Example: http://rest.bioontology.org/resource_index/ontologies?withresources=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Each Ontology is represented by ObrOntologyBean.

Response ObrOntologyBean contains all the contents of OntologyBean.Those contents are described in section Response Content: OntologyBean.

Following are remaining contents for ObrResourceBean :
{| border="2" 
|-valign="top"
|width="10%"|'''resources'''
|width="90%"| Represents list of resources. Response content for each resource is of type Resource.
|}

====Ontology Service with resources indexed ====
Returns the information about given ontologies used in resource index with list of resources.

*GET Request Format : ''/ontologies/{ontologyid}''
*Example: http://rest.bioontology.org/resource_index/ontologies/42693?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Ontology is represented by ObrOntologyBean.

====Virtual Ontology Service with resources indexed ====
Returns the ontology versions in resource index with list of resources for given virtual_ontology_id.

*GET Request Format : ''/virtual/ontology/{virtual_ontology_id}?withresources={true|false}''
*Example: http://rest.bioontology.org/resource_index/virtual/ontology/1032?withresources=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : List of ontologies represented by ObrOntologyBean.

====Concept Frequency Service====
Returns the get most used concepts for given resource id.

*GET Request Format : ''/most-used-concepts/{resourceid}?method={counts|score}&offset={offset}&limit={limit}''
*Example: http://rest.bioontology.org/resource_index/most-used-concepts/AE?method=counts&offset=0&limit=10&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource Index Concepts with format ObrConceptFrequencyBean.

'''Response Content: ObrConceptFrequencyBean'''

Following are contents for ObrConceptFrequencyBean:
{| border="2" 
|-valign="top"
|width="10%"|'''concept'''
|width="90%"|ConceptBean is a representation of concept

|-valign="top"
|width="10%"|'''counts'''
|width="90%"|Frequency counts for a concept .

|-valign="top"
|width="10%"|'''score'''
|width="90%"|score for a concept .

|}

====All Statistics Service====
Returns the information about number of all the annotations done in resource index.

*GET Request Format : ''/statistics/all''
*Example: http://rest.bioontology.org/resource_index/statistics/all?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : All annotations represented by ObrStatisticsBean.

'''Response Content: ObrStatisticsBean'''
Following are remaining contents for ObrStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''aggregatedAnnotations'''
|width="90%"|Sum of the number of rows in all the indexing tables

|-valign="top"
|width="10%"|'''mgrepAnnotations'''
|width="90%"|Number of mgrep annotations entries in direct annotation table.

|-valign="top"
|width="10%"|'''reportedAnnotations'''
|width="90%"|Number of reported annotations entries in direct annotation table.

|-valign="top"
|width="10%"|'''isaAnnotations'''
|width="90%"|Number of is-a annotations entries in extended annotation table.

|-valign="top"
|width="10%"|'''mappingAnnotations'''
|width="90%"|Number of mapping annotations entries in extended annotation table.

|}

====Ontology Statistics Service====
Returns the total statistics for given ontology for All resources.

*GET Request Format : ''/statistics/ontology/{ontologyid}''
*Example: http://rest.bioontology.org/resource_index/statistics/ontology/42693?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Ontology statistics with format ObrOntologyStatisticsBean.

'''Response Content: ObrOntologyStatisticsBean'''
Following are contents for ObrOntologyStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|Resource Id for resource.

|-valign="top"
|width="10%"|'''statistics'''
|width="90%"|ObrStatisticsBean is a representation of statistics

|}

====Ontology Statistics Service by resources====
Returns the statistics for given ontology for each resource separately.

*GET Request Format : ''/statistics/ontology/{onotlogyid}?byresource=true''
*Example: http://rest.bioontology.org/resource_index/statistics/ontology/42693?byresource=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : ObrOntologyStatisticsBean

====Resource Statistics Service====
Returns the total statistics for given resource for All ontology.

*GET Request Format : ''/statistics/resource/{resourceid}''
*Example: http://rest.bioontology.org/resource_index/statistics/resource/CANANO?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource statistics with format ObrResourceStatisticsBean.

'''Response Content: ObrResourceStatisticsBean'''
Following are contents for ObrResourceStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''localOntologyID'''
|width="90%"|local ontology id for given ontology.

|-valign="top"
|width="10%"|'''statistics'''
|width="90%"|ObrStatisticsBean is a representation of statistics

|}

====Resource Statistics Service by ontologies====
Returns the statistics for given resource for each ontology separately.

*GET Request Format : ''/statistics/resource/{resourceid}?byontology=true ''
*Example: http://rest.bioontology.org/resource_index/statistics/resource/AE?byontology=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource statistics with format ObrResourceStatisticsBean.

----
'''Note* :''' ''Old Request Format not working anymore.''

----

Resource Index REST Web Service User Guide

2010-07-28T23:42:42Z

Jonquet: /* Web Service Response */

===Introduction===
The Resource Index API is available through a REST web services interface.

This documentation describes the current version of the API. Some changes may append in the future.

The Resource index API is based on the web service that returns annotations from the Resource Index (called via a REST post). Additionally some simplified REST get services returned simplified results.

'''Attention, this documentation is not currently in sync with the deployed version... we plan to release pretty soon the new API (that goes with this documentation). Please refer to the history of this wiki page for [http://www.bioontology.org/wiki/index.php?title=Resource_Index_REST_Web_Service_User_Guide&oldid=10015, old documentation].'''

----

===Sample HTTP Client for the Resource Index REST Web Service===

* Test HTML Page : http://rest.bioontology.org/resource_index/test

* Test HTML Page ('''element per concept(s)''') : http://rest.bioontology.org/resource_index/test/search

* Resources Page : http://rest.bioontology.org/resource_index/resources/list/

===Service endpoints===
* To retrieve "annotations" either per element or per concept(s) : http://rest.bioontology.org/resource_index/

* To retrieve "element" per concept(s) : http://rest.bioontology.org/resource_index/search

=== POST calls ===

POST your requests at the service endpoints.

====Parameters====

The Resource Index web service offers a set of parameters that allows a user to customize the annotations returned according to his specific requirements. For example, the annotations returned can be limited to a specific set of ontology and a specific set of semantic types. Plus, the expanded annotations can be filtered.

Please see below for the list of parameters and the possible values.

'''Note** :''' ''Parameter '''email''' and '''applicationid''' applies to all POST and GET calls.''

{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''email**'''
|width="10%"|{email id}
|width="10%"|default: null
|width="70%"|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.

|-valign="top"
|width="10%"|'''applicationid**'''
|width="10%"|{aplicationid}
|width="10%"|default: null
|width="70%"|Identifies the application calling the REST service.

|-valign="top"
|width="10%"|'''ontologiesToKeepInResult'''
|width="10%"|{localOntology1,...,localOntologyN}
|width="10%"|default: empty (i.e. all ontologies)
|width="70%"|Specifies the list of ontologies you want to filter in the result from the annotation process. The list of ontologies that can be used is available in the sample HTML page. The values are separated with comma (without spaces)
* For example, 42789,42838,42142.

|-valign="top"
|width="10%"|'''semanticTypes'''
|width="10%"|{semanticType1,...,semanticTypeN}
|width="10%"|default: empty (i.e. all semanticTypes)
|width="70%"|Specifies the list of UMLS semantic types to use in the annotation process. The list of semantic types that can be used is available at the /obs/semanticTypes URL. Note that the restriction to semantic types is also applied during the semantic expansion steps.
* For example, T047,T048,T191.

|-valign="top"
|width="10%"|'''levelMax'''
|width="10%"|{integer}
|width="10%"|default: 0
|width="70%"|Specifies the maximum level a parent concept must have to be considered for the is_a semantic closure expansion step.
* For example, an annotation done with levelMax=3 will expand a direct annotations done with a concept up to the 3rd level parent in the is_a hierarchy for this concept. An annotation done with levelMax=0 is equivalent to disable the is_a transitive closure expansion step.

|-valign="top"
|width="10%"|'''mappingTypes'''
|width="10%"|{null,mappingType1,...,mappingTypeN}
|width="10%"|default: empty (i.e. all mappingTypes)
|width="70%"|Specifies the list of mapping types to use during the mapping expansion step. The list of rmapping types that can be used is available at the /obs/mappingTypes URL. The current list is described in section Mapping types.
* For example, Automatic,Manual.
* Note that the use of the key word "'''null'''" in the mappingTypes list disables the mapping expansion component.

|-valign="top"
|width="10%"|'''filterNumber'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies whether the concept recognition step to filter numbers or not.

|-valign="top"
|width="10%"|'''minTermSize'''
|width="10%"|{integer}
|width="10%"|default: 0
|width="70%"|Specifies the minimum length of the term to be included in the annotations.

|-valign="top"
|width="10%"|'''withSynonyms'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies either or not the direct annotations are done with or without Synonyms. By default it includes all the synonyms and preferred name. If 'false' is selected, the direct annotations are done with only preferred name.

|-valign="top"
|width="10%"|'''additionalStopWords'''
|width="10%"|{stopWord1,...,stopWordN}
|width="10%"|default: empty (i.e. none)
|width="70%"|Specifies the list of additional stop words to use. Already used stop words are available here: [[http://rest.bioontology.org/obs/stopwords]]

|-valign="top"
|width="10%"|'''isStopWordsCaseSenstive '''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies whether stopwords are case-sensitive or not.

|-valign="top"
|width="10%"|'''conceptids'''
|width="10%"|{conceptid1,...,conceptidn}
|width="10%"|default: empty (i.e. all concepts)
|width="70%"|Specifies the list of concept to use to query the Resource index (i.e., get the annotations done with this list). This parameter must be jointly specified with the mode parameter. If conceptids contains only one element then the mode parameter can be ignored. The values are separated with comma (without spaces).
* For example, 40401/D008545,4513/Virtual_surface.

|-valign="top"
|width="10%"|'''isVirtualOntologyId'''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies the if the list of ontologies are all BioPortal virtual ontology IDs. This parameter applies to both conceptids and ontologiesToKeepInResult parameters.

|-valign="top"
|width="10%"|'''mode'''
|width="10%"|{union, intersection}
|width="10%"|default: union
|width="70%"|Specifies the mode to use when querying the resource index with several concept (parameter conceptids ). The union mode returns the union of all the annotations (filtered eventually with other parameters) done with each specified conceptid. The intersection mode returns the intersection.

|-valign="top"
|width="10%"|'''elementid'''
|width="10%"|
|width="10%"|default: all
|width="70%"|Specifies the identifier of the resource element for which annotations are requested. The elementid is defined by the original resource e.g., PMID for PubMed, NCT for ClinicalTrials. The full list of the elementid type is defined in Section Local element ID used.
* For example, NCT00001589 or GDS2735.

|-valign="top"
|width="10%"|'''resourceid'''
|width="10%"|
|width="10%"|default: all
|width="70%"|Specifies the resource to filter the annotations with. The resourceid identifies a resource in the Resource Index. They are defined in section Resource identifiers. The list of resourceid can be used is available at the /obs/resources URL.
* For example, GEO,CT,AE.

|-valign="top"
|width="10%"|'''elementDetails'''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies the if the returned resource elements to be detailed or not.

|-valign="top"
|width="10%"|'''withContext'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies whether the annotations context information to be available or not. If turn to false, the set of annotations returned will be simplified and will not detail the context information for an annotation. Only the score will be returned.

|-valign="top"
|width="10%"|'''offset and limit'''
|width="10%"|{integer}
|width="10%"|default: 0/10 respectively
|width="70%"|Specifies an offset and limits the number of annotation results.

|-valign="top"
|width="10%"|'''format'''
|width="10%"|{text, tabDelimited, owl, xml}
|width="10%"|default: xml
|width="70%"|Specifies the desired format of the response.

|}

===Web Service Response===

'''Response Format'''
{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''text'''
|width="90%"| Returns plain text representation of the ObrResultBean(Detailled).

|-valign="top"
|width="10%"|'''tabDelimited'''
|width="90%"| Shorter version of "Text" format, returns not the full result content but the annotations only (no statistics, etc.). The format of the tab delimited file is: score \t conceptId \t preferredName \t synonyms (separated by ' /// ') \t semanticType (separated by ' /// ') \t contextName \t isDirect \t other context information (e.g., childConceptId, mappedConceptId, level, mappingType) (separated by ' /// ').

|-valign="top"
|width="10%"|'''xml'''
|width="90%"| Returns XML representation of the ObrResultBean(Detailled).

|-valign="top"
|width="10%"|'''owl'''
|width="90%"| Returns OWL representation of the ObrResultBean(Detailled). The elementsof the result (dictionary, parameters, annotations, etc) are described as instances in the following ontology: http://obs.bioontology.org/ontologies/NCBO_OBS_ontology.owl
|}

'''Note :''' ''if request parameter withContext is true, then returns representation of the ObrResultBeanDetailled and if request parameter withContext is false, then returns representation of the ObrResultBean.''

'''Response Content: ObrResultBeanDetailled'''

Response ObrResultBeanDetailled contains all the contents of ObrResultBean. Those contents are described in section Response Content: ObrResultBean.

Following are remaining contents for ObrResultBeanDetailled :

{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''directAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|-valign="top"
|width="10%"|'''isaAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|-valign="top"
|width="10%"|'''mappingAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|}

'''Note :''' ''Response contents of the ObrAnnotationBean are described in section ObrResultBean annotations''

'''Response Content: ObrResultBean'''
{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''resultID'''
|width="90%"|
|-valign="top"
|width="10%"|'''dictionary'''
|width="90%"| Dictionary contains the metadata (not the content) of the dictionary used for a result. dictionaryId, dictionaryName, and dictionaryDate identify the dictionary on the server side and give information about its content. Dictionary versioning is strongly linked to the evolution of the ontologies used. Each time ontologies change, the dictionary is updated. All the dictionary information may be useful for comparing results of the Annotator Restlet service on time.
|-valign="top"
|width="10%"|'''statistics'''
|width="90%"| Statistics contains information on the number of annotations done for a given context. The contextName keyword identifies the type of context and nbAnnotation is the number of annotations of this type.
|-valign="top"
|width="10%"|'''parameters'''
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Annotator Restlet service. Those parameters are described in section Service parameters
|-valign="top"
|width="10%"|'''ontologies'''
|width="90%"| To keep the model simple, we provide only the global ontology identifier, localOntologyId the name (ontologyName) and version (ontologyVersion). This information come from the original repositories (UMLS/BioPortal) and might help the user to select the right ontology to use. When an ontology is used in the annotation, a result has a set of OntologyUsed which specify 2 other properties: nbAnnotation, the number of annotation that have been made with concepts from this ontology. score, the sum of all the scores of the annotations done with concepts from this ontology (if parameter scored=true). Therefore, score represents the most accurate ontology to annotate the given text.
|-valign="top"
|width="10%"|'''annotations'''
|width="90%"| ObrAnnotationBean/ObrAnnotationBeanDetailled is a representation of one annotation. If ''elementDetails'' parameter is true the service return response of type ObrAnnotationBean ,otherwise ObrAnnotationBeanDetailled. An annotation has a score which represents the accuracy of the annotation computed by the scoring algorithm (if the scored=true parameter was chosen, otherwise score=-1). An annotation is done with a concept in a context.

'''Response Content: ObrAnnotationBeanDetailled'''

Response ObrAnnotationBeanDetailled contains all the contents of ObrAnnotationBean. Those contents are described in section Response Content: ObrAnnotationBean.

Following are remaining contents for ObrAnnotationBeanDetailled :

{| border="2" 

|-valign="top"
|width="10%"|'''element'''
|width="90%"|
* ''localElementID'' - Global identifier for the resource element.
* ''elementStructure'' - Represents Structure of an element for a given resource.

'''Response Content: Structure'''

{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|resource identifier for Resource.

|-valign="top"
|width="10%"|'''contexts'''
|width="90%"|list of context for resource.

|-valign="top"
|width="10%"|'''itemKeys'''
|width="90%"|list of itemKeys for resource.

|-valign="top"
|width="10%"|'''weights'''
|width="90%"|map contain weights (as double) for each context (as String).

|-valign="top"
|width="10%"|'''ontoIDs'''
|width="90%"|map contain ontologyIDs for each context (as String).
|}

|}

'''Response Content: ObrAnnotationBean'''

{| border="2" 
|-valign="top"
|width="10%"|'''localElementID'''
|width="90%"| Identifier for resource element.
|-valign="top"
|width="10%"|'''score'''
|width="90%"|
|-valign="top"
|width="10%"|'''concept'''
|width="90%"|
* ''localConceptId'' - global identifier for the concept in its original repository.
* ''localOntologyId'' - identifier for the ontology in which the concept is defined.
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology.
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository).
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred.
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999).
|-valign="top"
|width="10%"|'''context'''
|width="90%"| Context specifies if it is a direct or expanded annotation and give precision about the origin of the annotation. ''contextName'' identifies the type of context. The context properties vary with the type of concept. There are 3 possible contexts identified by their contextName:
{| border="2" style="background:#ABCDEF;" 
|-valign="top"
|width="10%"|'''MGREP'''
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A Mgrep context has 3 properties:
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression. Attention, those values are in number of bytes, not characters e.g., ½ is a two-byte character, thus will count for 2 characters.
|-valign="top"
|width="10%"|'''ISA_CLOSURE'''
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:
* ''childConceptId'' - the concept from which the annotation was derived.
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.
* For example, if a direct annotation with NCI/C0025202 (melanoma) was done, the is_a transitive closure component may expand it to another annotation with NCI/C1302746 (Melanocytic Neoplasm) because the latter is a direct parent (i.e., level 1) concept of the former. The ISA_CLOSURE annotation generated will have the following properties {NCI/C0025202, 1}.
|-valign="top"
|width="10%"|'''MAPPING'''
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties:
* mappedConceptId identifies the concept from which the annotation was derived.
* mappingType specifies the type of mapping.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.
|}
|}

|-valign="top"
|width="10%"|'''localElementID localConceptIDs mode withContext elementDetails counts offsetStart offsetMax'''
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Resource Index Restlet service. Those parameters are described in section Service parameters

|}

===GET calls===
Following section describes all other simplified GET services available in Resource_Index_API.

====Annotation by Concept Service====
Returns the set of annotations done with a given localConceptID.

*GET Request Format : '''/byconcept/{ontologyid}/{withContext}/{counts}/{offset}/{limit}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/42693/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/{ontologyID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/{ontologyID}/{conceptID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled. If request parameter withContext is true, then returns representation of the ObrResultBeanDetailled and if request parameter withContext is false, then returns representation of the ObrResultBean.

====Annotation for BioPortal virtual ontology Concept Service ====
Returns the set of all annotations done with a given localConceptID using BioPortal virtual ontology ID.

*GET Request Format : '''/byconcept/virtual/{virtualOntologyID}/{withContext}/{counts}/{offset}/{limit}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/virtual/1032/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/virtual/{virtualOntologyID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/virtual/{virtualOntologyID}/{conceptID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation By Concept And Resource Service ====
Returns the set of all annotations done with a given localConceptID for given resourceID.

*GET Request Format : '''/byconcept/{ontologyid}/{resourceid}/{withContext}/{counts}/{offset}/{limit}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/42693/AE/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/{ontologyID}/{resourceID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/{ontologyID}/{conceptID}/{resourceID}/{withContext}/{counts}/{from}/{number}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation for BioPortal virtual ontology Concept And Resource Service ====
Returns the set of all annotations done with a given localConceptID using BioPortal virtual ontology ID and using particular resourceID.

*GET Request Format : '''/byconcept/virtual/{virtualOntologyID}/{resourceid}/{withContext}/{counts}/{offset}/{limit}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/virtual/1032/AE/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/virtual/{virtualOntologyID}/{resourceID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/virtual/{virtualOntologyID}/{conceptID}/{resourceID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation By Resource Element Service ====
Returns the set of all annotations done with a given resource element localElementID for all the concepts.

*GET Request Format : '''/byelement/{resourceid}/{elementDetails}{withContext}/{counts}/{offset}/{limit}?elementid={elementid}'''
*Example 1 : http://rest.bioontology.org/resource_index/byelement/AE/false/true/false/0/10?elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Example 1 : http://rest.bioontology.org/resource_index/byelement/AE/true/true/false/0/10?elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest

*Old Request Format* :
**/byelement/{resourceID}/{withContext}/{counts}/{from}/{number}?elementID={localElementID}
**/byelement/{resourceID}/{localElementID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation Details By Resource Element Service ====
Returns the set of all annotations details with a given resource element localElementID for given conceptID

*GET Request Format : '''/details/{elementDetails}/concept/{ontologyid}/resource/{resourceid}?conceptid={conceptid}&elementid={elementid}'''
*Example1 : http://rest.bioontology.org/resource_index/details/true/concept/42693/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Example2 : http://rest.bioontology.org/resource_index/details/false/concept/42693/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/details/{elementDetails}/concept/{ontologyID}/resource/{resourceID}?conceptID={conceptID}&elementID={localElementID}
**/details/{elementDetails}/concept/{ontologyID}/{conceptID}/resource/{resourceID}/element/{localElementID}

*Response Content : ObrAnnotationBeanDetailled if elementDetails is true otherwise ObrAnnotationBean

====Annotation Details By Resource Element Service for BioPortal Virtual OntologyID====
Returns the set of all annotations details with a given resource element localElementID for given conceptID of BioPortal virtual ontologyID

*GET Request Format : '''/details/{elementDetails}/virtual/concept/{virtualOntologyID}/resource/{resourceid}?conceptid={conceptid}&elementid={elementid}'''
*Example1 : http://rest.bioontology.org/resource_index/details/true/virtual/concept/1032/Melanoma/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Example2 : http://rest.bioontology.org/resource_index/details/false/virtual/concept/1032/npo:Nanoparticle/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/details/{elementDetails}/virtual/concept/{virtualOntologyID}/resource/{resourceID}?conceptID={conceptID}&elementID={localElementID}
**/details/{elementDetails}/virtual/concept/{virtualOntologyID}/{conceptID}/resource/{resourceID}/element/{localElementID}

*Response Content : ObrAnnotationBeanDetailled if elementDetails is true otherwise ObrAnnotationBean.

====Resources Service ====
Returns the set of all resources available in resource index and information related to it.

*GET Request Format : ''/resources''
*Example: http://rest.bioontology.org/resource_index/resources?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource is a representation of one resource
'''Response Content: Resource'''

{| border="2" 
|-valign="top"
|width="10%"|'''resourceName'''
|width="90%"| Name of the particular resource.

|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"| Identifier of the resource.

|-valign="top"
|width="10%"|'''mainContext'''
|width="90%"| Main context string for the resource.

|-valign="top"
|width="10%"|'''resourceURL'''
|width="90%"| Website URL for the resource

|-valign="top"
|width="10%"|'''resourceElementURL'''
|width="90%"| Base URL for getting elements for resource.

|-valign="top"
|width="10%"|'''resourceDescription'''
|width="90%"| Description of the resource.

|-valign="top"
|width="10%"|'''resourceLogo'''
|width="90%"| URL of logo image for the resource.

|-valign="top"
|width="10%"|'''resourceStructure'''
|width="90%"| Represents Structure of an element for the resource.

'''Response Content: Structure'''

{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|resource identifier for Resource.

|-valign="top"
|width="10%"|'''contexts'''
|width="90%"|list of context for resource.

|-valign="top"
|width="10%"|'''itemKeys'''
|width="90%"|list of itemKeys for resource.

|-valign="top"
|width="10%"|'''weights'''
|width="90%"|map contain weights (as double) for each context (as String).

|-valign="top"
|width="10%"|'''ontoIDs'''
|width="90%"|map contain ontologyIDs for each context (as String).
|}

|}

====Resource Service ====
Returns the resource in resource index for given resourceID and information related to it.

*GET Request Format : ''/resources/{resourceid}''
*Example: http://rest.bioontology.org/resource_index/resources/AE?email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /resources/{resourceID}
*Response Content : Resource.

====Resource Element Service ====
Service returns elementURL for given localElementID and redirect it to get resource element on the web.

*GET Request Format : ''/element/{resourceid}?elementid={elementid}''
*Example: http://rest.bioontology.org/resource_index/element/AE?elementid=E-GEOD-9118&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /element/{resourceID}?element={localElementID}
*Response Content : Web page containing details of the element.

====Element details service by elementid ====
Returns detail for given element using resource id and element id

*GET Request Format : ''/elementDetails/{resourceid}?elementid={elementid}''
*Example: http://rest.bioontology.org/resource_index/elementDetails/AE?elementid=E-GEOD-9118&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : element

====Elements detail service by chronology ====
Retruns elements details for given resource id cronologically

*GET Request Format : ''/elements/{resourceid}?method={method}&offset={offset}&limit={limit}''
*Example: http://rest.bioontology.org/resource_index/elements/AE?method=chronology&offset=0&limit=10&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Element is a representation of one element.

====Resources Service with ontologies used for indexing ====
Returns the set of all resources available in resource index and list of onotolgies used for indexing them.

*GET Request Format : ''/resources?withontologies=true''
*Example: http://rest.bioontology.org/resource_index/resources?withontologies=true&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /resources?withOntologies=true
*Response Content : ObrResourceBean is a representation of one resource with ontologies
'''Response Content: ObrResourceBean'''

Response ObrResourceBean contains all the contents of Resource. Those contents are described in section ''Response Content: Resource''.

Following are remaining contents for ObrResourceBean :

{| border="2" 
|-valign="top"
|width="10%"|'''ontologiesUsed'''
|width="90%"| Presents list of ontologies used for indexing. Each ontology of type OntologyBean.
'''Response Content: OntologyBean'''
{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''localOntologyID'''
|width="90%"|Local onotology id for Ontology.

|-valign="top"
|width="10%"|'''ontologyName'''
|width="90%"|name of the resource.

|-valign="top"
|width="10%"|'''ontologyVersion'''
|width="90%"|version number for resource.

|-valign="top"
|width="10%"|'''virtualOntologyID'''
|width="90%"|virtual ontology id for ontology.
|}
|}

====Resource Service with ontologies used for indexing ====
Returns the information about resources and list of onotolgies used for indexing it.

*GET Request Format : ''/resources/{resourceid}?withontologies=true''
*Example: http://rest.bioontology.org/resource_index/resources/AE?withOntologies=true&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format : /resources/{resourceID}?withOntologies=true
*Response Content : Resource is represented by ObrResourceBean.

====Ontologies Service with resources indexed ====
Returns the set of all ontologies used in resource index with list of resources indexed by given ontology.

*GET Request Format : ''/ontologies?withresources=true''
*Example: http://rest.bioontology.org/resource_index/ontologies?withresources=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Each Ontology is represented by ObrOntologyBean.

Response ObrOntologyBean contains all the contents of OntologyBean.Those contents are described in section Response Content: OntologyBean.

Following are remaining contents for ObrResourceBean :
{| border="2" 
|-valign="top"
|width="10%"|'''resources'''
|width="90%"| Represents list of resources. Response content for each resource is of type Resource.
|}

====Ontology Service with resources indexed ====
Returns the information about given ontologies used in resource index with list of resources.

*GET Request Format : ''/ontologies/{ontologyid}''
*Example: http://rest.bioontology.org/resource_index/ontologies/42693?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Ontology is represented by ObrOntologyBean.

====Virtual Ontology Service with resources indexed ====
Returns the ontology versions in resource index with list of resources for given virtual_ontology_id.

*GET Request Format : ''/virtual/ontology/{virtual_ontology_id}?withresources={true|false}''
*Example: http://rest.bioontology.org/resource_index/virtual/ontology/1032?withresources=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : List of ontologies represented by ObrOntologyBean.

====Concept Frequency Service====
Returns the get most used concepts for given resource id.

*GET Request Format : ''/most-used-concepts/{resourceid}?method={counts|score}&offset={offset}&limit={limit}''
*Example: http://rest.bioontology.org/resource_index/most-used-concepts/AE?method=counts&offset=0&limit=10&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource Index Concepts with format ObrConceptFrequencyBean.

'''Response Content: ObrConceptFrequencyBean'''

Following are contents for ObrConceptFrequencyBean:
{| border="2" 
|-valign="top"
|width="10%"|'''concept'''
|width="90%"|ConceptBean is a representation of concept

|-valign="top"
|width="10%"|'''counts'''
|width="90%"|Frequency counts for a concept .

|-valign="top"
|width="10%"|'''score'''
|width="90%"|score for a concept .

|}

====All Statistics Service====
Returns the information about number of all the annotations done in resource index.

*GET Request Format : ''/statistics/all''
*Example: http://rest.bioontology.org/resource_index/statistics/all?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : All annotations represented by ObrStatisticsBean.

'''Response Content: ObrStatisticsBean'''
Following are remaining contents for ObrStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''aggregatedAnnotations'''
|width="90%"|Sum of the number of rows in all the indexing tables

|-valign="top"
|width="10%"|'''mgrepAnnotations'''
|width="90%"|Number of mgrep annotations entries in direct annotation table.

|-valign="top"
|width="10%"|'''reportedAnnotations'''
|width="90%"|Number of reported annotations entries in direct annotation table.

|-valign="top"
|width="10%"|'''isaAnnotations'''
|width="90%"|Number of is-a annotations entries in extended annotation table.

|-valign="top"
|width="10%"|'''mappingAnnotations'''
|width="90%"|Number of mapping annotations entries in extended annotation table.

|}

====Ontology Statistics Service====
Returns the total statistics for given ontology for All resources.

*GET Request Format : ''/statistics/ontology/{ontologyid}''
*Example: http://rest.bioontology.org/resource_index/statistics/ontology/42693?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Ontology statistics with format ObrOntologyStatisticsBean.

'''Response Content: ObrOntologyStatisticsBean'''
Following are contents for ObrOntologyStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|Resource Id for resource.

|-valign="top"
|width="10%"|'''statistics'''
|width="90%"|ObrStatisticsBean is a representation of statistics

|}

====Ontology Statistics Service by resources====
Returns the statistics for given ontology for each resource separately.

*GET Request Format : ''/statistics/ontology/{onotlogyid}?byresource=true''
*Example: http://rest.bioontology.org/resource_index/statistics/ontology/42693?byresource=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : ObrOntologyStatisticsBean

====Resource Statistics Service====
Returns the total statistics for given resource for All ontology.

*GET Request Format : ''/statistics/resource/{resourceid}''
*Example: http://rest.bioontology.org/resource_index/statistics/resource/CANANO?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource statistics with format ObrResourceStatisticsBean.

'''Response Content: ObrResourceStatisticsBean'''
Following are contents for ObrResourceStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''localOntologyID'''
|width="90%"|local ontology id for given ontology.

|-valign="top"
|width="10%"|'''statistics'''
|width="90%"|ObrStatisticsBean is a representation of statistics

|}

====Resource Statistics Service by ontologies====
Returns the statistics for given resource for each ontology separately.

*GET Request Format : ''/statistics/resource/{resourceid}?byontology=true ''
*Example: http://rest.bioontology.org/resource_index/statistics/resource/AE?byontology=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource statistics with format ObrResourceStatisticsBean.

----
'''Note* :''' ''Old Request Format not working anymore.''

----

Annotator User Guide

2010-07-28T23:41:04Z

Jonquet: /* Annotator Web Service Response */

===Sample HTTP Client for the Annotator===

HTML http://rest.bioontology.org/test_oba.html

===Annotator web service endpoint===

* Web service signature: http://rest.bioontology.org/obs/annotator?email=example@example.org
* Type: POST

=== Annotator Web Service Workflow===

The Annotator Web service’s workflow is composed of two main steps (figure):

[[Image:OBA_service_workflow.png|thumb|NCBO Annotator Web service workflow]]

First, direct annotations are created from raw text. Annotations are based on syntactic concept recognition using a dictionary compiled from terms (concept names and synonyms) pulled from the ontologies. The Annotator enables the selection of ontologies from one of the largest sets of available biomedical ontologies. We implemented the service using a subset of the BioPortal ontologies which includes 16 ontologies from UMLS (12 in RRF format, 2 in OBO format, 2 in OWL format). These ontologies provide a dictionary of 1,594,785 concepts and 3,200,654 terms.

In the second step, semantic expansion components leverage the semantics in ontologies (e.g., is_a relations and mappings) to create additional annotations. For example, the is_a transitive closure component traverses an ontology parent-child hierarchy to create new annotations with parent concepts of concepts in direct annotations. The ontology-mapping component creates new annotations based on existing mappings between different ontologies. Point-to-point mappings that link concepts one another are defined manually or by automatic algorithms in BioPortal.

==== The is_a transitive closure expansion component ====
An is_a transitive closure component traverses an ontology parent-child hierarchy to create new annotations with parent concepts. For instance, if data are annotated with a concept from the NCI Thesaurus, such as ''melanoma'', this component generates a new annotation with the concept ''skin neoplasm'', because the NCI Thesaurus provides the knowledge that ''melanoma'' is_a ''skin neoplasm.''
The Annotator uses the is_a relations as they are defined by BioPortal in the <SubClass>/<SuperClass> information for a given concept (accessed via REST web service).

==== The mapping expansion component ====
An ontology-mapping component creates new annotations based on existing mappings between different ontologies. For example, an annotation done with concept ''40644/Melanoma'' in NCI Thesaurus can be expanded to another one with in SNOMED-CT because the BioPortal provides the mapping information.
The Annotator uses the mapping as they are defined by the repositories: BioPortal mappings are defined in the BioPortal front-end and accessed in an ad-hoc manner.

=== Annotator Web Service Parameters===

*See http://www.bioontology.org/wiki/index.php/BioPortal_2.3_Release_Notes for changes in Annotator output and updated information on how to use UMLS ontologies with the Annotator.

The Annotator web service offers a set of parameters that allows a user to customize the Annotator workflow and filter the result. To customize the workflow and the result, the user can specify a set of ontologies and a specific set of semantic types. Plus, the two steps of the annotation workflow can be parametrized.

The Annotator web service response time depends on the selected components as each consumes resources at a different level. For example, the ''is_a'' transitive closure takes a long time to process, even when using a pre-computed hierarchy table. As another example, an annotation with ''wholeWordOnly=false'' will be significantly longer that with ''wholeWordOnly=true''.

Please see below for the list of parameters and the possible values.

{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''longestOnly'''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies either or not the concept recognition step (done with University of Michigan Mgrep tool) must match the longest words only if they are several concepts that match to an expression.

* If ''longestOnly=true'', the Annotator selects only the longest term matching phrase. For example, if ''longestOnly=true'', the phrase ''breast cancer'' generates only ''breast cancer.'' If ''longestOnly=false'', it generates three annotations: ''breast'', ''cancer'' and ''breast cancer.''

* Attention, if the Annotator finds an annotation with the complete phrase in an ontology composing the dictionary, partial annotations with other ontologies will not be generated. For example, because ''breast cancer'' exists in Human Disease and the NCI Thesaurus, if ''longestOnly=true'', annotations generated with those terms will block annotations with the terms ''breast'' in the Vaccine Ontology or ''cancer'' in BIRNLex. For this reason, we discourage the uses of the '''longestOnly''' parameter when the Annotator is used with one or a small number of ontologies.

|-valign="top"
|width="10%"|'''wholeWordOnly'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies whether the concept recognition step must match whole words only or not, if they are several concepts that match to a given word.
* For example: If ''wholeWordOnly=true'', the phrase 'neoplasms' will match the concept NCI/C0027651 (Neoplasms) only. If ''wholeWordOnly=false'', the concept NCI/C1551054 (S) or the concept NCI/C0242536 (ASM) will also match (~80 concepts in NCI) in addition.
* Note that the concept recognition step does not consider text cast.

|-valign="top"
|width="10%"|'''filterNumber'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies whether the concept recognition step to filter numbers or not.

|-valign="top"
|width="10%"|'''stopWords'''
|width="10%"|{stopWord1,...,stopWordN}
|width="10%"|default: empty (i.e. none)
|width="70%"|Specifies the list of stop words to use.
|-valign="top"
|width="10%"|'''withDefaultStopWords'''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies whether to use the default stop words or not. The default stop word list is available from sample HTML page. If set to true, this override the value of stopWords given by the user.
|-valign="top"
|width="10%"|'''isStopWordsCaseSenstive '''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies whether stopwords are case-sensitive or not.
|-valign="top"
|width="10%"|'''minTermSize'''
|width="10%"|{integer}
|width="10%"|default: 0
|width="70%"|Specifies the minimum length of the term to be included in the annotations.
|-valign="top"
|width="10%"|'''scored'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies either or not the annotations are scored. A score is a number assigned to an annotation that reflects the accuracy of the annotation. The higher the score is the better the annotation is. The scoring algorithm gives a specific weight to an annotation according to the context of this annotation. For instance, an annotation done by matching a concept preferred name will be given a higher weight than an annotation done by matching a concept synonym or than an annotation done with a parent level 3 in the is_a hierarchy. Details on the scoring algorithm are given in section Scoring algorithm.
* For example, the phrase 'melanoma' is annotated both with the concept NCI/C0025202 (melanoma) and the concept NCI/C1522102 (Mouse Melanoma). The former annotation is scored 10 where as the latter is scored 8.
|-valign="top"
|width="10%"|'''withSynonyms'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies either or not the direct annotations are done with or without Synonyms. By default it includes all the synonyms and preferred name. If 'false' is selected, the direct annotations are done with only preferred name.
|-valign="top"
|width="10%"|'''ontologiesToExpand'''
|width="10%"|{localOntology1,...,localOntologyN}
|width="10%"|default: empty (i.e. all ontologies)
|width="70%"|Specifies the list of ontologies to use with the mapping semantic expansion component. The list of ontologies that can be used is available in the sample HTML page. The values are separated with comma (without spaces).
* For example, 40403,40644,40401.
* '''NOTE''': The list of ontologies that are available via the Annotator Web service are those listed with <status>28</status> from this Web service call: http://rest.bioontology.org/obs/ontologies
|-valign="top"
|width="10%"|'''ontologiesToKeepInResult'''
|width="10%"|{localOntology1,...,localOntologyN}
|width="10%"|default: empty (i.e. all ontologies)
|width="70%"|Specifies the list of ontologies to keep in the result of the annotation process. The list of ontologies that can be used is available in the sample HTML page. The values are separated with comma (without spaces).
* For example, 40403,40644,40401.
* '''NOTE''': The list of ontologies that are available via the Annotator Web service are those listed with <status>28</status> from this Web service call: http://rest.bioontology.org/obs/ontologies
|-valign="top"
|width="10%"|'''isVirtualOntologyId'''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies whether the input values are virtualOntologyId instead of localOntologyid. VirtualOntologyId is not version-specific.
|-valign="top"
|width="10%"|'''semanticTypes'''
|width="10%"|{semanticType1,...,semanticTypeN}
|width="10%"|default: empty (i.e. all semanticTypes)
|width="70%"|Specifies the list of semantic types to use in the annotation process. The list of semantic types that can be used is available in the sample HTML page. The values are separated with comma (without spaces). Note that the restriction to semantic types is also applied during the semantic expansion steps.
* For example, T047,T048,T191.
|-valign="top"
|width="10%"|'''levelMax'''
|width="10%"|{integer}
|width="10%"|default: 0
|width="70%"|Specifies the maximum level a parent concept must have to be considered for the is_a semantic closure expansion step.
* For example, a call done with ''levelMax=3'' will expand a direct annotations done with a concept up to the 3rd level parent in the is_a hierarchy for this concept. A call done with ''levelMax=0'' is equivalent to disable the is_a transitive closure expansion step.
|-valign="top"
|width="10%"|'''mappingTypes'''
|width="10%"|{null,mappingType1,...,mappingTypeN}
|width="10%"|default: empty (i.e. all mappingTypes)
|width="70%"|Specifies the list of mapping type to use during the mapping expansion step. The list of semantic types that can be used is available in the sample HTML page. The values are separated with comma (without spaces). The current list is described hereafter.
* For example, from-mrrel,Human.
* Note that the use of the key word "'''null'''" in the '''mappingTypes''' list disables the mapping expansion component. Note also that the mapping expansion is also limited by other parameters such as ''ontologiesToExpand'' and ''ontologiesToKeepInResult''.
* The current list of mapping type is:
** ''inter-cui'': This mapping type corresponds to the mappings available between CUIs in the UMLS Metathesaurus. For instance, NCI/C0025202 and MSH/C0025202 are mapped together because the share the same CUI in UMLS.
** ''from-mrrel'': This mapping type corresponds to the mappings available in the MRREL table from UMLS.
** ''Automatic'': This mapping type corresponds to the mappings automatically imported in BioPortal.
** ''Manual'': This relation name corresponds to the mappings created by users in BioPortal.
** ''Human'': This relation name corresponds to the mapping s [not used anymore] in BioPortal.

|-valign="top"
|width="10%"|'''textToAnnotate'''
|width="10%"|
|width="10%"|
|width="70%"|Specifies the text to be annotated.
|-valign="top"
|width="10%"|'''format'''
|width="10%"|{xml,text,tabDelimited}
|width="10%"|default: xml
|width="70%"|Specifies the desired format of the response from Annotator. For programmatic access, XML is strongly suggested.

* ''xml'': returns XML representation of the annotatorResultBean.
* ''text'': returns plain text representation of the annotatorResultBean.
* ''tabDelimited'': shorter version of "Text" format. returns not the full result content but the annotations only (no statistics, etc.). The format of the tab delimited file is: score \t conceptId \t preferredName \t synonyms (separated by ' /// ') \t semanticType (separated by ' /// ') \t contextName \t isDirect \t other context information (e.g., childConceptId, mappedConceptId, level, mappingType) (separated by ' /// ').

The elements of the Annotator response are described in next section.

|}

===Annotator Web Service Response===

In this section we define the Annotator web service model i.e., what the service returns to the user: the objects as well as their relations and the constraints that applies. Cf the UML class diagram here: http://obs.bioontology.org/docs/model/EARoot/EA3/EA46.htm

'''Response Content: annotatorResultBean'''
{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''resultId'''
|width="90%"| The id of the annotatorResultBean.
|-valign="top"
|width="10%"|'''dictionary'''
|width="90%"| Dictionary contains the metadata (not the content) of the dictionary used for a result. ''dictionaryId'', ''dictionaryName'', and ''dictionaryDate'' identify the dictionary on the server side and give information about its content. Dictionary versioning is strongly linked to the evolution of the ontologies used. Each time ontologies change, the dictionary is updated. All the dictionary information may be useful for comparing results of the Annotator service on time.
|-valign="top"
|width="10%"|'''statistics'''
|width="90%"| Statistics contains information on the number of annotations done for a given context. The ''contextName'' keyword identifies the type of context and ''nbAnnotation'' is the number of annotations of this type.
|-valign="top"
|width="10%"|'''parameters'''
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Annotator service. Those parameters are described in previous section.
|-valign="top"
|width="10%"|'''ontologies'''
|width="90%"| To keep the model simple, we provide only the global ontology identifier, ''localOntologyId'' the name (''ontologyName'') and version (''ontologyVersion''). This information come from the original repositories (UMLS/BioPortal) and might help the user to select the right ontology to use. When an ontology is used in the annotation, a result has a set of OntologyUsed which specify 2 other properties: ''nbAnnotation'', the number of annotation that have been made with concepts from this ontology. ''score'', the sum of all the scores of the annotations done with concepts from this ontology (if parameter ''scored=true''). Therefore, score represents the most accurate ontology to annotate the given text.
|-valign="top"
|width="10%"|'''annotations'''
|width="90%"| Annotation is a representation of one annotation. An annotation has a ''score'' which represents the accuracy of the annotation computed by the scoring algorithm (if the scored=true parameter was chosen, otherwise score=-1). An annotation is done with a ''concept'' in a ''context''.

{| border="2" 
|-valign="top"
|width="10%"|'''score'''
|width="90%"| The scoring algorithm gives weight to each annotation according to the annotation context. The final score for an annotation is then calculated as the sum of all the scores of the annotations done with the same concept. Cf Recommender journal paper for more detail for now.

|-valign="top"
|width="10%"|'''concept'''
|width="90%"| ''Concept'' is a representation of an ontology concept in the Annotator web service ontology model
* ''localConceptId'' - global identifier for the concept in its original repository.
* ''localOntologyId'' - identifier for the ontology in which the concept is defined.
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology.
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository).
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred.
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999).
|-valign="top"
|width="10%"|'''context'''
|width="90%"| ''Context'' specifies if it is a direct or expanded annotation and give precision about the origin of the annotation. ''contextName'' identifies the type of context. The context properties vary with the type of concept. There are 3 possible contexts identified by their contextName:
{| border="2" style="background:#ABCDEF;" 
|-valign="top"
|width="10%"|'''MGREP'''
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A Mgrep context has 3 properties:
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression. Attention, those values are in number of bytes, not characters e.g., ½ is a two-byte character, thus will count for 2 characters.
|-valign="top"
|width="10%"|'''ISA_CLOSURE'''
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:
* ''childConceptId'' - the concept from which the annotation was derived.
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived.
* For example, if a direct annotation with NCI/C0025202 (melanoma) was done, the is_a transitive closure component may expand it to another annotation with NCI/C1302746 (Melanocytic Neoplasm) because the latter is a direct parent (i.e., level 1) concept of the former. The ISA_CLOSURE annotation generated will have the following properties {NCI/C0025202, 1}.
|-valign="top"
|width="10%"|'''MAPPING'''
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties:
* mappedConceptId identifies the concept from which the annotation was derived.
* mappingType specifies the type of mapping.
|}
|}
|}

Resource Index REST Web Service User Guide

2010-07-14T16:45:38Z

Jonquet: /* Web Service Response */

===Introduction===
The Resource Index API is available through a REST web services interface.

This documentation describes the current version of the API. Some changes may append in the future.

The Resource index API is based on the web service that returns annotations from the Resource Index (called via a REST post). Additionally some simplified REST get services returned simplified results.

'''Attention, this documentation is not currently in sync with the deployed version... we plan to release pretty soon the new API (that goes with this documentation). Please refer to the history of this wiki page for [http://www.bioontology.org/wiki/index.php?title=Resource_Index_REST_Web_Service_User_Guide&oldid=10015, old documentation].'''

----

===Sample HTTP Client for the Resource Index REST Web Service===

Test HTML Page : http://rest.bioontology.org/resource_index/test

Resources Service Page : http://rest.bioontology.org/resource_index/resources/list/

===Service endpoint===

http://rest.bioontology.org/resource_index/

=== POST calls ===

POST your requests at the service endpoint.

====Parameters====

The Resource Index web service offers a set of parameters that allows a user to customize the annotations returned according to his specific requirements. For example, the annotations returned can be limited to a specific set of ontology and a specific set of semantic types. Plus, the expanded annotations can be filtered.

Please see below for the list of parameters and the possible values.

'''Note** :''' ''Parameter '''email''' and '''applicationid''' applies to all POST and GET calls.''

{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''email**'''
|width="10%"|{email id}
|width="10%"|default: null
|width="70%"|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.

|-valign="top"
|width="10%"|'''applicationid**'''
|width="10%"|{aplicationid}
|width="10%"|default: null
|width="70%"|Identifies the application calling the REST service.

|-valign="top"
|width="10%"|'''ontologiesToKeepInResult'''
|width="10%"|{localOntology1,...,localOntologyN}
|width="10%"|default: empty (i.e. all ontologies)
|width="70%"|Specifies the list of ontologies you want to filter in the result from the annotation process. The list of ontologies that can be used is available in the sample HTML page. The values are separated with comma (without spaces)
* For example, 42789,42838,42142.

|-valign="top"
|width="10%"|'''semanticTypes'''
|width="10%"|{semanticType1,...,semanticTypeN}
|width="10%"|default: empty (i.e. all semanticTypes)
|width="70%"|Specifies the list of UMLS semantic types to use in the annotation process. The list of semantic types that can be used is available at the /obs/semanticTypes URL. Note that the restriction to semantic types is also applied during the semantic expansion steps.
* For example, T047,T048,T191.

|-valign="top"
|width="10%"|'''levelMax'''
|width="10%"|{integer}
|width="10%"|default: 0
|width="70%"|Specifies the maximum level a parent concept must have to be considered for the is_a semantic closure expansion step.
* For example, an annotation done with levelMax=3 will expand a direct annotations done with a concept up to the 3rd level parent in the is_a hierarchy for this concept. An annotation done with levelMax=0 is equivalent to disable the is_a transitive closure expansion step.

|-valign="top"
|width="10%"|'''mappingTypes'''
|width="10%"|{null,mappingType1,...,mappingTypeN}
|width="10%"|default: empty (i.e. all mappingTypes)
|width="70%"|Specifies the list of mapping types to use during the mapping expansion step. The list of rmapping types that can be used is available at the /obs/mappingTypes URL. The current list is described in section Mapping types.
* For example, Automatic,Manual.
* Note that the use of the key word "'''null'''" in the mappingTypes list disables the mapping expansion component.

|-valign="top"
|width="10%"|'''filterNumber'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies whether the concept recognition step to filter numbers or not.

|-valign="top"
|width="10%"|'''minTermSize'''
|width="10%"|{integer}
|width="10%"|default: 0
|width="70%"|Specifies the minimum length of the term to be included in the annotations.

|-valign="top"
|width="10%"|'''withSynonyms'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies either or not the direct annotations are done with or without Synonyms. By default it includes all the synonyms and preferred name. If 'false' is selected, the direct annotations are done with only preferred name.

|-valign="top"
|width="10%"|'''additionalStopWords'''
|width="10%"|{stopWord1,...,stopWordN}
|width="10%"|default: empty (i.e. none)
|width="70%"|Specifies the list of additional stop words to use. Already used stop words are available here: [[http://rest.bioontology.org/obs/stopwords]]

|-valign="top"
|width="10%"|'''isStopWordsCaseSenstive '''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies whether stopwords are case-sensitive or not.

|-valign="top"
|width="10%"|'''conceptids'''
|width="10%"|{conceptid1,...,conceptidn}
|width="10%"|default: empty (i.e. all concepts)
|width="70%"|Specifies the list of concept to use to query the Resource index (i.e., get the annotations done with this list). This parameter must be jointly specified with the mode parameter. If conceptids contains only one element then the mode parameter can be ignored. The values are separated with comma (without spaces).
* For example, 40401/D008545,4513/Virtual_surface.

|-valign="top"
|width="10%"|'''isVirtualOntologyId'''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies the if the list of ontologies are all BioPortal virtual ontology IDs. This parameter applies to both conceptids and ontologiesToKeepInResult parameters.

|-valign="top"
|width="10%"|'''mode'''
|width="10%"|{union, intersection}
|width="10%"|default: union
|width="70%"|Specifies the mode to use when querying the resource index with several concept (parameter conceptids ). The union mode returns the union of all the annotations (filtered eventually with other parameters) done with each specified conceptid. The intersection mode returns the intersection.

|-valign="top"
|width="10%"|'''elementid'''
|width="10%"|
|width="10%"|default: all
|width="70%"|Specifies the identifier of the resource element for which annotations are requested. The elementid is defined by the original resource e.g., PMID for PubMed, NCT for ClinicalTrials. The full list of the elementid type is defined in Section Local element ID used.
* For example, NCT00001589 or GDS2735.

|-valign="top"
|width="10%"|'''resourceid'''
|width="10%"|
|width="10%"|default: all
|width="70%"|Specifies the resource to filter the annotations with. The resourceid identifies a resource in the Resource Index. They are defined in section Resource identifiers. The list of resourceid can be used is available at the /obs/resources URL.
* For example, GEO,CT,AE.

|-valign="top"
|width="10%"|'''elementDetails'''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies the if the returned resource elements to be detailed or not.

|-valign="top"
|width="10%"|'''withContext'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies whether the annotations context information to be available or not. If turn to false, the set of annotations returned will be simplified and will not detail the context information for an annotation. Only the score will be returned.

|-valign="top"
|width="10%"|'''from and number'''
|width="10%"|{real_number}
|width="10%"|default: 0/10 respectively
|width="70%"|Specifies an offset of annotations defined by from and number.

|-valign="top"
|width="10%"|'''format'''
|width="10%"|{text, tabDelimited, owl, xml}
|width="10%"|default: xml
|width="70%"|Specifies the desired format of the response.

|}

===Web Service Response===

'''Response Format'''
{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''text'''
|width="90%"| Returns plain text representation of the ObrResultBean(Detailled).

|-valign="top"
|width="10%"|'''tabDelimited'''
|width="90%"| Shorter version of "Text" format, returns not the full result content but the annotations only (no statistics, etc.). The format of the tab delimited file is: score \t conceptId \t preferredName \t synonyms (separated by ' /// ') \t semanticType (separated by ' /// ') \t contextName \t isDirect \t other context information (e.g., childConceptId, mappedConceptId, level, mappingType) (separated by ' /// ').

|-valign="top"
|width="10%"|'''xml'''
|width="90%"| Returns XML representation of the ObrResultBean(Detailled).

|-valign="top"
|width="10%"|'''owl'''
|width="90%"| Returns OWL representation of the ObrResultBean(Detailled). The elementsof the result (dictionary, parameters, annotations, etc) are described as instances in the following ontology: http://obs.bioontology.org/ontologies/NCBO_OBS_ontology.owl
|}

'''Note :''' ''if request parameter withContext is true, then returns representation of the ObrResultBeanDetailled and if request parameter withContext is false, then returns representation of the ObrResultBean.''

'''Response Content: ObrResultBeanDetailled'''

Response ObrResultBeanDetailled contains all the contents of ObrResultBean. Those contents are described in section Response Content: ObrResultBean.

Following are remaining contents for ObrResultBeanDetailled :

{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''directAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|-valign="top"
|width="10%"|'''isaAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|-valign="top"
|width="10%"|'''mappingAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|}

'''Note :''' ''Response contents of the ObrAnnotationBean are described in section ObrResultBean annotations''

'''Response Content: ObrResultBean'''
{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''resultID'''
|width="90%"|
|-valign="top"
|width="10%"|'''dictionary'''
|width="90%"| Dictionary contains the metadata (not the content) of the dictionary used for a result. dictionaryId, dictionaryName, and dictionaryDate identify the dictionary on the server side and give information about its content. Dictionary versioning is strongly linked to the evolution of the ontologies used. Each time ontologies change, the dictionary is updated. All the dictionary information may be useful for comparing results of the Annotator Restlet service on time.
|-valign="top"
|width="10%"|'''statistics'''
|width="90%"| Statistics contains information on the number of annotations done for a given context. The contextName keyword identifies the type of context and nbAnnotation is the number of annotations of this type.
|-valign="top"
|width="10%"|'''parameters'''
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Annotator Restlet service. Those parameters are described in section Service parameters
|-valign="top"
|width="10%"|'''ontologies'''
|width="90%"| To keep the model simple, we provide only the global ontology identifier, localOntologyId the name (ontologyName) and version (ontologyVersion). This information come from the original repositories (UMLS/BioPortal) and might help the user to select the right ontology to use. When an ontology is used in the annotation, a result has a set of OntologyUsed which specify 2 other properties: nbAnnotation, the number of annotation that have been made with concepts from this ontology. score, the sum of all the scores of the annotations done with concepts from this ontology (if parameter scored=true). Therefore, score represents the most accurate ontology to annotate the given text.
|-valign="top"
|width="10%"|'''annotations'''
|width="90%"| ObrAnnotationBean/ObrAnnotationBeanDetailled is a representation of one annotation. If ''elementDetails'' parameter is true the service return response of type ObrAnnotationBean ,otherwise ObrAnnotationBeanDetailled. An annotation has a score which represents the accuracy of the annotation computed by the scoring algorithm (if the scored=true parameter was chosen, otherwise score=-1). An annotation is done with a concept in a context.

'''Response Content: ObrAnnotationBeanDetailled'''

Response ObrAnnotationBeanDetailled contains all the contents of ObrAnnotationBean. Those contents are described in section Response Content: ObrAnnotationBean.

Following are remaining contents for ObrAnnotationBeanDetailled :

{| border="2" 

|-valign="top"
|width="10%"|'''element'''
|width="90%"|
* ''localElementID'' - Global identifier for the resource element.
* ''elementStructure'' - Represents Structure of an element for a given resource.

'''Response Content: Structure'''

{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|resource identifier for Resource.

|-valign="top"
|width="10%"|'''contexts'''
|width="90%"|list of context for resource.

|-valign="top"
|width="10%"|'''itemKeys'''
|width="90%"|list of itemKeys for resource.

|-valign="top"
|width="10%"|'''weights'''
|width="90%"|map contain weights (as double) for each context (as String).

|-valign="top"
|width="10%"|'''ontoIDs'''
|width="90%"|map contain ontologyIDs for each context (as String).
|}

|}

'''Response Content: ObrAnnotationBean'''

{| border="2" 
|-valign="top"
|width="10%"|'''localElementID'''
|width="90%"| Identifier for resource element.
|-valign="top"
|width="10%"|'''score'''
|width="90%"|
|-valign="top"
|width="10%"|'''concept'''
|width="90%"|
* ''localConceptId'' - global identifier for the concept in its original repository.
* ''localOntologyId'' - identifier for the ontology in which the concept is defined.
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology.
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository).
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred.
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999).
|-valign="top"
|width="10%"|'''context'''
|width="90%"| Context specifies if it is a direct or expanded annotation and give precision about the origin of the annotation. ''contextName'' identifies the type of context. The context properties vary with the type of concept. There are 3 possible contexts identified by their contextName:
{| border="2" style="background:#ABCDEF;" 
|-valign="top"
|width="10%"|'''MGREP'''
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A Mgrep context has 3 properties:
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.
|-valign="top"
|width="10%"|'''ISA_CLOSURE'''
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:
* ''childConceptId'' - the concept from which the annotation was derived.
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.
* For example, if a direct annotation with NCI/C0025202 (melanoma) was done, the is_a transitive closure component may expand it to another annotation with NCI/C1302746 (Melanocytic Neoplasm) because the latter is a direct parent (i.e., level 1) concept of the former. The ISA_CLOSURE annotation generated will have the following properties {NCI/C0025202, 1}.
|-valign="top"
|width="10%"|'''MAPPING'''
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties:
* mappedConceptId identifies the concept from which the annotation was derived.
* mappingType specifies the type of mapping.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.
|}
|}

|-valign="top"
|width="10%"|'''localElementID localConceptIDs mode withContext elementDetails counts offsetStart offsetMax'''
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Resource Index Restlet service. Those parameters are described in section Service parameters

|}

===GET calls===
Following section describes all other simplified GET services available in Resource_Index_API.

====Annotation by Concept Service====
Returns the set of annotations done with a given localConceptID.

*GET Request Format : '''/byconcept/{ontologyid}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/42693/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/{ontologyID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/{ontologyID}/{conceptID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled. If request parameter withContext is true, then returns representation of the ObrResultBeanDetailled and if request parameter withContext is false, then returns representation of the ObrResultBean.

====Annotation for BioPortal virtual ontology Concept Service ====
Returns the set of all annotations done with a given localConceptID using BioPortal virtual ontology ID.

*GET Request Format : '''/byconcept/virtual/{virtualOntologyID}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/virtual/1032/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/virtual/{virtualOntologyID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/virtual/{virtualOntologyID}/{conceptID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation By Concept And Resource Service ====
Returns the set of all annotations done with a given localConceptID for given resourceID.

*GET Request Format : '''/byconcept/{ontologyid}/{resourceid}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/42693/AE/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/{ontologyID}/{resourceID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/{ontologyID}/{conceptID}/{resourceID}/{withContext}/{counts}/{from}/{number}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation for BioPortal virtual ontology Concept And Resource Service ====
Returns the set of all annotations done with a given localConceptID using BioPortal virtual ontology ID and using particular resourceID.

*GET Request Format : '''/byconcept/virtual/{virtualOntologyID}/{resourceid}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/virtual/1032/AE/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/virtual/{virtualOntologyID}/{resourceID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/virtual/{virtualOntologyID}/{conceptID}/{resourceID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation By Resource Element Service ====
Returns the set of all annotations done with a given resource element localElementID for all the concepts.

*GET Request Format : '''/byelement/{resourceid}/{elementDetails}{withContext}/{counts}/{from}/{number}?elementid={elementid}'''
*Example 1 : http://rest.bioontology.org/resource_index/byelement/AE/false/true/false/0/10?elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Example 1 : http://rest.bioontology.org/resource_index/byelement/AE/true/true/false/0/10?elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest

*Old Request Format* :
**/byelement/{resourceID}/{withContext}/{counts}/{from}/{number}?elementID={localElementID}
**/byelement/{resourceID}/{localElementID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation Details By Resource Element Service ====
Returns the set of all annotations details with a given resource element localElementID for given conceptID

*GET Request Format : '''/details/{elementDetails}/concept/{ontologyid}/resource/{resourceid}?conceptid={conceptid}&elementid={elementid}'''
*Example1 : http://rest.bioontology.org/resource_index/details/true/concept/42693/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Example2 : http://rest.bioontology.org/resource_index/details/false/concept/42693/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/details/{elementDetails}/concept/{ontologyID}/resource/{resourceID}?conceptID={conceptID}&elementID={localElementID}
**/details/{elementDetails}/concept/{ontologyID}/{conceptID}/resource/{resourceID}/element/{localElementID}

*Response Content : ObrAnnotationBeanDetailled if elementDetails is true otherwise ObrAnnotationBean

====Annotation Details By Resource Element Service for BioPortal Virtual OntologyID====
Returns the set of all annotations details with a given resource element localElementID for given conceptID of BioPortal virtual ontologyID

*GET Request Format : '''/details/{elementDetails}/virtual/concept/{virtualOntologyID}/resource/{resourceid}?conceptid={conceptid}&elementid={elementid}'''
*Example1 : http://rest.bioontology.org/resource_index/details/true/virtual/concept/1032/Melanoma/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Example2 : http://rest.bioontology.org/resource_index/details/false/virtual/concept/1032/npo:Nanoparticle/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/details/{elementDetails}/virtual/concept/{virtualOntologyID}/resource/{resourceID}?conceptID={conceptID}&elementID={localElementID}
**/details/{elementDetails}/virtual/concept/{virtualOntologyID}/{conceptID}/resource/{resourceID}/element/{localElementID}

*Response Content : ObrAnnotationBeanDetailled if elementDetails is true otherwise ObrAnnotationBean.

====Resources Service ====
Returns the set of all resources available in resource index and information related to it.

*GET Request Format : ''/resources''
*Example: http://rest.bioontology.org/resource_index/resources?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource is a representation of one resource
'''Response Content: Resource'''

{| border="2" 
|-valign="top"
|width="10%"|'''resourceName'''
|width="90%"| Name of the particular resource.

|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"| Identifier of the resource.

|-valign="top"
|width="10%"|'''mainContext'''
|width="90%"| Main context string for the resource.

|-valign="top"
|width="10%"|'''resourceURL'''
|width="90%"| Website URL for the resource

|-valign="top"
|width="10%"|'''resourceElementURL'''
|width="90%"| Base URL for getting elements for resource.

|-valign="top"
|width="10%"|'''resourceDescription'''
|width="90%"| Description of the resource.

|-valign="top"
|width="10%"|'''resourceLogo'''
|width="90%"| URL of logo image for the resource.

|-valign="top"
|width="10%"|'''resourceStructure'''
|width="90%"| Represents Structure of an element for the resource.

'''Response Content: Structure'''

{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|resource identifier for Resource.

|-valign="top"
|width="10%"|'''contexts'''
|width="90%"|list of context for resource.

|-valign="top"
|width="10%"|'''itemKeys'''
|width="90%"|list of itemKeys for resource.

|-valign="top"
|width="10%"|'''weights'''
|width="90%"|map contain weights (as double) for each context (as String).

|-valign="top"
|width="10%"|'''ontoIDs'''
|width="90%"|map contain ontologyIDs for each context (as String).
|}

|}

====Resource Service ====
Returns the resource in resource index for given resourceID and information related to it.

*GET Request Format : ''/resources/{resourceid}''
*Example: http://rest.bioontology.org/resource_index/resources/AE?email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /resources/{resourceID}
*Response Content : Resource.

====Resource Element Service ====
Service returns elementURL for given localElementID and redirect it to get resource element on the web.

*GET Request Format : ''/element/{resourceid}?elementid={elementid}''
*Example: http://rest.bioontology.org/resource_index/element/AE?elementid=E-GEOD-9118&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /element/{resourceID}?element={localElementID}
*Response Content : Web page containing details of the element.

====Element details service by elementid ====
Retruns detail for given element using resource id and element id

*GET Request Format : ''/elementDetails/{resourceid}?elementid={elementid}''
*Example: http://rest.bioontology.org/resource_index/elementDetails/AE?elementid=E-GEOD-9118&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : element

====Resources Service with ontologies used for indexing ====
Returns the set of all resources available in resource index and list of onotolgies used for indexing them.

*GET Request Format : ''/resources?withontologies=true''
*Example: http://rest.bioontology.org/resource_index/resources?withontologies=true&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /resources?withOntologies=true
*Response Content : ObrResourceBean is a representation of one resource with ontologies
'''Response Content: ObrResourceBean'''

Response ObrResourceBean contains all the contents of Resource. Those contents are described in section ''Response Content: Resource''.

Following are remaining contents for ObrResourceBean :

{| border="2" 
|-valign="top"
|width="10%"|'''ontologiesUsed'''
|width="90%"| Presents list of ontologies used for indexing. Each ontology of type OntologyBean.
'''Response Content: OntologyBean'''
{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''localOntologyID'''
|width="90%"|Local onotology id for Ontology.

|-valign="top"
|width="10%"|'''ontologyName'''
|width="90%"|name of the resource.

|-valign="top"
|width="10%"|'''ontologyVersion'''
|width="90%"|version number for resource.

|-valign="top"
|width="10%"|'''virtualOntologyID'''
|width="90%"|virtual ontology id for ontology.
|}
|}

====Resource Service with ontologies used for indexing ====
Returns the information about resources and list of onotolgies used for indexing it.

*GET Request Format : ''/resources/{resourceid}?withontologies=true''
*Example: http://rest.bioontology.org/resource_index/resources/AE?withOntologies=true&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format : /resources/{resourceID}?withOntologies=true
*Response Content : Resource is represented by ObrResourceBean.

====Ontologies Service with resources indexed ====
Returns the set of all ontologies used in resource index with list of resources indexed by given ontology.

*GET Request Format : ''/ontologies?withresources=true''
*Example: http://rest.bioontology.org/resource_index/ontologies?withresources=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Each Ontology is represented by ObrOntologyBean.

Response ObrOntologyBean contains all the contents of OntologyBean.Those contents are described in section Response Content: OntologyBean.

Following are remaining contents for ObrResourceBean :
{| border="2" 
|-valign="top"
|width="10%"|'''resources'''
|width="90%"| Represents list of resources. Response content for each resource is of type Resource.
|}

====Ontology Service with resources indexed ====
Returns the information about given ontologies used in resource index with list of resources.

*GET Request Format : ''/ontologies/{ontologyid}''
*Example: http://rest.bioontology.org/resource_index/ontologies/42693?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Ontology is represented by ObrOntologyBean.

====All Statistics Service====
Returns the information about number of all the annotations done in resource index.

*GET Request Format : ''/statistics/all''
*Example: http://rest.bioontology.org/resource_index/statistics/all?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : All annotations represented by ObrStatisticsBean.

'''Response Content: ObrStatisticsBean'''
Following are remaining contents for ObrStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''aggregatedAnnotations'''
|width="90%"|Sum of the number of rows in all the indexing tables

|-valign="top"
|width="10%"|'''mgrepAnnotations'''
|width="90%"|Number of mgrep annotations entries in direct annotation table.

|-valign="top"
|width="10%"|'''reportedAnnotations'''
|width="90%"|Number of reported annotations entries in direct annotation table.

|-valign="top"
|width="10%"|'''isaAnnotations'''
|width="90%"|Number of is-a annotations entries in extended annotation table.

|-valign="top"
|width="10%"|'''mappingAnnotations'''
|width="90%"|Number of mapping annotations entries in extended annotation table.

|}

====Ontology Statistics Service====
Returns the total statistics for given ontology for All resources.

*GET Request Format : ''/statistics/ontology/{ontologyid}''
*Example: http://rest.bioontology.org/resource_index/statistics/ontology/42693?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Ontology statistics with format ObrOntologyStatisticsBean.

'''Response Content: ObrOntologyStatisticsBean'''
Following are contents for ObrOntologyStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|Resource Id for resource.

|-valign="top"
|width="10%"|'''statistics'''
|width="90%"|ObrStatisticsBean is a representation of statistics

|}

====Ontology Statistics Service by resources====
Returns the statistics for given ontology for each resource separately.

*GET Request Format : ''/statistics/ontology/{onotlogyid}?byresource=true''
*Example: http://rest.bioontology.org/resource_index/statistics/ontology/42693?byresource=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : ObrOntologyStatisticsBean

====Resource Statistics Service====
Returns the total statistics for given resource for All ontology.

*GET Request Format : ''/statistics/resource/{resourceid}''
*Example: http://rest.bioontology.org/resource_index/statistics/resource/CANANO?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource statistics with format ObrResourceStatisticsBean.

'''Response Content: ObrResourceStatisticsBean'''
Following are contents for ObrResourceStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''localOntologyID'''
|width="90%"|local ontology id for given ontology.

|-valign="top"
|width="10%"|'''statistics'''
|width="90%"|ObrStatisticsBean is a representation of statistics

|}

====Resource Statistics Service by ontologies====
Returns the statistics for given resource for each ontology separately.

*GET Request Format : ''/statistics/resource/{resourceid}?byontology=true ''
*Example: http://rest.bioontology.org/resource_index/statistics/resource/AE?byontology=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource statistics with format ObrResourceStatisticsBean.

----
'''Note* :''' ''Old Request Format not working anymore.''

----

Resource Index REST Web Service User Guide

2010-07-14T16:40:47Z

Jonquet: /* Parameters */

===Introduction===
The Resource Index API is available through a REST web services interface.

This documentation describes the current version of the API. Some changes may append in the future.

The Resource index API is based on the web service that returns annotations from the Resource Index (called via a REST post). Additionally some simplified REST get services returned simplified results.

'''Attention, this documentation is not currently in sync with the deployed version... we plan to release pretty soon the new API (that goes with this documentation). Please refer to the history of this wiki page for [http://www.bioontology.org/wiki/index.php?title=Resource_Index_REST_Web_Service_User_Guide&oldid=10015, old documentation].'''

----

===Sample HTTP Client for the Resource Index REST Web Service===

Test HTML Page : http://rest.bioontology.org/resource_index/test

Resources Service Page : http://rest.bioontology.org/resource_index/resources/list/

===Service endpoint===

http://rest.bioontology.org/resource_index/

=== POST calls ===

POST your requests at the service endpoint.

====Parameters====

The Resource Index web service offers a set of parameters that allows a user to customize the annotations returned according to his specific requirements. For example, the annotations returned can be limited to a specific set of ontology and a specific set of semantic types. Plus, the expanded annotations can be filtered.

Please see below for the list of parameters and the possible values.

'''Note** :''' ''Parameter '''email''' and '''applicationid''' applies to all POST and GET calls.''

{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''email**'''
|width="10%"|{email id}
|width="10%"|default: null
|width="70%"|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.

|-valign="top"
|width="10%"|'''applicationid**'''
|width="10%"|{aplicationid}
|width="10%"|default: null
|width="70%"|Identifies the application calling the REST service.

|-valign="top"
|width="10%"|'''ontologiesToKeepInResult'''
|width="10%"|{localOntology1,...,localOntologyN}
|width="10%"|default: empty (i.e. all ontologies)
|width="70%"|Specifies the list of ontologies you want to filter in the result from the annotation process. The list of ontologies that can be used is available in the sample HTML page. The values are separated with comma (without spaces)
* For example, 42789,42838,42142.

|-valign="top"
|width="10%"|'''semanticTypes'''
|width="10%"|{semanticType1,...,semanticTypeN}
|width="10%"|default: empty (i.e. all semanticTypes)
|width="70%"|Specifies the list of UMLS semantic types to use in the annotation process. The list of semantic types that can be used is available at the /obs/semanticTypes URL. Note that the restriction to semantic types is also applied during the semantic expansion steps.
* For example, T047,T048,T191.

|-valign="top"
|width="10%"|'''levelMax'''
|width="10%"|{integer}
|width="10%"|default: 0
|width="70%"|Specifies the maximum level a parent concept must have to be considered for the is_a semantic closure expansion step.
* For example, an annotation done with levelMax=3 will expand a direct annotations done with a concept up to the 3rd level parent in the is_a hierarchy for this concept. An annotation done with levelMax=0 is equivalent to disable the is_a transitive closure expansion step.

|-valign="top"
|width="10%"|'''mappingTypes'''
|width="10%"|{null,mappingType1,...,mappingTypeN}
|width="10%"|default: empty (i.e. all mappingTypes)
|width="70%"|Specifies the list of mapping types to use during the mapping expansion step. The list of rmapping types that can be used is available at the /obs/mappingTypes URL. The current list is described in section Mapping types.
* For example, Automatic,Manual.
* Note that the use of the key word "'''null'''" in the mappingTypes list disables the mapping expansion component.

|-valign="top"
|width="10%"|'''filterNumber'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies whether the concept recognition step to filter numbers or not.

|-valign="top"
|width="10%"|'''minTermSize'''
|width="10%"|{integer}
|width="10%"|default: 0
|width="70%"|Specifies the minimum length of the term to be included in the annotations.

|-valign="top"
|width="10%"|'''withSynonyms'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies either or not the direct annotations are done with or without Synonyms. By default it includes all the synonyms and preferred name. If 'false' is selected, the direct annotations are done with only preferred name.

|-valign="top"
|width="10%"|'''additionalStopWords'''
|width="10%"|{stopWord1,...,stopWordN}
|width="10%"|default: empty (i.e. none)
|width="70%"|Specifies the list of additional stop words to use. Already used stop words are available here: [[http://rest.bioontology.org/obs/stopwords]]

|-valign="top"
|width="10%"|'''isStopWordsCaseSenstive '''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies whether stopwords are case-sensitive or not.

|-valign="top"
|width="10%"|'''conceptids'''
|width="10%"|{conceptid1,...,conceptidn}
|width="10%"|default: empty (i.e. all concepts)
|width="70%"|Specifies the list of concept to use to query the Resource index (i.e., get the annotations done with this list). This parameter must be jointly specified with the mode parameter. If conceptids contains only one element then the mode parameter can be ignored. The values are separated with comma (without spaces).
* For example, 40401/D008545,4513/Virtual_surface.

|-valign="top"
|width="10%"|'''isVirtualOntologyId'''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies the if the list of ontologies are all BioPortal virtual ontology IDs. This parameter applies to both conceptids and ontologiesToKeepInResult parameters.

|-valign="top"
|width="10%"|'''mode'''
|width="10%"|{union, intersection}
|width="10%"|default: union
|width="70%"|Specifies the mode to use when querying the resource index with several concept (parameter conceptids ). The union mode returns the union of all the annotations (filtered eventually with other parameters) done with each specified conceptid. The intersection mode returns the intersection.

|-valign="top"
|width="10%"|'''elementid'''
|width="10%"|
|width="10%"|default: all
|width="70%"|Specifies the identifier of the resource element for which annotations are requested. The elementid is defined by the original resource e.g., PMID for PubMed, NCT for ClinicalTrials. The full list of the elementid type is defined in Section Local element ID used.
* For example, NCT00001589 or GDS2735.

|-valign="top"
|width="10%"|'''resourceid'''
|width="10%"|
|width="10%"|default: all
|width="70%"|Specifies the resource to filter the annotations with. The resourceid identifies a resource in the Resource Index. They are defined in section Resource identifiers. The list of resourceid can be used is available at the /obs/resources URL.
* For example, GEO,CT,AE.

|-valign="top"
|width="10%"|'''elementDetails'''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies the if the returned resource elements to be detailed or not.

|-valign="top"
|width="10%"|'''withContext'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies whether the annotations context information to be available or not. If turn to false, the set of annotations returned will be simplified and will not detail the context information for an annotation. Only the score will be returned.

|-valign="top"
|width="10%"|'''from and number'''
|width="10%"|{real_number}
|width="10%"|default: 0/10 respectively
|width="70%"|Specifies an offset of annotations defined by from and number.

|-valign="top"
|width="10%"|'''format'''
|width="10%"|{text, tabDelimited, owl, xml}
|width="10%"|default: xml
|width="70%"|Specifies the desired format of the response.

|}

===Web Service Response===

'''Response Format'''
{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''xml'''
|width="90%"| returns XML representation of the ObrResultBeanDetailled.

|-valign="top"
|width="10%"|'''text'''
|width="90%"| returns plain text representation of the ObrResultBeanDetailled.

|-valign="top"
|width="10%"|'''tabDelimited'''
|width="90%"| shorter version of "Text" format. returns not the full result content but the annotations only (no statistics, etc.). The format of the tab delimited file is: score \t conceptId \t preferredName \t synonyms (separated by ' /// ') \t semanticType (separated by ' /// ') \t contextName \t isDirect \t other context information (e.g., childConceptId, mappedConceptId, level, mappingType) (separated by ' /// ').
|}

'''Note :''' ''if request parameter withContext is true, then returns representation of the ObrResultBeanDetailled and if request parameter withContext is false, then returns representation of the ObrResultBean.''

'''Response Content: ObrResultBeanDetailled'''

Response ObrResultBeanDetailled contains all the contents of ObrResultBean. Those contents are described in section Response Content: ObrResultBean.

Following are remaining contents for ObrResultBeanDetailled :

{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''directAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|-valign="top"
|width="10%"|'''isaAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|-valign="top"
|width="10%"|'''mappingAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|}

'''Note :''' ''Response contents of the ObrAnnotationBean are described in section ObrResultBean annotations''

'''Response Content: ObrResultBean'''
{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''resultID'''
|width="90%"|
|-valign="top"
|width="10%"|'''dictionary'''
|width="90%"| Dictionary contains the metadata (not the content) of the dictionary used for a result. dictionaryId, dictionaryName, and dictionaryDate identify the dictionary on the server side and give information about its content. Dictionary versioning is strongly linked to the evolution of the ontologies used. Each time ontologies change, the dictionary is updated. All the dictionary information may be useful for comparing results of the Annotator Restlet service on time.
|-valign="top"
|width="10%"|'''statistics'''
|width="90%"| Statistics contains information on the number of annotations done for a given context. The contextName keyword identifies the type of context and nbAnnotation is the number of annotations of this type.
|-valign="top"
|width="10%"|'''parameters'''
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Annotator Restlet service. Those parameters are described in section Service parameters
|-valign="top"
|width="10%"|'''ontologies'''
|width="90%"| To keep the model simple, we provide only the global ontology identifier, localOntologyId the name (ontologyName) and version (ontologyVersion). This information come from the original repositories (UMLS/BioPortal) and might help the user to select the right ontology to use. When an ontology is used in the annotation, a result has a set of OntologyUsed which specify 2 other properties: nbAnnotation, the number of annotation that have been made with concepts from this ontology. score, the sum of all the scores of the annotations done with concepts from this ontology (if parameter scored=true). Therefore, score represents the most accurate ontology to annotate the given text.
|-valign="top"
|width="10%"|'''annotations'''
|width="90%"| ObrAnnotationBean/ObrAnnotationBeanDetailled is a representation of one annotation. If ''elementDetails'' parameter is true the service return response of type ObrAnnotationBean ,otherwise ObrAnnotationBeanDetailled. An annotation has a score which represents the accuracy of the annotation computed by the scoring algorithm (if the scored=true parameter was chosen, otherwise score=-1). An annotation is done with a concept in a context.

'''Response Content: ObrAnnotationBeanDetailled'''

Response ObrAnnotationBeanDetailled contains all the contents of ObrAnnotationBean. Those contents are described in section Response Content: ObrAnnotationBean.

Following are remaining contents for ObrAnnotationBeanDetailled :

{| border="2" 

|-valign="top"
|width="10%"|'''element'''
|width="90%"|
* ''localElementID'' - Global identifier for the resource element.
* ''elementStructure'' - Represents Structure of an element for a given resource.

'''Response Content: Structure'''

{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|resource identifier for Resource.

|-valign="top"
|width="10%"|'''contexts'''
|width="90%"|list of context for resource.

|-valign="top"
|width="10%"|'''itemKeys'''
|width="90%"|list of itemKeys for resource.

|-valign="top"
|width="10%"|'''weights'''
|width="90%"|map contain weights (as double) for each context (as String).

|-valign="top"
|width="10%"|'''ontoIDs'''
|width="90%"|map contain ontologyIDs for each context (as String).
|}

|}

'''Response Content: ObrAnnotationBean'''

{| border="2" 
|-valign="top"
|width="10%"|'''localElementID'''
|width="90%"| Identifier for resource element.
|-valign="top"
|width="10%"|'''score'''
|width="90%"|
|-valign="top"
|width="10%"|'''concept'''
|width="90%"|
* ''localConceptId'' - global identifier for the concept in its original repository.
* ''localOntologyId'' - identifier for the ontology in which the concept is defined.
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology.
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository).
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred.
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999).
|-valign="top"
|width="10%"|'''context'''
|width="90%"| Context specifies if it is a direct or expanded annotation and give precision about the origin of the annotation. ''contextName'' identifies the type of context. The context properties vary with the type of concept. There are 3 possible contexts identified by their contextName:
{| border="2" style="background:#ABCDEF;" 
|-valign="top"
|width="10%"|'''MGREP'''
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A Mgrep context has 3 properties:
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.
|-valign="top"
|width="10%"|'''ISA_CLOSURE'''
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:
* ''childConceptId'' - the concept from which the annotation was derived.
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.
* For example, if a direct annotation with NCI/C0025202 (melanoma) was done, the is_a transitive closure component may expand it to another annotation with NCI/C1302746 (Melanocytic Neoplasm) because the latter is a direct parent (i.e., level 1) concept of the former. The ISA_CLOSURE annotation generated will have the following properties {NCI/C0025202, 1}.
|-valign="top"
|width="10%"|'''MAPPING'''
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties:
* mappedConceptId identifies the concept from which the annotation was derived.
* mappingType specifies the type of mapping.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.
|}
|}

|-valign="top"
|width="10%"|'''localElementID localConceptIDs mode withContext elementDetails counts offsetStart offsetMax'''
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Resource Index Restlet service. Those parameters are described in section Service parameters

|}

===GET calls===
Following section describes all other simplified GET services available in Resource_Index_API.

====Annotation by Concept Service====
Returns the set of annotations done with a given localConceptID.

*GET Request Format : '''/byconcept/{ontologyid}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/42693/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/{ontologyID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/{ontologyID}/{conceptID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled. If request parameter withContext is true, then returns representation of the ObrResultBeanDetailled and if request parameter withContext is false, then returns representation of the ObrResultBean.

====Annotation for BioPortal virtual ontology Concept Service ====
Returns the set of all annotations done with a given localConceptID using BioPortal virtual ontology ID.

*GET Request Format : '''/byconcept/virtual/{virtualOntologyID}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/virtual/1032/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/virtual/{virtualOntologyID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/virtual/{virtualOntologyID}/{conceptID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation By Concept And Resource Service ====
Returns the set of all annotations done with a given localConceptID for given resourceID.

*GET Request Format : '''/byconcept/{ontologyid}/{resourceid}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/42693/AE/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/{ontologyID}/{resourceID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/{ontologyID}/{conceptID}/{resourceID}/{withContext}/{counts}/{from}/{number}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation for BioPortal virtual ontology Concept And Resource Service ====
Returns the set of all annotations done with a given localConceptID using BioPortal virtual ontology ID and using particular resourceID.

*GET Request Format : '''/byconcept/virtual/{virtualOntologyID}/{resourceid}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/virtual/1032/AE/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/virtual/{virtualOntologyID}/{resourceID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/virtual/{virtualOntologyID}/{conceptID}/{resourceID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation By Resource Element Service ====
Returns the set of all annotations done with a given resource element localElementID for all the concepts.

*GET Request Format : '''/byelement/{resourceid}/{elementDetails}{withContext}/{counts}/{from}/{number}?elementid={elementid}'''
*Example 1 : http://rest.bioontology.org/resource_index/byelement/AE/false/true/false/0/10?elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Example 1 : http://rest.bioontology.org/resource_index/byelement/AE/true/true/false/0/10?elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest

*Old Request Format* :
**/byelement/{resourceID}/{withContext}/{counts}/{from}/{number}?elementID={localElementID}
**/byelement/{resourceID}/{localElementID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation Details By Resource Element Service ====
Returns the set of all annotations details with a given resource element localElementID for given conceptID

*GET Request Format : '''/details/{elementDetails}/concept/{ontologyid}/resource/{resourceid}?conceptid={conceptid}&elementid={elementid}'''
*Example1 : http://rest.bioontology.org/resource_index/details/true/concept/42693/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Example2 : http://rest.bioontology.org/resource_index/details/false/concept/42693/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/details/{elementDetails}/concept/{ontologyID}/resource/{resourceID}?conceptID={conceptID}&elementID={localElementID}
**/details/{elementDetails}/concept/{ontologyID}/{conceptID}/resource/{resourceID}/element/{localElementID}

*Response Content : ObrAnnotationBeanDetailled if elementDetails is true otherwise ObrAnnotationBean

====Annotation Details By Resource Element Service for BioPortal Virtual OntologyID====
Returns the set of all annotations details with a given resource element localElementID for given conceptID of BioPortal virtual ontologyID

*GET Request Format : '''/details/{elementDetails}/virtual/concept/{virtualOntologyID}/resource/{resourceid}?conceptid={conceptid}&elementid={elementid}'''
*Example1 : http://rest.bioontology.org/resource_index/details/true/virtual/concept/1032/Melanoma/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Example2 : http://rest.bioontology.org/resource_index/details/false/virtual/concept/1032/npo:Nanoparticle/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/details/{elementDetails}/virtual/concept/{virtualOntologyID}/resource/{resourceID}?conceptID={conceptID}&elementID={localElementID}
**/details/{elementDetails}/virtual/concept/{virtualOntologyID}/{conceptID}/resource/{resourceID}/element/{localElementID}

*Response Content : ObrAnnotationBeanDetailled if elementDetails is true otherwise ObrAnnotationBean.

====Resources Service ====
Returns the set of all resources available in resource index and information related to it.

*GET Request Format : ''/resources''
*Example: http://rest.bioontology.org/resource_index/resources?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource is a representation of one resource
'''Response Content: Resource'''

{| border="2" 
|-valign="top"
|width="10%"|'''resourceName'''
|width="90%"| Name of the particular resource.

|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"| Identifier of the resource.

|-valign="top"
|width="10%"|'''mainContext'''
|width="90%"| Main context string for the resource.

|-valign="top"
|width="10%"|'''resourceURL'''
|width="90%"| Website URL for the resource

|-valign="top"
|width="10%"|'''resourceElementURL'''
|width="90%"| Base URL for getting elements for resource.

|-valign="top"
|width="10%"|'''resourceDescription'''
|width="90%"| Description of the resource.

|-valign="top"
|width="10%"|'''resourceLogo'''
|width="90%"| URL of logo image for the resource.

|-valign="top"
|width="10%"|'''resourceStructure'''
|width="90%"| Represents Structure of an element for the resource.

'''Response Content: Structure'''

{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|resource identifier for Resource.

|-valign="top"
|width="10%"|'''contexts'''
|width="90%"|list of context for resource.

|-valign="top"
|width="10%"|'''itemKeys'''
|width="90%"|list of itemKeys for resource.

|-valign="top"
|width="10%"|'''weights'''
|width="90%"|map contain weights (as double) for each context (as String).

|-valign="top"
|width="10%"|'''ontoIDs'''
|width="90%"|map contain ontologyIDs for each context (as String).
|}

|}

====Resource Service ====
Returns the resource in resource index for given resourceID and information related to it.

*GET Request Format : ''/resources/{resourceid}''
*Example: http://rest.bioontology.org/resource_index/resources/AE?email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /resources/{resourceID}
*Response Content : Resource.

====Resource Element Service ====
Service returns elementURL for given localElementID and redirect it to get resource element on the web.

*GET Request Format : ''/element/{resourceid}?elementid={elementid}''
*Example: http://rest.bioontology.org/resource_index/element/AE?elementid=E-GEOD-9118&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /element/{resourceID}?element={localElementID}
*Response Content : Web page containing details of the element.

====Element details service by elementid ====
Retruns detail for given element using resource id and element id

*GET Request Format : ''/elementDetails/{resourceid}?elementid={elementid}''
*Example: http://rest.bioontology.org/resource_index/elementDetails/AE?elementid=E-GEOD-9118&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : element

====Resources Service with ontologies used for indexing ====
Returns the set of all resources available in resource index and list of onotolgies used for indexing them.

*GET Request Format : ''/resources?withontologies=true''
*Example: http://rest.bioontology.org/resource_index/resources?withontologies=true&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /resources?withOntologies=true
*Response Content : ObrResourceBean is a representation of one resource with ontologies
'''Response Content: ObrResourceBean'''

Response ObrResourceBean contains all the contents of Resource. Those contents are described in section ''Response Content: Resource''.

Following are remaining contents for ObrResourceBean :

{| border="2" 
|-valign="top"
|width="10%"|'''ontologiesUsed'''
|width="90%"| Presents list of ontologies used for indexing. Each ontology of type OntologyBean.
'''Response Content: OntologyBean'''
{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''localOntologyID'''
|width="90%"|Local onotology id for Ontology.

|-valign="top"
|width="10%"|'''ontologyName'''
|width="90%"|name of the resource.

|-valign="top"
|width="10%"|'''ontologyVersion'''
|width="90%"|version number for resource.

|-valign="top"
|width="10%"|'''virtualOntologyID'''
|width="90%"|virtual ontology id for ontology.
|}
|}

====Resource Service with ontologies used for indexing ====
Returns the information about resources and list of onotolgies used for indexing it.

*GET Request Format : ''/resources/{resourceid}?withontologies=true''
*Example: http://rest.bioontology.org/resource_index/resources/AE?withOntologies=true&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format : /resources/{resourceID}?withOntologies=true
*Response Content : Resource is represented by ObrResourceBean.

====Ontologies Service with resources indexed ====
Returns the set of all ontologies used in resource index with list of resources indexed by given ontology.

*GET Request Format : ''/ontologies?withresources=true''
*Example: http://rest.bioontology.org/resource_index/ontologies?withresources=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Each Ontology is represented by ObrOntologyBean.

Response ObrOntologyBean contains all the contents of OntologyBean.Those contents are described in section Response Content: OntologyBean.

Following are remaining contents for ObrResourceBean :
{| border="2" 
|-valign="top"
|width="10%"|'''resources'''
|width="90%"| Represents list of resources. Response content for each resource is of type Resource.
|}

====Ontology Service with resources indexed ====
Returns the information about given ontologies used in resource index with list of resources.

*GET Request Format : ''/ontologies/{ontologyid}''
*Example: http://rest.bioontology.org/resource_index/ontologies/42693?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Ontology is represented by ObrOntologyBean.

====All Statistics Service====
Returns the information about number of all the annotations done in resource index.

*GET Request Format : ''/statistics/all''
*Example: http://rest.bioontology.org/resource_index/statistics/all?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : All annotations represented by ObrStatisticsBean.

'''Response Content: ObrStatisticsBean'''
Following are remaining contents for ObrStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''aggregatedAnnotations'''
|width="90%"|Sum of the number of rows in all the indexing tables

|-valign="top"
|width="10%"|'''mgrepAnnotations'''
|width="90%"|Number of mgrep annotations entries in direct annotation table.

|-valign="top"
|width="10%"|'''reportedAnnotations'''
|width="90%"|Number of reported annotations entries in direct annotation table.

|-valign="top"
|width="10%"|'''isaAnnotations'''
|width="90%"|Number of is-a annotations entries in extended annotation table.

|-valign="top"
|width="10%"|'''mappingAnnotations'''
|width="90%"|Number of mapping annotations entries in extended annotation table.

|}

====Ontology Statistics Service====
Returns the total statistics for given ontology for All resources.

*GET Request Format : ''/statistics/ontology/{ontologyid}''
*Example: http://rest.bioontology.org/resource_index/statistics/ontology/42693?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Ontology statistics with format ObrOntologyStatisticsBean.

'''Response Content: ObrOntologyStatisticsBean'''
Following are contents for ObrOntologyStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|Resource Id for resource.

|-valign="top"
|width="10%"|'''statistics'''
|width="90%"|ObrStatisticsBean is a representation of statistics

|}

====Ontology Statistics Service by resources====
Returns the statistics for given ontology for each resource separately.

*GET Request Format : ''/statistics/ontology/{onotlogyid}?byresource=true''
*Example: http://rest.bioontology.org/resource_index/statistics/ontology/42693?byresource=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : ObrOntologyStatisticsBean

====Resource Statistics Service====
Returns the total statistics for given resource for All ontology.

*GET Request Format : ''/statistics/resource/{resourceid}''
*Example: http://rest.bioontology.org/resource_index/statistics/resource/CANANO?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource statistics with format ObrResourceStatisticsBean.

'''Response Content: ObrResourceStatisticsBean'''
Following are contents for ObrResourceStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''localOntologyID'''
|width="90%"|local ontology id for given ontology.

|-valign="top"
|width="10%"|'''statistics'''
|width="90%"|ObrStatisticsBean is a representation of statistics

|}

====Resource Statistics Service by ontologies====
Returns the statistics for given resource for each ontology separately.

*GET Request Format : ''/statistics/resource/{resourceid}?byontology=true ''
*Example: http://rest.bioontology.org/resource_index/statistics/resource/AE?byontology=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource statistics with format ObrResourceStatisticsBean.

----
'''Note* :''' ''Old Request Format not working anymore.''

----

BioPortal Mappings

2010-07-13T23:17:01Z

Jonquet: /* BioPortal Mapping Types */

This page defines common mappings types in the [http://bioportal.bioontology.org NCBO BioPortal] and provides examples of different mappings that already exist in BioPortal. We welcome comments on this set of mapping relations. Please send email to [mailto:support@bioontology.org support@bioontology.org].

= BioPortal Mapping Types =

There are mappings of the following types in BioPortal:

* '''identical, the same''' : [http://www.w3.org/2002/07/owl#sameAs owl:sameAs]
** '''Definition''' (from [http://www.w3.org/TR/owl-ref/#sameAs-def OWL]): <tt>owl:sameAs</tt> is used to state that two URI references refer to the same individual
* '''exact match''': [http://www.w3.org/2008/05/skos#exactMatch skos:exactMatch]
** '''Definition''' (from [http://www.w3.org/TR/skos-reference/#mapping SKOS]): The property <tt>skos:exactMatch</tt> is used to link two concepts, indicating a high degree of confidence that the concepts can be used interchangeably across a wide range of information retrieval applications. <tt>skos:exactMatch</tt> is a transitive property, and is a sub-property of <tt>skos:closeMatch</tt>.
* '''close match''': [http://www.w3.org/2008/05/skos#closeMatch skos:closeMatch]
** '''Definition''' (from [http://www.w3.org/TR/skos-reference/#mapping SKOS]): The property <tt>skos:closeMatch</tt> is used to link two concepts that are sufficiently similar that they can be used interchangeably in some information retrieval applications. In order to avoid the possibility of "compound errors" when combining mappings across more than two concept schemes, <tt>skos:closeMatch</tt> is not declared to be a transitive property.
* '''related''' (but not necessarily similar): [http://www.w3.org/2000/01/rdf-schema#seeAlso rdfs:seeAlso]
** '''Definition''' (from [http://www.w3.org/TR/2000/CR-rdf-schema-20000327/#s2.3.4 RDFS]): The property <tt>rdfs:seeAlso</tt> specifies a resource that might provide additional information about the subject resource.
* '''homologous to''' (for anatomical terms): ''not defined yet''
** '''Definition''': The property links two anatomical terms from different species that refer to terms that have a common ancestor (evolutionary derived form a common ancestor).

= Survey of BioPortal Mappings =
The table below presents the statistics and examples of BioPortal mappings as of July 2010.

{| border="1" cellpadding="2"
| align="center" style="background:#f0f0f0;"|'''relationship'''
| width="125" align="center" style="background:#f0f0f0;"|'''basis'''
| align="center" style="background:#f0f0f0;"|'''Manual/Automatic'''
| align="center" style="background:#f0f0f0;"|'''Source'''
| align="center" style="background:#f0f0f0;"|'''Total mappings'''
| align="center" style="background:#f0f0f0;"|'''Notes'''
|-
| skos:closeMatch||identical UMLS CUIs||Manual||LEXEVS_UMLS_MAPPER||2,028,186||Mappings between terms in UMLS ontologies that were created automatically, linking terms with the same CUI. Because CUIs were assigned manually by UMLS editors, we treat these mapings as manual mappings
|-
| skos:closeMatch||lexical similarity||Automatic||LOOM||1,449,303||Mappings were generated by the LOOM algorithm automatically based on close lexical match between preferred names of terms or a preferred name and a synonym
|-
| skos:closeMatch||lexical similarity||Automatic||||2,562||Mappings were generated automatically based on the exact match of preferred names or synonyms for terms in FMA, ZFA, and mouse anatomy. Note: These mappings are likely homology mappings
|-
| skos:closeMatch||lexical similarity||Automatic with manual review||||628||Mappings were generated manually by a user and uploaded to BioPortal. The mappings were generated automatically based on lexical similarity but later manually reviewed by a domain expert. All mappings involve terms in the MGED ontology
|-
| owl:sameAs||shared id||Manual||LOOM||271,000||Mappings between the terms that share the same ID
|-
| rdfs:seeAlso||OBO xref||Manual||||17,776||Mappings based on OBO xref mappings, which indicate related terms
|-
| skos:exactMatch||Dbxref||Manual||||7,028||Mappings based on the use of Dbxref to indicate term reuse in OBO Foundry ontologies. Very close to having identical ids, but because the ids are different, we use exact match rather than owl:sameAs
|-
| skos:exactMatch||||Manual||||68||Mappings generated manually by a user; all involve terms from NEMO
|-
| skos:closeMatch||identical UMLS CUIs||Manual||||902||Mappings between non-UMLS ontologies where concepts do have cui. So, technically, similar to inter-cui mappings
|-
| skos:closeMatch||||Manual||BioPortal UI||117||Mappings created by users through the BioPortal user interface
|-
| skos:closeMatch||||Manual||NCICB||3078||Manual mappings between Mouse anatomy and NCIT
|-
| skos:closeMatch||lexical similarity||Automatic||EFO||673||Mappings generated automatically based on lexical similarity
|-
| skos:closeMatch||||Manual||NLM||2,662||Manual mappings between Mouse anatomy and NCIT
|}

Resource Index REST Web Service User Guide

2010-07-09T21:02:14Z

Jonquet: /* GET calls */

===Introduction===
The Resource Index API is available through a REST web services interface.

This documentation describes the current version of the API. Some changes may append in the future.

The Resource index API is based on the web service that returns annotations from the Resource Index (called via a REST post). Additionally some simplified REST get services returned simplified results.

'''Attention, this documentation is not currently in sync with the deployed version... we plan to release pretty soon the new API (that goes with this documentation). Please refer to the history of this wiki page for [http://www.bioontology.org/wiki/index.php?title=Resource_Index_REST_Web_Service_User_Guide&oldid=10015, old documentation].'''

----

===Sample HTTP Client for the Resource Index REST Web Service===

Test HTML Page : http://rest.bioontology.org/resource_index/test

Resources Service Page : http://rest.bioontology.org/resource_index/resources/list/

===Service endpoint===

http://rest.bioontology.org/resource_index/

=== POST calls ===

POST your requests at the service endpoint.

====Parameters====

The Resource Index web service offers a set of parameters that allows a user to customize the annotations returned according to his specific requirements. For example, the annotations returned can be limited to a specific set of ontology and a specific set of semantic types. Plus, the expanded annotations can be filtered.

Please see below for the list of parameters and the possible values.

'''Note** :''' ''Parameter '''email''' and '''applicationid''' applies to all POST and GET calls.''

{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''email**'''
|width="10%"|{email id}
|width="10%"|default: null
|width="70%"|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.

|-valign="top"
|width="10%"|'''applicationid**'''
|width="10%"|{aplicationid}
|width="10%"|default: null
|width="70%"|Identifies the application calling the REST service.

|-valign="top"
|width="10%"|'''ontologiesToKeepInResult'''
|width="10%"|{localOntology1,...,localOntologyN}
|width="10%"|default: empty (i.e. all ontologies)
|width="70%"|Specifies the list of ontologies you want to filter in the result from the annotation process. The list of ontologies that can be used is available in the sample HTML page. The values are separated with comma (without spaces)
* For example, 42789,42838,42142.

|-valign="top"
|width="10%"|'''semanticTypes'''
|width="10%"|{semanticType1,...,semanticTypeN}
|width="10%"|default: empty (i.e. all semanticTypes)
|width="70%"|Specifies the list of UMLS semantic types to use in the annotation process. The list of semantic types that can be used is available at the /obs/semanticTypes URL. Note that the restriction to semantic types is also applied during the semantic expansion steps.
* For example, T047,T048,T191.

|-valign="top"
|width="10%"|'''levelMax'''
|width="10%"|{integer}
|width="10%"|default: 0
|width="70%"|Specifies the maximum level a parent concept must have to be considered for the is_a semantic closure expansion step.
* For example, an annotation done with levelMax=3 will expand a direct annotations done with a concept up to the 3rd level parent in the is_a hierarchy for this concept. An annotation done with levelMax=0 is equivalent to disable the is_a transitive closure expansion step.

|-valign="top"
|width="10%"|'''mappingTypes'''
|width="10%"|{null,mappingType1,...,mappingTypeN}
|width="10%"|default: empty (i.e. all mappingTypes)
|width="70%"|Specifies the list of mapping types to use during the mapping expansion step. The list of rmapping types that can be used is available at the /obs/mappingTypes URL. The current list is described in section Mapping types.
* For example, Automatic,Manual.
* Note that the use of the key word "'''null'''" in the mappingTypes list disables the mapping expansion component.

|-valign="top"
|width="10%"|'''filterNumber'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies whether the concept recognition step to filter numbers or not.

|-valign="top"
|width="10%"|'''minTermSize'''
|width="10%"|{integer}
|width="10%"|default: 0
|width="70%"|Specifies the minimum length of the term to be included in the annotations.

|-valign="top"
|width="10%"|'''withSynonyms'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies either or not the direct annotations are done with or without Synonyms. By default it includes all the synonyms and preferred name. If 'false' is selected, the direct annotations are done with only preferred name.

|-valign="top"
|width="10%"|'''additionalStopWords'''
|width="10%"|{stopWord1,...,stopWordN}
|width="10%"|default: empty (i.e. none)
|width="70%"|Specifies the list of additional stop words to use. Already used stop words are available here: [[http://rest.bioontology.org/obs/stopwords]]

|-valign="top"
|width="10%"|'''isStopWordsCaseSenstive '''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies whether stopwords are case-sensitive or not.

|-valign="top"
|width="10%"|'''conceptids'''
|width="10%"|{conceptid1,...,conceptidn}
|width="10%"|default: empty (i.e. all concepts)
|width="70%"|Specifies the list of concept to use to query the Resource index (i.e., get the annotations done with this list). This parameter must be jointly specified with the mode parameter. If conceptids contains only one element then the mode parameter can be ignored. The values are separated with comma (without spaces).
* For example, 40401/D008545,4513/Virtual_surface.

|-valign="top"
|width="10%"|'''isVirtualOntologyId'''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies the if the list of ontologies are all BioPortal virtual ontology IDs. This parameter applies to both conceptids and ontologiesToKeepInResult parameters.

|-valign="top"
|width="10%"|'''mode'''
|width="10%"|{union, intersection}
|width="10%"|default: union
|width="70%"|Specifies the mode to use when querying the resource index with several concept (parameter conceptids ). The union mode returns the union of all the annotations (filtered eventually with other parameters) done with each specified conceptid. The intersection mode returns the intersection.

|-valign="top"
|width="10%"|'''elementid'''
|width="10%"|
|width="10%"|default: all
|width="70%"|Specifies the identifier of the resource element for which annotations are requested. The elementid is defined by the original resource e.g., PMID for PubMed, NCT for ClinicalTrials. The full list of the elementid type is defined in Section Local element ID used.
* For example, NCT00001589 or GDS2735.

|-valign="top"
|width="10%"|'''resourceid'''
|width="10%"|
|width="10%"|default: all
|width="70%"|Specifies the resource to filter the annotations with. The resourceid identifies a resource in the Resource Index. They are defined in section Resource identifiers. The list of resourceid can be used is available at the /obs/resources URL.
* For example, GEO,CT,AE.

|-valign="top"
|width="10%"|'''elementDetails'''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies the if the returned resource elements to be detailed or not.

|-valign="top"
|width="10%"|'''withContext'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies whether the annotations context information to be available or not. If turn to false, the set of annotations returned will be simplified and will not detail the context information for an annotation. Only the score will be returned.

|-valign="top"
|width="10%"|'''from and number'''
|width="10%"|{real_number}
|width="10%"|default: 0/10 respectively
|width="70%"|Specifies an offset of annotations defined by from and number.

|-valign="top"
|width="10%"|'''format'''
|width="10%"|{text,tabDelimited, xml}
|width="10%"|default: xml
|width="70%"|Specifies the desired format of the response.

|}

===Web Service Response===

'''Response Format'''
{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''xml'''
|width="90%"| returns XML representation of the ObrResultBeanDetailled.

|-valign="top"
|width="10%"|'''text'''
|width="90%"| returns plain text representation of the ObrResultBeanDetailled.

|-valign="top"
|width="10%"|'''tabDelimited'''
|width="90%"| shorter version of "Text" format. returns not the full result content but the annotations only (no statistics, etc.). The format of the tab delimited file is: score \t conceptId \t preferredName \t synonyms (separated by ' /// ') \t semanticType (separated by ' /// ') \t contextName \t isDirect \t other context information (e.g., childConceptId, mappedConceptId, level, mappingType) (separated by ' /// ').
|}

'''Note :''' ''if request parameter withContext is true, then returns representation of the ObrResultBeanDetailled and if request parameter withContext is false, then returns representation of the ObrResultBean.''

'''Response Content: ObrResultBeanDetailled'''

Response ObrResultBeanDetailled contains all the contents of ObrResultBean. Those contents are described in section Response Content: ObrResultBean.

Following are remaining contents for ObrResultBeanDetailled :

{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''directAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|-valign="top"
|width="10%"|'''isaAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|-valign="top"
|width="10%"|'''mappingAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|}

'''Note :''' ''Response contents of the ObrAnnotationBean are described in section ObrResultBean annotations''

'''Response Content: ObrResultBean'''
{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''resultID'''
|width="90%"|
|-valign="top"
|width="10%"|'''dictionary'''
|width="90%"| Dictionary contains the metadata (not the content) of the dictionary used for a result. dictionaryId, dictionaryName, and dictionaryDate identify the dictionary on the server side and give information about its content. Dictionary versioning is strongly linked to the evolution of the ontologies used. Each time ontologies change, the dictionary is updated. All the dictionary information may be useful for comparing results of the Annotator Restlet service on time.
|-valign="top"
|width="10%"|'''statistics'''
|width="90%"| Statistics contains information on the number of annotations done for a given context. The contextName keyword identifies the type of context and nbAnnotation is the number of annotations of this type.
|-valign="top"
|width="10%"|'''parameters'''
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Annotator Restlet service. Those parameters are described in section Service parameters
|-valign="top"
|width="10%"|'''ontologies'''
|width="90%"| To keep the model simple, we provide only the global ontology identifier, localOntologyId the name (ontologyName) and version (ontologyVersion). This information come from the original repositories (UMLS/BioPortal) and might help the user to select the right ontology to use. When an ontology is used in the annotation, a result has a set of OntologyUsed which specify 2 other properties: nbAnnotation, the number of annotation that have been made with concepts from this ontology. score, the sum of all the scores of the annotations done with concepts from this ontology (if parameter scored=true). Therefore, score represents the most accurate ontology to annotate the given text.
|-valign="top"
|width="10%"|'''annotations'''
|width="90%"| ObrAnnotationBean/ObrAnnotationBeanDetailled is a representation of one annotation. If ''elementDetails'' parameter is true the service return response of type ObrAnnotationBean ,otherwise ObrAnnotationBeanDetailled. An annotation has a score which represents the accuracy of the annotation computed by the scoring algorithm (if the scored=true parameter was chosen, otherwise score=-1). An annotation is done with a concept in a context.

'''Response Content: ObrAnnotationBeanDetailled'''

Response ObrAnnotationBeanDetailled contains all the contents of ObrAnnotationBean. Those contents are described in section Response Content: ObrAnnotationBean.

Following are remaining contents for ObrAnnotationBeanDetailled :

{| border="2" 

|-valign="top"
|width="10%"|'''element'''
|width="90%"|
* ''localElementID'' - Global identifier for the resource element.
* ''elementStructure'' - Represents Structure of an element for a given resource.

'''Response Content: Structure'''

{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|resource identifier for Resource.

|-valign="top"
|width="10%"|'''contexts'''
|width="90%"|list of context for resource.

|-valign="top"
|width="10%"|'''itemKeys'''
|width="90%"|list of itemKeys for resource.

|-valign="top"
|width="10%"|'''weights'''
|width="90%"|map contain weights (as double) for each context (as String).

|-valign="top"
|width="10%"|'''ontoIDs'''
|width="90%"|map contain ontologyIDs for each context (as String).
|}

|}

'''Response Content: ObrAnnotationBean'''

{| border="2" 
|-valign="top"
|width="10%"|'''localElementID'''
|width="90%"| Identifier for resource element.
|-valign="top"
|width="10%"|'''score'''
|width="90%"|
|-valign="top"
|width="10%"|'''concept'''
|width="90%"|
* ''localConceptId'' - global identifier for the concept in its original repository.
* ''localOntologyId'' - identifier for the ontology in which the concept is defined.
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology.
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository).
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred.
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999).
|-valign="top"
|width="10%"|'''context'''
|width="90%"| Context specifies if it is a direct or expanded annotation and give precision about the origin of the annotation. ''contextName'' identifies the type of context. The context properties vary with the type of concept. There are 3 possible contexts identified by their contextName:
{| border="2" style="background:#ABCDEF;" 
|-valign="top"
|width="10%"|'''MGREP'''
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A Mgrep context has 3 properties:
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.
|-valign="top"
|width="10%"|'''ISA_CLOSURE'''
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:
* ''childConceptId'' - the concept from which the annotation was derived.
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.
* For example, if a direct annotation with NCI/C0025202 (melanoma) was done, the is_a transitive closure component may expand it to another annotation with NCI/C1302746 (Melanocytic Neoplasm) because the latter is a direct parent (i.e., level 1) concept of the former. The ISA_CLOSURE annotation generated will have the following properties {NCI/C0025202, 1}.
|-valign="top"
|width="10%"|'''MAPPING'''
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties:
* mappedConceptId identifies the concept from which the annotation was derived.
* mappingType specifies the type of mapping.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.
|}
|}

|-valign="top"
|width="10%"|'''localElementID localConceptIDs mode withContext elementDetails counts offsetStart offsetMax'''
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Resource Index Restlet service. Those parameters are described in section Service parameters

|}

===GET calls===
Following section describes all other simplified GET services available in Resource_Index_API.

====Annotation by Concept Service====
Returns the set of annotations done with a given localConceptID.

*GET Request Format : '''/byconcept/{ontologyid}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/42693/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/{ontologyID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/{ontologyID}/{conceptID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled. If request parameter withContext is true, then returns representation of the ObrResultBeanDetailled and if request parameter withContext is false, then returns representation of the ObrResultBean.

====Annotation for BioPortal virtual ontology Concept Service ====
Returns the set of all annotations done with a given localConceptID using BioPortal virtual ontology ID.

*GET Request Format : '''/byconcept/virtual/{virtualOntologyID}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/virtual/1032/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/virtual/{virtualOntologyID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/virtual/{virtualOntologyID}/{conceptID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation By Concept And Resource Service ====
Returns the set of all annotations done with a given localConceptID for given resourceID.

*GET Request Format : '''/byconcept/{ontologyid}/{resourceid}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/42693/AE/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/{ontologyID}/{resourceID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/{ontologyID}/{conceptID}/{resourceID}/{withContext}/{counts}/{from}/{number}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation for BioPortal virtual ontology Concept And Resource Service ====
Returns the set of all annotations done with a given localConceptID using BioPortal virtual ontology ID and using particular resourceID.

*GET Request Format : '''/byconcept/virtual/{virtualOntologyID}/{resourceid}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/virtual/1032/AE/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/virtual/{virtualOntologyID}/{resourceID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/virtual/{virtualOntologyID}/{conceptID}/{resourceID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation By Resource Element Service ====
Returns the set of all annotations done with a given resource element localElementID for all the concepts.

*GET Request Format : '''/byelement/{resourceid}/{elementDetails}{withContext}/{counts}/{from}/{number}?elementid={elementid}'''
*Example 1 : http://rest.bioontology.org/resource_index/byelement/AE/false/true/false/0/10?elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Example 1 : http://rest.bioontology.org/resource_index/byelement/AE/true/true/false/0/10?elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest

*Old Request Format* :
**/byelement/{resourceID}/{withContext}/{counts}/{from}/{number}?elementID={localElementID}
**/byelement/{resourceID}/{localElementID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation Details By Resource Element Service ====
Returns the set of all annotations details with a given resource element localElementID for given conceptID

*GET Request Format : '''/details/{elementDetails}/concept/{ontologyid}/resource/{resourceid}?conceptid={conceptid}&elementid={elementid}'''
*Example1 : http://rest.bioontology.org/resource_index/details/true/concept/42693/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Example2 : http://rest.bioontology.org/resource_index/details/false/concept/42693/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/details/{elementDetails}/concept/{ontologyID}/resource/{resourceID}?conceptID={conceptID}&elementID={localElementID}
**/details/{elementDetails}/concept/{ontologyID}/{conceptID}/resource/{resourceID}/element/{localElementID}

*Response Content : ObrAnnotationBeanDetailled if elementDetails is true otherwise ObrAnnotationBean

====Annotation Details By Resource Element Service for BioPortal Virtual OntologyID====
Returns the set of all annotations details with a given resource element localElementID for given conceptID of BioPortal virtual ontologyID

*GET Request Format : '''/details/{elementDetails}/virtual/concept/{virtualOntologyID}/resource/{resourceid}?conceptid={conceptid}&elementid={elementid}'''
*Example1 : http://rest.bioontology.org/resource_index/details/true/virtual/concept/1032/Melanoma/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Example2 : http://rest.bioontology.org/resource_index/details/false/virtual/concept/1032/npo:Nanoparticle/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/details/{elementDetails}/virtual/concept/{virtualOntologyID}/resource/{resourceID}?conceptID={conceptID}&elementID={localElementID}
**/details/{elementDetails}/virtual/concept/{virtualOntologyID}/{conceptID}/resource/{resourceID}/element/{localElementID}

*Response Content : ObrAnnotationBeanDetailled if elementDetails is true otherwise ObrAnnotationBean.

====Resources Service ====
Returns the set of all resources available in resource index and information related to it.

*GET Request Format : ''/resources''
*Example: http://rest.bioontology.org/resource_index/resources?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource is a representation of one resource
'''Response Content: Resource'''

{| border="2" 
|-valign="top"
|width="10%"|'''resourceName'''
|width="90%"| Name of the particular resource.

|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"| Identifier of the resource.

|-valign="top"
|width="10%"|'''mainContext'''
|width="90%"| Main context string for the resource.

|-valign="top"
|width="10%"|'''resourceURL'''
|width="90%"| Website URL for the resource

|-valign="top"
|width="10%"|'''resourceElementURL'''
|width="90%"| Base URL for getting elements for resource.

|-valign="top"
|width="10%"|'''resourceDescription'''
|width="90%"| Description of the resource.

|-valign="top"
|width="10%"|'''resourceLogo'''
|width="90%"| URL of logo image for the resource.

|-valign="top"
|width="10%"|'''resourceStructure'''
|width="90%"| Represents Structure of an element for the resource.

'''Response Content: Structure'''

{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|resource identifier for Resource.

|-valign="top"
|width="10%"|'''contexts'''
|width="90%"|list of context for resource.

|-valign="top"
|width="10%"|'''itemKeys'''
|width="90%"|list of itemKeys for resource.

|-valign="top"
|width="10%"|'''weights'''
|width="90%"|map contain weights (as double) for each context (as String).

|-valign="top"
|width="10%"|'''ontoIDs'''
|width="90%"|map contain ontologyIDs for each context (as String).
|}

|}

====Resource Service ====
Returns the resource in resource index for given resourceID and information related to it.

*GET Request Format : ''/resources/{resourceid}''
*Example: http://rest.bioontology.org/resource_index/resources/AE?email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /resources/{resourceID}
*Response Content : Resource.

====Resource Element Service ====
Service returns elementURL for given localElementID and redirect it to get resource element on the web.

*GET Request Format : ''/element/{resourceid}?elementid={elementid}''
*Example: http://rest.bioontology.org/resource_index/element/AE?elementid=E-GEOD-9118&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /element/{resourceID}?element={localElementID}
*Response Content : Web page containing details of the element.

====Element details service by elementid ====
Retruns detail for given element using resource id and element id

*GET Request Format : ''/elementDetails/{resourceid}?elementid={elementid}''
*Example: http://rest.bioontology.org/resource_index/elementDetails/AE?elementid=E-GEOD-9118&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : element

====Resources Service with ontologies used for indexing ====
Returns the set of all resources available in resource index and list of onotolgies used for indexing them.

*GET Request Format : ''/resources?withontologies=true''
*Example: http://rest.bioontology.org/resource_index/resources?withontologies=true&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /resources?withOntologies=true
*Response Content : ObrResourceBean is a representation of one resource with ontologies
'''Response Content: ObrResourceBean'''

Response ObrResourceBean contains all the contents of Resource. Those contents are described in section ''Response Content: Resource''.

Following are remaining contents for ObrResourceBean :

{| border="2" 
|-valign="top"
|width="10%"|'''ontologiesUsed'''
|width="90%"| Presents list of ontologies used for indexing. Each ontology of type OntologyBean.
'''Response Content: OntologyBean'''
{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''localOntologyID'''
|width="90%"|Local onotology id for Ontology.

|-valign="top"
|width="10%"|'''ontologyName'''
|width="90%"|name of the resource.

|-valign="top"
|width="10%"|'''ontologyVersion'''
|width="90%"|version number for resource.

|-valign="top"
|width="10%"|'''virtualOntologyID'''
|width="90%"|virtual ontology id for ontology.
|}
|}

====Resource Service with ontologies used for indexing ====
Returns the information about resources and list of onotolgies used for indexing it.

*GET Request Format : ''/resources/{resourceid}?withontologies=true''
*Example: http://rest.bioontology.org/resource_index/resources/AE?withOntologies=true&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format : /resources/{resourceID}?withOntologies=true
*Response Content : Resource is represented by ObrResourceBean.

====Ontologies Service with resources indexed ====
Returns the set of all ontologies used in resource index with list of resources indexed by given ontology.

*GET Request Format : ''/ontologies?withresources=true''
*Example: http://rest.bioontology.org/resource_index/ontologies?withresources=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Each Ontology is represented by ObrOntologyBean.

Response ObrOntologyBean contains all the contents of OntologyBean.Those contents are described in section Response Content: OntologyBean.

Following are remaining contents for ObrResourceBean :
{| border="2" 
|-valign="top"
|width="10%"|'''resources'''
|width="90%"| Represents list of resources. Response content for each resource is of type Resource.
|}

====Ontology Service with resources indexed ====
Returns the information about given ontologies used in resource index with list of resources.

*GET Request Format : ''/ontologies/{ontologyid}''
*Example: http://rest.bioontology.org/resource_index/ontologies/42693?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Ontology is represented by ObrOntologyBean.

====All Statistics Service====
Returns the information about number of all the annotations done in resource index.

*GET Request Format : ''/statistics/all''
*Example: http://rest.bioontology.org/resource_index/statistics/all?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : All annotations represented by ObrStatisticsBean.

'''Response Content: ObrStatisticsBean'''
Following are remaining contents for ObrStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''aggregatedAnnotations'''
|width="90%"|Sum of the number of rows in all the indexing tables

|-valign="top"
|width="10%"|'''mgrepAnnotations'''
|width="90%"|Number of mgrep annotations entries in direct annotation table.

|-valign="top"
|width="10%"|'''reportedAnnotations'''
|width="90%"|Number of reported annotations entries in direct annotation table.

|-valign="top"
|width="10%"|'''isaAnnotations'''
|width="90%"|Number of is-a annotations entries in extended annotation table.

|-valign="top"
|width="10%"|'''mappingAnnotations'''
|width="90%"|Number of mapping annotations entries in extended annotation table.

|}

====Ontology Statistics Service====
Returns the total statistics for given ontology for All resources.

*GET Request Format : ''/statistics/ontology/{ontologyid}''
*Example: http://rest.bioontology.org/resource_index/statistics/ontology/42693?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Ontology statistics with format ObrOntologyStatisticsBean.

'''Response Content: ObrOntologyStatisticsBean'''
Following are contents for ObrOntologyStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|Resource Id for resource.

|-valign="top"
|width="10%"|'''statistics'''
|width="90%"|ObrStatisticsBean is a representation of statistics

|}

====Ontology Statistics Service by resources====
Returns the statistics for given ontology for each resource separately.

*GET Request Format : ''/statistics/ontology/{onotlogyid}?byresource=true''
*Example: http://rest.bioontology.org/resource_index/statistics/ontology/42693?byresource=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : ObrOntologyStatisticsBean

====Resource Statistics Service====
Returns the total statistics for given resource for All ontology.

*GET Request Format : ''/statistics/resource/{resourceid}''
*Example: http://rest.bioontology.org/resource_index/statistics/resource/CANANO?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource statistics with format ObrResourceStatisticsBean.

'''Response Content: ObrResourceStatisticsBean'''
Following are contents for ObrResourceStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''localOntologyID'''
|width="90%"|local ontology id for given ontology.

|-valign="top"
|width="10%"|'''statistics'''
|width="90%"|ObrStatisticsBean is a representation of statistics

|}

====Resource Statistics Service by ontologies====
Returns the statistics for given resource for each ontology separately.

*GET Request Format : ''/statistics/resource/{resourceid}?byontology=true ''
*Example: http://rest.bioontology.org/resource_index/statistics/resource/AE?byontology=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource statistics with format ObrResourceStatisticsBean.

----
'''Note* :''' ''Old Request Format not working anymore.''

----

Resource Index REST Web Service User Guide

2010-07-06T18:43:01Z

Jonquet: /* Parameters */

===Introduction===
The Resource Index API is available through a REST web services interface.

This documentation describes the current version of the API. Some changes may append in the future.

The Resource index API is based on the web service that returns annotations from the Resource Index (called via a REST post). Additionally some simplified REST get services returned simplified results.

== Attention, this documentation is not currently in sync with the deployed version... we plan to release pretty soon the new API (that goes with this documentation). Please refer to the history of this wiki page for old documentation. ==

===Sample HTTP Client for the Resource Index REST Web Service===

Test HTML Page : http://rest.bioontology.org/resource_index/test

Resources Service Page : http://rest.bioontology.org/resource_index/resources/list/

===Service endpoint===

http://rest.bioontology.org/resource_index/

=== POST calls ===

POST your requests at the service endpoint.

====Parameters====

The Resource Index web service offers a set of parameters that allows a user to customize the annotations returned according to his specific requirements. For example, the annotations returned can be limited to a specific set of ontology and a specific set of semantic types. Plus, the expanded annotations can be filtered.

Please see below for the list of parameters and the possible values.

{| border="1" cellpadding="2"

|-valign="top"
|width="10%"|'''ontologiesToKeepInResult'''
|width="10%"|{localOntology1,...,localOntologyN}
|width="10%"|default: empty (i.e. all ontologies)
|width="70%"|Specifies the list of ontologies you want to filter in the result from the annotation process. The list of ontologies that can be used is available in the sample HTML page. The values are separated with comma (without spaces)
* For example, 42789,42838,42142.

|-valign="top"
|width="10%"|'''semanticTypes'''
|width="10%"|{semanticType1,...,semanticTypeN}
|width="10%"|default: empty (i.e. all semanticTypes)
|width="70%"|Specifies the list of UMLS semantic types to use in the annotation process. The list of semantic types that can be used is available at the /obs/semanticTypes URL. Note that the restriction to semantic types is also applied during the semantic expansion steps.
* For example, T047,T048,T191.

|-valign="top"
|width="10%"|'''levelMax'''
|width="10%"|{integer}
|width="10%"|default: 0
|width="70%"|Specifies the maximum level a parent concept must have to be considered for the is_a semantic closure expansion step.
* For example, an annotation done with levelMax=3 will expand a direct annotations done with a concept up to the 3rd level parent in the is_a hierarchy for this concept. An annotation done with levelMax=0 is equivalent to disable the is_a transitive closure expansion step.

|-valign="top"
|width="10%"|'''mappingTypes'''
|width="10%"|{null,mappingType1,...,mappingTypeN}
|width="10%"|default: empty (i.e. all mappingTypes)
|width="70%"|Specifies the list of mapping types to use during the mapping expansion step. The list of rmapping types that can be used is available at the /obs/mappingTypes URL. The current list is described in section Mapping types.
* For example, Automatic,Manual.
* Note that the use of the key word "'''null'''" in the mappingTypes list disables the mapping expansion component.

|-valign="top"
|width="10%"|'''filterNumber'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies whether the concept recognition step to filter numbers or not.

|-valign="top"
|width="10%"|'''minTermSize'''
|width="10%"|{integer}
|width="10%"|default: 0
|width="70%"|Specifies the minimum length of the term to be included in the annotations.

|-valign="top"
|width="10%"|'''withSynonyms'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies either or not the direct annotations are done with or without Synonyms. By default it includes all the synonyms and preferred name. If 'false' is selected, the direct annotations are done with only preferred name.

|-valign="top"
|width="10%"|'''additionalStopWords'''
|width="10%"|{stopWord1,...,stopWordN}
|width="10%"|default: empty (i.e. none)
|width="70%"|Specifies the list of additional stop words to use. Already used stop words are available here: [[http://rest.bioontology.org/obs/stopwords]]

|-valign="top"
|width="10%"|'''isStopWordsCaseSenstive '''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies whether stopwords are case-sensitive or not.

|-valign="top"
|width="10%"|'''conceptids'''
|width="10%"|{conceptid1,...,conceptidn}
|width="10%"|default: empty (i.e. all concepts)
|width="70%"|Specifies the list of concept to use to query the Resource index (i.e., get the annotations done with this list). This parameter must be jointly specified with the mode parameter. If conceptids contains only one element then the mode parameter can be ignored. The values are separated with comma (without spaces).
* For example, 40401/D008545,4513/Virtual_surface.

|-valign="top"
|width="10%"|'''isVirtualOntologyId'''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies the if the list of ontologies are all BioPortal virtual ontology IDs. This parameter applies to both conceptids and ontologiesToKeepInResult parameters.

|-valign="top"
|width="10%"|'''mode'''
|width="10%"|{union, intersection}
|width="10%"|default: union
|width="70%"|Specifies the mode to use when querying the resource index with several concept (parameter conceptids ). The union mode returns the union of all the annotations (filtered eventually with other parameters) done with each specified conceptid. The intersection mode returns the intersection.

|-valign="top"
|width="10%"|'''elementid'''
|width="10%"|
|width="10%"|default: all
|width="70%"|Specifies the identifier of the resource element for which annotations are requested. The elementid is defined by the original resource e.g., PMID for PubMed, NCT for ClinicalTrials. The full list of the elementid type is defined in Section Local element ID used.
* For example, NCT00001589 or GDS2735.

|-valign="top"
|width="10%"|'''resourceid'''
|width="10%"|
|width="10%"|default: all
|width="70%"|Specifies the resource to filter the annotations with. The resourceid identifies a resource in the Resource Index. They are defined in section Resource identifiers. The list of resourceid can be used is available at the /obs/resources URL.
* For example, GEO,CT,AE.

|-valign="top"
|width="10%"|'''elementDetails'''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies the if the returned resource elements to be detailed or not.

|-valign="top"
|width="10%"|'''withContext'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies whether the annotations context information to be available or not. If turn to false, the set of annotations returned will be simplified and will not detail the context information for an annotation. Only the score will be returned.

|-valign="top"
|width="10%"|'''from and number'''
|width="10%"|{real_number}
|width="10%"|default: 0/10 respectively
|width="70%"|Specifies an offset of annotations defined by from and number.

|-valign="top"
|width="10%"|'''format'''
|width="10%"|{text,tabDelimited, xml}
|width="10%"|default: xml
|width="70%"|Specifies the desired format of the response.

|}

===Web Service Response===

'''Response Format'''
{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''xml'''
|width="90%"| returns XML representation of the ObrResultBeanDetailled.

|-valign="top"
|width="10%"|'''text'''
|width="90%"| returns plain text representation of the ObrResultBeanDetailled.

|-valign="top"
|width="10%"|'''tabDelimited'''
|width="90%"| shorter version of "Text" format. returns not the full result content but the annotations only (no statistics, etc.). The format of the tab delimited file is: score \t conceptId \t preferredName \t synonyms (separated by ' /// ') \t semanticType (separated by ' /// ') \t contextName \t isDirect \t other context information (e.g., childConceptId, mappedConceptId, level, mappingType) (separated by ' /// ').
|}

'''Note :''' ''if request parameter withContext is true, then returns representation of the ObrResultBeanDetailled and if request parameter withContext is false, then returns representation of the ObrResultBean.''

'''Response Content: ObrResultBeanDetailled'''

Response ObrResultBeanDetailled contains all the contents of ObrResultBean. Those contents are described in section Response Content: ObrResultBean.

Following are remaining contents for ObrResultBeanDetailled :

{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''directAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|-valign="top"
|width="10%"|'''isaAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|-valign="top"
|width="10%"|'''mappingAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|}

'''Note :''' ''Response contents of the ObrAnnotationBean are described in section ObrResultBean annotations''

'''Response Content: ObrResultBean'''
{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''resultID'''
|width="90%"|
|-valign="top"
|width="10%"|'''dictionary'''
|width="90%"| Dictionary contains the metadata (not the content) of the dictionary used for a result. dictionaryId, dictionaryName, and dictionaryDate identify the dictionary on the server side and give information about its content. Dictionary versioning is strongly linked to the evolution of the ontologies used. Each time ontologies change, the dictionary is updated. All the dictionary information may be useful for comparing results of the Annotator Restlet service on time.
|-valign="top"
|width="10%"|'''statistics'''
|width="90%"| Statistics contains information on the number of annotations done for a given context. The contextName keyword identifies the type of context and nbAnnotation is the number of annotations of this type.
|-valign="top"
|width="10%"|'''parameters'''
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Annotator Restlet service. Those parameters are described in section Service parameters
|-valign="top"
|width="10%"|'''ontologies'''
|width="90%"| To keep the model simple, we provide only the global ontology identifier, localOntologyId the name (ontologyName) and version (ontologyVersion). This information come from the original repositories (UMLS/BioPortal) and might help the user to select the right ontology to use. When an ontology is used in the annotation, a result has a set of OntologyUsed which specify 2 other properties: nbAnnotation, the number of annotation that have been made with concepts from this ontology. score, the sum of all the scores of the annotations done with concepts from this ontology (if parameter scored=true). Therefore, score represents the most accurate ontology to annotate the given text.
|-valign="top"
|width="10%"|'''annotations'''
|width="90%"| ObrAnnotationBean/ObrAnnotationBeanDetailled is a representation of one annotation. If ''elementDetails'' parameter is true the service return response of type ObrAnnotationBean ,otherwise ObrAnnotationBeanDetailled. An annotation has a score which represents the accuracy of the annotation computed by the scoring algorithm (if the scored=true parameter was chosen, otherwise score=-1). An annotation is done with a concept in a context.

'''Response Content: ObrAnnotationBeanDetailled'''

Response ObrAnnotationBeanDetailled contains all the contents of ObrAnnotationBean. Those contents are described in section Response Content: ObrAnnotationBean.

Following are remaining contents for ObrAnnotationBeanDetailled :

{| border="2" 

|-valign="top"
|width="10%"|'''element'''
|width="90%"|
* ''localElementID'' - Global identifier for the resource element.
* ''elementStructure'' - Represents Structure of an element for a given resource.

'''Response Content: Structure'''

{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|resource identifier for Resource.

|-valign="top"
|width="10%"|'''contexts'''
|width="90%"|list of context for resource.

|-valign="top"
|width="10%"|'''itemKeys'''
|width="90%"|list of itemKeys for resource.

|-valign="top"
|width="10%"|'''weights'''
|width="90%"|map contain weights (as double) for each context (as String).

|-valign="top"
|width="10%"|'''ontoIDs'''
|width="90%"|map contain ontologyIDs for each context (as String).
|}

|}

'''Response Content: ObrAnnotationBean'''

{| border="2" 
|-valign="top"
|width="10%"|'''localElementID'''
|width="90%"| Identifier for resource element.
|-valign="top"
|width="10%"|'''score'''
|width="90%"|
|-valign="top"
|width="10%"|'''concept'''
|width="90%"|
* ''localConceptId'' - global identifier for the concept in its original repository.
* ''localOntologyId'' - identifier for the ontology in which the concept is defined.
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology.
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository).
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred.
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999).
|-valign="top"
|width="10%"|'''context'''
|width="90%"| Context specifies if it is a direct or expanded annotation and give precision about the origin of the annotation. ''contextName'' identifies the type of context. The context properties vary with the type of concept. There are 3 possible contexts identified by their contextName:
{| border="2" style="background:#ABCDEF;" 
|-valign="top"
|width="10%"|'''MGREP'''
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A Mgrep context has 3 properties:
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.
|-valign="top"
|width="10%"|'''ISA_CLOSURE'''
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:
* ''childConceptId'' - the concept from which the annotation was derived.
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.
* For example, if a direct annotation with NCI/C0025202 (melanoma) was done, the is_a transitive closure component may expand it to another annotation with NCI/C1302746 (Melanocytic Neoplasm) because the latter is a direct parent (i.e., level 1) concept of the former. The ISA_CLOSURE annotation generated will have the following properties {NCI/C0025202, 1}.
|-valign="top"
|width="10%"|'''MAPPING'''
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties:
* mappedConceptId identifies the concept from which the annotation was derived.
* mappingType specifies the type of mapping.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.
|}
|}

|-valign="top"
|width="10%"|'''localElementID localConceptIDs mode withContext elementDetails counts offsetStart offsetMax'''
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Resource Index Restlet service. Those parameters are described in section Service parameters

|}

===GET calls===
Following section describes all other simplified GET services available in Resource_Index_API.

====Annotation by Concept Service====
Returns the set of annotations done with a given localConceptID.

*GET Request Format : '''/byconcept/{ontologyid}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/42693/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/{ontologyID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/{ontologyID}/{conceptID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled. If request parameter withContext is true, then returns representation of the ObrResultBeanDetailled and if request parameter withContext is false, then returns representation of the ObrResultBean.

====Annotation for BioPortal virtual ontology Concept Service ====
Returns the set of all annotations done with a given localConceptID using BioPortal virtual ontology ID.

*GET Request Format : '''/byconcept/virtual/{virtualOntologyID}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/virtual/1032/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/virtual/{virtualOntologyID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/virtual/{virtualOntologyID}/{conceptID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation By Concept And Resource Service ====
Returns the set of all annotations done with a given localConceptID for given resourceID.

*GET Request Format : '''/byconcept/{ontologyid}/{resourceid}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/42693/AE/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/{ontologyID}/{resourceID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/{ontologyID}/{conceptID}/{resourceID}/{withContext}/{counts}/{from}/{number}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation for BioPortal virtual ontology Concept And Resource Service ====
Returns the set of all annotations done with a given localConceptID using BioPortal virtual ontology ID and using particular resourceID.

*GET Request Format : '''/byconcept/virtual/{virtualOntologyID}/{resourceid}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/virtual/1032/AE/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/virtual/{virtualOntologyID}/{resourceID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/virtual/{virtualOntologyID}/{conceptID}/{resourceID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation By Resource Element Service ====
Returns the set of all annotations done with a given resource element localElementID for all the concepts.

*GET Request Format : '''/byelement/{resourceid}/{withContext}/{counts}/{from}/{number}?elementid={elementid}'''
*Example : http://rest.bioontology.org/resource_index/byelement/AE/true/false/0/10?elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byelement/{resourceID}/{withContext}/{counts}/{from}/{number}?elementID={localElementID}
**/byelement/{resourceID}/{localElementID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation Details By Resource Element Service ====
Returns the set of all annotations details with a given resource element localElementID for given conceptID

*GET Request Format : '''/details/{elementDetails}/concept/{ontologyid}/resource/{resourceid}?conceptid={conceptid}&elementid={elementid}'''
*Example1 : http://rest.bioontology.org/resource_index/details/true/concept/42693/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Example1 : http://rest.bioontology.org/resource_index/details/false/concept/42693/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/details/{elementDetails}/concept/{ontologyID}/resource/{resourceID}?conceptID={conceptID}&elementID={localElementID}
**/details/{elementDetails}/concept/{ontologyID}/{conceptID}/resource/{resourceID}/element/{localElementID}

*Response Content : ObrAnnotationBeanDetailled if elementDetails is true otherwise ObrAnnotationBean

====Annotation Details By Resource Element Service for BioPortal Virtual OntologyID====
Returns the set of all annotations details with a given resource element localElementID for given conceptID of BioPortal virtual ontologyID

*GET Request Format : '''/details/{elementDetails}/virtual/concept/{virtualOntologyID}/resource/{resourceid}?conceptid={conceptid}&elementid={elementid}'''
*Example1 : http://rest.bioontology.org/resource_index/details/true/virtual/concept/1032/Melanoma/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Example2 : http://rest.bioontology.org/resource_index/details/false/virtual/concept/1032/npo:Nanoparticle/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/details/{elementDetails}/virtual/concept/{virtualOntologyID}/resource/{resourceID}?conceptID={conceptID}&elementID={localElementID}
**/details/{elementDetails}/virtual/concept/{virtualOntologyID}/{conceptID}/resource/{resourceID}/element/{localElementID}

*Response Content : ObrAnnotationBeanDetailled if elementDetails is true otherwise ObrAnnotationBean.

====Resources Service ====
Returns the set of all resources available in resource index and information related to it.

*GET Request Format : ''/resources''
*Example: http://rest.bioontology.org/resource_index/resources?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource is a representation of one resource
'''Response Content: Resource'''

{| border="2" 
|-valign="top"
|width="10%"|'''resourceName'''
|width="90%"| Name of the particular resource.

|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"| Identifier of the resource.

|-valign="top"
|width="10%"|'''mainContext'''
|width="90%"| Main context string for the resource.

|-valign="top"
|width="10%"|'''resourceURL'''
|width="90%"| Website URL for the resource

|-valign="top"
|width="10%"|'''resourceElementURL'''
|width="90%"| Base URL for getting elements for resource.

|-valign="top"
|width="10%"|'''resourceDescription'''
|width="90%"| Description of the resource.

|-valign="top"
|width="10%"|'''resourceLogo'''
|width="90%"| URL of logo image for the resource.

|-valign="top"
|width="10%"|'''resourceStructure'''
|width="90%"| Represents Structure of an element for the resource.

'''Response Content: Structure'''

{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|resource identifier for Resource.

|-valign="top"
|width="10%"|'''contexts'''
|width="90%"|list of context for resource.

|-valign="top"
|width="10%"|'''itemKeys'''
|width="90%"|list of itemKeys for resource.

|-valign="top"
|width="10%"|'''weights'''
|width="90%"|map contain weights (as double) for each context (as String).

|-valign="top"
|width="10%"|'''ontoIDs'''
|width="90%"|map contain ontologyIDs for each context (as String).
|}

|}

====Resource Service ====
Returns the resource in resource index for given resourceID and information related to it.

*GET Request Format : ''/resources/{resourceid}''
*Example: http://rest.bioontology.org/resource_index/resources/AE?email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /resources/{resourceID}
*Response Content : Resource.

====Resource Element Service ====
Service returns elementURL for given localElementID and redirect it to get resource element on the web.

*GET Request Format : ''/element/{resourceid}?elementid={elementid}''
*Example: http://rest.bioontology.org/resource_index/element/AE?elementid=E-GEOD-9118&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /element/{resourceID}?element={localElementID}
*Response Content : Web page containing details of the element.

====Resources Service with ontologies used for indexing ====
Returns the set of all resources available in resource index and list of onotolgies used for indexing them.

*GET Request Format : ''/resources?withontologies=true''
*Example: http://rest.bioontology.org/resource_index/resources?withontologies=true&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /resources?withOntologies=true
*Response Content : ObrResourceBean is a representation of one resource with ontologies
'''Response Content: ObrResourceBean'''

Response ObrResourceBean contains all the contents of Resource. Those contents are described in section ''Response Content: Resource''.

Following are remaining contents for ObrResourceBean :

{| border="2" 
|-valign="top"
|width="10%"|'''ontologiesUsed'''
|width="90%"| Presents list of ontologies used for indexing. Each ontology of type OntologyBean.
'''Response Content: OntologyBean'''
{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''localOntologyID'''
|width="90%"|Local onotology id for Ontology.

|-valign="top"
|width="10%"|'''ontologyName'''
|width="90%"|name of the resource.

|-valign="top"
|width="10%"|'''ontologyVersion'''
|width="90%"|version number for resource.

|-valign="top"
|width="10%"|'''virtualOntologyID'''
|width="90%"|virtual ontology id for ontology.
|}
|}

====Resource Service with ontologies used for indexing ====
Returns the information about resources and list of onotolgies used for indexing it.

*GET Request Format : ''/resources/{resourceid}?withontologies=true''
*Example: http://rest.bioontology.org/resource_index/resources/AE?withOntologies=true&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format : /resources/{resourceID}?withOntologies=true
*Response Content : Resource is represented by ObrResourceBean.

====Ontologies Service with resources indexed ====
Returns the set of all ontologies used in resource index with list of resources indexed by given ontology.

*GET Request Format : ''/ontologies?withresources=true''
*Example: http://rest.bioontology.org/resource_index/ontologies?withresources=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Each Ontology is represented by ObrOntologyBean.

Response ObrOntologyBean contains all the contents of OntologyBean.Those contents are described in section Response Content: OntologyBean.

Following are remaining contents for ObrResourceBean :
{| border="2" 
|-valign="top"
|width="10%"|'''resources'''
|width="90%"| Represents list of resources. Response content for each resource is of type Resource.
|}

====Ontology Service with resources indexed ====
Returns the information about given ontologies used in resource index with list of resources.

*GET Request Format : ''/ontologies/{ontologyid}''
*Example: http://rest.bioontology.org/resource_index/ontologies/42693?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Ontology is represented by ObrOntologyBean.

====All Statistics Service====
Returns the information about number of all the annotations done in resource index.

*GET Request Format : ''/statistics/all''
*Example: http://rest.bioontology.org/resource_index/statistics/all?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : All annotations represented by ObrStatisticsBean.

'''Response Content: ObrStatisticsBean'''
Following are remaining contents for ObrStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''aggregatedAnnotations'''
|width="90%"|Sum of the number of rows in all the indexing tables

|-valign="top"
|width="10%"|'''mgrepAnnotations'''
|width="90%"|Number of mgrep annotations entries in direct annotation table.

|-valign="top"
|width="10%"|'''reportedAnnotations'''
|width="90%"|Number of reported annotations entries in direct annotation table.

|-valign="top"
|width="10%"|'''isaAnnotations'''
|width="90%"|Number of is-a annotations entries in extended annotation table.

|-valign="top"
|width="10%"|'''mappingAnnotations'''
|width="90%"|Number of mapping annotations entries in extended annotation table.

|}

====Ontology Statistics Service====
Returns the total statistics for given ontology for All resources.

*GET Request Format : ''/statistics/ontology/{ontologyid}''
*Example: http://rest.bioontology.org/resource_index/statistics/ontology/42693?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Ontology statistics with format ObrOntologyStatisticsBean.

'''Response Content: ObrOntologyStatisticsBean'''
Following are contents for ObrOntologyStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|Resource Id for resource.

|-valign="top"
|width="10%"|'''statistics'''
|width="90%"|ObrStatisticsBean is a representation of statistics

|}

====Ontology Statistics Service by resources====
Returns the statistics for given ontology for each resource separately.

*GET Request Format : ''/statistics/ontology/{onotlogyid}?byresource=true''
*Example: http://rest.bioontology.org/resource_index/statistics/ontology/42693?byresource=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : ObrOntologyStatisticsBean

====Resource Statistics Service====
Returns the total statistics for given resource for All ontology.

*GET Request Format : ''/statistics/resource/{resourceid}''
*Example: http://rest.bioontology.org/resource_index/statistics/resource/CANANO?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource statistics with format ObrResourceStatisticsBean.

'''Response Content: ObrResourceStatisticsBean'''
Following are contents for ObrResourceStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''localOntologyID'''
|width="90%"|local ontology id for given ontology.

|-valign="top"
|width="10%"|'''statistics'''
|width="90%"|ObrStatisticsBean is a representation of statistics

|}

====Resource Statistics Service by ontologies====
Returns the statistics for given resource for each ontology separately.

*GET Request Format : ''/statistics/resource/{resourceid}?byontology=true ''
*Example: http://rest.bioontology.org/resource_index/statistics/resource/AE?byontology=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource statistics with format ObrResourceStatisticsBean.

----
'''Note* :''' ''Old Request Format not working anymore.''

----

Resource Index REST Web Service User Guide

2010-07-06T18:30:52Z

Jonquet: /* Introduction */

===Introduction===
The Resource Index API is available through a REST web services interface.

This documentation describes the current version of the API. Some changes may append in the future.

The Resource index API is based on the web service that returns annotations from the Resource Index (called via a REST post). Additionally some simplified REST get services returned simplified results.

== Attention, this documentation is not currently in sync with the deployed version... we plan to release pretty soon the new API (that goes with this documentation). Please refer to the history of this wiki page for old documentation. ==

===Sample HTTP Client for the Resource Index REST Web Service===

Test HTML Page : http://rest.bioontology.org/resource_index/test

Resources Service Page : http://rest.bioontology.org/resource_index/resources/list/

===Service endpoint===

http://rest.bioontology.org/resource_index/

=== POST calls ===

POST your requests at the service endpoint.

====Parameters====

The Resource Index web service offers a set of parameters that allows a user to customize the annotations returned according to his specific requirements. For example, the annotations returned can be limited to a specific set of ontology and a specific set of semantic types. Plus, the expanded annotations can be filtered.

Please see below for the list of parameters and the possible values.

{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''ontologiesToKeepInResult'''
|width="10%"|{localOntology1,...,localOntologyN}
|width="10%"|default: empty (i.e. all ontologies)
|width="70%"|Specifies the list of ontologies you want to filter in the result from the annotation process. The list of ontologies that can be used is available in the sample HTML page. The values are separated with comma (without spaces)
* For example, SNOMEDCT,NCI,MSH.
|-valign="top"
|width="10%"|'''semanticTypes'''
|width="10%"|{semanticType1,...,semanticTypeN}
|width="10%"|default: empty (i.e. all semanticTypes)
|width="70%"|Specifies the list of semantic types to use in the annotation process. The list of semantic types that can be used is available at the /obs/semanticTypes URL. Note that the restriction to semantic types is also applied during the semantic expansion steps.
* For example, T047,T048,T191.
|-valign="top"
|width="10%"|'''levelMax'''
|width="10%"|{integer}
|width="10%"|default: 0
|width="70%"|Specifies the maximum level a parent concept must have to be considered for the is_a semantic closure expansion step.
* For example, an annotation done with levelMax=3 will expand a direct annotations done with a concept up to the 3rd level parent in the is_a hierarchy for this concept. An annotation done with levelMax=0 is equivalent to disable the is_a transitive closure expansion step.
|-valign="top"
|width="10%"|'''mappingTypes'''
|width="10%"|{null,mappingType1,...,mappingTypeN}
|width="10%"|default: empty (i.e. all mappingTypes)
|width="70%"|Specifies the list of mapping type to use during the mapping expansion step. The list of rmapping types that can be used is available at the /obs/mappingTypes URL. The current list is described in section Mapping types.
* For example, from-mrrel,Human.
* Note that the use of the key word "'''null'''" in the mappingTypes list disables the mapping expansion component. Note also that the mapping expansion is also limited by other parameters such as ''ontologiesToExpand'' and ''ontologiesToKeepInResult''.

|-valign="top"
|width="10%"|'''filterNumber'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies whether the concept recognition step to filter numbers or not.

|-valign="top"
|width="10%"|'''minTermSize'''
|width="10%"|{integer}
|width="10%"|default: 0
|width="70%"|Specifies the minimum length of the term to be included in the annotations.

|-valign="top"
|width="10%"|'''withSynonyms'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies either or not the direct annotations are done with or without Synonyms. By default it includes all the synonyms and preferred name. If 'false' is selected, the direct annotations are done with only preferred name.

|-valign="top"
|width="10%"|'''additionalStopWords'''
|width="10%"|{stopWord1,...,stopWordN}
|width="10%"|default: empty (i.e. none)
|width="70%"|Specifies the list of stop words to use.

|-valign="top"
|width="10%"|'''isStopWordsCaseSenstive '''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies whether stopwords are case-sensitive or not.

|-valign="top"
|width="10%"|'''conceptids'''
|width="10%"|{localConceptID1,...,localConceptIDN}
|width="10%"|default: empty (i.e. all concepts)
|width="70%"|Specifies the list of concept to use to query the Resource index (i.e., get the annotations done with this list). This parameter must be jointly specified with the mode parameter. If conceptids contains only one element then the mode parameter can be ignored.The values are separated with comma (without spaces).
* For example, NCI/C0025202,4513/Virtual_surface.

|-valign="top"
|width="10%"|'''isVirtualOntologyId'''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies the if the list of ontologies are all BioPortal virtual ontology IDs or UMLS ontologies.

|-valign="top"
|width="10%"|'''mode'''
|width="10%"|{union, intersection}
|width="10%"|default: union
|width="70%"|Specifies the mode to use when querying the resource index with several concept (parameter localConceptIDs). The union mode returns the union of all the annotations (filtered eventually with other parameters) done with each specified localConceptID. The intersection mode returns the intersection.

|-valign="top"
|width="10%"|'''elementid'''
|width="10%"|
|width="10%"|default: all
|width="70%"|Specifies the identifier of the resource element for which annotations are requested. The elementid is defined by the original resource e.g., PMID for PubMed, NCT for ClinicalTrials. The full list of the elementid type is defined in Section Local element ID used.
* For example, NCT00001589 or GDS2735.

|-valign="top"
|width="10%"|'''resourceid'''
|width="10%"|
|width="10%"|default: all
|width="70%"|Specifies the resource to filter the annotations with. The resource_identifier used for this parameter identify a resource in the OBR index. They are defined in section Resource identifiers.The list of resourceID can be used is available at the /obs/resources URL.
* For example, GEO,CT,AE.

|-valign="top"
|width="10%"|'''resourceid'''
|width="10%"|{true, false}
|width="10%"|default: false
|width="70%"|Specifies the if the returned resource elements to be detailed or not.

|-valign="top"
|width="10%"|'''withContext'''
|width="10%"|{true, false}
|width="10%"|default: true
|width="70%"|Specifies whether the annotations context information to be available or not.If turn to false, the set of annotations returned will be simplified and will not detail the context information for an annotation. Only the score will be returned (which implies score=true)

|-valign="top"
|width="10%"|'''from and number'''
|width="10%"|{real_number}
|width="10%"|default: 0/10 respectively
|width="70%"|Specifies an offset of annotations defined by from and number.

|-valign="top"
|width="10%"|'''format'''
|width="10%"|{text,tabDelimited, xml}
|width="10%"|default: xml
|width="70%"|Specifies the desired format of the response.

|}

===Web Service Response===

'''Response Format'''
{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''xml'''
|width="90%"| returns XML representation of the ObrResultBeanDetailled.

|-valign="top"
|width="10%"|'''text'''
|width="90%"| returns plain text representation of the ObrResultBeanDetailled.

|-valign="top"
|width="10%"|'''tabDelimited'''
|width="90%"| shorter version of "Text" format. returns not the full result content but the annotations only (no statistics, etc.). The format of the tab delimited file is: score \t conceptId \t preferredName \t synonyms (separated by ' /// ') \t semanticType (separated by ' /// ') \t contextName \t isDirect \t other context information (e.g., childConceptId, mappedConceptId, level, mappingType) (separated by ' /// ').
|}

'''Note :''' ''if request parameter withContext is true, then returns representation of the ObrResultBeanDetailled and if request parameter withContext is false, then returns representation of the ObrResultBean.''

'''Response Content: ObrResultBeanDetailled'''

Response ObrResultBeanDetailled contains all the contents of ObrResultBean. Those contents are described in section Response Content: ObrResultBean.

Following are remaining contents for ObrResultBeanDetailled :

{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''directAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|-valign="top"
|width="10%"|'''isaAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|-valign="top"
|width="10%"|'''mappingAnnotations'''
|width="90%"| ObrAnnotationBean is a representation of one annotation.

|}

'''Note :''' ''Response contents of the ObrAnnotationBean are described in section ObrResultBean annotations''

'''Response Content: ObrResultBean'''
{| border="1" cellpadding="2"
|-valign="top"
|width="10%"|'''resultID'''
|width="90%"|
|-valign="top"
|width="10%"|'''dictionary'''
|width="90%"| Dictionary contains the metadata (not the content) of the dictionary used for a result. dictionaryId, dictionaryName, and dictionaryDate identify the dictionary on the server side and give information about its content. Dictionary versioning is strongly linked to the evolution of the ontologies used. Each time ontologies change, the dictionary is updated. All the dictionary information may be useful for comparing results of the Annotator Restlet service on time.
|-valign="top"
|width="10%"|'''statistics'''
|width="90%"| Statistics contains information on the number of annotations done for a given context. The contextName keyword identifies the type of context and nbAnnotation is the number of annotations of this type.
|-valign="top"
|width="10%"|'''parameters'''
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Annotator Restlet service. Those parameters are described in section Service parameters
|-valign="top"
|width="10%"|'''ontologies'''
|width="90%"| To keep the model simple, we provide only the global ontology identifier, localOntologyId the name (ontologyName) and version (ontologyVersion). This information come from the original repositories (UMLS/BioPortal) and might help the user to select the right ontology to use. When an ontology is used in the annotation, a result has a set of OntologyUsed which specify 2 other properties: nbAnnotation, the number of annotation that have been made with concepts from this ontology. score, the sum of all the scores of the annotations done with concepts from this ontology (if parameter scored=true). Therefore, score represents the most accurate ontology to annotate the given text.
|-valign="top"
|width="10%"|'''annotations'''
|width="90%"| ObrAnnotationBean/ObrAnnotationBeanDetailled is a representation of one annotation. If ''elementDetails'' parameter is true the service return response of type ObrAnnotationBean ,otherwise ObrAnnotationBeanDetailled. An annotation has a score which represents the accuracy of the annotation computed by the scoring algorithm (if the scored=true parameter was chosen, otherwise score=-1). An annotation is done with a concept in a context.

'''Response Content: ObrAnnotationBeanDetailled'''

Response ObrAnnotationBeanDetailled contains all the contents of ObrAnnotationBean. Those contents are described in section Response Content: ObrAnnotationBean.

Following are remaining contents for ObrAnnotationBeanDetailled :

{| border="2" 

|-valign="top"
|width="10%"|'''element'''
|width="90%"|
* ''localElementID'' - Global identifier for the resource element.
* ''elementStructure'' - Represents Structure of an element for a given resource.

'''Response Content: Structure'''

{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|resource identifier for Resource.

|-valign="top"
|width="10%"|'''contexts'''
|width="90%"|list of context for resource.

|-valign="top"
|width="10%"|'''itemKeys'''
|width="90%"|list of itemKeys for resource.

|-valign="top"
|width="10%"|'''weights'''
|width="90%"|map contain weights (as double) for each context (as String).

|-valign="top"
|width="10%"|'''ontoIDs'''
|width="90%"|map contain ontologyIDs for each context (as String).
|}

|}

'''Response Content: ObrAnnotationBean'''

{| border="2" 
|-valign="top"
|width="10%"|'''localElementID'''
|width="90%"| Identifier for resource element.
|-valign="top"
|width="10%"|'''score'''
|width="90%"|
|-valign="top"
|width="10%"|'''concept'''
|width="90%"|
* ''localConceptId'' - global identifier for the concept in its original repository.
* ''localOntologyId'' - identifier for the ontology in which the concept is defined.
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology.
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository).
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred.
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999).
|-valign="top"
|width="10%"|'''context'''
|width="90%"| Context specifies if it is a direct or expanded annotation and give precision about the origin of the annotation. ''contextName'' identifies the type of context. The context properties vary with the type of concept. There are 3 possible contexts identified by their contextName:
{| border="2" style="background:#ABCDEF;" 
|-valign="top"
|width="10%"|'''MGREP'''
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A Mgrep context has 3 properties:
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.
|-valign="top"
|width="10%"|'''ISA_CLOSURE'''
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:
* ''childConceptId'' - the concept from which the annotation was derived.
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.
* For example, if a direct annotation with NCI/C0025202 (melanoma) was done, the is_a transitive closure component may expand it to another annotation with NCI/C1302746 (Melanocytic Neoplasm) because the latter is a direct parent (i.e., level 1) concept of the former. The ISA_CLOSURE annotation generated will have the following properties {NCI/C0025202, 1}.
|-valign="top"
|width="10%"|'''MAPPING'''
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties:
* mappedConceptId identifies the concept from which the annotation was derived.
* mappingType specifies the type of mapping.
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.
|}
|}

|-valign="top"
|width="10%"|'''localElementID localConceptIDs mode withContext elementDetails counts offsetStart offsetMax'''
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Resource Index Restlet service. Those parameters are described in section Service parameters

|}

===GET calls===
Following section describes all other simplified GET services available in Resource_Index_API.

====Annotation by Concept Service====
Returns the set of annotations done with a given localConceptID.

*GET Request Format : '''/byconcept/{ontologyid}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/42693/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/{ontologyID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/{ontologyID}/{conceptID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled. If request parameter withContext is true, then returns representation of the ObrResultBeanDetailled and if request parameter withContext is false, then returns representation of the ObrResultBean.

====Annotation for BioPortal virtual ontology Concept Service ====
Returns the set of all annotations done with a given localConceptID using BioPortal virtual ontology ID.

*GET Request Format : '''/byconcept/virtual/{virtualOntologyID}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/virtual/1032/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/virtual/{virtualOntologyID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/virtual/{virtualOntologyID}/{conceptID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation By Concept And Resource Service ====
Returns the set of all annotations done with a given localConceptID for given resourceID.

*GET Request Format : '''/byconcept/{ontologyid}/{resourceid}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/42693/AE/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/{ontologyID}/{resourceID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/{ontologyID}/{conceptID}/{resourceID}/{withContext}/{counts}/{from}/{number}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation for BioPortal virtual ontology Concept And Resource Service ====
Returns the set of all annotations done with a given localConceptID using BioPortal virtual ontology ID and using particular resourceID.

*GET Request Format : '''/byconcept/virtual/{virtualOntologyID}/{resourceid}/{withContext}/{counts}/{from}/{number}?conceptid={conceptid}'''
*Example : http://rest.bioontology.org/resource_index/byconcept/virtual/1032/AE/false/true/0/10?conceptid=Melanoma&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byconcept/virtual/{virtualOntologyID}/{resourceID}/{withContext}/{counts}/{from}/{number}?conceptID={conceptID}
**/byconcept/virtual/{virtualOntologyID}/{conceptID}/{resourceID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation By Resource Element Service ====
Returns the set of all annotations done with a given resource element localElementID for all the concepts.

*GET Request Format : '''/byelement/{resourceid}/{withContext}/{counts}/{from}/{number}?elementid={elementid}'''
*Example : http://rest.bioontology.org/resource_index/byelement/AE/true/false/0/10?elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/byelement/{resourceID}/{withContext}/{counts}/{from}/{number}?elementID={localElementID}
**/byelement/{resourceID}/{localElementID}/{withContext}/{counts}/{from}/{number}

*Response Content : ObrResultBean/ObrResultBeanDetailled.

====Annotation Details By Resource Element Service ====
Returns the set of all annotations details with a given resource element localElementID for given conceptID

*GET Request Format : '''/details/{elementDetails}/concept/{ontologyid}/resource/{resourceid}?conceptid={conceptid}&elementid={elementid}'''
*Example1 : http://rest.bioontology.org/resource_index/details/true/concept/42693/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Example1 : http://rest.bioontology.org/resource_index/details/false/concept/42693/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/details/{elementDetails}/concept/{ontologyID}/resource/{resourceID}?conceptID={conceptID}&elementID={localElementID}
**/details/{elementDetails}/concept/{ontologyID}/{conceptID}/resource/{resourceID}/element/{localElementID}

*Response Content : ObrAnnotationBeanDetailled if elementDetails is true otherwise ObrAnnotationBean

====Annotation Details By Resource Element Service for BioPortal Virtual OntologyID====
Returns the set of all annotations details with a given resource element localElementID for given conceptID of BioPortal virtual ontologyID

*GET Request Format : '''/details/{elementDetails}/virtual/concept/{virtualOntologyID}/resource/{resourceid}?conceptid={conceptid}&elementid={elementid}'''
*Example1 : http://rest.bioontology.org/resource_index/details/true/virtual/concept/1032/Melanoma/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Example2 : http://rest.bioontology.org/resource_index/details/false/virtual/concept/1032/npo:Nanoparticle/resource/AE?conceptid=Melanoma&elementid=E-GEOD-18509&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* :
**/details/{elementDetails}/virtual/concept/{virtualOntologyID}/resource/{resourceID}?conceptID={conceptID}&elementID={localElementID}
**/details/{elementDetails}/virtual/concept/{virtualOntologyID}/{conceptID}/resource/{resourceID}/element/{localElementID}

*Response Content : ObrAnnotationBeanDetailled if elementDetails is true otherwise ObrAnnotationBean.

====Resources Service ====
Returns the set of all resources available in resource index and information related to it.

*GET Request Format : ''/resources''
*Example: http://rest.bioontology.org/resource_index/resources?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource is a representation of one resource
'''Response Content: Resource'''

{| border="2" 
|-valign="top"
|width="10%"|'''resourceName'''
|width="90%"| Name of the particular resource.

|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"| Identifier of the resource.

|-valign="top"
|width="10%"|'''mainContext'''
|width="90%"| Main context string for the resource.

|-valign="top"
|width="10%"|'''resourceURL'''
|width="90%"| Website URL for the resource

|-valign="top"
|width="10%"|'''resourceElementURL'''
|width="90%"| Base URL for getting elements for resource.

|-valign="top"
|width="10%"|'''resourceDescription'''
|width="90%"| Description of the resource.

|-valign="top"
|width="10%"|'''resourceLogo'''
|width="90%"| URL of logo image for the resource.

|-valign="top"
|width="10%"|'''resourceStructure'''
|width="90%"| Represents Structure of an element for the resource.

'''Response Content: Structure'''

{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|resource identifier for Resource.

|-valign="top"
|width="10%"|'''contexts'''
|width="90%"|list of context for resource.

|-valign="top"
|width="10%"|'''itemKeys'''
|width="90%"|list of itemKeys for resource.

|-valign="top"
|width="10%"|'''weights'''
|width="90%"|map contain weights (as double) for each context (as String).

|-valign="top"
|width="10%"|'''ontoIDs'''
|width="90%"|map contain ontologyIDs for each context (as String).
|}

|}

====Resource Service ====
Returns the resource in resource index for given resourceID and information related to it.

*GET Request Format : ''/resources/{resourceid}''
*Example: http://rest.bioontology.org/resource_index/resources/AE?email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /resources/{resourceID}
*Response Content : Resource.

====Resource Element Service ====
Service returns elementURL for given localElementID and redirect it to get resource element on the web.

*GET Request Format : ''/element/{resourceid}?elementid={elementid}''
*Example: http://rest.bioontology.org/resource_index/element/AE?elementid=E-GEOD-9118&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /element/{resourceID}?element={localElementID}
*Response Content : Web page containing details of the element.

====Resources Service with ontologies used for indexing ====
Returns the set of all resources available in resource index and list of onotolgies used for indexing them.

*GET Request Format : ''/resources?withontologies=true''
*Example: http://rest.bioontology.org/resource_index/resources?withontologies=true&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format* : /resources?withOntologies=true
*Response Content : ObrResourceBean is a representation of one resource with ontologies
'''Response Content: ObrResourceBean'''

Response ObrResourceBean contains all the contents of Resource. Those contents are described in section ''Response Content: Resource''.

Following are remaining contents for ObrResourceBean :

{| border="2" 
|-valign="top"
|width="10%"|'''ontologiesUsed'''
|width="90%"| Presents list of ontologies used for indexing. Each ontology of type OntologyBean.
'''Response Content: OntologyBean'''
{| border="2" style="background:#ABCDEF;"
|-valign="top"
|width="10%"|'''localOntologyID'''
|width="90%"|Local onotology id for Ontology.

|-valign="top"
|width="10%"|'''ontologyName'''
|width="90%"|name of the resource.

|-valign="top"
|width="10%"|'''ontologyVersion'''
|width="90%"|version number for resource.

|-valign="top"
|width="10%"|'''virtualOntologyID'''
|width="90%"|virtual ontology id for ontology.
|}
|}

====Resource Service with ontologies used for indexing ====
Returns the information about resources and list of onotolgies used for indexing it.

*GET Request Format : ''/resources/{resourceid}?withontologies=true''
*Example: http://rest.bioontology.org/resource_index/resources/AE?withOntologies=true&email=example@bioontology.org&applicationid=NCBOtest
*Old Request Format : /resources/{resourceID}?withOntologies=true
*Response Content : Resource is represented by ObrResourceBean.

====Ontologies Service with resources indexed ====
Returns the set of all ontologies used in resource index with list of resources indexed by given ontology.

*GET Request Format : ''/ontologies?withresources=true''
*Example: http://rest.bioontology.org/resource_index/ontologies?withresources=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Each Ontology is represented by ObrOntologyBean.

Response ObrOntologyBean contains all the contents of OntologyBean.Those contents are described in section Response Content: OntologyBean.

Following are remaining contents for ObrResourceBean :
{| border="2" 
|-valign="top"
|width="10%"|'''resources'''
|width="90%"| Represents list of resources. Response content for each resource is of type Resource.
|}

====Ontology Service with resources indexed ====
Returns the information about given ontologies used in resource index with list of resources.

*GET Request Format : ''/ontologies/{ontologyid}''
*Example: http://rest.bioontology.org/resource_index/ontologies/42693?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Ontology is represented by ObrOntologyBean.

====All Statistics Service====
Returns the information about number of all the annotations done in resource index.

*GET Request Format : ''/statistics/all''
*Example: http://rest.bioontology.org/resource_index/statistics/all?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : All annotations represented by ObrStatisticsBean.

'''Response Content: ObrStatisticsBean'''
Following are remaining contents for ObrStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''aggregatedAnnotations'''
|width="90%"|Sum of the number of rows in all the indexing tables

|-valign="top"
|width="10%"|'''mgrepAnnotations'''
|width="90%"|Number of mgrep annotations entries in direct annotation table.

|-valign="top"
|width="10%"|'''reportedAnnotations'''
|width="90%"|Number of reported annotations entries in direct annotation table.

|-valign="top"
|width="10%"|'''isaAnnotations'''
|width="90%"|Number of is-a annotations entries in extended annotation table.

|-valign="top"
|width="10%"|'''mappingAnnotations'''
|width="90%"|Number of mapping annotations entries in extended annotation table.

|}

====Ontology Statistics Service====
Returns the total statistics for given ontology for All resources.

*GET Request Format : ''/statistics/ontology/{ontologyid}''
*Example: http://rest.bioontology.org/resource_index/statistics/ontology/42693?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Ontology statistics with format ObrOntologyStatisticsBean.

'''Response Content: ObrOntologyStatisticsBean'''
Following are contents for ObrOntologyStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''resourceID'''
|width="90%"|Resource Id for resource.

|-valign="top"
|width="10%"|'''statistics'''
|width="90%"|ObrStatisticsBean is a representation of statistics

|}

====Ontology Statistics Service by resources====
Returns the statistics for given ontology for each resource separately.

*GET Request Format : ''/statistics/ontology/{onotlogyid}?byresource=true''
*Example: http://rest.bioontology.org/resource_index/statistics/ontology/42693?byresource=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : ObrOntologyStatisticsBean

====Resource Statistics Service====
Returns the total statistics for given resource for All ontology.

*GET Request Format : ''/statistics/resource/{resourceid}''
*Example: http://rest.bioontology.org/resource_index/statistics/resource/CANANO?email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource statistics with format ObrResourceStatisticsBean.

'''Response Content: ObrResourceStatisticsBean'''
Following are contents for ObrResourceStatisticsBean:
{| border="2" 
|-valign="top"
|width="10%"|'''localOntologyID'''
|width="90%"|local ontology id for given ontology.

|-valign="top"
|width="10%"|'''statistics'''
|width="90%"|ObrStatisticsBean is a representation of statistics

|}

====Resource Statistics Service by ontologies====
Returns the statistics for given resource for each ontology separately.

*GET Request Format : ''/statistics/resource/{resourceid}?byontology=true ''
*Example: http://rest.bioontology.org/resource_index/statistics/resource/AE?byontology=true&email=example@bioontology.org&applicationid=NCBOtest

*Response Content : Resource statistics with format ObrResourceStatisticsBean.

----
'''Note* :''' ''Old Request Format not working anymore.''

----

File:OBR index creation resources.png

2010-04-28T19:57:49Z

Jonquet: uploaded a new version of "Image:OBR index creation resources.png"

NCBO Biomedical Resource Index creation

Resource Index

2010-04-28T19:56:25Z

Jonquet:

''Indexing biomedical resources with ontology concepts ''

=== Presentation & Demonstration ===

The range of publicly available biomedical data is enormous and is expanding fast. This expansion means that researchers now face a hurdle to extracting the data they need from the large numbers of data that are available. Biomedical researchers have turned to ontologies and terminologies to structure and annotate their data with ontology concepts for better search and retrieval.

Using the annotation workflow of the [[Annotator_Web_service|Annotator Web Service]] NCBO has built an biomedical resources index in which biomedical data is indexed by ontology concepts. The index allows a user to search for biomedical data based on ontology concepts. The NCBO Resource Index is directly queriable in the [http://bioportal.bioontology.org BioPortal] ontology repository: when a user browses a given concept, he has access (link) to the list of resource elements that have been annotated with this concept. A user can also search for resources direclty using the 'All resources' tab.

In the NCBO Resource Index, we have processed the textual metadata of elements from several biomedical resources such as: [http://www.ebi.ac.uk/arrayexpress/ ArrayExpress], [http://clinicaltrials.gov/ Clinical Trials.gov], [http://goldminer.arrs.org GoldMiner], [http://www.ncbi.nlm.nih.gov/geo/ Gene Expression Omnibus (GEO)] and others. The annotations in the index keeps track of the structures of elements that have been annotated i.e., from which part of the element (e.g., title, description) an annotation has been produced. This information is used to score annotations.

[[Image:NCBO_Resource_Index_workflow.png|thumb|NCBO Resource Index workflow]]

[[Image:OBR_index_creation_resources.png|thumb|NCBO Resource Index creation]]

Please try the [http://bioportal.bioontology.org/resources NCBO Resource Index] in BioPortal.

=== Contacts ===

*For questions or feature requests, contact [mailto:support@bioontology.org?subject=NCBO%20Resources%20Index%20support Support]

=== Documentation ===

* [[Resource Index REST Web Service User Guide]]

* [http://rest.bioontology.org/resource_index/resources/list/ Currently available resource list.]

* Resource index design and underlying data model (see the bottom image on the right) [[Image:OBR_result_model.png|thumb| NCBO Resource Index data model]]

* [[Processing_OBR_Resources]] - Notes on resources being processed - Developers only.

* [[Populating_OBS_database]] - Notes on the population of the NCBO Resource Index DB used in the annotation workflow - Developers only.

* [https://bmir-gforge.stanford.edu/gf/project/obs/ Corresponding Gforge project] - Developers only.

=== References ===

* Clement Jonquet, Mark A. Musen and Nigam H. Shah, '''A System for Ontology-Based Annotation of Biomedical Data''', ''In A. Bairoch, S. Cohen-Boulakia and C. Froidevaux (eds): International Workshop on Data Integration in The Life Sciences 2008, DILS'08,'' Vol. 5109, Lecture Notes in BioInformatics, p.144-152, Springer-Verlag, June 2008, Evry, France. [http://dils2008.lri.fr/ conference's web site] [http://www.stanford.edu/~jonquet/Publications/Documents/Article-DILS08_Jonquet_Musen_Shah_published.pdf pdf - 431Kb]

* Nigam H. Shah, Clement Jonquet, Annie P. Chiang, Atul J. Butte, Rong Chen, Mark A. Musen, '''Ontology-driven Indexing of Public Datasets for Translational Bioinformatics''', ''BMC Bioinformatics'', Vol. 10, February 2009. [http://www.biomedcentral.com/bmcbioinformatics/ journal's web site] [http://www.stanford.edu/~jonquet/Publications/Documents/Article-BMCBioInformatics08-Shah-Jonquet-Ontolgy-based_Indexing.pdf pdf - 651 Kb]

=== Versions (prototypes & releases) ===

* February 2009 - New prototype release (v1.2). API: http://obs.bioontology.org/obr/OBR_v1.2_rest.html

* March 2008 - First prototype (v1 and v1.1) API: http://ncbolabs-dev2.stanford.edu:8080/Ontrez_v1_API/ - not maintained anymore, please do not use.

* December 2008 - API specification for the new prototype (v1.2) - not maintained anymore, please do not use.

=== Collaboration & Acknowledgment ===

* The annotation workflow used to create the NCBO Resource Index uses Mgrep in the concept recognition step. We acknowledge the assistance of Manhong Dai and Fan Meng from the [http://portal.ncibi.org/gateway/ National Center for Integrative Biomedical Informatics] (NCIBI).

* The user interface for the NCBO Resource Index client in BioPortal (http://bioportal.bioontology.org/all_resources) is designed & developed by NCBO members from [http://www.thechiselgroup.org/ University of Victoria]

2009-11-30T23:21:17Z

Jonquet:

Ontology Recommender Web service

2009-11-30T23:20:35Z

Jonquet: /* Presentation & Demonstration */

''To automatically recommend an ontology to use for semantic annotations''

=== Presentation & Demonstration ===
As the use of ontologies for annotation of biomedical datasets rises, a common question researchers face is that of identifying which ontologies are relevant to annotate their datasets. The number and variety of biomedical ontologies is now quite large and it is cumbersome for a scientist to figure out which ontology to (re)use in their annotation tasks. NCBO develops an ontology recommender service, which informs the user of the most appropriate ontologies relevant for their given dataset. The recommender service uses a semantic annotation based approach and scores the ontologies according to those annotations. The recommender service uses the [[Annotator Web service]] . The prototype service can recommend ontologies from UMLS and the NCBO BioPortal.

[[Image:Recommender_method.png|thumb|NCBO Recommender Web Service workflow]]

Please try the NCBO Recommender Web Service prototype: http://stage.bioontology.org/recommender

=== Contacts ===

* Community & usage: [[mailto:whetzel@stanford.edu Trish Whetzel]]
* Design, utility & applications: [[mailto:nigam@stanford.edu Nigam Shah]] and [[mailto:jonquet@stanford.edu Clement Jonquet]]
* Technical support: [[mailto:jonquet@stanford.edu]]

=== Documentation & References ===

* See also the [[Annotator Web service]] wiki page.

* Please refer to:
** Clement Jonquet, Nigam H. Shah, Mark A. Musen, Prototyping a Biomedical Ontology Recommender Service, Bio-Ontologies: Knowledge in Biology, SIG, ISMBECCB 2009, pp. 65-68, Stockholm, Sweden, July 2009. [http://www.bio-ontologies.org.uk/home.html SIG's web site] [http://www.stanford.edu/~jonquet/Publications/Documents/Article-Bio-Ontologies2009-Jonquet-Shah-Musen.pdf pdf - 152Kb]

=== Versions (prototypes & releases) ===

* November 2009 - Second prototype (v1.1) UI in stage BioPortal http://stage.bioontology.org/recommender

* November 2009 - Second prototype (v1.1) for the recommender: http://obs.bioontology.org/recommender/Recommender1.1.html

* March 2009 - First prototype of UI for the recommender: http://keg.cs.uvic.ca/ncbo/obs/OBARecommender.html

* February 2009 - The first prototype (v0) has been released for testing and evaluation. Please check it out: http://obs.bioontology.org/recommender/Recommender.html

=== Evaluation ===

The original datasets used for evaluating the Recommender 1.1, as well as the recommendations generated are available here: http://obs.bioontology.org/recommender/results/

=== Collaboration & Acknowledgment ===

* The user interface for the recommender serice UI prototype is designed & developed by NCBO members from [http://www.thechiselgroup.org/ University of Victoria]

* We also thank Helen Parkinson (European Biomedical Institute), Stephen Granite (Johns Hopkins University) and Wei-Nchih Lee (Stanford University) for the help in the Recommender (version 1.1) evaluation.

Ontology Recommender Web service

2009-11-24T17:06:49Z

Jonquet: /* Versions (prototypes & releases) */

''To automatically recommend an ontology to use for semantic annotations''

=== Presentation & Demonstration ===
As the use of ontologies for annotation of biomedical datasets rises, a common question researchers face is that of identifying which ontologies are relevant to annotate their datasets. The number and variety of biomedical ontologies is now quite large and it is cumbersome for a scientist to figure out which ontology to (re)use in their annotation tasks. NCBO develops an ontology recommender service, which informs the user of the most appropriate ontologies relevant for their given dataset. The recommender service uses a semantic annotation based approach and scores the ontologies according to those annotations. The recommender service uses the [[Annotator Web service]] . The prototype service can recommend ontologies from UMLS and the NCBO BioPortal.

Please try the NCBO Ontology Recommender service prototype: http://keg.cs.uvic.ca/ncbo/obs/OBARecommender.html.

=== Contacts ===

* Community & usage: [[mailto:whetzel@stanford.edu Trish Whetzel]]
* Design, utility & applications: [[mailto:nigam@stanford.edu Nigam Shah]] and [[mailto:jonquet@stanford.edu Clement Jonquet]]
* Technical support: [[mailto:jonquet@stanford.edu]]

=== Documentation & References ===

* See also the [[Annotator Web service]] wiki page.

* Please refer to:
** Clement Jonquet, Nigam H. Shah, Mark A. Musen, Prototyping a Biomedical Ontology Recommender Service, Bio-Ontologies: Knowledge in Biology, SIG, ISMBECCB 2009, pp. 65-68, Stockholm, Sweden, July 2009. [http://www.bio-ontologies.org.uk/home.html SIG's web site] [http://www.stanford.edu/~jonquet/Publications/Documents/Article-Bio-Ontologies2009-Jonquet-Shah-Musen.pdf pdf - 152Kb]

=== Versions (prototypes & releases) ===

* November 2009 - Second prototype (v1.1) UI in stage BioPortal http://stage.bioontology.org/recommender

* November 2009 - Second prototype (v1.1) for the recommender: http://obs.bioontology.org/recommender/Recommender1.1.html

* March 2009 - First prototype of UI for the recommender: http://keg.cs.uvic.ca/ncbo/obs/OBARecommender.html

* February 2009 - The first prototype (v0) has been released for testing and evaluation. Please check it out: http://obs.bioontology.org/recommender/Recommender.html

=== Evaluation ===

The original datasets used for evaluating the Recommender 1.1, as well as the recommendations generated are available here: http://obs.bioontology.org/recommender/results/

=== Collaboration & Acknowledgment ===

* The user interface for the recommender serice UI prototype is designed & developed by NCBO members from [http://www.thechiselgroup.org/ University of Victoria]

* We also thank Helen Parkinson (European Biomedical Institute), Stephen Granite (Johns Hopkins University) and Wei-Nchih Lee (Stanford University) for the help in the Recommender (version 1.1) evaluation.

Ontology Recommender Web service

2009-11-19T00:14:43Z

Jonquet:

''To automatically recommend an ontology to use for semantic annotations''

=== Presentation & Demonstration ===
As the use of ontologies for annotation of biomedical datasets rises, a common question researchers face is that of identifying which ontologies are relevant to annotate their datasets. The number and variety of biomedical ontologies is now quite large and it is cumbersome for a scientist to figure out which ontology to (re)use in their annotation tasks. NCBO develops an ontology recommender service, which informs the user of the most appropriate ontologies relevant for their given dataset. The recommender service uses a semantic annotation based approach and scores the ontologies according to those annotations. The recommender service uses the [[Annotator Web service]] . The prototype service can recommend ontologies from UMLS and the NCBO BioPortal.

Please try the NCBO Ontology Recommender service prototype: http://keg.cs.uvic.ca/ncbo/obs/OBARecommender.html.

=== Contacts ===

* Community & usage: [[mailto:whetzel@stanford.edu Trish Whetzel]]
* Design, utility & applications: [[mailto:nigam@stanford.edu Nigam Shah]] and [[mailto:jonquet@stanford.edu Clement Jonquet]]
* Technical support: [[mailto:jonquet@stanford.edu]]

=== Documentation & References ===

* See also the [[Annotator Web service]] wiki page.

* Please refer to:
** Clement Jonquet, Nigam H. Shah, Mark A. Musen, Prototyping a Biomedical Ontology Recommender Service, Bio-Ontologies: Knowledge in Biology, SIG, ISMBECCB 2009, pp. 65-68, Stockholm, Sweden, July 2009. [http://www.bio-ontologies.org.uk/home.html SIG's web site] [http://www.stanford.edu/~jonquet/Publications/Documents/Article-Bio-Ontologies2009-Jonquet-Shah-Musen.pdf pdf - 152Kb]

=== Versions (prototypes & releases) ===

* November 2009 - Second prototype (v1.1) for the recommender: http://obs.bioontology.org/recommender/Recommender1.1.html

* March 2009 - First prototype of UI for the recommender: http://keg.cs.uvic.ca/ncbo/obs/OBARecommender.html

* February 2009 - The first prototype (v0) has been released for testing and evaluation. Please check it out: http://obs.bioontology.org/recommender/Recommender.html

=== Evaluation ===

The original datasets used for evaluating the Recommender 1.1, as well as the recommendations generated are available here: http://obs.bioontology.org/recommender/results/

=== Collaboration & Acknowledgment ===

* The user interface for the recommender serice UI prototype is designed & developed by NCBO members from [http://www.thechiselgroup.org/ University of Victoria]

* We also thank Helen Parkinson (European Biomedical Institute), Stephen Granite (Johns Hopkins University) and Wei-Nchih Lee (Stanford University) for the help in the Recommender (version 1.1) evaluation.

Ontology Recommender Web service

2009-11-19T00:12:45Z

Jonquet: /* Collaboration & Acknowledgment */

''To automatically recommend an ontology to use for semantic annotations''

=== Presentation & Demonstration ===
As the use of ontologies for annotation of biomedical datasets rises, a common question researchers face is that of identifying which ontologies are relevant to annotate their datasets. The number and variety of biomedical ontologies is now quite large and it is cumbersome for a scientist to figure out which ontology to (re)use in their annotation tasks. NCBO develops an ontology recommender service, which informs the user of the most appropriate ontologies relevant for their given dataset. The recommender service uses a semantic annotation based approach and scores the ontologies according to those annotations. The recommender service uses the [[Annotator Web service]] . The prototype service can recommend ontologies from UMLS and the NCBO BioPortal.

Please try the NCBO Ontology Recommender service prototype: http://keg.cs.uvic.ca/ncbo/obs/OBARecommender.html.

=== Contacts ===

* Community & usage: [[mailto:whetzel@stanford.edu Trish Whetzel]]
* Design, utility & applications: [[mailto:nigam@stanford.edu Nigam Shah]] and [[mailto:jonquet@stanford.edu Clement Jonquet]]
* Technical support: [[mailto:jonquet@stanford.edu]]

=== Documentation & References ===

* See also the [[Annotator Web service]] wiki page.

* Please refer to:
** Clement Jonquet, Nigam H. Shah, Mark A. Musen, Prototyping a Biomedical Ontology Recommender Service, Bio-Ontologies: Knowledge in Biology, SIG, ISMBECCB 2009, pp. 65-68, Stockholm, Sweden, July 2009. [http://www.bio-ontologies.org.uk/home.html SIG's web site] [http://www.stanford.edu/~jonquet/Publications/Documents/Article-Bio-Ontologies2009-Jonquet-Shah-Musen.pdf pdf - 152Kb]

=== Versions (prototypes & releases) ===

* November 2009 - Second prototype (v1.1) for the recommender: http://obs.bioontology.org/recommender/Recommender1.1.html

* March 2009 - First prototype of UI for the recommender: http://keg.cs.uvic.ca/ncbo/obs/OBARecommender.html

* February 2009 - The first prototype (v0) has been released for testing and evaluation. Please check it out: http://obs.bioontology.org/recommender/Recommender.html

=== Collaboration & Acknowledgment ===

* The user interface for the recommender serice UI prototype is designed & developed by NCBO members from [http://www.thechiselgroup.org/ University of Victoria]

* We also thank Helen Parkinson (European Biomedical Institute), Stephen Granite (Johns Hopkins University) and Wei-Nchih Lee (Stanford University) for the help in the Recommender (version 1.1) evaluation.

Annotator Web service

2009-11-13T20:52:19Z

Jonquet: /* Versions (prototypes & releases) */

''To automatically process a piece of data text to annotate it with relevant ontology concepts and return the annotations
''

=== Presentation & Demonstration ===

The range of publicly available biomedical data is enormous and is expanding fast. This expansion means that researchers now face a hurdle to extracting the data they need from the large numbers of data that are available. Biomedical researchers have turned to ontologies and terminologies to structure and annotate their data with ontology concepts for better search and retrieval. However, this annotation process cannot be easily automated and often requires expert curators. Plus, there is a lack of easy-to-use systems that facilitate the use of ontologies for annotation. The NCBO Annotator (or Open Biomedical Annotator (OBA)) is an ontology-based Web service that annotates public datasets with biomedical ontology concepts based on their textual metadata. The biomedical community can use the annotator service to tag thier data automatically with ontology concepts. These concepts come from the [http://www.nlm.nih.gov/research/umls/ Unified Medical Language System (UMLS) Metathesaurus] and the [http://bioportal.bioontology.org/ National Center for Biomedical Ontology (NCBO) BioPortal] ontologies. Such annotations facilitate translational discoveries by integrating annotated data.

[[Image:OBA_service_workflow.png|thumb|NCBO Annotator Web service workflow]]

Please try the [http://bioportal.bioontology.org/annotate NCBO Annotator service in BioPortal].

=== Contacts ===

* For questions or feature requests, contact [mailto:support@bioontology.org?subject=Annotator%20help%20request Support]

=== Documentation & References ===

* Annotator REST Web Service User Guide [[Annotator_User_Guide | Annotator User Guide]]

* Annotator REST Web Service client examples [[Annotator_Client_Examples | Annotator Client Examples]]

* Annotator Design and underlying Data model: [http://obs.bioontology.org/docs/oba/OBA_v1.1_documentation.htm Documentation here]... to be move to the wiki soon.

* Please refer to:
** Clement Jonquet, Nigam H. Shah, Mark A. Musen, '''The Open Biomedical Annotator''', ''AMIA Summit on Translational Bioinformatics'', p. 56-60, March 2009, San Francisco, CA, USA. [http://summit2009.amia.org/ conference's web site] [http://www.stanford.edu/~jonquet/Publications/Documents/Article-AmiaSTB09_Jonquet_Shah_Musen.pdf pdf - 201Kb]

=== Versions (prototypes & releases) ===

* November 2009 - Second prototype including Mmtx: [http://obs.bioontology.org/oba/OBA_v1.2_rest.html]

* April 2009 - First production release in BioPortal 2.1

* March 2009 - Prototype user interface has been deployed on the BioPortal staging server.

* October 2008 - The prototype (v1.1) has bee released for testing and evaluation. The prototype is still available but please don't use it anymore: [http://obs.bioontology.org/oba/OBA_v1.1_rest.html]

* May 2008 - First prototype (v1.0) - Has been removed from servers.

=== Community ===

After eight months of existence the NCBO Annotator counts already eight academic groups including UCSF, University of Indiana and the Jackson Laboratory that use and experiment the service in specific scenarios. Internally, we have used the annotation workflow to index biomedical data resources with ontology concepts (cf. [[Resource_Index]]).

Learn more about NCBO Annotator users & use cases: [[NCBO Annotator community]]

=== Collaboration & Acknowledgment ===

* The NCBO Annotator service uses Mgrep in the concept recognition step. We acknowledge the assistance of Manhong Dai and Fan Meng from the [http://portal.ncibi.org/gateway/ National Center for Integrative Biomedical Informatics] (NCIBI).

* The user interface for the Annotator client in BioPortal (http://bioportal.bioontology.org/annotate) is designed & developed by NCBO members from [http://www.thechiselgroup.org/ University of Victoria]

Ontology Recommender Web service

2009-11-11T03:01:19Z

Jonquet: /* Versions (prototypes & releases) */

''To automatically recommend an ontology to use for semantic annotations''

=== Presentation & Demonstration ===
As the use of ontologies for annotation of biomedical datasets rises, a common question researchers face is that of identifying which ontologies are relevant to annotate their datasets. The number and variety of biomedical ontologies is now quite large and it is cumbersome for a scientist to figure out which ontology to (re)use in their annotation tasks. NCBO develops an ontology recommender service, which informs the user of the most appropriate ontologies relevant for their given dataset. The recommender service uses a semantic annotation based approach and scores the ontologies according to those annotations. The recommender service uses the [[Annotator Web service]] . The prototype service can recommend ontologies from UMLS and the NCBO BioPortal.

Please try the NCBO Ontology Recommender service prototype: http://keg.cs.uvic.ca/ncbo/obs/OBARecommender.html.

=== Contacts ===

* Community & usage: [[mailto:whetzel@stanford.edu Trish Whetzel]]
* Design, utility & applications: [[mailto:nigam@stanford.edu Nigam Shah]] and [[mailto:jonquet@stanford.edu Clement Jonquet]]
* Technical support: [[mailto:jonquet@stanford.edu]]

=== Documentation & References ===

* See also the [[Annotator Web service]] wiki page.

* Please refer to:
** Clement Jonquet, Nigam H. Shah, Mark A. Musen, Prototyping a Biomedical Ontology Recommender Service, Bio-Ontologies: Knowledge in Biology, SIG, ISMBECCB 2009, pp. 65-68, Stockholm, Sweden, July 2009. [http://www.bio-ontologies.org.uk/home.html SIG's web site] [http://www.stanford.edu/~jonquet/Publications/Documents/Article-Bio-Ontologies2009-Jonquet-Shah-Musen.pdf pdf - 152Kb]

=== Versions (prototypes & releases) ===

* November 2009 - Second prototype (v1.1) for the recommender: http://obs.bioontology.org/recommender/Recommender1.1.html

* March 2009 - First prototype of UI for the recommender: http://keg.cs.uvic.ca/ncbo/obs/OBARecommender.html

* February 2009 - The first prototype (v0) has been released for testing and evaluation. Please check it out: http://obs.bioontology.org/recommender/Recommender.html

=== Collaboration & Acknowledgment ===

* The user interface for the recommender serice UI prototype is designed & developed by NCBO members from [http://www.thechiselgroup.org/ University of Victoria]

File:OBR index creation resources.png

2009-11-06T22:28:18Z

Jonquet: uploaded a new version of "Image:OBR index creation resources.png"

NCBO Biomedical Resource Index creation

File:OBA service workflow.png

2009-10-20T16:22:23Z

Jonquet: uploaded a new version of "Image:OBA service workflow.png"

First, direct annotations are created from raw text based on syntactic concept recognition according to a dictionary that use terms (concept names and synonyms) from both UMLS and NCBO ontologies. Second, different components expand the first set of annotations using ontologies semantics.

Resource Index

2009-10-16T20:20:54Z

Jonquet: /* Presentation & Demonstration */

''Indexing biomedical resources with ontology concepts thanks to semantic annotations ''

=== Presentation & Demonstration ===

The range of publicly available biomedical data is enormous and is expanding fast. This expansion means that researchers now face a hurdle to extracting the data they need from the large numbers of data that are available. Biomedical researchers have turned to ontologies and terminologies to structure and annotate their data with ontology concepts for better search and retrieval.

Using the annotation workflow of the [[Annotator_Web_service]] NCBO has built an biomedical resources index in which biomedical data is indexed by ontology concepts. The index allows a user to search for biomedical data based on ontology concepts. The NCBO Resource Index is directly queriable in the [[http://bioportal.bioontology.org BioPortal]] ontology repository: when a user browses a given concept, he has access (link) to the list of resource elements that have been annotated with this concept. A user can also search for resources direclty using the 'All resources' tab.

In the OBR index, we have processed the textual metadata of elements from several biomedical resources such as: [http://www.ebi.ac.uk/arrayexpress/ ArrayExpress], [http://clinicaltrials.gov/ Clinical Trials.gov], [http://goldminer.arrs.org GoldMiner], [http://www.ncbi.nlm.nih.gov/geo/ Gene Expression Omnibus (GEO)] and others. The annotations in the index keeps track of the structures of elements that have been annotated i.e., from which part of the element (e.g., title, description) an annotation has been produced. This information is used to score annotations.

[[Image:NCBO_BRI_workflow.png|thumb|NCBO Biomedical Resources Index workflow]]

[[Image:OBR_index_creation_resources.png|thumb|NCBO Biomedical Resources Index creation]]

Please try the [NCBO Biomedical Resource Index in BioPortal http://bioportal.bioontology.org/all_resources].

=== Contacts ===

*For questions or feature requests, contact [mailto:support@bioontology.org?subject=NCBO%20Resources%20Index%20support Support]

=== Documentation & References ===

* [[Resource Index REST Web Service User Guide]]

* [http://rest.bioontology.org/resource_index/resources/list/ Currently available resource list.]

* Resource index design and underlying data model: [http://obs.bioontology.org/docs/obr/OBR_1.2_documentation.htm Documentation here]... to be move and updated to the wiki soon.

* Please refer to:

** Clement Jonquet, Mark A. Musen and Nigam H. Shah, '''A System for Ontology-Based Annotation of Biomedical Data''', ''In A. Bairoch, S. Cohen-Boulakia and C. Froidevaux (eds): International Workshop on Data Integration in The Life Sciences 2008, DILS'08,'' Vol. 5109, Lecture Notes in BioInformatics, p.144-152, Springer-Verlag, June 2008, Evry, France. [http://dils2008.lri.fr/ conference's web site] [http://www.stanford.edu/~jonquet/Publications/Documents/Article-DILS08_Jonquet_Musen_Shah_published.pdf pdf - 431Kb]

** Nigam H. Shah, Clement Jonquet, Annie P. Chiang, Atul J. Butte, Rong Chen, Mark A. Musen, '''Ontology-driven Indexing of Public Datasets for Translational Bioinformatics''', ''BMC Bioinformatics'', Vol. 10, February 2009. [http://www.biomedcentral.com/bmcbioinformatics/ journal's web site] [http://www.stanford.edu/~jonquet/Publications/Documents/Article-BMCBioInformatics08-Shah-Jonquet-Ontolgy-based_Indexing.pdf pdf - 651 Kb]

* [[Processing_OBR_Resources]] - Notes on resources being processed - Developers only.

* [[Populating_OBS_database]] - Notes on the population of the OBS DB used in the annotation workflow - Developers only.

* [https://bmir-gforge.stanford.edu/gf/project/obs/ Corresponding Gforge project] - Developers only.

=== Versions (prototypes & releases) ===

* February 2009 - New prototype release (v1.2). API: http://obs.bioontology.org/obr/OBR_v1.2_rest.html

* March 2008 - First prototype (v1 and v1.1) API: http://ncbolabs-dev2.stanford.edu:8080/Ontrez_v1_API/ - not maintained anymore, please do not use.

* December 2008 - API specification for the new prototype (v1.2) - not maintained anymore, please do not use.

=== Collaboration & Acknowledgment ===

* The annotation workflow used to create the NCBO Biomedical Resource Index uses Mgrep in the concept recognition step. We acknowledge the assistance of Manhong Dai and Fan Meng from the [http://portal.ncibi.org/gateway/ National Center for Integrative Biomedical Informatics] (NCIBI).

* The user interface for the NCBO Biomedical Resource Index client in BioPortal (http://bioportal.bioontology.org/all_resources) is designed & developped by NCBO members from [http://www.thechiselgroup.org/ University of Victoria]

Annotator Web service

2009-10-16T20:19:57Z

Jonquet: /* Community */

''To automatically process a piece of data text to annotate it with relevant ontology concepts and return the annotations
''

=== Presentation & Demonstration ===

The range of publicly available biomedical data is enormous and is expanding fast. This expansion means that researchers now face a hurdle to extracting the data they need from the large numbers of data that are available. Biomedical researchers have turned to ontologies and terminologies to structure and annotate their data with ontology concepts for better search and retrieval. However, this annotation process cannot be easily automated and often requires expert curators. Plus, there is a lack of easy-to-use systems that facilitate the use of ontologies for annotation. The NCBO Annotator (or Open Biomedical Annotator (OBA)) is an ontology-based Web service that annotates public datasets with biomedical ontology concepts based on their textual metadata. The biomedical community can use the annotator service to tag thier data automatically with ontology concepts. These concepts come from the [http://www.nlm.nih.gov/research/umls/ Unified Medical Language System (UMLS) Metathesaurus] and the [http://bioportal.bioontology.org/ National Center for Biomedical Ontology (NCBO) BioPortal] ontologies. Such annotations facilitate translational discoveries by integrating annotated data.

[[Image:OBA_service_workflow.png|thumb|OBA web service workflow]]

Please try the [http://bioportal.bioontology.org/annotate NCBO Annotator service in BioPortal].

=== Contacts ===

* For questions or feature requests, contact [mailto:support@bioontology.org?subject=Annotator%20help%20request Support]

=== Documentation & References ===

* Annotator REST Web Service User Guide [[Annotator_User_Guide | Annotator User Guide]]

* Annotator REST Web Service client examples [[Annotator_Client_Examples | Annotator Client Examples]]

* Annotator Design and underlying Data model: [http://obs.bioontology.org/docs/oba/OBA_v1.1_documentation.htm Documentation here]... to be move to the wiki soon.

* Please refer to:
** Clement Jonquet, Nigam H. Shah, Mark A. Musen, '''The Open Biomedical Annotator''', ''AMIA Summit on Translational Bioinformatics'', p. 56-60, March 2009, San Francisco, CA, USA. [http://summit2009.amia.org/ conference's web site] [http://www.stanford.edu/~jonquet/Publications/Documents/Article-AmiaSTB09_Jonquet_Shah_Musen.pdf pdf - 201Kb]

=== Versions (prototypes & releases) ===

* April 2009 - First production release in BioPortal 2.1

* March 2009 - Prototype user interface has been deployed on the BioPortal staging server.

* October 2008 - The prototype (v1.1) has bee released for testing and evaluation. The prototype is still available but please don't use it anymore: [http://obs.bioontology.org/oba/OBA_v1.1_rest.html]

* May 2008 - First prototype (v1.0) - Has been removed from servers.

=== Community ===

After 8 months of existence OBA counts already 8 academic groups (Univ. of California, San Francisco, Univ. of Indiana, Jackson Lab) that use and experiment the service in specific scenarios. Internally, we have used the annotation workflow to index biomedical data resources with ontology concepts (cf. [[Resource_Index]]).

Learn more about NCBO Annotator users & use cases: [[NCBO Annotator community]]

=== Collaboration & Acknowledgment ===

* The OBA service uses Mgrep in the concept recognition step. We acknowledge the assistance of Manhong Dai and Fan Meng from the [http://portal.ncibi.org/gateway/ National Center for Integrative Biomedical Informatics] (NCIBI).

* The user interface for the annotator client in BioPortal (http://bioportal.bioontology.org/annotate) is designed & developped by NCBO members from [http://www.thechiselgroup.org/ University of Victoria]