Annotator User Guide - Revision history

Fergerson: Replaced content with "This service has been replaced. Instead please see: http://data.bioontology.org/documentation#nav_annotator"

2014-03-03T22:46:07Z

Replaced content with "This service has been replaced. Instead please see: http://data.bioontology.org/documentation#nav_annotator"

Show changes

Whetzel: /* Annotator Web Service Parameters */

2012-07-13T08:03:07Z

Annotator Web Service Parameters

Whetzel: /* Annotator Web Service Parameters */

2012-07-13T07:57:15Z

Annotator Web Service Parameters

Whetzel: /* Annotator Web Service Response */

2011-09-28T06:25:53Z

Annotator Web Service Response

Whetzel at 15:54, 26 April 2011

2011-04-26T15:54:12Z

Whetzel: /* Annotator Web Service Parameters */

2011-03-30T21:27:18Z

Annotator Web Service Parameters

Whetzel: /* Annotator Web Service Parameters */

2011-03-30T21:23:41Z

Annotator Web Service Parameters

Whetzel: /* Annotator Web Service Response */

2011-03-28T15:30:37Z

Annotator Web Service Response

Whetzel: /* Annotator Web Service Response */

2011-03-26T02:37:56Z

Annotator Web Service Response

Whetzel: /* Annotator Web Service Response */

2011-03-26T02:34:47Z

Annotator Web Service Response

@@ Line 116: / Line 116: @@
 |width="10%"|{true, false}
 |width="10%"|default: false
-|width="70%"|Specifies whether the input values are the virtual ontology identifier instead of ontology version identifiers. The virtual ontology identifier is stable across all versions of the ontology and it is recommended that this parameter be set to true.
+|width="70%"|Specifies whether the input values are the virtual ontology identifier instead versus the ontology version identifier. The virtual ontology identifier is stable across all versions of the ontology. '''''It is strongly recommended that this parameter be set to true.'''''
 |-valign="top"
 |width="10%"|'''semanticTypes'''

@@ Line 47: / Line 47: @@
 |width="10%"|{true, false}
 |width="10%"|default: false
-|width="70%"|Specifies either or not the concept recognition step (done with University of Michigan Mgrep tool) must match the longest words only if they are several concepts that match to an expression.
+|width="70%"|Specifies whether or not the entity recognition step (done with University of Michigan Mgrep tool) must match the longest word only if they are several terms that match to an expression.
-* If ''longestOnly=true'', the Annotator selects only the longest term matching phrase. For example, if ''longestOnly=true'', the phrase ''breast cancer'' generates only ''breast cancer.'' If ''longestOnly=false'', it generates three annotations: ''breast'', ''cancer'' and ''breast cancer.''
+* If ''longestOnly=true'', the Annotator selects only the longest term matching phrase. For example, if ''longestOnly=true'', the phrase ''breast cancer'' returns only the result ''breast cancer.'' If ''longestOnly=false'', it generates three annotations: ''breast'', ''cancer'' and ''breast cancer.''
-* Attention, if the Annotator finds an annotation with the complete phrase in an ontology composing the dictionary, partial annotations with other ontologies will not be generated.  For example, because ''breast cancer'' exists in Human Disease and the NCI Thesaurus, if ''longestOnly=true'', annotations generated with those terms will block annotations with the terms ''breast'' in the Vaccine Ontology or ''cancer'' in BIRNLex. For this reason, we discourage the uses of the '''longestOnly''' parameter when the Annotator is used with one or a small number of ontologies.
+* Attention, if the Annotator finds a match  to the complete phrase in an ontology within the dictionary, partial annotations with other ontologies will not be generated.  For example, because ''breast cancer'' exists in Human Disease and the NCI Thesaurus, if ''longestOnly=true'', annotations generated with those terms will block annotations with the terms ''breast'' in the Vaccine Ontology or ''cancer'' in BIRNLex. For this reason, we discourage the uses of the '''longestOnly''' parameter when the Annotator is used with one or a small number of ontologies.
 |-valign="top"
@@ Line 57: / Line 57: @@
 |width="10%"|{true, false}
 |width="10%"|default: true
-|width="70%"|Specifies whether the concept recognition step must match whole words only or not, if they are several concepts that match to a given word.
+|width="70%"|Specifies whether the term recognition step must match whole words only or not, if they are several terms that match to a given word from the input text.
-* 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.
+* For example: If ''wholeWordOnly=true'', the phrase 'neoplasms'  will match the concept NCI/C0027651 (Neoplasms) only. If ''wholeWordOnly=false'', the term http://bioportal.bioontology.org/ontologies/47638/?p=terms&conceptid=Siemens with synonym "S" or the term http://bioportal.bioontology.org/ontologies/47638/?p=terms&conceptid=Aggressive_Systemic_Mastocytosis with synonym "ASM" will also match (~80 terms in NCI).
 * Note that the concept recognition step does not consider text cast.
