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.
