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/06/18 13:33:24 UTC
svn commit: r1351301 - in
/incubator/stanbol/site/trunk/content/stanbol/docs/trunk:
enhancementusage.mdtext enhancer/enhancementstructure.mdtext
Author: rwesten
Date: Mon Jun 18 11:33:23 2012
New Revision: 1351301
URL: http://svn.apache.org/viewvc?rev=1351301&view=rev
Log:
added/corrected links
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancementusage.mdtext
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancementstructure.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=1351301&r1=1351300&r2=1351301&view=diff
==============================================================================
--- incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancementusage.mdtext (original)
+++ incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancementusage.mdtext Mon Jun 18 11:33:23 2012
@@ -20,27 +20,27 @@ But this does not only work with famous
### Suggest Entities with the Stanbol Enhancer
-Requesting the Stanbol Enhancer to analyze a text requires to send an POST the the [RESTful API](enhancerrest.html) of the Stanbol Enhancer.
+Requesting the Stanbol Enhancer to analyze a text requires to send an POST the the [RESTful API](enhancer/enhancerrest.html) of the Stanbol Enhancer.
curl -X POST -H "Accept: application/rdf+xml" -H "Content-type: text/plain" \
--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 RDF graph in the serialization 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.
+As response you will receive the enhancement results formatted as RDF graph in the serialization 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 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. EntityAnnotations: Resources with the 'rdf:type' 'fise:EntityAnnotation' do represent the entity suggestions by the 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 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 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 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: This are all resources such as "{entity-annotation} rdf:type fise:EntityAnnotation"
+1. Iterate over all suggested Entities: This 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 there 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' 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 a 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 with "Apache Solr", a nice event in the "Sternbräu" in "Salzburg")
-The usage of 'fise:TopicAnnotation' is similar to EntityAnnotation. They do 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-anntoation} 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 EntityAnnotation. They do 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-anntoation} 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 "Entity Disambiguation" 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.
@@ -66,9 +66,9 @@ In the next section "Entity Disambiguati
Entity Disambiguation is required if an entity detected in the analyzed text can refer to different Entities. The following figure shows an example where "Bob Marley" is detected as a person in the text however there are two possible matches within the controlled vocabulary.
-![Entity Disambiguation](es_entitydisambiguation.png "Bob Marley as spotted in the Text may refer to two different persons in DBpedia.org)
+![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' 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" he 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" he 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 the Entity Tagging UI with d
There are several options on how to do active this. Here an option is presented that starts with iterating over 'fise:EntityAnnotation's because the assumption that one wants to improve an existing [Entity Tagging](#entity-tagging) interface.
-1. Iterate over all 'fise:EntityAnnotation' 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 simple [Entity Tagging](#entity-tagging) interface.
-2. Retrieve the 'fise:TextAnnotation' referenced by processed 'fise:EntityAnnotation's. For that one needs to 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 that one needs to 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 in with the disambiguation task.
-The following information of the TextAnnotation 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 EnhancementEngine. But 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
@@ -103,21 +103,21 @@ The following information of the TextAnn
This describes a user interface similar to one of a spell/grammar checker. But instead of marking misspelled words entities recognized within the text are suggested to the user. The following figure shows such an interface as implemented by the [hallo.js](http://hallojs.org) combined with the [annotate.js](https://github.com/szabyg/annotate.js) plugin (see the [Demo here](http://hallojs.org/annotate.html) <small>(last accessed 2012-05-30)</small> - click in the Text and press the "annotate" button).
-
+
To implement user interfaces like that one needs to (1) show occurrences of extracted features within the text and (2) let the user interact with suggested entities.
### Visualise Occurrences of extracted features
-The occurrence of extracted features are represented by instances of the concept 'fise:TextAnnotation'. 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'](es_textannotation.png "This figure shows a TextAnnotation describing the occurrence of "Bob Marley" located from character 59 to 69 in the given 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")
Applications that want to visualize extracted features will need to follow/implement the following steps:
Typically the following steps are required to correctly show extracted features within the content.
-1. Query for/iterate over 'fise:TextAnnotation'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's. Those EntityAnnotations are linked with the TextAnnotations (occurrences) and 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 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 EntityAnnotations 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 to matching Entity was found within the knowledge base. In this case users might want to
* manually search the knowledge base for an Entity. The 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,11 +168,11 @@ The main purpose of EntityAnnotations is
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' - 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.
- * the 'fise:confidence' property represents the confidence of the suggestion in the range FROM 0 (very uncertain) TO 1 (very certain). Note that the 'fise:confidence' value is optional - so there might be EntityAnnotations without confidence information. However all [EnhancementEngines managed by the Stanbol community](engines/list.html) do provide confidence information.
+ * the 'fise:confidence' property represents the confidence of the suggestion in the range FROM 0 (very uncertain) TO 1 (very certain). Note that the 'fise:confidence' value is optional - so there might be EntityAnnotations without confidence information. However all [EnhancementEngines managed by the Stanbol community](enhancer/engines/list.html) do provide confidence information.
2. Visualize suggestions: EntityAnnotations do provide some basic information about the suggested Entity that can be used for visualization. Most important the URI of the suggested entity as value of 'fise:referenced-entity'. Additional the label and the types of the Entity are included.
3. Retrieving additional information about referenced Entities: While the EntityAnnotation includes some basic information some users might want to retrieve all available information of referenced Entities - to dereference the Entity:
* As this is a rather common use case the [EntityLinkingEngine]() and [KeywordLinkingEngine]() are by default configured to include information of Entities within the EnhancementResults. So users that use those EnhancementEngines will not need to dereference Entities as those information are already available within the enhancement results.
Modified: incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancementstructure.mdtext
URL: http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancementstructure.mdtext?rev=1351301&r1=1351300&r2=1351301&view=diff
==============================================================================
--- incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancementstructure.mdtext (original)
+++ incubator/stanbol/site/trunk/content/stanbol/docs/trunk/enhancer/enhancementstructure.mdtext Mon Jun 18 11:33:23 2012
@@ -128,3 +128,5 @@ TopicAnnotation are used to categorize/c
* __dc:relation__ _(required, multiple)_: The dc:relation property is required for topic annotations. It refers to the fise:TextAnnotation specifying the part of the text this topic is applied to.
* __entityhub:site__ (optional, single)_: The name of the Entityhub ReferencedSite managing the the suggested Entity. If this property is present users can dereference the suggested Entity with a GET request to "{stanbol}/entityhub/site/{site-name}/entity?id={entity}" where {site-name} is the value of this property and {entity} is the value of the "fise:entity-reference" property.
NOTE: the values "local" and "entityhub" need to be treated separately. In those cases the GET request need to use "{stanbol}/entityhub/entity?id={entity}".
+
+