@@ Line 65: / Line 65: @@
 |width="10%"|{true, false}
 |width="10%"|default: true
-|width="70%"|Specifies whether the concept recognition step to filter numbers or not.
+|width="70%"|Specifies whether the entity recognition step to filter numbers or not.
 |-valign="top"
@@ Line 76: / Line 76: @@
 |width="10%"|{true, false}
 |width="10%"|default: false
-|width="70%"|Specifies whether to use the default stop words or not. The default stop word list is available from this Web service call: http://rest.bioontology.org/obs/stopwords. If this parameter is set to true, this will override any stopWords provided by the user in the parameter "stopWords".
+|width="70%"|Specifies whether or not to use the default stop words. The default stop word list is available from this Web service call: http://rest.bioontology.org/obs/stopwords?apikey=YourAPIKey. If this parameter is set to true, this will override any stop words provided by the user in the parameter "stopWords".
 |-valign="top"
 |width="10%"|'''isStopWordsCaseSenstive  '''
 |width="10%"|{true, false}
 |width="10%"|default: false
-|width="70%"|Specifies whether stopwords are case-sensitive or not.
+|width="70%"|Specifies whether stop words are case-sensitive or not.
 |-valign="top"
 |width="10%"|'''minTermSize'''
@@ Line 91: / Line 91: @@
 |width="10%"|{true, false}
 |width="10%"|default: true
-|width="70%"|Specifies either or not the annotations are scored. A score is a number assigned to an annotation that reflects the accuracy of the annotation. The higher the score is the better the annotation is. The scoring algorithm gives a specific weight to an annotation according to the context of this annotation. For instance, an annotation done by matching a concept preferred name will be given a higher weight than an annotation done by matching a concept synonym or than an annotation done with a parent level 3 in the is_a hierarchy. Details on the scoring algorithm are given in section Scoring algorithm.
+|width="70%"|Specifies whether or not the annotations are scored. A score is a number assigned to an annotation that reflects the accuracy of the annotation. The higher the score is the better the annotation is. The scoring algorithm gives a specific weight to an annotation according to the context of this annotation. For instance, an annotation done by matching a concept preferred name will be given a higher weight than an annotation done by matching a concept synonym or than an annotation done with a parent level 3 in the is_a hierarchy. Details on the scoring algorithm are given in section Scoring algorithm.
-* For example, the phrase 'melanoma' is annotated both with the concept NCI/C0025202 (melanoma) and the concept NCI/C1522102 (Mouse Melanoma). The former annotation is scored 10 where as the latter is scored 8.
+* For example, the phrase 'melanoma' is annotated both with the term http://bioportal.bioontology.org/ontologies/47638/?p=terms&conceptid=Melanoma "melanoma" and the term http://bioportal.bioontology.org/ontologies/47638/?p=terms&conceptid=Mouse_Melanoma "Mouse Melanoma". The former annotation is scored 10 where as the latter is scored 8.
 |-valign="top"
 |width="10%"|'''withSynonyms'''
 |width="10%"|{true, false}
 |width="10%"|default: true
-|width="70%"|Specifies either or not the direct annotations are done with or without Synonyms. By default it includes all the synonyms and preferred name. If 'false' is selected, the direct annotations are done with only preferred name.
+|width="70%"|Specifies whether or not the direct annotations are generated based on term synonyms. By default it includes all the synonyms and preferred name of a term. If 'false' is selected, the direct annotations are done with only the preferred name.
 |-valign="top"
 |width="10%"|'''ontologiesToExpand'''
@@ Line 103: / Line 103: @@
 |width="10%"|default: empty (i.e. all ontologies)
 |width="70%"|Specifies the list of ontologies to use with the mapping semantic expansion component. The list of ontologies that can be used is available in the sample HTML page. The values are separated with comma (without spaces).
-* For example, 40403,40644,40401.
+* For example, 1353,1032,1351 (these numbers represent the virtual ontology identifier, which is stable across different versions of the ontology).
 * '''NOTE''': The list of ontologies that are available via the Annotator Web service are those listed with <status>28</status> from this Web service call: http://rest.bioontology.org/obs/ontologies
 |-valign="top"
@@ Line 110: / Line 110: @@
 |width="10%"|default: empty (i.e. all ontologies)
 |width="70%"|Specifies the list of ontologies to keep in the result of the annotation process. The list of ontologies that can be used is available in the sample HTML page. The values are separated with comma (without spaces).
-* For example, 40403,40644,40401.
+* For example, 1353,1032,1351 (these numbers represent the virtual ontology identifier, which is stable across different versions of the ontology).
-* '''NOTE''': The list of ontologies that are available via the Annotator Web service are those listed with <status>28</status> from this Web service call: http://rest.bioontology.org/obs/ontologies
+* '''NOTE''': The list of ontologies that are available via the Annotator Web service are those listed with <status>28</status> from this Web service call: http://rest.bioontology.org/obs/ontologies?apikey=YourAPIKey
 |-valign="top"
 |width="10%"|'''isVirtualOntologyId'''
 |width="10%"|{true, false}
 |width="10%"|default: false
