https://www.bioontology.org//mediawiki/api.php?action=feedcontributions&feedformat=atom&user=CyounNCBO Wiki - User contributions [en]2026-06-05T12:17:19ZUser contributionsMediaWiki 1.35.9https://www.bioontology.org//mediawiki/index.php?title=BioPortal_2.3_Release_Notes&diff=9755BioPortal 2.3 Release Notes2010-02-24T21:04:59Z<p>Cyoun: /* New features */</p>
<hr />
<div>== New features == <br />
* BioPortal will process SKOS labels for preferred names and synonyms:<br />
** The following is the default property for synonyms: http://www.w3.org/2004/02/skos/core#altLabel<br />
** The following is the default property for preferred name: http://www.w3.org/2004/02/skos/core#prefLabel (rdfs:label otherwise)<br />
* Ontologies used by Annotator & Hierarchy services will now be updated on a regular basis (around every week).<br />
* The filtering of annotation by semantic types is available only for the ontologies which provide that information<br />
* The Annotator scoring function has changed a bit. <br />
* Users can now exclude the annotations created with synonym terms. <br />
* Users can now exclude the annotations less than a certain length. <br />
* There is a change in the concept XML returned by the Annotator service. Please note that the <semanticTypeBean> information is presented differently in <concept>. The Get all terms REST service is also affected.<br />
<pre><br />
<concept><br />
<id>2357621</id><br />
<localConceptId>40399/CDR0000038833</localConceptId><br />
<localOntologyId>40399</localOntologyId><br />
<isTopLevel>0</isTopLevel><br />
<preferredName>melanoma</preferredName><br />
<synonyms><br />
<string>Skin cancer, melanoma</string><br />
<string>melanoma, cutaneous</string><br />
<string>cutaneous melanoma</string><br />
</synonyms><br />
<semanticTypes><br />
<semanticTypeBean><br />
<id>3410411</id><br />
<semanticType>T191</semanticType><br />
<description>Neoplastic Process</description><br />
</semanticTypeBean><br />
<semanticTypeBean><br />
<id>3410007</id><br />
<semanticType>T999</semanticType><br />
<description>NCBO BioPortal concept</description><br />
</semanticTypeBean><br />
</semanticTypes><br />
</concept><br />
</pre><br />
<br />
* There is a change in the mapping context XML returned by the Annotator service. <term>, <from>, <to> information has been added.<br />
<pre><br />
<context class="mappingContextBean"><br />
<contextName>MAPPING</contextName><br />
<isDirect>false</isDirect><br />
<term><br />
<name>Melanoma</name><br />
<localConceptId>42331/Melanoma</localConceptId><br />
<isPreferred>1</isPreferred><br />
<dictionaryId>3</dictionaryId><br />
</term><br />
<from>1</from><br />
<to>8</to><br />
<mappedConceptId>42331/Melanoma</mappedConceptId><br />
<mappingType>Automatic</mappingType><br />
</context><br />
</pre><br />
<br />
<br />
* There is a change in the XML returned by the /obs/ontologies service. The ontologyBean now includes the following output:<br />
<br />
<pre><br />
<ontologyBean><br />
<id>3</id> <br />
<localOntologyId>40571</localOntologyId> <br />
<name>Electrocardiography Ontology</name> <br />
<version>0.1.5</version> <br />
<description /> <br />
<status>28</status> <br />
<virtualOntologyId>1146</virtualOntologyId> <br />
<format>OWL</format> <br />
</ontologyBean><br />
</pre><br />
<br />
* There is a change in the XML returned by the /obs/semanticTypes service. The semanticTypeBean now includes the following output:<br />
<br />
<pre><br />
<semanticTypeBean><br />
<id>1</id> <br />
<semanticType>T000</semanticType> <br />
<description>UMLS concept</description> <br />
</semanticTypeBean><br />
</pre><br />
<br />
* Users can now define target terminologies for RRF ontologies via the BioPortal UI.<br />
* Referencing the tabs on ontology visualization pages in the BioPortal UI is now done using the tab name:<br />
** http://bioportal.bioontology.org/visualize/40644#mappings<br />
<br />
<br />
Please refer to http://www.bioontology.org/wiki/index.php/Annotator_User_Guide for details on Annotator enhancements<br />
<br />
== New way to address UMLS ontologies ==<br />
<br />
We have harmonized the ontologies in the Annotator and BioPortal. The full list is available at: http://rest.bioontology.org/obs/ontologies. This change has implications when using the Annotator with UMLS ontologies.<br />
* Currently, BioPortal (and, therefore, Annotator and Hierarchy services) can use 16 ontologies from UMLS. We will add UMLS ontologies to BioPortal on demand. Please send email to support@bioontology.org to request a specific UMLS ontology to be added to BioPortal. <br />
* UMLS SAB is no longer valid as ontologyId. Please refer to http://bioportal.bioontology.org/ontologies/?filter=UMLS to map your SAB to the corresponding ontology version id. <br />
* UMLS CUIs are no longer valid as conceptId. You can look up the conceptId corresponding to a CUI by using the NCBO search interface (http://bioportal.bioontology.org/search): type in the CUI and check "Include attributes in search". You can also use the search REST service (http://www.bioontology.org/wiki/index.php/BioPortal_REST_services#Search_services) to search for the concept by CUI. We are working on a new concept service that will accept CUI as conceptId in the near future.<br />
<br />
== Known issues ==<br />
* ISA closure in the Annotator and Hierarchy services do not work properly for NCIT and Galen. This will be fixed in an upcoming release.<br />
* Some mappings present in BioPortal are not yet available for use with the Annotator.<br />
<br />
== Other features and bug fixes ==<br />
<br />
* Implemented updates to Hierarchy (OBS Wrapper) Services to conform to the new OBS output XML structure<br />
* Added case sensitivity check for the root concept (per #1793)<br />
* Upgraded the deprecated Acegi Security to Spring Security<br />
* Implemented support for OpenID Authentication<br />
* New lexbig JAR intended to fix the problem with the graph not focused properly when there are 2 ontologies with the same uri.(Bioportal bug #1783)<br />
<br />
== BioPortal UI Internal Features and Bugfixes ==<br />
* Fixed bug in autocomplete drop-downs where they could not distinguish between two ontologies or concepts with the same name.<br />
* New functionality to display messages on the front page with a close button that remembers that users closed the message. Set $FRONT_NOTICE in environment.rb to your desired message in order to display a message.<br />
* Updated language on error messages when attempting to browse individuals/properties.<br />
* Fixed a bug where submiting a remote ontology would trigger an exception because the app was looking for an uploaded file.<br />
* Fixed a bug in URI generation for resources where fixnums were being interpreted as strings without conversion.<br />
* Added a custom logging framework to enable logging to the BioPortal Core.<br />
* Added functionality to hide explore and download links using a global array. This fix is temporary until this information is stored in the ontology metadata.<br />
* A custom Google Analytics ID can now be provided via the environment.rb file.<br />
* If metrics don't exist, the UI now checks prior versions (back through 21 versions, three weeks for ontologies that are updated daily). The user is informed that the metrics are from a previous version and given a link to that version.<br />
* When registering a new account, a check is now made to make sure that the username doesn't already exist.<br />
* Before displaying a link for downloading diffs, the UI now makes sure that the diff is between that ontology and the prior existing ontology. This is to handle cases where an ontology may have been deleted but the record of a diff still exists. (Bug #1389)<br />
* Somehow sorting was removed from the resources on the Resource Index tab. This has been re-enabled.<br />
* Extending the slider on the ontology visualization page now works properly in IE (Bug #1500)<br />
* The BioPortal UI is now using the REST service to gather its list of Groups and related ontologies. In addition, Groups have been added to the ontology summary page. (Bug #1607)<br />
* Fixed a bug where visiting the "Submit new ontology" link on the Browse page while logged out didn't redirect properly once a user logged in (Bug #1486).<br />
* Removed extra characters from search fields on the BioPortal index page (Bug #1390)<br />
* Refactored much of the code in the DataAccess class to implement a common method to store/retrieve objects from the cache and make calls to the BioPortal Core when objects aren't in the cache.<br />
* Exception handling for IO errors due to calls to the back-end that could not be completed. Generally these were improper or unknown concept ids being passed by GoogleBot, but there were some genuine errors that weren't being handled. The user is now informed, via a very basic error message, when a concept can't be found in an existing ontology.<br />
* Added a REST_DOMAIN config option so that we could pass this parameter to Flex apps and have them use the appropriate locations for REST services. Prior to this the Flex apps were hard-coded to use production for many parts of their operation.<br />
* Added a FLEX_URL config option to allow for hosting of Flex apps in different locations.</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=BioPortal_2.3_Release_Notes&diff=9736BioPortal 2.3 Release Notes2010-02-10T23:25:04Z<p>Cyoun: /* New features */</p>
<hr />
<div>== New features == <br />
* BioPortal will process SKOS labels for preferred names and synonyms:<br />
** The following is the default property for synonyms: http://www.w3.org/2004/02/skos/core#altLabel<br />
** The following is the default property for preferred name: http://www.w3.org/2004/02/skos/core#prefLabel (rdfs:label otherwise)<br />
* Ontologies used by Annotator & Hierarchy services will now be updated on a regular basis (around every week).<br />
* The filtering of annotation by semantic types is available only for the ontologies which provide that information<br />
* The Annotator scoring function has changed a bit. <br />
* Users can now exclude the annotations created with synonym terms. <br />
* Users can now exclude the annotations less than a certain length. <br />
* There is a change in the XML returned by the Annotator service. Please note that the <semanticTypeBean> information is presented differently in <concept>. The Get all terms REST service is also affected.<br />
<pre><br />
<concept><br />
<id>2357621</id><br />
<localConceptId>40399/CDR0000038833</localConceptId><br />
<localOntologyId>40399</localOntologyId><br />
<isTopLevel>0</isTopLevel><br />
<preferredName>melanoma</preferredName><br />
<synonyms><br />
<string>Skin cancer, melanoma</string><br />
<string>melanoma, cutaneous</string><br />
<string>cutaneous melanoma</string><br />
</synonyms><br />
<semanticTypes><br />
<semanticTypeBean><br />
<id>3410411</id><br />
<semanticType>T191</semanticType><br />
<description>Neoplastic Process</description><br />
</semanticTypeBean><br />
<semanticTypeBean><br />
<id>3410007</id><br />
<semanticType>T999</semanticType><br />
<description>NCBO BioPortal concept</description><br />
</semanticTypeBean><br />
</semanticTypes><br />
</concept><br />
</pre><br />
<br />
<br />
* There is a change in the XML returned by the /obs/ontologies service. The ontologyBean now includes the following output:<br />
<br />
<pre><br />
<ontologyBean><br />
<id>3</id> <br />
<localOntologyId>40571</localOntologyId> <br />
<name>Electrocardiography Ontology</name> <br />
<version>0.1.5</version> <br />
<description /> <br />
<status>28</status> <br />
<virtualOntologyId>1146</virtualOntologyId> <br />
<format>OWL</format> <br />
</ontologyBean><br />
</pre><br />
<br />
* There is a change in the XML returned by the /obs/semanticTypes service. The semanticTypeBean now includes the following output:<br />
<br />
<pre><br />
<semanticTypeBean><br />
<id>1</id> <br />
<semanticType>T000</semanticType> <br />
<description>UMLS concept</description> <br />
</semanticTypeBean><br />
</pre><br />
<br />
* Users can now define target terminologies for RRF ontologies via the BioPortal UI.<br />
* Referencing the tabs on ontology visualization pages in the BioPortal UI is now done using the tab name:<br />
** http://bioportal.bioontology.org/visualize/40644#mappings<br />
<br />
<br />
Please refer to http://www.bioontology.org/wiki/index.php/Annotator_User_Guide for details on Annotator enhancements<br />
<br />
== New way to address UMLS ontologies ==<br />
<br />
We have harmonized the ontologies in the Annotator and BioPortal. The full list is available at: http://rest.bioontology.org/obs/ontologies. This change has implications when using the Annotator with UMLS ontologies.<br />
* Currently, BioPortal (and, therefore, Annotator and Hierarchy services) can use 16 ontologies from UMLS. We will add UMLS ontologies to BioPortal on demand. Please send email to support@bioontology.org to request a specific UMLS ontology to be added to BioPortal. <br />
* UMLS SAB is no longer valid as ontologyId. Please refer to http://bioportal.bioontology.org/ontologies/?filter=UMLS to map your SAB to the corresponding ontology version id. <br />
* UMLS CUIs are no longer valid as conceptId. You can look up the conceptId corresponding to a CUI by using the NCBO search interface (http://bioportal.bioontology.org/search): type in the CUI and check "Include attributes in search". You can also use the search REST service (http://www.bioontology.org/wiki/index.php/BioPortal_REST_services#Search_services) to search for the concept by CUI. We are working on a new concept service that will accept CUI as conceptId in the near future.<br />
<br />
== Known issues ==<br />
* ISA closure in the Annotator and Hierarchy services do not work properly for NCIT and Galen. This will be fixed in an upcoming release.<br />
* Some mappings present in BioPortal are not yet available for use with the Annotator.<br />
<br />
== Other features and bug fixes ==<br />
<br />
* Implemented updates to Hierarchy (OBS Wrapper) Services to conform to the new OBS output XML structure<br />
* Added case sensitivity check for the root concept (per #1793)<br />
* Upgraded the deprecated Acegi Security to Spring Security<br />
* Implemented support for OpenID Authentication<br />
* New lexbig JAR intended to fix the problem with the graph not focused properly when there are 2 ontologies with the same uri.(Bioportal bug #1783)<br />
<br />
== BioPortal UI Internal Features and Bugfixes ==<br />
* Fixed bug in autocomplete drop-downs where they could not distinguish between two ontologies or concepts with the same name.<br />
* New functionality to display messages on the front page with a close button that remembers that users closed the message. Set $FRONT_NOTICE in environment.rb to your desired message in order to display a message.<br />
* Updated language on error messages when attempting to browse individuals/properties.<br />
* Fixed a bug where submiting a remote ontology would trigger an exception because the app was looking for an uploaded file.<br />
* Fixed a bug in URI generation for resources where fixnums were being interpreted as strings without conversion.<br />
* Added a custom logging framework to enable logging to the BioPortal Core.<br />
* Added functionality to hide explore and download links using a global array. This fix is temporary until this information is stored in the ontology metadata.<br />
* A custom Google Analytics ID can now be provided via the environment.rb file.<br />
* If metrics don't exist, the UI now checks prior versions (back through 21 versions, three weeks for ontologies that are updated daily). The user is informed that the metrics are from a previous version and given a link to that version.<br />
* When registering a new account, a check is now made to make sure that the username doesn't already exist.<br />
* Before displaying a link for downloading diffs, the UI now makes sure that the diff is between that ontology and the prior existing ontology. This is to handle cases where an ontology may have been deleted but the record of a diff still exists. (Bug #1389)<br />
* Somehow sorting was removed from the resources on the Resource Index tab. This has been re-enabled.<br />
* Extending the slider on the ontology visualization page now works properly in IE (Bug #1500)<br />
* The BioPortal UI is now using the REST service to gather its list of Groups and related ontologies. In addition, Groups have been added to the ontology summary page. (Bug #1607)<br />
* Fixed a bug where visiting the "Submit new ontology" link on the Browse page while logged out didn't redirect properly once a user logged in (Bug #1486).<br />
* Removed extra characters from search fields on the BioPortal index page (Bug #1390)<br />
* Refactored much of the code in the DataAccess class to implement a common method to store/retrieve objects from the cache and make calls to the BioPortal Core when objects aren't in the cache.<br />
* Exception handling for IO errors due to calls to the back-end that could not be completed. Generally these were improper or unknown concept ids being passed by GoogleBot, but there were some genuine errors that weren't being handled. The user is now informed, via a very basic error message, when a concept can't be found in an existing ontology.<br />
* Added a REST_DOMAIN config option so that we could pass this parameter to Flex apps and have them use the appropriate locations for REST services. Prior to this the Flex apps were hard-coded to use production for many parts of their operation.<br />
* Added a FLEX_URL config option to allow for hosting of Flex apps in different locations.</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=9714Annotator User Guide2010-02-02T23:27:45Z<p>Cyoun: /* Annotator Web Service Parameters */</p>
<hr />
<div>===Sample HTTP Client for the Annotator===<br />
<br />
HTML http://rest.bioontology.org/test_oba.html<br />
<br />
===Annotator web service endpoint===<br />
<br />
POST your requests at http://rest.bioontology.org/obs/annotator?email=example@example.org<br />
<br />
=== Annotator Web Service Workflow===<br />
<br />
The Annotator Web service’s workflow is composed of two main steps (figure):<br />
<br />
[[Image:OBA_service_workflow.png|thumb|NCBO Annotator Web service workflow]]<br />
<br />
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. <br />
<br />
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.<br />
<br />
==== The is_a transitive closure expansion component ====<br />
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.''<br />
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).<br />
<br />
==== The mapping expansion component ====<br />
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.<br />
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.<br />
<br />
=== Annotator Web Service Parameters===<br />
<br />
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.<br />
<br />
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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
<br />
* 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.'' <br />
<br />
* 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.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
* Note that the concept recognition step does not consider text cast.<br />
<br />
|-valign="top"<br />
|width="10%"|'''filterNumber'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|width="70%"|Specifies whether the concept recognition step to filter numbers or not.<br />
<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''isStopWordsCaseSenstive '''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|width="70%"|Specifies whether stopwords are case-sensitive or not.<br />
|-valign="top"<br />
|width="10%"|'''minTermSize'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum length of the term to be included in the annotations. <br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''withSynonyms'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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. <br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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).<br />
* For example, 40403,40644,40401.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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).<br />
* For example, 40403,40644,40401.<br />
|-valign="top"<br />
|width="10%"|'''isVirtualOntologyId'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|width="70%"|Specifies whether the input values are virtualOntologyId instead of localOntologyid. VirtualOntologyId is not version-specific.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the maximum level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
* The current list of mapping type is:<br />
** ''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.<br />
** ''from-mrrel'': This mapping type corresponds to the mappings available in the MRREL table from UMLS.<br />
** ''Automatic'': This mapping type corresponds to the mappings automatically imported in BioPortal.<br />
** ''Manual'': This relation name corresponds to the mappings created by users in BioPortal.<br />
** ''Human'': This relation name corresponds to the mapping s [not used anymore] in BioPortal.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated.<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator. For programmatic access, XML is strongly suggested. <br />
<br />
* ''xml'': returns XML representation of the annotatorResultBean.<br />
* ''text'': returns plain text representation of the annotatorResultBean.<br />
* ''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 ' /// ').<br />
<br />
The elements of the Annotator response are described in next section.<br />
<br />
|}<br />
<br />
===Annotator Web Service Response===<br />
<br />
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<br />
<br />
'''Response Content: annotatorResultBean'''<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''resultId'''<br />
|width="90%"| The id of the annotatorResultBean.<br />
|-valign="top"<br />
|width="10%"|'''dictionary'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''statistics'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''parameters'''<br />
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Annotator service. Those parameters are described in previous section.<br />
|-valign="top"<br />
|width="10%"|'''ontologies'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''annotations'''<br />
|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''.<br />
<br />
{| border="2" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''score'''<br />
|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.<br />
<br />
|-valign="top"<br />
|width="10%"|'''concept'''<br />
|width="90%"| ''Concept'' is a representation of an ontology concept in the Annotator web service ontology model<br />
* ''localConceptId'' - global identifier for the concept in its original repository. <br />
* ''localOntologyId'' - identifier for the ontology in which the concept is defined. <br />
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology. <br />
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository). <br />
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred. <br />
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999). <br />
|-valign="top"<br />
|width="10%"|'''context'''<br />
|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:<br />
{| border="2" style="background:#ABCDEF;" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''MGREP'''<br />
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A Mgrep context has 3 properties: <br />
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep. <br />
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.<br />
|-valign="top"<br />
|width="10%"|'''ISA_CLOSURE'''<br />
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:<br />
* ''childConceptId'' - the concept from which the annotation was derived. <br />
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived. <br />
* 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}.<br />
|-valign="top"<br />
|width="10%"|'''MAPPING'''<br />
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties: <br />
* mappedConceptId identifies the concept from which the annotation was derived. <br />
* mappingType specifies the type of mapping.<br />
|}<br />
|}<br />
|}</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=9713Annotator User Guide2010-02-02T23:27:11Z<p>Cyoun: /* Annotator Web Service Parameters */</p>
<hr />
<div>===Sample HTTP Client for the Annotator===<br />
<br />
HTML http://rest.bioontology.org/test_oba.html<br />
<br />
===Annotator web service endpoint===<br />
<br />
POST your requests at http://rest.bioontology.org/obs/annotator?email=example@example.org<br />
<br />
=== Annotator Web Service Workflow===<br />
<br />
The Annotator Web service’s workflow is composed of two main steps (figure):<br />
<br />
[[Image:OBA_service_workflow.png|thumb|NCBO Annotator Web service workflow]]<br />
<br />
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. <br />
<br />
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.<br />
<br />
==== The is_a transitive closure expansion component ====<br />
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.''<br />
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).<br />
<br />
==== The mapping expansion component ====<br />
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.<br />
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.<br />
<br />
=== Annotator Web Service Parameters===<br />
<br />
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.<br />
<br />
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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
<br />
* 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.'' <br />
<br />
* 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.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
* Note that the concept recognition step does not consider text cast.<br />
<br />
|-valign="top"<br />
|width="10%"|'''filterNumber'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|width="70%"|Specifies whether the concept recognition step to filter numbers or not.<br />
<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''isStopWordsCaseSenstive '''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|width="70%"|Specifies whether stopwords are case-sensitive or not.<br />
|-valign="top"<br />
|width="10%"|'''minTermSize'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum length of the term to be included in the annotations. <br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''withSynonyms'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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. <br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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).<br />
* For example, 40403,40644,40401.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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).<br />
* For example, 40403,40644,40401.<br />
|-valign="top"<br />
|width="10%"|'''isVirtualOntologyId'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|width="70%"|Specifies whether the input values are virtualOntologyId instead of localOntologyid. VirtualOntologyId is not version-specific.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the maximum level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
* The current list of mapping type is:<br />
** ''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.<br />
** ''from-mrrel'': This mapping type corresponds to the mappings available in the MRREL table from UMLS.<br />
** ''Automatic'': This mapping type corresponds to the mappings automatically imported in BioPortal.<br />
** ''Manual'': This relation name corresponds to the mappings created by users in BioPortal.<br />
** ''Human'': This relation name corresponds to the mapping s [not used anymore] in BioPortal.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated.<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator. For programmatic access, XML is strongly suggested. <br />
<br />
* ''xml'': returns XML representation of the annotatorResultBean.<br />
* ''text'': returns plain text representation of the annotatorResultBean.<br />
* ''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 ' /// ').<br />
<br />
The elements of the Annotator response are described in next section.<br />
<br />
|}<br />
<br />
===Annotator Web Service Response===<br />
<br />
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<br />
<br />
'''Response Content: annotatorResultBean'''<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''resultId'''<br />
|width="90%"| The id of the annotatorResultBean.<br />
|-valign="top"<br />
|width="10%"|'''dictionary'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''statistics'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''parameters'''<br />
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Annotator service. Those parameters are described in previous section.<br />
|-valign="top"<br />
|width="10%"|'''ontologies'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''annotations'''<br />
|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''.<br />
<br />
{| border="2" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''score'''<br />
|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.<br />
<br />
|-valign="top"<br />
|width="10%"|'''concept'''<br />
|width="90%"| ''Concept'' is a representation of an ontology concept in the Annotator web service ontology model<br />
* ''localConceptId'' - global identifier for the concept in its original repository. <br />
* ''localOntologyId'' - identifier for the ontology in which the concept is defined. <br />
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology. <br />
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository). <br />
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred. <br />
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999). <br />
|-valign="top"<br />
|width="10%"|'''context'''<br />
|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:<br />
{| border="2" style="background:#ABCDEF;" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''MGREP'''<br />
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A Mgrep context has 3 properties: <br />
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep. <br />
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.<br />
|-valign="top"<br />
|width="10%"|'''ISA_CLOSURE'''<br />
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:<br />
* ''childConceptId'' - the concept from which the annotation was derived. <br />
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived. <br />
* 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}.<br />
|-valign="top"<br />
|width="10%"|'''MAPPING'''<br />
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties: <br />
* mappedConceptId identifies the concept from which the annotation was derived. <br />
* mappingType specifies the type of mapping.<br />
|}<br />
|}<br />
|}</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=9712Annotator User Guide2010-02-02T23:24:55Z<p>Cyoun: /* Annotator Web Service Parameters */</p>
<hr />
<div>===Sample HTTP Client for the Annotator===<br />
<br />
HTML http://rest.bioontology.org/test_oba.html<br />
<br />
===Annotator web service endpoint===<br />
<br />
POST your requests at http://rest.bioontology.org/obs/annotator?email=example@example.org<br />
<br />
=== Annotator Web Service Workflow===<br />
<br />
The Annotator Web service’s workflow is composed of two main steps (figure):<br />
<br />
[[Image:OBA_service_workflow.png|thumb|NCBO Annotator Web service workflow]]<br />
<br />
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. <br />
<br />
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.<br />
<br />
==== The is_a transitive closure expansion component ====<br />
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.''<br />
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).<br />
<br />
==== The mapping expansion component ====<br />
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.<br />
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.<br />
<br />
=== Annotator Web Service Parameters===<br />
<br />
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.<br />
<br />
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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
<br />
* 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.'' <br />
<br />
* 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.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
* Note that the concept recognition step does not consider text cast.<br />
<br />
|-valign="top"<br />
|width="10%"|'''filterNumber'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|width="70%"|Specifies whether the concept recognition step to filter numbers or not.<br />
<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''isStopWordsCaseSenstive '''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|width="70%"|Specifies whether stopwords are case-sensitive or not.<br />
|-valign="top"<br />
|width="10%"|'''minTermSize'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum length of the term to be included in the annotations. <br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''withSynonyms'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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. <br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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).<br />
* For example, 40403,40644,40401.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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).<br />
* For example, 40403,40644,40401.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the maximum level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
* The current list of mapping type is:<br />
** ''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.<br />
** ''from-mrrel'': This mapping type corresponds to the mappings available in the MRREL table from UMLS.<br />
** ''Automatic'': This mapping type corresponds to the mappings automatically imported in BioPortal.<br />
** ''Manual'': This relation name corresponds to the mappings created by users in BioPortal.<br />
** ''Human'': This relation name corresponds to the mapping s [not used anymore] in BioPortal.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated.<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator. For programmatic access, XML is strongly suggested. <br />
<br />
* ''xml'': returns XML representation of the annotatorResultBean.<br />
* ''text'': returns plain text representation of the annotatorResultBean.<br />
* ''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 ' /// ').<br />
<br />
The elements of the Annotator response are described in next section.<br />
<br />
|}<br />
<br />
===Annotator Web Service Response===<br />
<br />
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<br />
<br />
'''Response Content: annotatorResultBean'''<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''resultId'''<br />
|width="90%"| The id of the annotatorResultBean.<br />
|-valign="top"<br />
|width="10%"|'''dictionary'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''statistics'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''parameters'''<br />
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Annotator service. Those parameters are described in previous section.<br />
|-valign="top"<br />
|width="10%"|'''ontologies'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''annotations'''<br />
|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''.<br />
<br />
{| border="2" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''score'''<br />
|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.<br />
<br />
|-valign="top"<br />
|width="10%"|'''concept'''<br />
|width="90%"| ''Concept'' is a representation of an ontology concept in the Annotator web service ontology model<br />
* ''localConceptId'' - global identifier for the concept in its original repository. <br />
* ''localOntologyId'' - identifier for the ontology in which the concept is defined. <br />
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology. <br />
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository). <br />
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred. <br />
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999). <br />
|-valign="top"<br />
|width="10%"|'''context'''<br />
|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:<br />
{| border="2" style="background:#ABCDEF;" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''MGREP'''<br />
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A Mgrep context has 3 properties: <br />
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep. <br />
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.<br />
|-valign="top"<br />
|width="10%"|'''ISA_CLOSURE'''<br />
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:<br />
* ''childConceptId'' - the concept from which the annotation was derived. <br />
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived. <br />
* 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}.<br />
|-valign="top"<br />
|width="10%"|'''MAPPING'''<br />
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties: <br />
* mappedConceptId identifies the concept from which the annotation was derived. <br />
* mappingType specifies the type of mapping.<br />
|}<br />
|}<br />
|}</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=9711Annotator User Guide2010-02-02T23:23:09Z<p>Cyoun: /* Annotator Web Service Parameters */</p>
<hr />
<div>===Sample HTTP Client for the Annotator===<br />
<br />
HTML http://rest.bioontology.org/test_oba.html<br />
<br />
===Annotator web service endpoint===<br />
<br />
POST your requests at http://rest.bioontology.org/obs/annotator?email=example@example.org<br />
<br />
=== Annotator Web Service Workflow===<br />
<br />
The Annotator Web service’s workflow is composed of two main steps (figure):<br />
<br />
[[Image:OBA_service_workflow.png|thumb|NCBO Annotator Web service workflow]]<br />
<br />
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. <br />
<br />
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.<br />
<br />
==== The is_a transitive closure expansion component ====<br />
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.''<br />
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).<br />
<br />
==== The mapping expansion component ====<br />
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.<br />
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.<br />
<br />
=== Annotator Web Service Parameters===<br />
<br />
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.<br />
<br />
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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
<br />
* 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.'' <br />
<br />
* 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.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
* Note that the concept recognition step does not consider text cast.<br />
<br />
|-valign="top"<br />
|width="10%"|'''filterNumber'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|width="70%"|Specifies whether the concept recognition step to filter numbers or not.<br />
<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''minTermSize'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum length of the term to be included in the annotations. <br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''withSynonyms'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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. <br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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).<br />
* For example, 40403,40644,40401.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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).<br />
* For example, 40403,40644,40401.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the maximum level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
* The current list of mapping type is:<br />
** ''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.<br />
** ''from-mrrel'': This mapping type corresponds to the mappings available in the MRREL table from UMLS.<br />
** ''Automatic'': This mapping type corresponds to the mappings automatically imported in BioPortal.<br />
** ''Manual'': This relation name corresponds to the mappings created by users in BioPortal.<br />
** ''Human'': This relation name corresponds to the mapping s [not used anymore] in BioPortal.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated.<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator. For programmatic access, XML is strongly suggested. <br />
<br />
* ''xml'': returns XML representation of the annotatorResultBean.<br />
* ''text'': returns plain text representation of the annotatorResultBean.<br />
* ''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 ' /// ').<br />
<br />
The elements of the Annotator response are described in next section.<br />
<br />
|}<br />
<br />
===Annotator Web Service Response===<br />
<br />
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<br />
<br />
'''Response Content: annotatorResultBean'''<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''resultId'''<br />
|width="90%"| The id of the annotatorResultBean.<br />
|-valign="top"<br />
|width="10%"|'''dictionary'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''statistics'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''parameters'''<br />
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Annotator service. Those parameters are described in previous section.<br />
|-valign="top"<br />
|width="10%"|'''ontologies'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''annotations'''<br />
|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''.<br />
<br />
{| border="2" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''score'''<br />
|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.<br />
<br />
|-valign="top"<br />
|width="10%"|'''concept'''<br />
|width="90%"| ''Concept'' is a representation of an ontology concept in the Annotator web service ontology model<br />
* ''localConceptId'' - global identifier for the concept in its original repository. <br />
* ''localOntologyId'' - identifier for the ontology in which the concept is defined. <br />
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology. <br />
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository). <br />
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred. <br />
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999). <br />
|-valign="top"<br />
|width="10%"|'''context'''<br />
|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:<br />
{| border="2" style="background:#ABCDEF;" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''MGREP'''<br />
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A Mgrep context has 3 properties: <br />
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep. <br />
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.<br />
|-valign="top"<br />
|width="10%"|'''ISA_CLOSURE'''<br />
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:<br />
* ''childConceptId'' - the concept from which the annotation was derived. <br />
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived. <br />
* 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}.<br />
|-valign="top"<br />
|width="10%"|'''MAPPING'''<br />
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties: <br />
* mappedConceptId identifies the concept from which the annotation was derived. <br />
* mappingType specifies the type of mapping.<br />
|}<br />
|}<br />
|}</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=9674Annotator User Guide2010-01-21T21:21:19Z<p>Cyoun: /* Annotator Web Service Workflow */</p>
<hr />
<div>===Sample HTTP Client for the Annotator===<br />
<br />
HTML http://rest.bioontology.org/test_oba.html<br />
<br />
===Annotator web service endpoint===<br />
<br />
POST your requests at http://rest.bioontology.org/obs/annotator?email=example@example.org<br />
<br />
=== Annotator Web Service Workflow===<br />
<br />
The Annotator Web service’s workflow is composed of two main steps (figure):<br />
<br />
[[Image:OBA_service_workflow.png|thumb|NCBO Annotator Web service workflow]]<br />
<br />
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. <br />
<br />
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.<br />
<br />
==== The is_a transitive closure expansion component ====<br />
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.''<br />
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).<br />
<br />
==== The mapping expansion component ====<br />
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.<br />
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.<br />
<br />
=== Annotator Web Service Parameters===<br />
<br />
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.<br />
<br />
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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
<br />
* 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.'' <br />
<br />
* 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.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
* Note that the concept recognition step does not consider text cast.<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''minTermSize'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum length of the term to be included in the annotations. <br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''withSynonyms'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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. <br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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).<br />
* For example, 40403,40644,40401.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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).<br />
* For example, 40403,40644,40401.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the maximum level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
* The current list of mapping type is:<br />
** ''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.<br />
** ''from-mrrel'': This mapping type corresponds to the mappings available in the MRREL table from UMLS.<br />
** ''Automatic'': This mapping type corresponds to the mappings automatically imported in BioPortal.<br />
** ''Manual'': This relation name corresponds to the mappings created by users in BioPortal.<br />
** ''Human'': This relation name corresponds to the mapping s [not used anymore] in BioPortal.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated.<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator. For programmatic access, XML is strongly suggested. <br />
<br />
* ''xml'': returns XML representation of the annotatorResultBean.<br />
* ''text'': returns plain text representation of the annotatorResultBean.<br />
* ''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 ' /// ').<br />
<br />
The elements of the Annotator response are described in next section.<br />
<br />
|}<br />
<br />
===Annotator Web Service Response===<br />
<br />
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<br />
<br />
'''Response Content: annotatorResultBean'''<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''resultId'''<br />
|width="90%"| The id of the annotatorResultBean.<br />
|-valign="top"<br />
|width="10%"|'''dictionary'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''statistics'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''parameters'''<br />
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Annotator service. Those parameters are described in previous section.<br />
|-valign="top"<br />
|width="10%"|'''ontologies'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''annotations'''<br />
|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''.<br />
<br />
{| border="2" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''score'''<br />
|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.<br />
<br />
|-valign="top"<br />
|width="10%"|'''concept'''<br />
|width="90%"| ''Concept'' is a representation of an ontology concept in the Annotator web service ontology model<br />
* ''localConceptId'' - global identifier for the concept in its original repository. <br />
* ''localOntologyId'' - identifier for the ontology in which the concept is defined. <br />
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology. <br />
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository). <br />
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred. <br />
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999). <br />
|-valign="top"<br />
|width="10%"|'''context'''<br />
|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:<br />
{| border="2" style="background:#ABCDEF;" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''MGREP'''<br />
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A Mgrep context has 3 properties: <br />
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep. <br />
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.<br />
|-valign="top"<br />
|width="10%"|'''ISA_CLOSURE'''<br />
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:<br />
* ''childConceptId'' - the concept from which the annotation was derived. <br />
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived. <br />
* 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}.<br />
|-valign="top"<br />
|width="10%"|'''MAPPING'''<br />
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties: <br />
* mappedConceptId identifies the concept from which the annotation was derived. <br />
* mappingType specifies the type of mapping.<br />
|}<br />
|}<br />
|}</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=9673Annotator User Guide2010-01-21T21:19:32Z<p>Cyoun: /* The mapping expansion component */</p>
<hr />
<div>===Sample HTTP Client for the Annotator===<br />
<br />
HTML http://rest.bioontology.org/test_oba.html<br />
<br />
===Annotator web service endpoint===<br />
<br />
POST your requests at http://rest.bioontology.org/obs/annotator?email=example@example.org<br />
<br />
=== Annotator Web Service Workflow===<br />
<br />
The Annotator Web service’s workflow is composed of two main steps (figure):<br />
<br />
[[Image:OBA_service_workflow.png|thumb|NCBO Annotator Web service workflow]]<br />
<br />
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. <br />
<br />
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 the UMLS Metathesaurus and in BioPortal.<br />
<br />
==== The is_a transitive closure expansion component ====<br />
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.''<br />
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).<br />
<br />
==== The mapping expansion component ====<br />
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.<br />
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.<br />
<br />
=== Annotator Web Service Parameters===<br />
<br />
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.<br />
<br />
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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
<br />
* 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.'' <br />
<br />
* 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.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
* Note that the concept recognition step does not consider text cast.<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''minTermSize'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum length of the term to be included in the annotations. <br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''withSynonyms'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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. <br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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).<br />
* For example, 40403,40644,40401.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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).<br />
* For example, 40403,40644,40401.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the maximum level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
* The current list of mapping type is:<br />
** ''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.<br />
** ''from-mrrel'': This mapping type corresponds to the mappings available in the MRREL table from UMLS.<br />
** ''Automatic'': This mapping type corresponds to the mappings automatically imported in BioPortal.<br />
** ''Manual'': This relation name corresponds to the mappings created by users in BioPortal.<br />
** ''Human'': This relation name corresponds to the mapping s [not used anymore] in BioPortal.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated.<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator. For programmatic access, XML is strongly suggested. <br />
<br />
* ''xml'': returns XML representation of the annotatorResultBean.<br />
* ''text'': returns plain text representation of the annotatorResultBean.<br />
* ''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 ' /// ').<br />
<br />
The elements of the Annotator response are described in next section.<br />
<br />
|}<br />
<br />
===Annotator Web Service Response===<br />
<br />
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<br />
<br />
'''Response Content: annotatorResultBean'''<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''resultId'''<br />
|width="90%"| The id of the annotatorResultBean.<br />
|-valign="top"<br />
|width="10%"|'''dictionary'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''statistics'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''parameters'''<br />
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Annotator service. Those parameters are described in previous section.<br />
|-valign="top"<br />
|width="10%"|'''ontologies'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''annotations'''<br />
|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''.<br />
<br />
{| border="2" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''score'''<br />
|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.<br />
<br />
|-valign="top"<br />
|width="10%"|'''concept'''<br />
|width="90%"| ''Concept'' is a representation of an ontology concept in the Annotator web service ontology model<br />
* ''localConceptId'' - global identifier for the concept in its original repository. <br />
* ''localOntologyId'' - identifier for the ontology in which the concept is defined. <br />
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology. <br />
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository). <br />
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred. <br />
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999). <br />
|-valign="top"<br />
|width="10%"|'''context'''<br />
|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:<br />
{| border="2" style="background:#ABCDEF;" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''MGREP'''<br />
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A Mgrep context has 3 properties: <br />
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep. <br />
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.<br />
|-valign="top"<br />
|width="10%"|'''ISA_CLOSURE'''<br />
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:<br />
* ''childConceptId'' - the concept from which the annotation was derived. <br />
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived. <br />
* 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}.<br />
|-valign="top"<br />
|width="10%"|'''MAPPING'''<br />
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties: <br />
* mappedConceptId identifies the concept from which the annotation was derived. <br />
* mappingType specifies the type of mapping.<br />
|}<br />
|}<br />
|}</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=9672Annotator User Guide2010-01-21T20:58:40Z<p>Cyoun: /* Annotator Web Service Workflow */</p>
<hr />
<div>===Sample HTTP Client for the Annotator===<br />
<br />
HTML http://rest.bioontology.org/test_oba.html<br />
<br />
===Annotator web service endpoint===<br />
<br />
POST your requests at http://rest.bioontology.org/obs/annotator?email=example@example.org<br />
<br />
=== Annotator Web Service Workflow===<br />
<br />
The Annotator Web service’s workflow is composed of two main steps (figure):<br />
<br />
[[Image:OBA_service_workflow.png|thumb|NCBO Annotator Web service workflow]]<br />
<br />
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. <br />
<br />
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 the UMLS Metathesaurus and in BioPortal.<br />
<br />
==== The is_a transitive closure expansion component ====<br />
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.''<br />
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).<br />
<br />
==== The mapping expansion component ====<br />
An ontology-mapping component creates new annotations based on existing mappings between different ontologies. For example, an annotation done with concept NCI/C0025202 (''melanoma'') in NCI Thesaurus can be expanded to another one with in SNOMED-CT because the UMLS Metathesaurus provides the mapping information.<br />
The Annotator uses the mapping as they are defined by the repositories: UMLS mappings come both from the CUI information and the MRREL table. BioPortal mappings are defined in the BioPortal backend and accessed in an ad-hoc manner.<br />
<br />
=== Annotator Web Service Parameters===<br />
<br />
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.<br />
<br />
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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
<br />
* 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.'' <br />
<br />
* 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.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
* Note that the concept recognition step does not consider text cast.<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''minTermSize'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum length of the term to be included in the annotations. <br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''withSynonyms'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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. <br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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).<br />
* For example, 40403,40644,40401.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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).<br />
* For example, 40403,40644,40401.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the maximum level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
* The current list of mapping type is:<br />
** ''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.<br />
** ''from-mrrel'': This mapping type corresponds to the mappings available in the MRREL table from UMLS.<br />
** ''Automatic'': This mapping type corresponds to the mappings automatically imported in BioPortal.<br />
** ''Manual'': This relation name corresponds to the mappings created by users in BioPortal.<br />
** ''Human'': This relation name corresponds to the mapping s [not used anymore] in BioPortal.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated.<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator. For programmatic access, XML is strongly suggested. <br />
<br />
* ''xml'': returns XML representation of the annotatorResultBean.<br />
* ''text'': returns plain text representation of the annotatorResultBean.<br />
* ''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 ' /// ').<br />
<br />
The elements of the Annotator response are described in next section.<br />
<br />
|}<br />
<br />
===Annotator Web Service Response===<br />
<br />
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<br />
<br />
'''Response Content: annotatorResultBean'''<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''resultId'''<br />
|width="90%"| The id of the annotatorResultBean.<br />
|-valign="top"<br />
|width="10%"|'''dictionary'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''statistics'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''parameters'''<br />
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Annotator service. Those parameters are described in previous section.<br />
|-valign="top"<br />
|width="10%"|'''ontologies'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''annotations'''<br />
|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''.<br />
<br />
{| border="2" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''score'''<br />
|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.<br />
<br />
|-valign="top"<br />
|width="10%"|'''concept'''<br />
|width="90%"| ''Concept'' is a representation of an ontology concept in the Annotator web service ontology model<br />
* ''localConceptId'' - global identifier for the concept in its original repository. <br />
* ''localOntologyId'' - identifier for the ontology in which the concept is defined. <br />
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology. <br />
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository). <br />
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred. <br />
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999). <br />
|-valign="top"<br />
|width="10%"|'''context'''<br />
|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:<br />
{| border="2" style="background:#ABCDEF;" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''MGREP'''<br />
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A Mgrep context has 3 properties: <br />
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep. <br />
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.<br />
|-valign="top"<br />
|width="10%"|'''ISA_CLOSURE'''<br />
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:<br />
* ''childConceptId'' - the concept from which the annotation was derived. <br />
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived. <br />
* 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}.<br />
|-valign="top"<br />
|width="10%"|'''MAPPING'''<br />
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties: <br />
* mappedConceptId identifies the concept from which the annotation was derived. <br />
* mappingType specifies the type of mapping.<br />
|}<br />
|}<br />
|}</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=9660Annotator User Guide2010-01-19T18:33:55Z<p>Cyoun: /* Annotator Web Service Parameters */</p>
<hr />
<div>===Sample HTTP Client for the Annotator===<br />
<br />
HTML http://rest.bioontology.org/test_oba.html<br />
<br />
===Annotator web service endpoint===<br />
<br />
POST your requests at http://rest.bioontology.org/obs/annotator?email=example@example.org<br />
<br />
=== Annotator Web Service Workflow===<br />
<br />
The Annotator Web service’s workflow is composed of two main steps (figure):<br />
<br />
[[Image:OBA_service_workflow.png|thumb|NCBO Annotator Web service workflow]]<br />
<br />
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 the 98 English ontologies in UMLS 2008AA and a subset of the BioPortal ontologies (122 as of this writing). These ontologies provide a dictionary of 4,222,921 concepts and 7,943,757 terms. <br />
<br />
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 the UMLS Metathesaurus and in BioPortal.<br />
<br />
==== The is_a transitive closure expansion component ====<br />
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.''<br />
The Annotator uses the is_a relations as they are defined by the repositories: UMLS is_a relations are extracted from the MRHIER table. BioPortal is_a relations are extracted from the <SubClass>/<SuperClass> information for a given concept (accessed via REST web service).<br />
<br />
==== The mapping expansion component ====<br />
An ontology-mapping component creates new annotations based on existing mappings between different ontologies. For example, an annotation done with concept NCI/C0025202 (''melanoma'') in NCI Thesaurus can be expanded to another one with in SNOMED-CT because the UMLS Metathesaurus provides the mapping information.<br />
The Annotator uses the mapping as they are defined by the repositories: UMLS mappings come both from the CUI information and the MRREL table. BioPortal mappings are defined in the BioPortal backend and accessed in an ad-hoc manner.<br />
<br />
=== Annotator Web Service Parameters===<br />
<br />
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.<br />
<br />
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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
<br />
* 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.'' <br />
<br />
* 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.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
* Note that the concept recognition step does not consider text cast.<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''minTermSize'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum length of the term to be included in the annotations. <br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''withSynonyms'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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. <br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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).<br />
* For example, 40403,40644,40401.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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).<br />
* For example, 40403,40644,40401.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the maximum level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
* The current list of mapping type is:<br />
** ''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.<br />
** ''from-mrrel'': This mapping type corresponds to the mappings available in the MRREL table from UMLS.<br />
** ''Automatic'': This mapping type corresponds to the mappings automatically imported in BioPortal.<br />
** ''Manual'': This relation name corresponds to the mappings created by users in BioPortal.<br />
** ''Human'': This relation name corresponds to the mapping s [not used anymore] in BioPortal.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated.<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator. For programmatic access, XML is strongly suggested. <br />
<br />
* ''xml'': returns XML representation of the annotatorResultBean.<br />
* ''text'': returns plain text representation of the annotatorResultBean.<br />
* ''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 ' /// ').<br />
<br />
The elements of the Annotator response are described in next section.<br />
<br />
|}<br />
<br />
===Annotator Web Service Response===<br />
<br />
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<br />
<br />
'''Response Content: annotatorResultBean'''<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''resultId'''<br />
|width="90%"| The id of the annotatorResultBean.<br />
|-valign="top"<br />
|width="10%"|'''dictionary'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''statistics'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''parameters'''<br />
|width="90%"| Parameters summarizes all the parameters specified by the user when requesting the Annotator service. Those parameters are described in previous section.<br />
|-valign="top"<br />
|width="10%"|'''ontologies'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''annotations'''<br />
|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''.<br />
<br />
{| border="2" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''score'''<br />
|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.<br />
<br />
|-valign="top"<br />
|width="10%"|'''concept'''<br />
|width="90%"| ''Concept'' is a representation of an ontology concept in the Annotator web service ontology model<br />
* ''localConceptId'' - global identifier for the concept in its original repository. <br />
* ''localOntologyId'' - identifier for the ontology in which the concept is defined. <br />
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology. <br />
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository). <br />
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred. <br />
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999). <br />
|-valign="top"<br />
|width="10%"|'''context'''<br />
|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:<br />
{| border="2" style="background:#ABCDEF;" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''MGREP'''<br />
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A Mgrep context has 3 properties: <br />
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep. <br />
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.<br />
|-valign="top"<br />
|width="10%"|'''ISA_CLOSURE'''<br />
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:<br />
* ''childConceptId'' - the concept from which the annotation was derived. <br />
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived. <br />
* 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}.<br />
|-valign="top"<br />
|width="10%"|'''MAPPING'''<br />
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties: <br />
* mappedConceptId identifies the concept from which the annotation was derived. <br />
* mappingType specifies the type of mapping.<br />
|}<br />
|}<br />
|}</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=9137Annotator User Guide2009-08-28T21:48:42Z<p>Cyoun: /* Web Service Response */</p>
<hr />
<div>===Sample HTTP Client for the Annotator Web Service===<br />
<br />
HTML http://rest.bioontology.org/test_oba.html<br />
<br />
===Service endpoint===<br />
<br />
POST your requests at http://rest.bioontology.org/obs_hibernate/annotator?email=example@example.org<br />
<br />
===Web Service Parameters===<br />
<br />
The Annotator Web service offers a set of parameters that allows a user to customize the annotator work flow and filter the result. To customize the work flow 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 work flow can be parametrized.<br />
<br />
The Annotator Web service level agreement (e.g., 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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
<br />
* For example: If ''longestOnly=true'', the phrase 'skin neoplasms' will match the concept NCI/C0037286 (Skin Neoplasms) and NCI/C0027651 (Neoplasms) only. If ''longestOnly=false'', the concept NCI/C1123023(Skin) will also match in addition.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
* Note that the concept recognition step does not consider text cast.<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|width="70%"|Specifies whether to use stop words or not. The default stop word list are available from sample HTML page. If set to true, this override the value of stopWords given by the user.<br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|width="70%"|Specifies the list of ontologies to use to expand in 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)<br />
* For example, SNOMEDCT,NCI,13578,36625,MSH.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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) <br />
* For example, SNOMEDCT,NCI,MSH.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum (resp. maximum) level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* For example, an annotation done with levelMin=1 & 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 levelMin=0 & levelMax=0 is equivalent to disable the is_a transitive closure expansion step.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator Restlet.<br />
<br />
|}<br />
<br />
<br />
===Web Service Response===<br />
<br />
'''Response Format'''<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''asXml'''<br />
|width="90%"| returns XML representation of the annotatorResultBean.<br />
|-valign="top"<br />
|width="10%"|'''asText'''<br />
|width="90%"| returns plain text representation of the annotatorResultBean.<br />
|-valign="top"<br />
|width="10%"|'''asTabDelimited'''<br />
|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 ' /// ').<br />
|}<br />
<br />
<br />
'''Response Content: annotatorResultBean'''<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''resultId'''<br />
|width="90%"|<br />
|-valign="top"<br />
|width="10%"|'''dictionary'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''statistics'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''parameters'''<br />
|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<br />
|-valign="top"<br />
|width="10%"|'''ontologies'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''annotations'''<br />
|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.<br />
<br />
{| border="2" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''score'''<br />
|width="90%"| <br />
|-valign="top"<br />
|width="10%"|'''concept'''<br />
|width="90%"| <br />
* ''localConceptId'' - global identifier for the concept in its original repository. <br />
* ''localOntologyId'' - identifier for the ontology in which the concept is defined. <br />
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology. <br />
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository). <br />
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred. <br />
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999). <br />
|-valign="top"<br />
|width="10%"|'''context'''<br />
|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:<br />
{| border="2" style="background:#ABCDEF;" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''MGREP'''<br />
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A Mgrep context has 3 properties: <br />
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep. <br />
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.<br />
|-valign="top"<br />
|width="10%"|'''ISA_CLOSURE'''<br />
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:<br />
* ''childConceptId'' - the concept from which the annotation was derived. <br />
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived. <br />
* 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}.<br />
|-valign="top"<br />
|width="10%"|'''MAPPING'''<br />
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties: <br />
* mappedConceptId identifies the concept from which the annotation was derived. <br />
* mappingType specifies the type of mapping.<br />
|}<br />
|}<br />
|}</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=8841Annotator User Guide2009-05-15T17:49:17Z<p>Cyoun: /* Service endpoint */</p>
<hr />
<div>===Sample HTTP Client for the Annotator Web Service===<br />
<br />
HTML http://rest.bioontology.org/test_oba.html<br />
<br />
===Service endpoint===<br />
<br />
POST your requests at http://rest.bioontology.org/obs_hibernate/annotator?email=example@example.org<br />
<br />
===Web Service Parameters===<br />
<br />
The Annotator Web service offers a set of parameters that allows a user to customize the annotator work flow and filter the result. To customize the work flow 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 work flow can be parametrized.<br />
<br />
The Annotator Web service level agreement (e.g., 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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
<br />
* For example: If ''longestOnly=true'', the phrase 'skin neoplasms' will match the concept NCI/C0037286 (Skin Neoplasms) and NCI/C0027651 (Neoplasms) only. If ''longestOnly=false'', the concept NCI/C1123023(Skin) will also match in addition.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
* Note that the concept recognition step does not consider text cast.<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|width="70%"|Specifies whether to use stop words or not. The default stop word list are available from sample HTML page. If set to true, this override the value of stopWords given by the user.<br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|width="70%"|Specifies the list of ontologies to use to expand in 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)<br />
* For example, SNOMEDCT,NCI,13578,36625,MSH.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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) <br />
* For example, SNOMEDCT,NCI,MSH.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum (resp. maximum) level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* For example, an annotation done with levelMin=1 & 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 levelMin=0 & levelMax=0 is equivalent to disable the is_a transitive closure expansion step.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator Restlet.<br />
<br />
|}<br />
<br />
<br />
===Web Service Response===<br />
<br />
'''Response Format'''<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''xml'''<br />
|width="90%"| returns XML representation of the annotatorResultBean.<br />
|-valign="top"<br />
|width="10%"|'''text'''<br />
|width="90%"| returns plain text representation of the annotatorResultBean.<br />
|-valign="top"<br />
|width="10%"|'''tabDelimited'''<br />
|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 ' /// ').<br />
|}<br />
<br />
<br />
'''Response Content: annotatorResultBean'''<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''resultID'''<br />
|width="90%"|<br />
|-valign="top"<br />
|width="10%"|'''dictionary'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''statistics'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''parameters'''<br />
|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<br />
|-valign="top"<br />
|width="10%"|'''ontologies'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''annotations'''<br />
|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.<br />
<br />
{| border="2" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''score'''<br />
|width="90%"| <br />
|-valign="top"<br />
|width="10%"|'''concept'''<br />
|width="90%"| <br />
* ''localConceptID'' - global identifier for the concept in its original repository. <br />
* ''localOntologyID'' - identifier for the ontology in which the concept is defined. <br />
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology. <br />
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository). <br />
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred. <br />
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999). <br />
|-valign="top"<br />
|width="10%"|'''context'''<br />
|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:<br />
{| border="2" style="background:#ABCDEF;" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''MGREP'''<br />
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A MGREP context has 3 properties: <br />
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep. <br />
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.<br />
|-valign="top"<br />
|width="10%"|'''ISA_CLOSURE'''<br />
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:<br />
* ''childConceptID'' - the concept from which the annotation was derived. <br />
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived. <br />
* 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}.<br />
|-valign="top"<br />
|width="10%"|'''MAPPING'''<br />
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties: <br />
* mappedConceptID identifies the concept from which the annotation was derived. <br />
* mappingType specifies the type of mapping.<br />
|}<br />
|}<br />
|}</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=8765Annotator User Guide2009-05-06T00:12:53Z<p>Cyoun: </p>
<hr />
<div>===Sample HTTP Client for the Annotator Web Service===<br />
<br />
HTML http://rest.bioontology.org/test_oba.html<br />
<br />
===Service endpoint===<br />
<br />
POST your requests at http://rest.bioontology.org/obs_hibernate/annotator<br />
<br />
===Web Service Parameters===<br />
<br />
The Annotator Web service offers a set of parameters that allows a user to customize the annotator work flow and filter the result. To customize the work flow 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 work flow can be parametrized.<br />
<br />
The Annotator Web service level agreement (e.g., 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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
<br />
* For example: If ''longestOnly=true'', the phrase 'skin neoplasms' will match the concept NCI/C0037286 (Skin Neoplasms) and NCI/C0027651 (Neoplasms) only. If ''longestOnly=false'', the concept NCI/C1123023(Skin) will also match in addition.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
* Note that the concept recognition step does not consider text cast.<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|width="70%"|Specifies whether to use stop words or not. The default stop word list are available from sample HTML page. If set to true, this override the value of stopWords given by the user.<br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|width="70%"|Specifies the list of ontologies to use to expand in 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)<br />
* For example, SNOMEDCT,NCI,13578,36625,MSH.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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) <br />
* For example, SNOMEDCT,NCI,MSH.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum (resp. maximum) level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* For example, an annotation done with levelMin=1 & 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 levelMin=0 & levelMax=0 is equivalent to disable the is_a transitive closure expansion step.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator Restlet.<br />
<br />
|}<br />
<br />
<br />
===Web Service Response===<br />
<br />
'''Response Format'''<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''xml'''<br />
|width="90%"| returns XML representation of the annotatorResultBean.<br />
|-valign="top"<br />
|width="10%"|'''text'''<br />
|width="90%"| returns plain text representation of the annotatorResultBean.<br />
|-valign="top"<br />
|width="10%"|'''tabDelimited'''<br />
|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 ' /// ').<br />
|}<br />
<br />
<br />
'''Response Content: annotatorResultBean'''<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''resultID'''<br />
|width="90%"|<br />
|-valign="top"<br />
|width="10%"|'''dictionary'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''statistics'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''parameters'''<br />
|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<br />
|-valign="top"<br />
|width="10%"|'''ontologies'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''annotations'''<br />
|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.<br />
<br />
{| border="2" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''score'''<br />
|width="90%"| <br />
|-valign="top"<br />
|width="10%"|'''concept'''<br />
|width="90%"| <br />
* ''localConceptID'' - global identifier for the concept in its original repository. <br />
* ''localOntologyID'' - identifier for the ontology in which the concept is defined. <br />
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology. <br />
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository). <br />
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred. <br />
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999). <br />
|-valign="top"<br />
|width="10%"|'''context'''<br />
|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:<br />
{| border="2" style="background:#ABCDEF;" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''MGREP'''<br />
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A MGREP context has 3 properties: <br />
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep. <br />
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.<br />
|-valign="top"<br />
|width="10%"|'''ISA_CLOSURE'''<br />
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:<br />
* ''childConceptID'' - the concept from which the annotation was derived. <br />
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived. <br />
* 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}.<br />
|-valign="top"<br />
|width="10%"|'''MAPPING'''<br />
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties: <br />
* mappedConceptID identifies the concept from which the annotation was derived. <br />
* mappingType specifies the type of mapping.<br />
|}<br />
|}<br />
|}</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=8763Annotator User Guide2009-05-05T23:48:45Z<p>Cyoun: </p>
<hr />
<div>===Sample HTTP Client for the Annotator Web Service===<br />
<br />
HTML http://rest.bioontology.org/test_oba.html<br />
<br />
===Service endpoint===<br />
<br />
POST your requests at http://rest.bioontology.org/obs_hibernate/annotator<br />
<br />
===Web Service Parameters===<br />
<br />
The Annotator Web service offers a set of parameters that allows a user to customize the annotator work flow and filter the result. To customize the work flow 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 work flow can be parametrized.<br />
<br />
The Annotator Web service level agreement (e.g., 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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
<br />
* For example: If ''longestOnly=true'', the phrase 'skin neoplasms' will match the concept NCI/C0037286 (Skin Neoplasms) and NCI/C0027651 (Neoplasms) only. If ''longestOnly=false'', the concept NCI/C1123023(Skin) will also match in addition.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
* Note that the concept recognition step does not consider text cast.<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|width="70%"|Specifies whether to use stop words or not. The default stop word list are available from sample HTML page. If set to true, this override the value of stopWords given by the user.<br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|width="70%"|Specifies the list of ontologies to use to expand in 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)<br />
* For example, SNOMEDCT,NCI,13578,36625,MSH.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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) <br />
* For example, SNOMEDCT,NCI,MSH.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum (resp. maximum) level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* For example, an annotation done with levelMin=1 & 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 levelMin=0 & levelMax=0 is equivalent to disable the is_a transitive closure expansion step.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator Restlet.<br />
<br />
|}<br />
<br />
<br />
===Web Service Response===<br />
<br />
'''Response Format'''<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''xml'''<br />
|width="90%"| returns XML representation of the annotatorResultBean.<br />
|-valign="top"<br />
|width="10%"|'''text'''<br />
|width="90%"| returns plain text representation of the annotatorResultBean.<br />
|-valign="top"<br />
|width="10%"|'''tabDelimited'''<br />
|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 ' /// ').<br />
|}<br />
<br />
<br />
'''Response Content: annotatorResultBean'''<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''resultID'''<br />
|width="90%"|<br />
|-valign="top"<br />
|width="10%"|'''dictionary'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''statistics'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''parameters'''<br />
|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<br />
|-valign="top"<br />
|width="10%"|'''ontologies'''<br />
|width="90%"| Ontology is a representation of an ontology in the Annotator Restlet service ontology model represented in Figure 1. 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.<br />
|-valign="top"<br />
|width="10%"|'''annotations'''<br />
|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.<br />
<br />
{| border="2" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''score'''<br />
|width="90%"| <br />
|-valign="top"<br />
|width="10%"|'''concept'''<br />
|width="90%"| <br />
* ''localConceptID'' - global identifier for the concept in its original repository. <br />
* ''localOntologyID'' - identifier for the ontology in which the concept is defined. <br />
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology. <br />
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository). <br />
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred. <br />
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999). <br />
|-valign="top"<br />
|width="10%"|'''context'''<br />
|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:<br />
{| border="2" style="background:#ABCDEF;" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''MGREP'''<br />
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A MGREP context has 3 properties: <br />
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep. <br />
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.<br />
|-valign="top"<br />
|width="10%"|'''ISA_CLOSURE'''<br />
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:<br />
* ''childConceptID'' - the concept from which the annotation was derived. <br />
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived. <br />
* 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}.<br />
|-valign="top"<br />
|width="10%"|'''MAPPING'''<br />
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties: <br />
* mappedConceptID identifies the concept from which the annotation was derived. <br />
* mappingType specifies the type of mapping.<br />
|}<br />
|}<br />
|}</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=8762Annotator User Guide2009-05-05T23:43:26Z<p>Cyoun: /* Restlet Service Response */</p>
<hr />
<div>===Sample HTTP Client for the Annotator Restlet===<br />
<br />
HTML http://rest.bioontology.org/test_oba.html<br />
<br />
<br />
===Service endpoint===<br />
<br />
POST your requests at http://rest.bioontology.org/obs_hibernate/annotator<br />
<br />
===Restlet Service Parameters===<br />
<br />
The Annotator Restlet service offers a set of parameters that allows a user to customize the annotator work flow and filter the result. To customize the work flow 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 work flow can be parametrized.<br />
<br />
The Annotator Restlet service level agreement (e.g., 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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
<br />
* For example: If ''longestOnly=true'', the phrase 'skin neoplasms' will match the concept NCI/C0037286 (Skin Neoplasms) and NCI/C0027651 (Neoplasms) only. If ''longestOnly=false'', the concept NCI/C1123023(Skin) will also match in addition.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
* Note that the concept recognition step does not consider text cast.<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|width="70%"|Specifies whether to use stop words or not. The default stop word list are available from sample HTML page. If set to true, this override the value of stopWords given by the user.<br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|width="70%"|Specifies the list of ontologies to use to expand in 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)<br />
* For example, SNOMEDCT,NCI,13578,36625,MSH.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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) <br />
* For example, SNOMEDCT,NCI,MSH.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum (resp. maximum) level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* For example, an annotation done with levelMin=1 & 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 levelMin=0 & levelMax=0 is equivalent to disable the is_a transitive closure expansion step.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator Restlet.<br />
<br />
|}<br />
<br />
<br />
===Web Service Response===<br />
<br />
ObaResultBean is the main object returned by the Annotator Web service. text refers to the piece of text originally sent to the service, while resultID identifies the result. The properties annotations, dictionary, ontologies and statistics and parameters are defined hereafter. There are three different format for the response as shown as following.<br />
<br />
'''response format'''<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''xml'''<br />
|width="90%"| returns XML representation of the annotatorResultBean.<br />
|-valign="top"<br />
|width="10%"|'''text'''<br />
|width="90%"| returns plain text representation of the annotatorResultBean.<br />
|-valign="top"<br />
|width="10%"|'''tabDelimited'''<br />
|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 ' /// ').<br />
|}<br />
<br />
<br />
'''annotatorResultBean'''<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''resultID'''<br />
|width="90%"|<br />
|-valign="top"<br />
|width="10%"|'''dictionary'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''statistics'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''parameters'''<br />
|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<br />
|-valign="top"<br />
|width="10%"|'''ontologies'''<br />
|width="90%"| Ontology is a representation of an ontology in the Annotator Restlet service ontology model represented in Figure 1. 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.<br />
|-valign="top"<br />
|width="10%"|'''annotations'''<br />
|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.<br />
<br />
{| border="2" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''score'''<br />
|width="90%"| <br />
|-valign="top"<br />
|width="10%"|'''concept'''<br />
|width="90%"| <br />
* ''localConceptID'' - global identifier for the concept in its original repository. <br />
* ''localOntologyID'' - identifier for the ontology in which the concept is defined. <br />
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology. <br />
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository). <br />
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred. <br />
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999). <br />
|-valign="top"<br />
|width="10%"|'''context'''<br />
|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:<br />
{| border="2" style="background:#ABCDEF;" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''MGREP'''<br />
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A MGREP context has 3 properties: <br />
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep. <br />
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.<br />
|-valign="top"<br />
|width="10%"|'''ISA_CLOSURE'''<br />
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:<br />
* ''childConceptID'' - the concept from which the annotation was derived. <br />
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived. <br />
* 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}.<br />
|-valign="top"<br />
|width="10%"|'''MAPPING'''<br />
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties: <br />
* mappedConceptID identifies the concept from which the annotation was derived. <br />
* mappingType specifies the type of mapping.<br />
|}<br />
|}<br />
|}</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=8758Annotator User Guide2009-05-05T23:36:37Z<p>Cyoun: </p>
<hr />
<div>===Sample HTTP Client for the Annotator Restlet===<br />
<br />
HTML http://rest.bioontology.org/test_oba.html<br />
<br />
<br />
===Service endpoint===<br />
<br />
POST your requests at http://rest.bioontology.org/obs_hibernate/annotator<br />
<br />
===Restlet Service Parameters===<br />
<br />
The Annotator Restlet service offers a set of parameters that allows a user to customize the annotator work flow and filter the result. To customize the work flow 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 work flow can be parametrized.<br />
<br />
The Annotator Restlet service level agreement (e.g., 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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
<br />
* For example: If ''longestOnly=true'', the phrase 'skin neoplasms' will match the concept NCI/C0037286 (Skin Neoplasms) and NCI/C0027651 (Neoplasms) only. If ''longestOnly=false'', the concept NCI/C1123023(Skin) will also match in addition.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
* Note that the concept recognition step does not consider text cast.<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|width="70%"|Specifies whether to use stop words or not. The default stop word list are available from sample HTML page. If set to true, this override the value of stopWords given by the user.<br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|width="70%"|Specifies the list of ontologies to use to expand in 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)<br />
* For example, SNOMEDCT,NCI,13578,36625,MSH.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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) <br />
* For example, SNOMEDCT,NCI,MSH.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum (resp. maximum) level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* For example, an annotation done with levelMin=1 & 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 levelMin=0 & levelMax=0 is equivalent to disable the is_a transitive closure expansion step.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator Restlet.<br />
<br />
|}<br />
<br />
<br />
===Restlet Service Response===<br />
<br />
* ObaResult is the main object returned by the Annotator Restlet service. text refers to the piece of text originally sent to the service, while resultID identifies the result. The properties annotations, dictionary, ontologies and statistics and parameters are defined hereafter. An ObaResult provides functions to export its content in different form for the user. There are three different format for the response from the Annotator Restlet service:<br />
<br />
* XML: returns XML representation of the result bean.<br />
* Text: returns the result content as plain text.<br />
* 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 ' /// ').<br />
<br />
annotatorResultBean<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''resultID'''<br />
|width="90%"|<br />
|-valign="top"<br />
|width="10%"|'''dictionary'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''statistics'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''parameters'''<br />
|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<br />
|-valign="top"<br />
|width="10%"|'''ontologies'''<br />
|width="90%"| Ontology is a representation of an ontology in the Annotator Restlet service ontology model represented in Figure 1. 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.<br />
|-valign="top"<br />
|width="10%"|'''annotations'''<br />
|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.<br />
<br />
{| border="2" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''score'''<br />
|width="90%"| <br />
|-valign="top"<br />
|width="10%"|'''concept'''<br />
|width="90%"| <br />
* ''localConceptID'' - global identifier for the concept in its original repository. <br />
* ''localOntologyID'' - identifier for the ontology in which the concept is defined. <br />
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology. <br />
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository). <br />
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred. <br />
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999). <br />
|-valign="top"<br />
|width="10%"|'''context'''<br />
|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:<br />
{| border="2" style="background:#ABCDEF;" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''MGREP'''<br />
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A MGREP context has 3 properties: <br />
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep. <br />
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.<br />
|-valign="top"<br />
|width="10%"|'''ISA_CLOSURE'''<br />
|width="90%"| represents expanded annotations done with the ''is_a'' transitive closure expansion component. A ISA_CLOSURE context has 2 properties:<br />
* ''childConceptID'' - the concept from which the annotation was derived. <br />
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived. <br />
* 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}.<br />
|-valign="top"<br />
|width="10%"|'''MAPPING'''<br />
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties: <br />
* mappedConceptID identifies the concept from which the annotation was derived. <br />
* mappingType specifies the type of mapping.<br />
|}<br />
|}<br />
|}</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=8757Annotator User Guide2009-05-05T23:25:48Z<p>Cyoun: </p>
<hr />
<div>'''Sample HTTP Client for the Annotator Restlet'''<br />
<br />
HTML http://ncbo-obs-prod1:8080/test_oba.html<br />
<br />
----<br />
<br />
'''Service endpoint'''<br />
<br />
POST your requests at http://ncbo-obs-prod1.stanford.edu:8080/obs_hibernate/annotator<br />
<br />
'''Restlet Service Parameters'''<br />
<br />
The Annotator Restlet service offers a set of parameters that allows a user to customize the annotator work flow and filter the result. To customize the work flow 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 work flow can be parametrized.<br />
<br />
The Annotator Restlet service level agreement (e.g., 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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
<br />
* For example: If ''longestOnly=true'', the phrase 'skin neoplasms' will match the concept NCI/C0037286 (Skin Neoplasms) and NCI/C0027651 (Neoplasms) only. If ''longestOnly=false'', the concept NCI/C1123023(Skin) will also match in addition.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
* Note that the concept recognition step does not consider text cast.<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|width="70%"|Specifies whether to use stop words or not. The default stop word list are available from sample HTML page. If set to true, this override the value of stopWords given by the user.<br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|width="70%"|Specifies the list of ontologies to use to expand in 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)<br />
* For example, SNOMEDCT,NCI,13578,36625,MSH.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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) <br />
* For example, SNOMEDCT,NCI,MSH.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum (resp. maximum) level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* For example, an annotation done with levelMin=1 & 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 levelMin=0 & levelMax=0 is equivalent to disable the is_a transitive closure expansion step.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator Restlet.<br />
<br />
|}<br />
<br />
<br />
'''Restlet Service Response'''<br />
<br />
* ObaResult is the main object returned by the Annotator Restlet service. text refers to the piece of text originally sent to the service, while resultID identifies the result. The properties annotations, dictionary, ontologies and statistics and parameters are defined hereafter. An ObaResult provides functions to export its content in different form for the user. There are three different format for the response from the Annotator Restlet service:<br />
<br />
* XML: returns XML representation of the result bean.<br />
* Text: returns the result content as plain text.<br />
* 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 ' /// ').<br />
<br />
annotatorResultBean<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''resultID'''<br />
|width="90%"|<br />
|-valign="top"<br />
|width="10%"|'''dictionary'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''statistics'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''parameters'''<br />
|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<br />
|-valign="top"<br />
|width="10%"|'''ontologies'''<br />
|width="90%"| Ontology is a representation of an ontology in the Annotator Restlet service ontology model represented in Figure 1. 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.<br />
|-valign="top"<br />
|width="10%"|'''annotations'''<br />
|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.<br />
<br />
{| border="2" style="background:#ABCDEF;" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''score'''<br />
|width="90%"| <br />
|-valign="top"<br />
|width="10%"|'''concept'''<br />
|width="90%"| <br />
* ''localConceptID'' - global identifier for the concept in its original repository. <br />
* ''localOntologyID'' - identifier for the ontology in which the concept is defined. <br />
* ''isTopLevel'' - specifies if the concept is a root concept in its ontology. <br />
* ''preferredName'' - label or preferred term for this concept (as assigned by the original repository). <br />
* ''synonyms'' - the set of possible terms that represent the concept but are not preferred. <br />
* ''semanticTypes'' - the set of the semantic types of the concept (assigned by UMLS + T000 and T999). <br />
|-valign="top"<br />
|width="10%"|'''context'''<br />
|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:<br />
{| border="2" style="background:#ABCDEF;" <!-- The nested table must be on a new line --><br />
|-valign="top"<br />
|width="10%"|'''MGREP'''<br />
|width="90%"| represents direct annotations done with the Mgrep concept recognizer. A MGREP context has 3 properties: <br />
* ''termName'' - the expression (preferred name or synonyms) that was matched by Mgrep. <br />
* ''from'' and ''to'' - specify the character index in the given text for the matched expression.<br />
|-valign="top"<br />
|width="10%"|'''ISA_CLOSURE'''<br />
|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. <br />
* ''level'' - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived. <br />
* 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}.<br />
|-valign="top"<br />
|width="10%"|'''MAPPING'''<br />
|width="90%"| represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties: <br />
* mappedConceptID identifies the concept from which the annotation was derived. <br />
* mappingType specifies the type of mapping.<br />
|}<br />
|}<br />
|}</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=8753Annotator User Guide2009-05-05T22:50:24Z<p>Cyoun: </p>
<hr />
<div>'''Sample HTTP Client for the Annotator Restlet'''<br />
<br />
HTML http://ncbo-obs-prod1:8080/test_oba.html<br />
<br />
----<br />
<br />
'''Service endpoint'''<br />
<br />
POST your requests at http://ncbo-obs-prod1.stanford.edu:8080/obs_hibernate/annotator<br />
<br />
'''Restlet Service Parameters'''<br />
<br />
The Annotator Restlet service offers a set of parameters that allows a user to customize the annotator work flow and filter the result. To customize the work flow 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 work flow can be parametrized.<br />
<br />
The Annotator Restlet service level agreement (e.g., 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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|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.<br />
<br />
* For example: If ''longestOnly=true'', the phrase 'skin neoplasms' will match the concept NCI/C0037286 (Skin Neoplasms) and NCI/C0027651 (Neoplasms) only. If ''longestOnly=false'', the concept NCI/C1123023(Skin) will also match in addition.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
* Note that the concept recognition step does not consider text cast.<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|width="70%"|Specifies whether to use stop words or not. The default stop word list are available from sample HTML page. If set to true, this override the value of stopWords given by the user.<br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|width="70%"|Specifies the list of ontologies to use to expand in 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)<br />
* For example, SNOMEDCT,NCI,13578,36625,MSH.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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) <br />
* For example, SNOMEDCT,NCI,MSH.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum (resp. maximum) level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* For example, an annotation done with levelMin=1 & 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 levelMin=0 & levelMax=0 is equivalent to disable the is_a transitive closure expansion step.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator Restlet.<br />
<br />
|}<br />
<br />
<br />
'''Restlet Service Response'''<br />
<br />
* ObaResult is the main object returned by the Annotator Restlet service. text refers to the piece of text originally sent to the service, while resultID identifies the result. The properties annotations, dictionary, ontologies and statistics and parameters are defined hereafter. An ObaResult provides functions to export its content in different form for the user. There are three different format for the response from the Annotator Restlet service:<br />
<br />
* XML: returns XML representation of the result bean.<br />
* Text: returns the result content as plain text.<br />
* 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 ' /// ').<br />
<br />
annotatorResultBean<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''resultID'''<br />
|width="90%"|<br />
|-valign="top"<br />
|width="10%"|'''dictionary'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''statistics'''<br />
|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.<br />
|-valign="top"<br />
|width="10%"|'''parameters'''<br />
|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<br />
|-valign="top"<br />
|width="10%"|'''ontologies'''<br />
|width="90%"| Ontology is a representation of an ontology in the Annotator Restlet service ontology model represented in Figure 1. 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.<br />
|-valign="top"<br />
|width="10%"|'''annotations'''<br />
|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.<br />
<br />
|} <br />
<br />
<br />
* Concept is a representation of an ontology concept in the Annotator Restlet service ontology model represented in Figure 1. localConceptID globally identifies the concept in its original repository. preferredName is the label or preferred term for this concept (as assigned by the original repository). synonyms is a set of possible terms that represent the concept but are not preferred. isTopLevel specifies if the concept is a root concept in its ontology. localOntologyID identifies the ontology in which the concept is defined. localSemanticTypesIDs is the set of the semantic types of the concept (assigned by UMLS + T000 and T999).<br />
<br />
<br />
* Context is a representation of the context in which annotation has been done. It 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 4 possible contexts identified by their contextName:<br />
<br />
* MGREP, used to identify direct annotations done with the Mgrep concept recognizer. A MGREP context has 3 properties: termName, identifies 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.<br />
<br />
* ISA_CLOSURE, used to identify expanded annotations done with the is_a transitive closure expansion component. A ISA_CLOSURE context has 2 properties: childConceptID identifies the concept from which the annotation was derived. level specifies 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}.<br />
<br />
* MAPPING, used to identify 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.<br />
<br />
* DISTANCE, used to identify expanded annotations done with the semantic distance expansion component. A DISTANCE context has 2 properties: relatedConceptID identifies the concept from which the annotation was derived. distance specifies the distance (as an integer) between the 2 concepts.</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=8750Annotator User Guide2009-05-05T21:27:31Z<p>Cyoun: </p>
<hr />
<div>'''Sample HTTP Client for the Annotator Restlet'''<br />
<br />
HTML http://ncbo-obs-prod1:8080/test_oba.html<br />
<br />
----<br />
<br />
<br />
'''Restlet Service Parameters'''<br />
<br />
The Annotator Restlet service offers a set of parameters that allows a user to customize the annotator work flow and filter the result. To customize the work flow 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 work flow can be parametrized.<br />
<br />
The Annotator Restlet service level agreement (e.g., 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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="5%"|{true, false}<br />
|width="5%"|default: false<br />
|width="80%"|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.<br />
<br />
* For example: If ''longestOnly=true'', the phrase 'skin neoplasms' will match the concept NCI/C0037286 (Skin Neoplasms) and NCI/C0027651 (Neoplasms) only. If ''longestOnly=false'', the concept NCI/C1123023(Skin) will also match in addition.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="5%"|{true, false}<br />
|width="5%"|default: true<br />
|width="80%"|Specifies whether the concept recognition step must match whole words only or not, if they are several concepts that match to a given word.<br />
* 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.<br />
* Note that the concept recognition step does not consider text cast.<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|width="70%"|Specifies whether to use stop words or not. The default stop word list are available from sample HTML page. If set to true, this override the value of stopWords given by the user.<br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|width="70%"|Specifies the list of ontologies to use to expand in 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)<br />
* For example, SNOMEDCT,NCI,13578,36625,MSH.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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) <br />
* For example, SNOMEDCT,NCI,MSH.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum (resp. maximum) level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* For example, an annotation done with levelMin=1 & 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 levelMin=0 & levelMax=0 is equivalent to disable the is_a transitive closure expansion step.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator Restlet.<br />
<br />
|}<br />
<br />
<br />
'''Restlet Service Response'''<br />
<br />
* ObaResult is the main object returned by the Annotator Restlet service. text refers to the piece of text originally sent to the service, while resultID identifies the result. The properties annotations, dictionary, ontologies and statistics and parameters are defined hereafter. An ObaResult provides functions to export its content in different form for the user. There are three different format for the response from the Annotator Restlet service:<br />
<br />
* XML: returns XML representation of the result bean.<br />
* Text: returns the result content as plain text.<br />
* 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 ' /// ').<br />
<br />
<br />
* 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.<br />
<br />
<br />
* Concept is a representation of an ontology concept in the Annotator Restlet service ontology model represented in Figure 1. localConceptID globally identifies the concept in its original repository. preferredName is the label or preferred term for this concept (as assigned by the original repository). synonyms is a set of possible terms that represent the concept but are not preferred. isTopLevel specifies if the concept is a root concept in its ontology. localOntologyID identifies the ontology in which the concept is defined. localSemanticTypesIDs is the set of the semantic types of the concept (assigned by UMLS + T000 and T999).<br />
<br />
<br />
* Context is a representation of the context in which annotation has been done. It 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 4 possible contexts identified by their contextName:<br />
<br />
* MGREP, used to identify direct annotations done with the Mgrep concept recognizer. A MGREP context has 3 properties: termName, identifies 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.<br />
<br />
* ISA_CLOSURE, used to identify expanded annotations done with the is_a transitive closure expansion component. A ISA_CLOSURE context has 2 properties: childConceptID identifies the concept from which the annotation was derived. level specifies 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}.<br />
<br />
* MAPPING, used to identify 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.<br />
<br />
* DISTANCE, used to identify expanded annotations done with the semantic distance expansion component. A DISTANCE context has 2 properties: relatedConceptID identifies the concept from which the annotation was derived. distance specifies the distance (as an integer) between the 2 concepts.<br />
<br />
* 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.<br />
<br />
* Ontology is a representation of an ontology in the Annotator Restlet service ontology model represented in Figure 1. 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.<br />
<br />
<br />
* 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.<br />
<br />
<br />
* Parameters summarizes all the parameters specified by the user when requesting the Annotator Restlet service. Those parameters are described in section Service parameters</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=8749Annotator User Guide2009-05-05T21:25:35Z<p>Cyoun: </p>
<hr />
<div>'''Sample HTTP Client for the Annotator Restlet'''<br />
<br />
HTML http://ncbo-obs-prod1:8080/test_oba.html<br />
<br />
----<br />
<br />
<br />
'''Restlet Service Parameters'''<br />
<br />
The Annotator Restlet service offers a set of parameters that allows a user to customize the annotator work flow and filter the result. To customize the work flow 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 work flow can be parametrized.<br />
<br />
The Annotator Restlet service level agreement (e.g., 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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="5%"|{true, false}<br />
|width="5%"|default: false<br />
|width="80%"|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.<br />
<br />
* For example: If ''longestOnly=true'' the phrase 'skin neoplasms' will match the concept NCI/C0037286 (Skin Neoplasms) and NCI/C0027651 (Neoplasms). If ''longestOnly=false'', the concept NCI/C1123023(Skin) will also match in addition.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="5%"|{true, false}<br />
|width="5%"|default: true<br />
|width="80%"|Specifies whether the concept recognition step must match whole words only or not, if they are several concepts that match to a given word.<br />
* For example: the phrase 'neoplasms' if wholeWordOnly=true will match to 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).<br />
* Note that the concept recognition step does not consider text cast.<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|width="70%"|Specifies whether to use stop words or not. The default stop word list are available from sample HTML page. If set to true, this override the value of stopWords given by the user.<br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|width="70%"|Specifies the list of ontologies to use to expand in 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)<br />
* For example, SNOMEDCT,NCI,13578,36625,MSH.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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) <br />
* For example, SNOMEDCT,NCI,MSH.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum (resp. maximum) level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* For example, an annotation done with levelMin=1 & 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 levelMin=0 & levelMax=0 is equivalent to disable the is_a transitive closure expansion step.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator Restlet.<br />
<br />
|}<br />
<br />
<br />
'''Restlet Service Response'''<br />
<br />
* ObaResult is the main object returned by the Annotator Restlet service. text refers to the piece of text originally sent to the service, while resultID identifies the result. The properties annotations, dictionary, ontologies and statistics and parameters are defined hereafter. An ObaResult provides functions to export its content in different form for the user. There are three different format for the response from the Annotator Restlet service:<br />
<br />
* XML: returns XML representation of the result bean.<br />
* Text: returns the result content as plain text.<br />
* 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 ' /// ').<br />
<br />
<br />
* 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.<br />
<br />
<br />
* Concept is a representation of an ontology concept in the Annotator Restlet service ontology model represented in Figure 1. localConceptID globally identifies the concept in its original repository. preferredName is the label or preferred term for this concept (as assigned by the original repository). synonyms is a set of possible terms that represent the concept but are not preferred. isTopLevel specifies if the concept is a root concept in its ontology. localOntologyID identifies the ontology in which the concept is defined. localSemanticTypesIDs is the set of the semantic types of the concept (assigned by UMLS + T000 and T999).<br />
<br />
<br />
* Context is a representation of the context in which annotation has been done. It 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 4 possible contexts identified by their contextName:<br />
<br />
* MGREP, used to identify direct annotations done with the Mgrep concept recognizer. A MGREP context has 3 properties: termName, identifies 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.<br />
<br />
* ISA_CLOSURE, used to identify expanded annotations done with the is_a transitive closure expansion component. A ISA_CLOSURE context has 2 properties: childConceptID identifies the concept from which the annotation was derived. level specifies 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}.<br />
<br />
* MAPPING, used to identify 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.<br />
<br />
* DISTANCE, used to identify expanded annotations done with the semantic distance expansion component. A DISTANCE context has 2 properties: relatedConceptID identifies the concept from which the annotation was derived. distance specifies the distance (as an integer) between the 2 concepts.<br />
<br />
* 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.<br />
<br />
* Ontology is a representation of an ontology in the Annotator Restlet service ontology model represented in Figure 1. 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.<br />
<br />
<br />
* 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.<br />
<br />
<br />
* Parameters summarizes all the parameters specified by the user when requesting the Annotator Restlet service. Those parameters are described in section Service parameters</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=8748Annotator User Guide2009-05-05T21:24:15Z<p>Cyoun: </p>
<hr />
<div>'''Sample HTTP Client for the Annotator Restlet'''<br />
<br />
HTML http://ncbo-obs-prod1:8080/test_oba.html<br />
<br />
----<br />
<br />
<br />
'''Restlet Service Parameters'''<br />
<br />
The Annotator Restlet service offers a set of parameters that allows a user to customize the annotator work flow and filter the result. To customize the work flow 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 work flow can be parametrized.<br />
<br />
The Annotator Restlet service level agreement (e.g., 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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="5%"|{true, false}<br />
|width="5%"|default: false<br />
|width="80%"|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.<br />
<br />
* For example: the phrase 'skin neoplasms' if longestOnly=true will match to the concept NCI/C0037286 (Skin Neoplasms) and NCI/C0027651 (Neoplasms). If longestOnly=false, the concept NCI/C1123023(Skin) will also match.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="5%"|{true, false}<br />
|width="5%"|default: true<br />
|width="80%"|Specifies whether the concept recognition step must match whole words only or not, if they are several concepts that match to a given word.<br />
* For example: the phrase 'neoplasms' if wholeWordOnly=true will match to 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).<br />
* Note that the concept recognition step does not consider text cast.<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|width="70%"|Specifies whether to use stop words or not. The default stop word list are available from sample HTML page. If set to true, this override the value of stopWords given by the user.<br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|width="70%"|Specifies the list of ontologies to use to expand in 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)<br />
* For example, SNOMEDCT,NCI,13578,36625,MSH.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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) <br />
* For example, SNOMEDCT,NCI,MSH.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum (resp. maximum) level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* For example, an annotation done with levelMin=1 & 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 levelMin=0 & levelMax=0 is equivalent to disable the is_a transitive closure expansion step.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator Restlet.<br />
<br />
|}<br />
<br />
<br />
'''Restlet Service Response'''<br />
<br />
* ObaResult is the main object returned by the Annotator Restlet service. text refers to the piece of text originally sent to the service, while resultID identifies the result. The properties annotations, dictionary, ontologies and statistics and parameters are defined hereafter. An ObaResult provides functions to export its content in different form for the user. There are three different format for the response from the Annotator Restlet service:<br />
<br />
* XML: returns XML representation of the result bean.<br />
* Text: returns the result content as plain text.<br />
* 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 ' /// ').<br />
<br />
<br />
* 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.<br />
<br />
<br />
* Concept is a representation of an ontology concept in the Annotator Restlet service ontology model represented in Figure 1. localConceptID globally identifies the concept in its original repository. preferredName is the label or preferred term for this concept (as assigned by the original repository). synonyms is a set of possible terms that represent the concept but are not preferred. isTopLevel specifies if the concept is a root concept in its ontology. localOntologyID identifies the ontology in which the concept is defined. localSemanticTypesIDs is the set of the semantic types of the concept (assigned by UMLS + T000 and T999).<br />
<br />
<br />
* Context is a representation of the context in which annotation has been done. It 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 4 possible contexts identified by their contextName:<br />
<br />
* MGREP, used to identify direct annotations done with the Mgrep concept recognizer. A MGREP context has 3 properties: termName, identifies 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.<br />
<br />
* ISA_CLOSURE, used to identify expanded annotations done with the is_a transitive closure expansion component. A ISA_CLOSURE context has 2 properties: childConceptID identifies the concept from which the annotation was derived. level specifies 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}.<br />
<br />
* MAPPING, used to identify 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.<br />
<br />
* DISTANCE, used to identify expanded annotations done with the semantic distance expansion component. A DISTANCE context has 2 properties: relatedConceptID identifies the concept from which the annotation was derived. distance specifies the distance (as an integer) between the 2 concepts.<br />
<br />
* 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.<br />
<br />
* Ontology is a representation of an ontology in the Annotator Restlet service ontology model represented in Figure 1. 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.<br />
<br />
<br />
* 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.<br />
<br />
<br />
* Parameters summarizes all the parameters specified by the user when requesting the Annotator Restlet service. Those parameters are described in section Service parameters</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=8747Annotator User Guide2009-05-05T21:23:37Z<p>Cyoun: </p>
<hr />
<div>'''Sample HTTP Client for the Annotator Restlet'''<br />
<br />
HTML http://ncbo-obs-prod1:8080/test_oba.html<br />
<br />
----<br />
<br />
<br />
'''Restlet Service Parameters'''<br />
<br />
The Annotator Restlet service offers a set of parameters that allows a user to customize the annotator work flow and filter the result. To customize the work flow 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 work flow can be parametrized.<br />
<br />
The Annotator Restlet service level agreement (e.g., 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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="5%"|{true, false}<br />
|width="5%"|default: false<br />
|width="80%"|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.<br />
<br />
For example: the phrase 'skin neoplasms' if longestOnly=true will match to the concept NCI/C0037286 (Skin Neoplasms) and NCI/C0027651 (Neoplasms). If longestOnly=false, the concept NCI/C1123023, (Skin) will also match.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="5%"|{true, false}<br />
|width="5%"|default: true<br />
|width="80%"|Specifies whether the concept recognition step must match whole words only or not, if they are several concepts that match to a given word.<br />
* For example: the phrase 'neoplasms' if wholeWordOnly=true will match to 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).<br />
* Note that the concept recognition step does not consider text cast.<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|width="70%"|Specifies whether to use stop words or not. The default stop word list are available from sample HTML page. If set to true, this override the value of stopWords given by the user.<br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|width="70%"|Specifies the list of ontologies to use to expand in 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)<br />
* For example, SNOMEDCT,NCI,13578,36625,MSH.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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) <br />
* For example, SNOMEDCT,NCI,MSH.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum (resp. maximum) level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* For example, an annotation done with levelMin=1 & 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 levelMin=0 & levelMax=0 is equivalent to disable the is_a transitive closure expansion step.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator Restlet.<br />
<br />
|}<br />
<br />
<br />
'''Restlet Service Response'''<br />
<br />
* ObaResult is the main object returned by the Annotator Restlet service. text refers to the piece of text originally sent to the service, while resultID identifies the result. The properties annotations, dictionary, ontologies and statistics and parameters are defined hereafter. An ObaResult provides functions to export its content in different form for the user. There are three different format for the response from the Annotator Restlet service:<br />
<br />
* XML: returns XML representation of the result bean.<br />
* Text: returns the result content as plain text.<br />
* 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 ' /// ').<br />
<br />
<br />
* 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.<br />
<br />
<br />
* Concept is a representation of an ontology concept in the Annotator Restlet service ontology model represented in Figure 1. localConceptID globally identifies the concept in its original repository. preferredName is the label or preferred term for this concept (as assigned by the original repository). synonyms is a set of possible terms that represent the concept but are not preferred. isTopLevel specifies if the concept is a root concept in its ontology. localOntologyID identifies the ontology in which the concept is defined. localSemanticTypesIDs is the set of the semantic types of the concept (assigned by UMLS + T000 and T999).<br />
<br />
<br />
* Context is a representation of the context in which annotation has been done. It 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 4 possible contexts identified by their contextName:<br />
<br />
* MGREP, used to identify direct annotations done with the Mgrep concept recognizer. A MGREP context has 3 properties: termName, identifies 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.<br />
<br />
* ISA_CLOSURE, used to identify expanded annotations done with the is_a transitive closure expansion component. A ISA_CLOSURE context has 2 properties: childConceptID identifies the concept from which the annotation was derived. level specifies 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}.<br />
<br />
* MAPPING, used to identify 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.<br />
<br />
* DISTANCE, used to identify expanded annotations done with the semantic distance expansion component. A DISTANCE context has 2 properties: relatedConceptID identifies the concept from which the annotation was derived. distance specifies the distance (as an integer) between the 2 concepts.<br />
<br />
* 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.<br />
<br />
* Ontology is a representation of an ontology in the Annotator Restlet service ontology model represented in Figure 1. 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.<br />
<br />
<br />
* 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.<br />
<br />
<br />
* Parameters summarizes all the parameters specified by the user when requesting the Annotator Restlet service. Those parameters are described in section Service parameters</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=8746Annotator User Guide2009-05-05T21:20:59Z<p>Cyoun: </p>
<hr />
<div>'''Sample HTTP Client for the Annotator Restlet'''<br />
<br />
HTML http://ncbo-obs-prod1:8080/test_oba.html<br />
<br />
----<br />
<br />
<br />
'''Restlet Service parameters'''<br />
<br />
The Annotator Restlet service offers a set of parameters that allows a user to customize the annotator work flow and filter the result. To customize the work flow 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 work flow can be parametrized.<br />
<br />
The Annotator Restlet service level agreement (e.g., 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''.<br />
<br />
Please see below for the list of parameters and the possible values.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="5%"|{true, false}<br />
|width="5%"|default: false<br />
|width="80%"|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.<br />
<br />
For example: the phrase 'skin neoplasms' if longestOnly=true will match to the concept NCI/C0037286 (Skin Neoplasms) and NCI/C0027651 (Neoplasms). If longestOnly=false, the concept NCI/C1123023, (Skin) will also match.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="5%"|{true, false}<br />
|width="5%"|default: true<br />
|width="80%"|Specifies whether the concept recognition step must match whole words only or not, if they are several concepts that match to a given word.<br />
* For example: the phrase 'neoplasms' if wholeWordOnly=true will match to 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).<br />
* Note that the concept recognition step does not consider text cast.<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|width="70%"|Specifies whether to use stop words or not. The default stop word list are available from sample HTML page. If set to true, this override the value of stopWords given by the user.<br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|width="70%"|Specifies the list of ontologies to use to expand in 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)<br />
* For example, SNOMEDCT,NCI,13578,36625,MSH.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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) <br />
* For example, SNOMEDCT,NCI,MSH.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum (resp. maximum) level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* For example, an annotation done with levelMin=1 & 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 levelMin=0 & levelMax=0 is equivalent to disable the is_a transitive closure expansion step.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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''.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator Restlet.<br />
<br />
|}<br />
<br />
<br />
'''Restlet Service Response'''<br />
<br />
* ObaResult is the main object returned by the Annotator Restlet service. text refers to the piece of text originally sent to the service, while resultID identifies the result. The properties annotations, dictionary, ontologies and statistics and parameters are defined hereafter. An ObaResult provides functions to export its content in different form for the user. There are three different format for the response from the Annotator Restlet service:<br />
<br />
* XML: returns XML representation of the result bean.<br />
* Text: returns the result content as plain text.<br />
* 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 ' /// ').<br />
<br />
<br />
* 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.<br />
<br />
<br />
* Concept is a representation of an ontology concept in the Annotator Restlet service ontology model represented in Figure 1. localConceptID globally identifies the concept in its original repository. preferredName is the label or preferred term for this concept (as assigned by the original repository). synonyms is a set of possible terms that represent the concept but are not preferred. isTopLevel specifies if the concept is a root concept in its ontology. localOntologyID identifies the ontology in which the concept is defined. localSemanticTypesIDs is the set of the semantic types of the concept (assigned by UMLS + T000 and T999).<br />
<br />
<br />
* Context is a representation of the context in which annotation has been done. It 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 4 possible contexts identified by their contextName:<br />
<br />
* MGREP, used to identify direct annotations done with the Mgrep concept recognizer. A MGREP context has 3 properties: termName, identifies 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.<br />
<br />
* ISA_CLOSURE, used to identify expanded annotations done with the is_a transitive closure expansion component. A ISA_CLOSURE context has 2 properties: childConceptID identifies the concept from which the annotation was derived. level specifies 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}.<br />
<br />
* MAPPING, used to identify 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.<br />
<br />
* DISTANCE, used to identify expanded annotations done with the semantic distance expansion component. A DISTANCE context has 2 properties: relatedConceptID identifies the concept from which the annotation was derived. distance specifies the distance (as an integer) between the 2 concepts.<br />
<br />
* 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.<br />
<br />
* Ontology is a representation of an ontology in the Annotator Restlet service ontology model represented in Figure 1. 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.<br />
<br />
<br />
* 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.<br />
<br />
<br />
* Parameters summarizes all the parameters specified by the user when requesting the Annotator Restlet service. Those parameters are described in section Service parameters</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=8745Annotator User Guide2009-05-05T21:10:19Z<p>Cyoun: </p>
<hr />
<div>'''Sample HTTP Client for the Annotator Restlet'''<br />
<br />
HTML http://ncbo-obs-prod1:8080/test_oba.html<br />
<br />
----<br />
<br />
<br />
'''Restlet Service parameters'''<br />
<br />
The Annotator Restlet service offers a set of parameters that allows a user to customize the annotations created according to his specific requirements. Especially, the annotation work flow can be limited to use a specific set of ontologies and a specific set of semantic types. Plus, the two steps of the annotation work flow can be parametrized.<br />
<br />
The Annotator Restlet service level agreement (e.g., 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''.<br />
<br />
The list of parameters and they possible values is specified here.<br />
<br />
<br />
{| border="1" cellpadding="2"<br />
|-valign="top"<br />
|width="10%"|'''longestOnly'''<br />
|width="5%"|{true, false}<br />
|width="5%"|default: false<br />
|width="80%"|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.<br />
<br />
For example: the phrase 'skin neoplasms' if longestOnly=true will match to the concept NCI/C0037286 (Skin Neoplasms) and NCI/C0027651 (Neoplasms). If longestOnly=false, the concept NCI/C1123023, (Skin) will also match.<br />
<br />
|-valign="top"<br />
|width="10%"|'''wholeWordOnly'''<br />
|width="5%"|{true, false}<br />
|width="5%"|default: true<br />
|width="80%"|Specifies whether the concept recognition step must match whole words only or not, if they are several concepts that match to a given word.<br />
* For example: the phrase 'neoplasms' if wholeWordOnly=true will match to 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).<br />
* Note that the concept recognition step does not consider text cast.<br />
|-valign="top"<br />
|width="10%"|'''stopWords'''<br />
|width="10%"|{stopWord1,...,stopWordN}<br />
|width="10%"|default: empty (i.e. none)<br />
|width="70%"|Specifies the list of stop words to use. <br />
|-valign="top"<br />
|width="10%"|'''withDefaultStopWords'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: false<br />
|width="70%"|Specifies whether to use stop words or not. The default stop word list are available from sample HTML page. If set to true, this override the value of stopWords given by the user.<br />
|-valign="top"<br />
|width="10%"|'''scored'''<br />
|width="10%"|{true, false}<br />
|width="10%"|default: true<br />
|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.<br />
* 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.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToExpand'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|width="70%"|Specifies the list of ontologies to use to expand in 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)<br />
* For example, SNOMEDCT,NCI,13578,36625,MSH.<br />
|-valign="top"<br />
|width="10%"|'''ontologiesToKeepInResult'''<br />
|width="10%"|{localOntology1,...,localOntologyN}<br />
|width="10%"|default: empty (i.e. all ontologies)<br />
|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) <br />
* For example, SNOMEDCT,NCI,MSH.<br />
|-valign="top"<br />
|width="10%"|'''semanticTypes'''<br />
|width="10%"|{semanticType1,...,semanticTypeN} <br />
|width="10%"|default: empty (i.e. all semanticTypes)<br />
|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.<br />
* For example, T047,T048,T191.<br />
|-valign="top"<br />
|width="10%"|'''levelMax'''<br />
|width="10%"|{integer} <br />
|width="10%"|default: 0<br />
|width="70%"|Specifies the minimum (resp. maximum) level a parent concept must have to be considered for the is_a semantic closure expansion step. <br />
* For example, an annotation done with levelMin=1 & 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 levelMin=0 & levelMax=0 is equivalent to disable the is_a transitive closure expansion step.<br />
|-valign="top"<br />
|width="10%"|'''mappingTypes'''<br />
|width="10%"|{null,mappingType1,...,mappingTypeN} <br />
|width="10%"|default: empty (i.e. all mappingTypes)<br />
|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.<br />
* For example, from-mrrel,Human.<br />
* 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 ontologies '''ontologiesToExpand''' and '''ontologiesToKeepInResult'''.<br />
<br />
|-valign="top"<br />
|width="10%"|'''textToAnnotate'''<br />
|width="10%"|<br />
|width="10%"|<br />
|width="70%"|Specifies the text to be annotated<br />
|-valign="top"<br />
|width="10%"|'''format'''<br />
|width="10%"|{xml,text,tabDelimited}<br />
|width="10%"|default: xml<br />
|width="70%"|Specifies the desired format of the response from Annotator Restlet.<br />
<br />
|}<br />
<br />
<br />
'''Restlet Service Response'''<br />
<br />
* ObaResult is the main object returned by the Annotator Restlet service. text refers to the piece of text originally sent to the service, while resultID identifies the result. The properties annotations, dictionary, ontologies and statistics and parameters are defined hereafter. An ObaResult provides functions to export its content in different form for the user. There are three different format for the response from the Annotator Restlet service:<br />
<br />
* XML: returns XML representation of the result bean.<br />
* Text: returns the result content as plain text.<br />
* 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 ' /// ').<br />
<br />
<br />
* 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.<br />
<br />
<br />
* Concept is a representation of an ontology concept in the Annotator Restlet service ontology model represented in Figure 1. localConceptID globally identifies the concept in its original repository. preferredName is the label or preferred term for this concept (as assigned by the original repository). synonyms is a set of possible terms that represent the concept but are not preferred. isTopLevel specifies if the concept is a root concept in its ontology. localOntologyID identifies the ontology in which the concept is defined. localSemanticTypesIDs is the set of the semantic types of the concept (assigned by UMLS + T000 and T999).<br />
<br />
<br />
* Context is a representation of the context in which annotation has been done. It 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 4 possible contexts identified by their contextName:<br />
<br />
* MGREP, used to identify direct annotations done with the Mgrep concept recognizer. A MGREP context has 3 properties: termName, identifies 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.<br />
<br />
* ISA_CLOSURE, used to identify expanded annotations done with the is_a transitive closure expansion component. A ISA_CLOSURE context has 2 properties: childConceptID identifies the concept from which the annotation was derived. level specifies 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}.<br />
<br />
* MAPPING, used to identify 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.<br />
<br />
* DISTANCE, used to identify expanded annotations done with the semantic distance expansion component. A DISTANCE context has 2 properties: relatedConceptID identifies the concept from which the annotation was derived. distance specifies the distance (as an integer) between the 2 concepts.<br />
<br />
* 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.<br />
<br />
* Ontology is a representation of an ontology in the Annotator Restlet service ontology model represented in Figure 1. 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.<br />
<br />
<br />
* 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.<br />
<br />
<br />
* Parameters summarizes all the parameters specified by the user when requesting the Annotator Restlet service. Those parameters are described in section Service parameters</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=8739Annotator User Guide2009-05-05T18:23:23Z<p>Cyoun: </p>
<hr />
<div>'''Sample HTTP Client for the Annotator Restlet'''<br />
<br />
HTML http://ncbo-obs-prod1:8080/test_oba.html<br />
<br />
----<br />
<br />
<br />
'''Restlet Service parameters'''<br />
<br />
The Annotator Restlet service offers a set of parameters that allows a user to customize the annotations created according to his specific requirements. Especially, the annotation workflow can be limited to use a specific set of ontologies and a specific set of semantic types. Plus, the two steps of the annotation workflow can be parameterized.<br />
<br />
The Annotator Restlet service level agreement (e.g., 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.<br />
<br />
The list of parameters and they possible values is specified here after:<br />
<br />
* longestOnly={true, false} (default: false)<br />
<br />
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.<br />
<br />
For example: the phrase 'skin neoplasms' if longestOnly=true will match to the concept NCI/C0037286 (Skin Neoplasms) and NCI/C0027651 (Neoplasms). If longestOnly=false, the concept NCI/C1123023, (Skin) will also match.<br />
<br />
The by default setting is longestOnly=false.<br />
<br />
* wholeWordOnly={true, false} (default: true)<br />
<br />
Specifies whether the concept recognition step must match whole words only or not, if they are several concepts that match to a given word.<br />
<br />
For example: the phrase 'neoplasms' if wholeWordOnly=true will match to 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).<br />
<br />
The by default setting is wholeWordOnly=true.<br />
<br />
Note that the concept recognition step does not consider text cast.<br />
<br />
* stopWords={true, false} (default: empty)<br />
<br />
Specifies the list of stop words to use. <br />
<br />
* withDefaultStopWords true false [default: false]<br />
<br />
Specifies whether to use stop words or not. The default stop word list are available from sample HTML page. If set to true, this override the value of stopWords given by the user.<br />
<br />
* scored={true, false} (default: true)<br />
<br />
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.<br />
<br />
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.<br />
<br />
The by default setting is scored=true.<br />
<br />
* ontologiesToExpand={localOntology1,...,localOntologyN} (default: all ontologies)<br />
<br />
Specifies the list of ontologies to use to expand in 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)<br />
<br />
For example, SNOMEDCT,NCI,13578,36625,MSH.<br />
<br />
The by default setting is to use all ontologies.<br />
<br />
* ontologiesToExpand={localOntology1,...,localOntologyN} (default: all ontologies)<br />
<br />
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) <br />
<br />
For example, SNOMEDCT,NCI,MSH.<br />
<br />
The by default setting is to use all ontologies.<br />
<br />
* semanticTypess={semanticType1,...,semanticTypeN} (default: all semanticTypes)<br />
<br />
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.<br />
<br />
For example, T047,T048,T191.<br />
<br />
The by default setting is to use all semantic types.<br />
<br />
* levelMax={integer} (default: 0)<br />
<br />
Specifies the minimum (resp. maximum) level a parent concept must have to be considered for the is_a semantic closure expansion step. For example, an annotation done with levelMin=1 & 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 levelMin=0 & levelMax=0 is equivalent to disable the is_a transitive closure expansion step.<br />
<br />
* mappingTypes={null,mappingType1,...,mappingTypeN} (default: all mappingTypes)<br />
<br />
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.<br />
<br />
For example, from-mrrel,Human.<br />
<br />
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 limited to the ontologies specified with the localOntologyIDs parameter.<br />
<br />
The by default setting is to use all mapping types.<br />
<br />
* textToAnnotate<br />
<br />
The text to be annotated<br />
<br />
* format={asXML,asText,asTabDelimited} (default: asXML)<br />
<br />
Specifies the format of the result of the annotation.<br />
<br />
----<br />
<br />
'''Restlet Service Response'''<br />
<br />
* ObaResult is the main object returned by the Annotator Restlet service. text refers to the piece of text originally sent to the service, while resultID identifies the result. The properties annotations, dictionary, ontologies and statistics and parameters are defined hereafter. An ObaResult provides functions to export its content in different form for the user. There are three different format for the response from the Annotator Restlet service:<br />
<br />
* XML: returns XML representation of the result bean.<br />
* Text: returns the result content as plain text.<br />
* 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 ' /// ').<br />
<br />
<br />
* 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.<br />
<br />
<br />
* Concept is a representation of an ontology concept in the Annotator Restlet service ontology model represented in Figure 1. localConceptID globally identifies the concept in its original repository. preferredName is the label or preferred term for this concept (as assigned by the original repository). synonyms is a set of possible terms that represent the concept but are not preferred. isTopLevel specifies if the concept is a root concept in its ontology. localOntologyID identifies the ontology in which the concept is defined. localSemanticTypesIDs is the set of the semantic types of the concept (assigned by UMLS + T000 and T999).<br />
<br />
<br />
* Context is a representation of the context in which annotation has been done. It 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 4 possible contexts identified by their contextName:<br />
<br />
* MGREP, used to identify direct annotations done with the Mgrep concept recognizer. A MGREP context has 3 properties: termName, identifies 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.<br />
<br />
* ISA_CLOSURE, used to identify expanded annotations done with the is_a transitive closure expansion component. A ISA_CLOSURE context has 2 properties: childConceptID identifies the concept from which the annotation was derived. level specifies 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}.<br />
<br />
* MAPPING, used to identify 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.<br />
<br />
* DISTANCE, used to identify expanded annotations done with the semantic distance expansion component. A DISTANCE context has 2 properties: relatedConceptID identifies the concept from which the annotation was derived. distance specifies the distance (as an integer) between the 2 concepts.<br />
<br />
* 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.<br />
<br />
* Ontology is a representation of an ontology in the Annotator Restlet service ontology model represented in Figure 1. 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.<br />
<br />
<br />
* 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.<br />
<br />
<br />
* Parameters summarizes all the parameters specified by the user when requesting the Annotator Restlet service. Those parameters are described in section Service parameters</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_Web_service&diff=8738Annotator Web service2009-05-05T00:43:51Z<p>Cyoun: /* Documentation */</p>
<hr />
<div>''To automatically process a piece of data text to annotate it with relevant ontology concepts and return the annotations<br />
''<br />
=== Presentation & Demonstration ===<br />
<br />
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.<br />
<br />
[[Image:OBA_service_workflow.png|thumb|OBA web service workflow]] <br />
<br />
=== Contacts ===<br />
<br />
* Community & usage: [[mailto:whetzel@stanford.edu Trish Whetzel]]<br />
* Design, utility & applications: [[mailto:nigam@stanford.edu Nigam Shah]] and [[mailto:jonquet@stanford.edu Clement Jonquet]]<br />
* Technical support: [[mailto:cyoun@stanford.edu Cherie Youn]]<br />
<br />
=== Documentation ===<br />
<br />
* 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.<br />
<br />
* Annotator Restlet User's Guide [[Annotator_User_Guide]]<br />
<br />
=== Versions (prototypes & releases) ===<br />
<br />
* April 2009 - First production version to come.<br />
<br />
* March 2009 - Prototype user interface has been deployed on the BioPortal staging server. Please contact us to try it.<br />
<br />
* October 2008 - The new prototype (v1.1) has bee released for testing and evaluation. Please check it out: [http://obs.bioontology.org/oba/OBA_v1.1_rest.html]<br />
<br />
* May 2008 - First prototype (v1.0) - Has been removed from servers.<br />
<br />
=== Community ===<br />
<br />
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. [[Resources index Web services]]).<br />
<br />
Learn more about NCBO Annotator users & use cases: [[NCBO Annotator community]]</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_User_Guide&diff=8737Annotator User Guide2009-05-05T00:42:55Z<p>Cyoun: /* Annotator Restlet User's Guide */</p>
<hr />
<div>'''Service parameters'''<br />
<br />
The OBA web service offers a set of parameters that allows a user to customize the annotations created according to his specific requirements. Especially, the annotation workflow can be limited to use a specific set of ontologies and a specific set of semantic types. Plus, the two steps of the annotation workflow can be parameterized.<br />
<br />
The OBA web service level agreement (e.g., 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.<br />
<br />
The list of parameters and they possible values is specified here after:<br />
<br />
* longestOnly={true, false} (default: false)<br />
<br />
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.<br />
<br />
For example: the phrase 'skin neoplasms' if longestOnly=true will match to the concept NCI/C0037286 (Skin Neoplasms) and NCI/C0027651 (Neoplasms). If longestOnly=false, the concept NCI/C1123023, (Skin) will also match.<br />
<br />
The by default setting is longestOnly=false.<br />
<br />
* wholeWordOnly={true, false} (default: true)<br />
<br />
Specifies whether the concept recognition step must match whole words only or not, if they are several concepts that match to a given word.<br />
<br />
For example: the phrase 'neoplasms' if wholeWordOnly=true will match to 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).<br />
<br />
The by default setting is wholeWordOnly=true.<br />
<br />
Note that the concept recognition step does not consider text cast.<br />
<br />
* stopWords={true, false} (default: empty)<br />
<br />
Specifies the list of stop words to use. <br />
<br />
* withDefaultStopWords true false [default: false]<br />
<br />
Specifies whether to use stop words or not. The default stop word list are available from sample HTML page. If set to true, this override the value of stopWords given by the user.<br />
<br />
* scored={true, false} (default: true)<br />
<br />
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.<br />
<br />
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.<br />
<br />
The by default setting is scored=true.<br />
<br />
* ontologiesToExpand={localOntology1,...,localOntologyN} (default: all ontologies)<br />
<br />
Specifies the list of ontologies to use to expand in 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)<br />
<br />
For example, SNOMEDCT,NCI,13578,36625,MSH.<br />
<br />
The by default setting is to use all ontologies.<br />
<br />
* ontologiesToExpand={localOntology1,...,localOntologyN} (default: all ontologies)<br />
<br />
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) <br />
<br />
For example, SNOMEDCT,NCI,MSH.<br />
<br />
The by default setting is to use all ontologies.<br />
<br />
* semanticTypess={semanticType1,...,semanticTypeN} (default: all semanticTypes)<br />
<br />
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.<br />
<br />
For example, T047,T048,T191.<br />
<br />
The by default setting is to use all semantic types.<br />
<br />
* levelMax={integer} (default: 0)<br />
<br />
Specifies the minimum (resp. maximum) level a parent concept must have to be considered for the is_a semantic closure expansion step. For example, an annotation done with levelMin=1 & 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 levelMin=0 & levelMax=0 is equivalent to disable the is_a transitive closure expansion step.<br />
<br />
* mappingTypes={null,mappingType1,...,mappingTypeN} (default: all mappingTypes)<br />
<br />
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.<br />
<br />
For example, from-mrrel,Human.<br />
<br />
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 limited to the ontologies specified with the localOntologyIDs parameter.<br />
<br />
The by default setting is to use all mapping types.<br />
<br />
* textToAnnotate<br />
<br />
The text to be annotated<br />
<br />
* format={asXML,asText,asTabDelimited} (default: asXML)<br />
<br />
Specifies the format of the result of the annotation.</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_Web_service&diff=8736Annotator Web service2009-05-05T00:18:17Z<p>Cyoun: /* Documentation */</p>
<hr />
<div>''To automatically process a piece of data text to annotate it with relevant ontology concepts and return the annotations<br />
''<br />
=== Presentation & Demonstration ===<br />
<br />
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.<br />
<br />
[[Image:OBA_service_workflow.png|thumb|OBA web service workflow]] <br />
<br />
=== Contacts ===<br />
<br />
* Community & usage: [[mailto:whetzel@stanford.edu Trish Whetzel]]<br />
* Design, utility & applications: [[mailto:nigam@stanford.edu Nigam Shah]] and [[mailto:jonquet@stanford.edu Clement Jonquet]]<br />
* Technical support: [[mailto:cyoun@stanford.edu Cherie Youn]]<br />
<br />
=== Documentation ===<br />
<br />
* 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.<br />
<br />
* Annotator User's Guide [[Annotator_User_Guide]]<br />
<br />
=== Versions (prototypes & releases) ===<br />
<br />
* April 2009 - First production version to come.<br />
<br />
* March 2009 - Prototype user interface has been deployed on the BioPortal staging server. Please contact us to try it.<br />
<br />
* October 2008 - The new prototype (v1.1) has bee released for testing and evaluation. Please check it out: [http://obs.bioontology.org/oba/OBA_v1.1_rest.html]<br />
<br />
* May 2008 - First prototype (v1.0) - Has been removed from servers.<br />
<br />
=== Community ===<br />
<br />
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. [[Resources index Web services]]).<br />
<br />
Learn more about NCBO Annotator users & use cases: [[NCBO Annotator community]]</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_Web_service&diff=8734Annotator Web service2009-05-05T00:12:51Z<p>Cyoun: /* Documentation */</p>
<hr />
<div>''To automatically process a piece of data text to annotate it with relevant ontology concepts and return the annotations<br />
''<br />
=== Presentation & Demonstration ===<br />
<br />
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.<br />
<br />
[[Image:OBA_service_workflow.png|thumb|OBA web service workflow]] <br />
<br />
=== Contacts ===<br />
<br />
* Community & usage: [[mailto:whetzel@stanford.edu Trish Whetzel]]<br />
* Design, utility & applications: [[mailto:nigam@stanford.edu Nigam Shah]] and [[mailto:jonquet@stanford.edu Clement Jonquet]]<br />
* Technical support: [[mailto:cyoun@stanford.edu Cherie Youn]]<br />
<br />
=== Documentation ===<br />
<br />
* 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.<br />
<br />
* Annotator User's Guide [[/Annotator_User_Guide]]<br />
<br />
=== Versions (prototypes & releases) ===<br />
<br />
* April 2009 - First production version to come.<br />
<br />
* March 2009 - Prototype user interface has been deployed on the BioPortal staging server. Please contact us to try it.<br />
<br />
* October 2008 - The new prototype (v1.1) has bee released for testing and evaluation. Please check it out: [http://obs.bioontology.org/oba/OBA_v1.1_rest.html]<br />
<br />
* May 2008 - First prototype (v1.0) - Has been removed from servers.<br />
<br />
=== Community ===<br />
<br />
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. [[Resources index Web services]]).<br />
<br />
Learn more about NCBO Annotator users & use cases: [[NCBO Annotator community]]</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_Web_service&diff=8733Annotator Web service2009-05-05T00:00:17Z<p>Cyoun: </p>
<hr />
<div>''To automatically process a piece of data text to annotate it with relevant ontology concepts and return the annotations<br />
''<br />
=== Presentation & Demonstration ===<br />
<br />
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.<br />
<br />
[[Image:OBA_service_workflow.png|thumb|OBA web service workflow]] <br />
<br />
=== Contacts ===<br />
<br />
* Community & usage: [[mailto:whetzel@stanford.edu Trish Whetzel]]<br />
* Design, utility & applications: [[mailto:nigam@stanford.edu Nigam Shah]] and [[mailto:jonquet@stanford.edu Clement Jonquet]]<br />
* Technical support: [[mailto:cyoun@stanford.edu Cherie Youn]]<br />
<br />
=== Documentation ===<br />
<br />
* 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.<br />
<br />
* Annotator User's Guide<br />
<br />
=== Versions (prototypes & releases) ===<br />
<br />
* April 2009 - First production version to come.<br />
<br />
* March 2009 - Prototype user interface has been deployed on the BioPortal staging server. Please contact us to try it.<br />
<br />
* October 2008 - The new prototype (v1.1) has bee released for testing and evaluation. Please check it out: [http://obs.bioontology.org/oba/OBA_v1.1_rest.html]<br />
<br />
* May 2008 - First prototype (v1.0) - Has been removed from servers.<br />
<br />
=== Community ===<br />
<br />
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. [[Resources index Web services]]).<br />
<br />
Learn more about NCBO Annotator users & use cases: [[NCBO Annotator community]]</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Annotator_Web_service&diff=8732Annotator Web service2009-05-04T23:57:38Z<p>Cyoun: /* Documentation */</p>
<hr />
<div>''To automatically process a piece of data text to annotate it with relevant ontology concepts and return the annotations<br />
''<br />
=== Presentation & Demonstration ===<br />
<br />
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.<br />
<br />
[[Image:OBA_service_workflow.png|thumb|OBA web service workflow]] <br />
<br />
=== Contacts ===<br />
<br />
* Community & usage: [[mailto:whetzel@stanford.edu Trish Whetzel]]<br />
* Design, utility & applications: [[mailto:nigam@stanford.edu Nigam Shah]] and [[mailto:jonquet@stanford.edu Clement Jonquet]]<br />
* Technical support: [[mailto:cyoun@stanford.edu Cherie Youn]]<br />
<br />
=== Documentation ===<br />
<br />
* 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.<br />
<br />
* Annotator User's Guide<br />
<br />
=== Versions (prototypes & releases) ===<br />
<br />
* April 2009 - First production version to come.<br />
<br />
* March 2009 - Prototype user interface has been deployed on the BioPortal staging server. Please contact us to try it.<br />
<br />
* October 2008 - The new prototype (v1.1) has bee released for testing and evaluation. Please check it out: [http://obs.bioontology.org/oba/OBA_v1.1_rest.html]<br />
<br />
* May 2008 - First prototype (v1.0) - Has been removed from servers.<br />
<br />
=== Community ===<br />
<br />
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. [[Resources index Web services]]).<br />
<br />
Learn more about NCBO Annotator users & use cases: [[NCBO Annotator community]]</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=File:BioPortal2.0_User_Guide_v2.doc&diff=7569File:BioPortal2.0 User Guide v2.doc2008-08-25T23:41:05Z<p>Cyoun: </p>
<hr />
<div></div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Shared_Materials&diff=7568Shared Materials2008-08-25T23:37:44Z<p>Cyoun: /* NCBO Documents */</p>
<hr />
<div>This page lists materials shared among members of NCBO<br />
==NCBO Documents==<br />
[[Public Requirements]]<br />
<br />
[[Media:cbio-r01-plan.v11.doc|Collaboration Plan]]<br />
<br />
[[Media:cBiO-5-pg Center Overview.v3.doc|Center Overview 5-page document]]<br />
<br />
[[Media:cbio_flyer_v3.pdf|NCBO Brochure]]<br />
<br />
[[Media:OBO-Foundry.doc|OBO Foundry]]<br />
<br />
[[Media:BioPortal2.0_User_Guide_v2.doc|BioPortal 2.0 Restful URI Documentation]]<br />
<br />
[[Media:BioPortal2.0_Admin_Guide_v2.doc|BioPortal 2.0 Restful URI Documentation (with Admin role)]]<br />
<br />
==NCBO Policies and Guidelines==<br />
[[Citing the Center]]<br />
<br />
[[Acknowledgements in NCBO Papers]]<br />
<br />
==PowerPoint Presentations==<br />
<br />
===Project meeting March 2006 Talks===<br />
<br />
*[[Media:OBO-Core-Criteria.ppt|OBO Core Criteria, Barry Smith slides]]<br />
*[[Media:AHM_Ashburner.ppt|Cambridge: Ashburner]]<br />
*[[Media:AHM_Barry.ppt|Buffalo: Smith]]<br />
*[[Media:AHM_Core1.ppt|Stanford: Murphy]]<br />
*[[Media:AHM_LexGrid.ppt|Mayo: Buntrock]]<br />
*[[Media:AHM_Monte.ppt|UOregon: Westerfield]]<br />
*[[Media:AHM_Sim.ppt|UCSF: Sim]]<br />
*[[Media:AHM_Peggy.ppt|UVic: Storey]]<br />
*[[Media:AHM_Suzi.ppt|Berkeley: Lewis]]<br />
*[[Media:AHM_OBD.ppt|Berkeley: Mungall]]<br />
<br />
===AMIA 2005 Talks===<br />
#[[Media:Musen AMIA Panel.ppt|Mark Musen slides]]<br />
#[[Media:AMIA_Bioontology_05.pdf|Chris Chute slides]]<br />
#[[Media:SmithpanelSemantics.ppt|Barry Smith slides]]<br />
#[[Media:AMIA_Oct2005_SLewis.ppt|Suzi Lewis slides]]<br />
<br />
===CSH Talks===<br />
#[[Media:CSHL_22Oct2005_SLewis.ppt|Suzi Lewis slides]]<br />
<br />
===NCOR Talks===<br />
#[[Media:cBio-NCOR_SLewis.ppt|Suzi Lewis slides]]<br />
<br />
===Phenotype November 2005 Talks===<br />
#[[Media:Westerfield_Pheno_CSH.ppt|Monte Westerfield slides]]<br />
#[[Media:Drysdale_Pheno_CSH.ppt|Rachel Drysdale slides]]<br />
#[[Media:Mungall_Pheno_CSH.ppt|Chris Mungall slides]]<br />
<br />
===Phenotype December 2005 Talks===<br />
* [[Media:cBioMockup_ZFIN0512.pdf|Erik Segerdell mockup]]<br />
* [[Media:cBioRequirements_ZFIN0512.doc|Melissa Haendel and Erik Segerdell requirements]]<br />
* [[Media:Uvic_viztools_Asimilar_Dec2005.ppt|Peggy Storey's (UVic) presentation on visualization]]<br />
<br />
===SMI Talk===<br />
* [[Media:OntologyJoy.ppt|Suzi SMI Talk]]<br />
<br />
===NIH Kickoff Meeting Talks Dec 2005===<br />
* [[Media:cBiO NCBC kickoff mtg.ppt|Kickoff Meeting Slides]]<br />
<br />
===HCLS===<br />
* [[Media:Musen W3C HCLS-converted.ppt|HCLS meeting]]<br />
<br />
===NIH Dissemination Event July 2006===<br />
*[http://www.bisti.nih.gov/ahm2006/Presentations/NCBO/Dissemination/Musen_AHM_Dissemination_Event.pdf Mark A. Musen: Ontology: A Vision for the Future and Its Realization]<br />
* [http://www.bisti.nih.gov/ahm2006/Presentations%5CNCBO%5CDissemination%5CSmith_OBOFoundry_071906.ppt Barry Smith: The OBO Foundry]<br />
<br />
===PATO meeting May 2006, Hinxton===<br />
*[[Media:Phenote-pato-hinxton-may-2006.ppt|Phenote slides, Mark Gibson]]<br />
<br />
===Berkeley-Stanford July 10 meeting===<br />
*[[Media:Phenote-stanford-july-2006.ppt|Phenote slides,Mark Gibson]]<br />
<br />
===ZFin early August 2006 meeting===<br />
*[[Media:Phenote-zfin-aug-1-2006.ppt|Phenote slides,Mark Gibson]]<br />
<br />
===CARO September 2006 meeting===<br />
[[Media:CARO_minutes.doc|MEETING MINUTES]]<br />
<br />
PRESENTATIONS:<br />
*[http://ontology.buffalo.edu/medo/CARO_Smith.ppt OBO Foundry Principles, Barry Smith]<br />
*[[Media:ncbo-anatomy-2006-intro-cjm.ppt|OBO Foundry principles in GO, Chris Mungall]]<br />
*[[Media:anatomy-and-stages.ppt|Stages,Chris Mungall]]<br />
*[[Media:MODs-anatomy-mah.ppt|MODs Anatomy,Melissa Haendel]]<br />
*[[Media:DOS_Seattle_SessionII.ppt|Part relationships during development, David Sutherland]]<br />
*[[Media:Homology-review.ppt|Homology Review, Melissa Haendel]]<br />
*[[Media:developing_structure_types.ppt|Classifying Developing Structures, David Sutherland]]</div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=File:BioPortal2.0_User_Guide_v2_.doc&diff=7567File:BioPortal2.0 User Guide v2 .doc2008-08-25T23:33:58Z<p>Cyoun: </p>
<hr />
<div></div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=File:BioPortal2.0_Admin_Guide_v2.doc&diff=7566File:BioPortal2.0 Admin Guide v2.doc2008-08-25T23:33:17Z<p>Cyoun: </p>
<hr />
<div></div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=File:BioPortal2.0_User_Guide_v1.doc&diff=7562File:BioPortal2.0 User Guide v1.doc2008-08-22T22:52:13Z<p>Cyoun: </p>
<hr />
<div></div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=File:BioPortal2.0_Admin_Guide_v1.doc&diff=7561File:BioPortal2.0 Admin Guide v1.doc2008-08-22T22:51:11Z<p>Cyoun: </p>
<hr />
<div></div>Cyounhttps://www.bioontology.org//mediawiki/index.php?title=Shared_Materials&diff=7560Shared Materials2008-08-22T22:46:07Z<p>Cyoun: /* NCBO Documents */</p>
<hr />
<div>This page lists materials shared among members of NCBO<br />
==NCBO Documents==<br />
[[Public Requirements]]<br />
<br />
[[Media:cbio-r01-plan.v11.doc|Collaboration Plan]]<br />
<br />
[[Media:cBiO-5-pg Center Overview.v3.doc|Center Overview 5-page document]]<br />
<br />
[[Media:cbio_flyer_v3.pdf|NCBO Brochure]]<br />
<br />
[[Media:OBO-Foundry.doc|OBO Foundry]]<br />
<br />
[[Media:BioPortal2.0_Admin_Guide_v1.doc|BioPortal 2.0 Admin Guide]]<br />
<br />
[[Media:BioPortal2.0_User_Guide_v1.doc|BioPortal 2.0 User Guide]]<br />
<br />
==NCBO Policies and Guidelines==<br />
[[Citing the Center]]<br />
<br />
[[Acknowledgements in NCBO Papers]]<br />
<br />
==PowerPoint Presentations==<br />
<br />
===Project meeting March 2006 Talks===<br />
<br />
*[[Media:OBO-Core-Criteria.ppt|OBO Core Criteria, Barry Smith slides]]<br />
*[[Media:AHM_Ashburner.ppt|Cambridge: Ashburner]]<br />
*[[Media:AHM_Barry.ppt|Buffalo: Smith]]<br />
*[[Media:AHM_Core1.ppt|Stanford: Murphy]]<br />
*[[Media:AHM_LexGrid.ppt|Mayo: Buntrock]]<br />
*[[Media:AHM_Monte.ppt|UOregon: Westerfield]]<br />
*[[Media:AHM_Sim.ppt|UCSF: Sim]]<br />
*[[Media:AHM_Peggy.ppt|UVic: Storey]]<br />
*[[Media:AHM_Suzi.ppt|Berkeley: Lewis]]<br />
*[[Media:AHM_OBD.ppt|Berkeley: Mungall]]<br />
<br />
===AMIA 2005 Talks===<br />
#[[Media:Musen AMIA Panel.ppt|Mark Musen slides]]<br />
#[[Media:AMIA_Bioontology_05.pdf|Chris Chute slides]]<br />
#[[Media:SmithpanelSemantics.ppt|Barry Smith slides]]<br />
#[[Media:AMIA_Oct2005_SLewis.ppt|Suzi Lewis slides]]<br />
<br />
===CSH Talks===<br />
#[[Media:CSHL_22Oct2005_SLewis.ppt|Suzi Lewis slides]]<br />
<br />
===NCOR Talks===<br />
#[[Media:cBio-NCOR_SLewis.ppt|Suzi Lewis slides]]<br />
<br />
===Phenotype November 2005 Talks===<br />
#[[Media:Westerfield_Pheno_CSH.ppt|Monte Westerfield slides]]<br />
#[[Media:Drysdale_Pheno_CSH.ppt|Rachel Drysdale slides]]<br />
#[[Media:Mungall_Pheno_CSH.ppt|Chris Mungall slides]]<br />
<br />
===Phenotype December 2005 Talks===<br />
* [[Media:cBioMockup_ZFIN0512.pdf|Erik Segerdell mockup]]<br />
* [[Media:cBioRequirements_ZFIN0512.doc|Melissa Haendel and Erik Segerdell requirements]]<br />
* [[Media:Uvic_viztools_Asimilar_Dec2005.ppt|Peggy Storey's (UVic) presentation on visualization]]<br />
<br />
===SMI Talk===<br />
* [[Media:OntologyJoy.ppt|Suzi SMI Talk]]<br />
<br />
===NIH Kickoff Meeting Talks Dec 2005===<br />
* [[Media:cBiO NCBC kickoff mtg.ppt|Kickoff Meeting Slides]]<br />
<br />
===HCLS===<br />
* [[Media:Musen W3C HCLS-converted.ppt|HCLS meeting]]<br />
<br />
===NIH Dissemination Event July 2006===<br />
*[http://www.bisti.nih.gov/ahm2006/Presentations/NCBO/Dissemination/Musen_AHM_Dissemination_Event.pdf Mark A. Musen: Ontology: A Vision for the Future and Its Realization]<br />
* [http://www.bisti.nih.gov/ahm2006/Presentations%5CNCBO%5CDissemination%5CSmith_OBOFoundry_071906.ppt Barry Smith: The OBO Foundry]<br />
<br />
===PATO meeting May 2006, Hinxton===<br />
*[[Media:Phenote-pato-hinxton-may-2006.ppt|Phenote slides, Mark Gibson]]<br />
<br />
===Berkeley-Stanford July 10 meeting===<br />
*[[Media:Phenote-stanford-july-2006.ppt|Phenote slides,Mark Gibson]]<br />
<br />
===ZFin early August 2006 meeting===<br />
*[[Media:Phenote-zfin-aug-1-2006.ppt|Phenote slides,Mark Gibson]]<br />
<br />
===CARO September 2006 meeting===<br />
[[Media:CARO_minutes.doc|MEETING MINUTES]]<br />
<br />
PRESENTATIONS:<br />
*[http://ontology.buffalo.edu/medo/CARO_Smith.ppt OBO Foundry Principles, Barry Smith]<br />
*[[Media:ncbo-anatomy-2006-intro-cjm.ppt|OBO Foundry principles in GO, Chris Mungall]]<br />
*[[Media:anatomy-and-stages.ppt|Stages,Chris Mungall]]<br />
*[[Media:MODs-anatomy-mah.ppt|MODs Anatomy,Melissa Haendel]]<br />
*[[Media:DOS_Seattle_SessionII.ppt|Part relationships during development, David Sutherland]]<br />
*[[Media:Homology-review.ppt|Homology Review, Melissa Haendel]]<br />
*[[Media:developing_structure_types.ppt|Classifying Developing Structures, David Sutherland]]</div>Cyoun