You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@stanbol.apache.org by rw...@apache.org on 2012/07/04 09:27:30 UTC
svn commit: r1357117 -
/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancementusage.mdtext
Author: rwesten
Date: Wed Jul 4 07:27:29 2012
New Revision: 1357117
URL: http://svn.apache.org/viewvc?rev=1357117&view=rev
Log:
corrected relative links
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancementusage.mdtext
Modified: incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancementusage.mdtext
URL: http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancementusage.mdtext?rev=1357117&r1=1357116&r2=1357117&view=diff
==============================================================================
--- incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancementusage.mdtext (original)
+++ incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancementusage.mdtext Wed Jul 4 07:27:29 2012
@@ -26,21 +26,21 @@ Requesting the Apache Stanbol Enhancer t
--data "The Stanbol enhancer can detect famous cities such as \
Paris and people such as Bob Marley." http://{host}:{port}/enhancer
-As response you will receive the enhancement results formatted as an RDF graph in a serialization format specified by the "Accept" header ('application/rdf+xml' in the above example request). This RDF graph contains the information about the entities extracted from the parsed content. See the documentation of the Apache Stanbol [enhancement structure](/enhancer/enhancementstructure.html) for details.
+As response you will receive the enhancement results formatted as an RDF graph in a serialization format specified by the "Accept" header ('application/rdf+xml' in the above example request). This RDF graph contains the information about the entities extracted from the parsed content. See the documentation of the Apache Stanbol [enhancement structure](enhancer/enhancementstructure.html) for details.
The following figure shows how extracted entities are described in the enhancement results.
In principle there are two resources that are of interest for the entity tagging use case:
-1. [EntityAnnotation](/enhancer/enhancementstructure.html#fiseentityannotation)s: Resources with the 'rdf:type' 'fise:EntityAnnotation' do represent the entity suggestions by the Apache Stanbol Enhancer. This resources provide the label, type and most important the URI of the extracted entity. In addition the value of the fise:confidence' [0..1] can be used as indication how certain the Apache Stanbol Enhancer is about this entity.
+1. [EntityAnnotation](enhancer/enhancementstructure.html#fiseentityannotation)s: Resources with the 'rdf:type' 'fise:EntityAnnotation' do represent the entity suggestions by the Apache Stanbol Enhancer. This resources provide the label, type and most important the URI of the extracted entity. In addition the value of the fise:confidence' [0..1] can be used as indication how certain the Apache Stanbol Enhancer is about this entity.
2. Entities: This refers to all resources with an incoming 'fise:entity-reference' relation (such as 'dbpedia:Bob_Marley' in the above example). Enhancement engines can be configured to "dereference" suggested entities - meaning to use the URI of the entity to retrieve additional information. In this case, additional information about suggested entities will be available in the enhancement results. If this in not the case, users will need to dereference suggested entities themselves.
### Process Suggested Entities
The following steps are typically needed to acquire the information needed to implement an entity tagging user interface:
-1. Iterate over all suggested entities: These are all resources such as "{entity-annotation} rdf:type [fise:EntityAnnotation](/enhancer/enhancementstructure.html#fiseentityannotation)"
+1. Iterate over all suggested entities: These are all resources such as "{entity-annotation} rdf:type [fise:EntityAnnotation](enhancer/enhancementstructure.html#fiseentityannotation)"
2. Basic information: Those are available directly via the {entity-annotation} to ensure their availability even if the {entity} itself in not not included - dereferenced - in the enhancement results.
* URI of the suggested entity: {entity-annotation} fise:entity-reference {entity}
* Label: The value of the fise:entity-label is typically the label via that the entity was recognized in the analyzed content. Additional labels are typically available via the {entity}
@@ -51,14 +51,14 @@ The following steps are typically needed
### Process Content Categorizations
-'[fise:TopicAnnotation](/enhancer/enhancementstructure.html#fisetopicannotation)' instances are used to formally represent categories assigned to the parsed Content. The main difference between extracted entities and assigned categories is that extracted entities do have one or more explicit mentions within the text while assigned categories are suggested based on the document as a whole - typically they are not explicitly mentioned in the text.
+'[fise:TopicAnnotation](enhancer/enhancementstructure.html#fisetopicannotation)' instances are used to formally represent categories assigned to the parsed Content. The main difference between extracted entities and assigned categories is that extracted entities do have one or more explicit mentions within the text while assigned categories are suggested based on the document as a whole - typically they are not explicitly mentioned in the text.
Typically, an entity tagging UI will want to distinguish between categories and entities because:
* categories are used to group content (e.g. blog posts about work and private things)
* entities are used to search/suggest blog posts about specific topics (e.g. a blog about some feature implemented for "Apache Solr", a nice event in the "Sternbräu" in "Salzburg")
-The usage of '[fise:TopicAnnotation](/enhancer/enhancementstructure.html#fisetopicannotation)' is similar to an EntityAnnotation. Both annotation types use the exact same properties ('fise:entity-referene','fise:entity-label',fise:entity-type', 'fise:confidence','entityhub:site'). The only difference is that one need to iterate over '{topic-annotation} rdf:type fise:TopicAnnotaion'. So typically clients will want to use the exact same code to process {entity-annotation} and {topic-annotation} instances.
+The usage of '[fise:TopicAnnotation](enhancer/enhancementstructure.html#fisetopicannotation)' is similar to an EntityAnnotation. Both annotation types use the exact same properties ('fise:entity-referene','fise:entity-label',fise:entity-type', 'fise:confidence','entityhub:site'). The only difference is that one need to iterate over '{topic-annotation} rdf:type fise:TopicAnnotaion'. So typically clients will want to use the exact same code to process {entity-annotation} and {topic-annotation} instances.
In the next section we will describe an improved version of entity tagging is described that allows users to: (1) accept/decline a spotted entity and than (2) select one of several suggested entities.
@@ -68,7 +68,7 @@ Entity disambiguation is required if an
![Entity Disambiguation](enhancer/es_entitydisambiguation.png "Bob Marley as spotted in the text may refer to two different persons in DBpedia.org)
-The fact that one entity detected in the text - represented by a '[fise:TextAnnotation](/enhancer/enhancementstructure.html#fisetextannotation)' may have multiple suggested entities - represented by the two 'fise:EntityAnnotation's - has a negative impact on [entity tagging](#entity-tagging) interface that suggest tags based on 'fise:entityAnnotation's. This is because such an interface would show in the above case two suggestions: (1) for ['dbpedia:Bob_Marley'](http:dbpedia.org/resource/Bob_Marley) and (2) for [dbpedia:Bob_Marley_(comedian)](http://dbpedia.org/resource/Bob_Marley_%28comedian%29). So even if the user want to tag this content with "Bob Marley", she will need to reject at least one of the two suggestions.
+The fact that one entity detected in the text - represented by a '[fise:TextAnnotation](enhancer/enhancementstructure.html#fisetextannotation)' may have multiple suggested entities - represented by the two 'fise:EntityAnnotation's - has a negative impact on [entity tagging](#entity-tagging) interface that suggest tags based on 'fise:entityAnnotation's. This is because such an interface would show in the above case two suggestions: (1) for ['dbpedia:Bob_Marley'](http:dbpedia.org/resource/Bob_Marley) and (2) for [dbpedia:Bob_Marley_(comedian)](http://dbpedia.org/resource/Bob_Marley_%28comedian%29). So even if the user want to tag this content with "Bob Marley", she will need to reject at least one of the two suggestions.
Adding explicit support for entity disambiguation to an entity tagging user interface can solve this problem by grouping suggested entities along 'fise:TextAnnotation's they are suggested for.
@@ -78,9 +78,9 @@ The goal of an entity tagging UI with di
There are several options on how to achieve this. We present a solution that iterates over the 'fise:EntityAnnotation's.
-1. Iterate over all '[fise:EntityAnnotation](/enhancer/enhancementstructure.html#fiseentityannotation)' instances. This refers to all resources such as "{entity-annotation} rdf:type fise:EntityAnnotation".
+1. Iterate over all '[fise:EntityAnnotation](enhancer/enhancementstructure.html#fiseentityannotation)' instances. This refers to all resources such as "{entity-annotation} rdf:type fise:EntityAnnotation".
* For more information on how to collect information for extracted entities see the [according section](#process-suggested-entities) in the [entity tagging](#entity-tagging) interface.
-2. Retrieve the '[fise:TextAnnotation](/enhancer/enhancementstructure.html#fisetextannotation)' referenced by processed 'fise:EntityAnnotation's. For this, we retrieve the value(s) of the 'dc:relation' property.
+2. Retrieve the '[fise:TextAnnotation](enhancer/enhancementstructure.html#fisetextannotation)' referenced by processed 'fise:EntityAnnotation's. For this, we retrieve the value(s) of the 'dc:relation' property.
3. While iterating over the 'fise:EntityAnnotation's establish a mapping 'fise:TextAnnotation' -> 'fise:EntityAnnotation','fise:EntityAnnotation, ...
* the list of 'fise:EntityAnnotation's for each 'fise:TextAnnotation' needs to be sorted based on the value of the 'fise:confidence' property of the EntityAnnotation. Ensure that the EntityAnnotation with the higher confidence is first in the list. 'fise:confidence' values are in the range 0..1 where higher numbers represent a higher certainly.
4. Suggest tags based on 'fise:TextAnnotation's - keys in the mapping created in step (3).
@@ -93,7 +93,7 @@ To allow users to more easily disambigua
Assuming the suggested entities are grouped by 'fise:TextAnnotation' - as explained in the above section - one can use the information provided by the TextAnnotation to visualize the context and therefore helping the user performing the disambiguation task.
-The following information of the [TextAnnotation](/enhancer/enhancementstructure.html#fisetextannotation) can be used for this task:
+The following information of the [TextAnnotation](enhancer/enhancementstructure.html#fisetextannotation) can be used for this task:
* 'fise:selection-context': This is the text surrounding the extracted entity. The exact size of this context depends on the configuration and the enhancement engine. Typically it is the current sentence or about 50 charters before an after the selection.
* 'fise:selected-text': This is the text representing the extracted entity - the section of the text the entity was suggested for. The 'fise:selected-text' MUST BE contained within the 'fise:selection-context' so user interfaces to want to highlight the selected part of the context can use a contains query in the selection context for the selected text. In case of multiple matches it is typically sufficient to highlight all occurrences.
@@ -109,7 +109,7 @@ To implement user interfaces like that o
### Visualise occurrences of extracted features
-The occurrence of extracted features are represented by instances of the concept '[fise:TextAnnotation](/enhancer/enhancementstructure.html#fisetextannotation)'. The next figure shows how TextAnnotations describe the occurrence of an recognized feature in the parsed text.
+The occurrence of extracted features are represented by instances of the concept '[fise:TextAnnotation](enhancer/enhancementstructure.html#fisetextannotation)'. The next figure shows how TextAnnotations describe the occurrence of an recognized feature in the parsed text.
!['fise:TextAnnotation'](enhancer/es_textannotation.png "This figure shows a TextAnnotation describing the occurrence of "Bob Marley" located from character 59 to 69 in the given text")
@@ -117,7 +117,7 @@ Applications that want to visualize extr
Typically the following steps are required to correctly show extracted features within the content.
-1. Query for/iterate over '[fise:TextAnnotation](/enhancer/enhancementstructure.html#fisetextannotation)'s of the enhancement results.
+1. Query for/iterate over '[fise:TextAnnotation](enhancer/enhancementstructure.html#fisetextannotation)'s of the enhancement results.
* it is important to only use TextAnnotations that define a 'fise:selected-text' property. TextAnnotations that do not define this property usually select whole sections or even the document as a whole. While such TextAnnotations are important (e.g. for annotating the language of the Text) they are of no interest for this use case and need therefore to be ignored.
2. Determine the exact occurrence of the TextAnnoations
* in case of plain text content this can be easily done by using the values of 'fise:start' and 'fise:end'
@@ -148,11 +148,11 @@ _Tips and Tricks:_
### Interact with suggested entities
-This section explains how users mitt want to interact with extracted/suggested entities. Extracted entities are represented by '[fise:EntityAnnotation](/enhancer/enhancementstructure.html#fiseentityannotation)'s. Those EntityAnnotations are linked with the [TextAnnotation](/enhancer/enhancementstructure.html#fisetextannotation) (occurrences) and to the entity of the used knowledge base. The following figure shows an example for an EntityAnnotation that suggests the entity ['dbpedia:Bob_Marley'](http:dbpedia.org/resource/Bob_Marley) for the TextAnnotation used in the example of the previous section.
+This section explains how users mitt want to interact with extracted/suggested entities. Extracted entities are represented by '[fise:EntityAnnotation](enhancer/enhancementstructure.html#fiseentityannotation)'s. Those EntityAnnotations are linked with the [TextAnnotation](enhancer/enhancementstructure.html#fisetextannotation) (occurrences) and to the entity of the used knowledge base. The following figure shows an example for an EntityAnnotation that suggests the entity ['dbpedia:Bob_Marley'](http:dbpedia.org/resource/Bob_Marley) for the TextAnnotation used in the example of the previous section.
-The main purpose of [EntityAnnotation](/enhancer/enhancementstructure.html#fiseentityannotation)s is to suggest entities (e.g. ['dbpedia:Bob_Marley'](http:dbpedia.org/resource/Bob_Marley) for mentions within natural languages texts. While the above example (to keep it simple) shows only a single suggestion in practice one need to distinguish between three different cases - that also imply different interaction needs for users:
+The main purpose of [EntityAnnotation](enhancer/enhancementstructure.html#fiseentityannotation)s is to suggest entities (e.g. ['dbpedia:Bob_Marley'](http:dbpedia.org/resource/Bob_Marley) for mentions within natural languages texts. While the above example (to keep it simple) shows only a single suggestion in practice one need to distinguish between three different cases - that also imply different interaction needs for users:
1. __No suggestion__: This indicates that a named entity was recognized during natural language processing, but no matching entity was found within the knowledge base. In this case users might want to
* manually search the knowledge base for an entity. The Apache Stanbol Entityhub sites endpoint can be used to implement this feature by sending a "GET http://{host}:{port}/entityhub/sites/find?name={name}" (see the WebUI of your Stanbol instance for the detailed documentation).
@@ -168,7 +168,7 @@ The main purpose of [EntityAnnotation](/
The required data for for the described interaction patters are available within the enhancement results as follows:
-The following assumes {text-annotation} - the URI of the current '[fise:TextAnnotation](/enhancer/enhancementstructure.html#fisetextannotation)' - as context
+The following assumes {text-annotation} - the URI of the current '[fise:TextAnnotation](enhancer/enhancementstructure.html#fisetextannotation)' - as context
1. Query for/iterate over all entity suggestions: The suggestions for {text-annotation} can be acquired by using "?entityAnnotation dc:relation {text-annotation}
* only results with the the 'rdf:type' 'fise:EntityAnnotation' should be processed. However, typically all results will be any way of that type.