-|width="70%"|Specifies whether the input values are virtualOntologyId instead of localOntologyid. VirtualOntologyId is not version-specific.
+|width="70%"|Specifies whether the input values are the virtual ontology identifier instead of ontology version identifiers. The virtual ontology identifier is stable across all versions of the ontology and it is recommended that this parameter be set to true.
 |-valign="top"
 |width="10%"|'''semanticTypes'''
 |width="10%"|{semanticType1,...,semanticTypeN}
 |width="10%"|default: empty (i.e. all semanticTypes)
-|width="70%"|Specifies the list of semantic types to use in the annotation process. The list of semantic types that can be used is available in the sample HTML page. The values are separated with comma (without spaces). Note that the restriction to semantic types is also applied during the semantic expansion steps.
+|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 from http://rest.bioontology.org/obs/semanticTypes?apikey=YourAPIKey. The values are separated with comma (without spaces). Note that the restriction to semantic types is also applied during the semantic expansion steps.
 * For example, T047,T048,T191.
 |-valign="top"
@@ Line 133: / Line 133: @@
 |width="10%"|{null,mappingType1,...,mappingTypeN}
 |width="10%"|default: empty (i.e. all mappingTypes)
-|width="70%"|Specifies the list of mapping type to use during the mapping expansion step. The list of semantic types that can be used is available in the sample HTML page. The values are separated with comma (without spaces). The current list is described hereafter.
+|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 from http://rest.bioontology.org/obs/semanticTypes?apikey=YourAPIKey. The values are separated with comma (without spaces). The current list is described hereafter.
 * For example, from-mrrel,Human.
 * Note that the use of the key word "'''null'''" in the '''mappingTypes''' list disables the mapping expansion component. Note also that the mapping expansion is also limited by other parameters such as ''ontologiesToExpand'' and ''ontologiesToKeepInResult''.

@@ Line 164: / Line 164: @@
 ===Annotator Web Service Response===
-In this section we define the Annotator Web service model i.e., what the service returns to the user: the objects as well as their relations and the constraints that applies. Cf the UML class diagram here: http://obs.bioontology.org/docs/model/EARoot/EA3/EA46.htm
+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.
 '''Response Content: annotatorResultBean'''

← Older revision		Revision as of 15:54, 26 April 2011
Line 1:		Line 1:
		+	=== Annotator Web service Validation ===
		+	* '''<font color='red'>Note</font>''': All NCBO REST Web services will be required to contain the parameter "apikey=YourApiKey" starting June 2011. The parameter will be added to all Web service calls for the April 27, 2011 release but will not be required until June 2011. To obtain an API key, login to BioPortal and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.
		+
	===Sample Clients for the Annotator===		===Sample Clients for the Annotator===

@@ Line 73: / Line 73: @@
 |width="10%"|{true, false}
 |width="10%"|default: false
-|width="70%"|Specifies whether to use the default stop words or not. The default stop word list is available from sample HTML page. If set to true, this override the value of stopWords given by the user.
+|width="70%"|Specifies whether to use the default stop words or not. The default stop word list is available from this Web service call: http://rest.bioontology.org/obs/stopwords. If this parameter is set to true, this will override any stopWords provided by the user in the parameter "stopWords".
 |-valign="top"
 |width="10%"|'''isStopWordsCaseSenstive  '''

@@ Line 68: / Line 68: @@
 |width="10%"|{stopWord1,...,stopWordN}
 |width="10%"|default: empty (i.e. none)
-|width="70%"|Specifies the list of stop words to use.
+|width="70%"|Specifies the list of words to exclude from matching.
 |-valign="top"
 |width="10%"|'''withDefaultStopWords'''

@@ Line 187: / Line 187: @@
 |-valign="top"
 |width="10%"|'''score'''
-|width="90%"| The scoring algorithm gives weight to each annotation according to the annotation context. The final score for an annotation is then calculated as the sum of all the scores of the annotations done with the same concept. Direct annotation done with a concept preferred name=10, Direct annotation done with a concept synonym=8, Expanded annotation done with a mapping=7, Expanded annotation done with a parent level n(e.g., 9 for n=1; 7 for n=2; 4 for n=5; 3 for n=8; 1 for n>12) = 1+10.e-0.2*n. Read the [http://www.ncbi.nlm.nih.gov/pubmed/20626921| Ontology Recommender] paper for more details.
+|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. Direct annotation done with a concept preferred name=10, Direct annotation done with a concept synonym=8, Expanded annotation done with a mapping=7, Expanded annotation done with a parent level n(e.g., 9 for n=1; 7 for n=2; 4 for n=5; 3 for n=8; 1 for n>12) = 1+10.e-0.2*n. Read the [http://www.ncbi.nlm.nih.gov/pubmed/20626921 OntologyRecommender] paper for more details.
 |-valign="top"