You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@stanbol.apache.org by bu...@apache.org on 2012/06/18 13:21:26 UTC
svn commit: r822239 - in /websites/staging/stanbol/trunk/content: ./
stanbol/docs/trunk/enhancementusage.html
stanbol/docs/trunk/enhancer/enhancementstructure.html
Author: buildbot
Date: Mon Jun 18 11:21:26 2012
New Revision: 822239
Log:
Staging update by buildbot for stanbol
Added:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancementusage.html
Modified:
websites/staging/stanbol/trunk/content/ (props changed)
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/enhancementstructure.html
Propchange: websites/staging/stanbol/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Jun 18 11:21:26 2012
@@ -1 +1 @@
-1351260
+1351299
Added: websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancementusage.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancementusage.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancementusage.html Mon Jun 18 11:21:26 2012
@@ -0,0 +1,263 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+ <link href="/stanbol/css/stanbol.css" rel="stylesheet" type="text/css">
+ <title>Apache Stanbol - Making use of Stanbol Enhancements</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <link rel="icon" type="image/png" href="/stanbol/images/stanbol-logo/stanbol-favicon.png"/>
+ <script type="text/javascript">
+ // Google Analytics Tracking Code
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-32086816-1']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+ </script>
+</head>
+
+<body>
+ <div id="navigation">
+ <a href="/stanbol/index.html"><img alt="Apache Stanbol" width="220" height="101" border="0" src="/stanbol/images/stanbol-logo/stanbol-2010-12-14.png"/></a>
+ <h1 id="stanbol">Stanbol</h1>
+<ul>
+<li><a href="/stanbol/index.html">Home</a></li>
+<li><a href="/stanbol/docs/trunk/tutorial.html">Tutorial</a></li>
+<li><a href="/stanbol/docs/trunk/">Documentation</a><ul>
+<li><a href="/stanbol/docs/0.9.0-incubating/">0.9.0-incubating</a></li>
+</ul>
+</li>
+<li><a href="/stanbol/docs/trunk/building.html">Building</a></li>
+<li><a href="/stanbol/development/">Development</a></li>
+</ul>
+<h1 id="project">Project</h1>
+<ul>
+<li><a href="/stanbol/docs/trunk/mailinglists.html">Mailing Lists</a></li>
+<li><a href="https://issues.apache.org/jira/browse/STANBOL">Issue Tracker</a></li>
+<li><a href="/stanbol/team.html">Project Team</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="/stanbol/privacy-policy.html">Privacy Policy</a></li>
+</ul>
+<h1 id="downloads">Downloads</h1>
+<ul>
+<li><a href="/stanbol/downloads/">Overview</a><ul>
+<li><a href="/stanbol/downloads/releases.html">Releases</a></li>
+<li><a href="/stanbol/downloads/launchers.html">Launchers</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="the-asf">The ASF</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+ </div>
+
+ <div id="content">
+ <h1 class="title">Making use of Stanbol Enhancements</h1>
+ <p>This document describes how to implement client side components/user interface by using the <a href="enhancer/engines/enhancementstructure.html">Enhancement Results</a> returned by the <a href="enhancer">Stanbol Enhancer</a>. It does so by using three different scenarios:</p>
+<ul>
+<li><strong>Entity Tagging</strong> - replacing text based tags such as "Bob Marley" with entities - <a href="dbpedia.org/resource/Bob_Marley">dbpedia:Bob_Marley</a> - to improve content search and categorization. As added value this can also be used for mashups with already available information about linked Entities and Search Engine optimization by <a href="http://schema.org/docs/datamodel.html">including metadata</a> of tagged Entities within the content.</li>
+<li><strong>Entity Disambiguation</strong> - enhance the entity tagging experience by explicit support for disambiguation between different suggested Entities. This allows users to explicitly link to Paris (Texas), Bob Marley (Comedian) or in between any other Entities that do share similar labels.</li>
+<li><strong>Entity Checker</strong> - interact with extracted Entities similar as with todays spellchecker: Show extracted/suggested dirtily within the content; Allow users to interact with suggestions and to disambiguate between different matches if necessary; Support search for additional/other Entities.</li>
+</ul>
+<p>This usage scenario assumes that you already know <a href="contentenhancement.html">how to use</a> the basic <a href="enhancer/enhancerrest.html">Stanbol Enhancer RESTful API</a>. If not you might want to read the according <a href="contentenhancement.html">usage scenario</a>.</p>
+<h2 id="entity-tagging-use-tags-to-relate-you-content-to-persons-places-events">Entity Tagging: Use Tags to relate you content to persons, places, events â¦</h2>
+<p>Entity Tagging is about suggesting Users Entities instead of Strings to tag their Documents. The difference is very easy to explain. Lets assume a Blogger that uses the tag "Bob Marley" to tag a blog entry. Tagging is all about structuring content - so by tagging it with "Bob Marley" he can not easily find all Documents that uses that tag. However most likely he would also want to create a category of Documents about Reggae music and most likely he would like that Documents tagged with "Bob Marley" are part of that group. </p>
+<p>But while the knowledge that "Bob Marley" is related to "Reggae music" might be obvious for the Blogger it can not be known by the Blgging Tool he uses. So typically the only way to active this is that the Blogger tags the document with both tags.</p>
+<p>Entity Tagging tries to work around that by linking Documents with Entities defined by a knowledge base. The fact that Bob Marley is related to Reggae music is nothing novel. <a href="http://dbpedia.org">DBpedia</a> - the Wikipedia database - does know that and a lot more about - the Entity - <a href="dbpedia.org/resource/Bob_Marley">dbpedia:Bob_Marley</a>. So if the blogger tags his Document with "dbpedia:Bob_Marley" he does not only tag it with "Bob Marley" but also with all the other contextual information provided by DBPedia - including the fact that Bob_Marley was an Reggae interpret.</p>
+<p>But this does not only work with famous people, big cities ⦠nowadays the web <a href="http://linked-data.org">links data</a> of different domains. However this is not only about the Web - it works even better if you also can use Entities relevant to yourself and/or your working environment (Products, CRM information, â¦).</p>
+<h3 id="suggest-entities-with-the-stanbol-enhancer">Suggest Entities with the Stanbol Enhancer</h3>
+<p>Requesting the Stanbol Enhancer to analyze a text requires to send an POST the the <a href="enhancerrest.html">RESTful API</a> of the Stanbol Enhancer.</p>
+<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">X</span> <span class="n">POST</span> <span class="o">-</span><span class="n">H</span> <span class="s">"Accept: application/rdf+xml"</span> <span class="o">-</span><span class="n">H</span> <span class="s">"Content-type: text/plain"</span> <span class="o">\</span>
+ <span class="o">--</span><span class="n">data</span> <span class="s">"The Stanbol enhancer can detect famous cities such as \</span>
+<span class="s"> Paris and people such as Bob Marley."</span> <span class="n">http:</span><span class="sr">//</span><span class="p">{</span><span class="n">host</span><span class="p">}:{</span><span class="n">port</span><span class="p">}</span><span class="o">/</span><span class="n">enhancer</span>
+</pre></div>
+
+
+<p>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. </p>
+<p>The following Figure shows how extracted entities are described in the enhancement results.
+<img alt="'fise:EntityAnnotation' example" src="es_entityannotation.png" title="This Example shown an EntityAnnotation that suggests the Entity 'dbpedia:Bob_Marley' for the TextAnnotation" /></p>
+<p>In principle there are two Resources that are of interest for the Entity tagging use case:</p>
+<ol>
+<li>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. </li>
+<li>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.</li>
+</ol>
+<h3 id="process-suggested-entities">Process Suggested Entities</h3>
+<p>The following steps are typically needed to acquire the information needed to implement an entity tagging user interface:</p>
+<ol>
+<li>Iterate over all suggested Entities: This are all resources such as "{entity-annotation} rdf:type fise:EntityAnnotation"</li>
+<li>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.<ul>
+<li>URI of the suggested Entity: {entity-annotation} fise:entity-reference {entity}</li>
+<li>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}</li>
+<li>Types: Tha value of the fise:entity-type property of the {entity-annotation} are the same as the rdf:type values of the {entity}.</li>
+<li>Confidence: The 'fise:confidence' value represent how confident the Stanbol Enhancer is about this suggestion. Values are in the range [0..1] where 0 means very uncertain and 1 represent a high certainly.</li>
+</ul>
+</li>
+<li>Dereferenced {entity}: Some EnhancementEngines support to add also information about suggested Entities to the enhancement results - in other words: to dereference suggested entities. In this case additional information about the {entity} can be retrieved directly from the enhancement results. Most important those information include all available labels (in all languages) of the Entity.</li>
+<li>Dereferencing suggested Entities: If the suggested Entity is available via the Stanbol Entityhub the {entity-anntotation} does have the 'entityhub:site' property. The value of this property is the name of the ReferencedSite of the Entityhub. To dereference the Entity a GET request to "{stanbol-root-URL}/entityhub/site/{site-name}/entity?id={entity}" need to be used. The "Accept" header of the request need to be set to the according RDF serialization (e.g. "application/rdf+json").</li>
+</ol>
+<h3 id="process-content-categorizations">Process Content Categorizations</h3>
+<p>'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.</p>
+<p>Typically a entity tagging UI will want to distinguish between Categories and Entities because:</p>
+<ul>
+<li>Categories are used to group Content (e.g. Blog posts about Work and private things)</li>
+<li>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")</li>
+</ul>
+<p>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.</p>
+<p>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.</p>
+<h2 id="entity-tagging-with-disambiguation-support">Entity Tagging with Disambiguation support</h2>
+<p>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.</p>
+<p><img alt="Entity Disambiguation" src="es_entitydisambiguation.png" title=""Bob Marley as spotted in the Text may refer to two different persons in DBpedia.org" /></p>
+<p>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 <a href="#entity-tagging">Entity Tagging</a> 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 <a href="http:dbpedia.org/resource/Bob_Marley">'dbpedia:Bob_Marley'</a> and (2) for <a href="http://dbpedia.org/resource/Bob_Marley_%28comedian%29">dbpedia:Bob_Marley_(comedian)</a>. 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.</p>
+<p>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. </p>
+<h3 id="grouping-suggested-entities">Grouping suggested Entities</h3>
+<p>The goal of the Entity Tagging UI with disambiguation support is to show only a single tag suggestion for all Entities suggested for the same section in the analyzed text. To active this we need to follow the link between 'fise:EntityAnnotation' and 'fise:TextAnnotation'.</p>
+<p>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 <a href="#entity-tagging">Entity Tagging</a> interface.</p>
+<ol>
+<li>Iterate over all 'fise:EntityAnnotation' instances. This refers to all resources such as "{entity-annotation} rdf:type fise:EntityAnnotation". <ul>
+<li>For more information on how to collect information for extracted Entities see the <a href="#process-suggested-entities">according section</a> in the simple <a href="#entity-tagging">Entity Tagging</a> interface.</li>
+</ul>
+</li>
+<li>Retrieve the 'fise:TextAnnotation' referenced by processed 'fise:EntityAnnotation's. For that one needs to retrieve the value(s) of the 'dc:relation' property.</li>
+<li>While iterating over the 'fise:EntityAnnotation's establish a mapping 'fise:TextAnnotation' -> 'fise:EntityAnnotation','fise:EntityAnnotation, ...<ul>
+<li>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.</li>
+</ul>
+</li>
+<li>Suggest tags based on 'fise:TextAnnotation's - keys in the mapping created in step (3).<ul>
+<li>Allow users to easily accept the Entity with the highest rank - <a href="http:dbpedia.org/resource/Bob_Marley">'dbpedia:Bob_Marley'</a> in the above example. Especially if the confidence of the first suggestion is high (e.g. >= 0.8) and considerable higher as confidence values of other options.</li>
+<li>Provide users with the possibility to inspect further suggested options - to disambiguate between different options.</li>
+</ul>
+</li>
+</ol>
+<h3 id="showing-the-extraction-context">Showing the extraction Context</h3>
+<p>To allow users to more easily disambiguate between the suggested Entities it is important to provide them with information about the extraction context of the suggested entities. This is of special importance if content is not completely visible to the user (e.g. because it is to long to fit on the screen or the content is of a type that can not be rendered within the browser).</p>
+<p>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.</p>
+<p>The following information of the TextAnnotation can be used for this task:</p>
+<ul>
+<li>'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</li>
+<li>'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</li>
+<li>'fise:start' and 'fise:end' values could be also used to determine the location however because those offset are relative to the start of the content it is typically easier to use the occurrences of the selected text within the selection context.</li>
+</ul>
+<h2 id="entity-checker-inline-editing-of-content-enhancements">Entity Checker - inline Editing of Content Enhancements</h2>
+<p>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 <a href="http://hallojs.org">hallo.js</a> combined with the <a href="https://github.com/szabyg/annotate.js">annotate.js</a> plugin (see the <a href="http://hallojs.org/annotate.html">Demo here</a> <small>(last accessed 2012-05-30)</small> - click in the Text and press the "annotate" button).</p>
+<p><img alt="Occurrence based Annotation UI" src="hallo-annotate_scrrenshot.png" title="hallo.js with the annotate.js plugin used to implement an text occurrence based annotation UI" /></p>
+<p>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.</p>
+<h3 id="visualise-occurrences-of-extracted-features">Visualise Occurrences of extracted features</h3>
+<p>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.</p>
+<p><img alt="'fise:TextAnnotation'" src="es_textannotation.png" title="This figure shows a TextAnnotation describing the occurrence of "Bob Marley" located from character 59 to 69 in the given text" /></p>
+<p>Applications that want to visualize extracted features will need to follow/implement the following steps:</p>
+<p>Typically the following steps are required to correctly show extracted features within the content.</p>
+<ol>
+<li>Query for/iterate over 'fise:TextAnnotation's of the enhancement results.<ul>
+<li>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.</li>
+</ul>
+</li>
+<li>Determine the exact occurrence of the TextAnnoations<ul>
+<li>in case of plain text content this can be easily done by using the values of 'fise:start' and 'fise:end'</li>
+<li>in case the content includes additional markup the char indexes of 'fise:start'/'fise:end' will not match. In such cases the preferred way is to first search the occurrence of'fise:selection-context' and thann the occurrence of 'fise:selected-text' within.</li>
+</ul>
+</li>
+<li>Retrieve the suggestions ('fise:TextAnnoation' instances) for a given TextAnnotation. For that one needs to search for "?suggestion dc:relation {text-annotation}" where '{text-annotation}' refers to the URI of the current TextAnnotation. Note that:<ul>
+<li>Not every TextAnnotation will have suggestions</li>
+<li>One and the same suggestion might be linked with several TextAnnotations.</li>
+</ul>
+</li>
+</ol>
+<p>The following SPARQL query could be used to select all the required information. However the use of SPARQL is optional as the required information can be also easily retrieved by other means (e.g. the filtered Iteratros as typically provided by RDF frameworks). </p>
+<div class="codehilite"><pre><span class="nb">select</span> <span class="o">*</span>
+<span class="n">from</span> <span class="p">{</span>
+ <span class="p">?</span><span class="n">textAnnotation</span> <span class="n">rdfs:type</span> <span class="n">fise:TextAnnotation</span>
+ <span class="p">?</span><span class="n">textAnnotation</span> <span class="n">fise:selected</span><span class="o">-</span><span class="n">text</span> <span class="p">?</span><span class="n">selected</span>
+ <span class="p">?</span><span class="n">textAnnotation</span> <span class="n">fise:selection</span><span class="o">-</span><span class="n">context</span> <span class="p">?</span><span class="n">context</span>
+ <span class="p">?</span><span class="n">textAnnotation</span> <span class="n">fise:start</span> <span class="p">?</span><span class="n">startIndex</span>
+ <span class="p">?</span><span class="n">textAnnotation</span> <span class="n">fise:end</span> <span class="p">?</span><span class="n">endIndex</span>
+ <span class="p">?</span><span class="n">textAnnotation</span> <span class="n">dc:type</span> <span class="p">?</span><span class="n">nature</span>
+ <span class="n">optional</span> <span class="p">{</span>
+ <span class="p">?</span><span class="n">suggestions</span> <span class="n">dc:relation</span> <span class="p">?</span><span class="n">textAnnotation</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p><em>Tips and Tricks:</em></p>
+<ul>
+<li>Applications that want to differentiate between different types of extracted entities (e.g. applying different stylesheets for persons, organizations and places) can use the value of the 'dc:type' for that purpose. See the section for <a href="#fisetextannotation">fise:TextAnnotation</a> for detailed information. </li>
+</ul>
+<h3 id="interact-with-suggested-entities">Interact with suggested Entities</h3>
+<p>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 <a href="http:dbpedia.org/resource/Bob_Marley">'dbpedia:Bob_Marley'</a> for the TextAnnotation used in the example of the previous section.</p>
+<p><img alt="'fise:EntityAnnotation' example" src="es_entityannotation.png" title="This Example shown an EntityAnnotation that suggests the Entity 'dbpedia:Bob_Marley' for the TextAnnotation" /></p>
+<p>The main purpose of EntityAnnotations is to suggest Entities (e.g. <a href="http:dbpedia.org/resource/Bob_Marley">'dbpedia:Bob_Marley'</a> 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:</p>
+<ol>
+<li><strong>No suggestion</strong>: 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<ul>
+<li>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).</li>
+<li>Create a new Entity based on the current TextAnnotation. In this case the 'fise:selected-text' should be suggested as 'rdfs:label' and the 'dc:type' value could be used for the 'rdf:type'. New Entities can be added to the knowledge base by sending a "POST http://{host}:{port}/entityhub/entity" with the RDF data of the Entity as content (see the WebUI of your Stanbol instance for the detailed documentation).</li>
+</ul>
+</li>
+<li><strong>Distinct suggestion</strong>: This means that there is only a single suggestion with a high 'fise:confidence'. Also multiple suggestions where the first one as a high confidence and additional suggestions come with low confidence values may fit this description. In such situations <ul>
+<li>the UI might want to automatically accept the suggestion</li>
+<li>allow users to show additional suggestion on request.</li>
+<li>undo automatic acceptance of the suggestion.</li>
+</ul>
+</li>
+<li><strong>Ambiguous Suggestions</strong>: This situation is satisfied if multiple entities are suggested with a medium to high 'fise:confidence'. This also applies to situations where there is no suggestion with an high 'fise:confidence' value. In those cases typically the user must provide additional input by<ul>
+<li>selecting the correct entity</li>
+<li>rejecting all suggestions</li>
+<li>also manually searching and/or creating a new Entity as described for (1) would be possible interaction</li>
+</ul>
+</li>
+</ol>
+<p>The required data for for the described interaction patters are available within the enhancement results as follows:</p>
+<p>The following assumes {text-annotation} - the URI of the current 'fise:TextAnnotation' - as context</p>
+<ol>
+<li>Query for/iterate over all entity suggestions: The suggestions for {text-annotation} can be acquired by using "?entityAnnotation dc:relation {text-annotation}<ul>
+<li>only results with the the 'rdf:type' 'fise:EntityAnnotation' should be processed. However typically all results will be any way of that type.</li>
+<li>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 <a href="engines/list.html">EnhancementEngines managed by the Stanbol community</a> do provide confidence information.</li>
+</ul>
+</li>
+<li>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.</li>
+<li>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:<ul>
+<li>As this is a rather common use case the <a href="">EntityLinkingEngine</a> and <a href="">KeywordLinkingEngine</a> 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.</li>
+<li>If a 'fise:EntityAnnotation' has the 'entityhub:site' property Entities can be dereferenced by using the Stanbol Entityhub (see the section for <a href="#fiseentityannotation">fise:EntityAnnotation</a> for details)</li>
+<li>In all other cases the URI of the suggested entity need to be used for dereferencing. If the referenced Entity is part of the <a href="http://linkeddata.org/">Linked Data</a> cloud this is often possible by the <a href="http://www.w3.org/TR/cooluris/">CoolURI</a> - basically sending a "GET -h "Accept: application/json+rdf" {entity-uri}".</li>
+</ul>
+</li>
+</ol>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2010 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, Stanbol and the Apache feather and Stanbol logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>
Modified: websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/enhancementstructure.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/enhancementstructure.html (original)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/trunk/enhancer/enhancementstructure.html Mon Jun 18 11:21:26 2012
@@ -82,20 +82,16 @@
<p>Its two main purposes are to facilitate the:</p>
<ol>
<li>Interoperability between EnhancementEngines: The design of the Stanbol Enhancer is based on the processing of an <a href="contentitem.html">ContentItem</a> by multiple <a href="engines">EnhancementEngine</a>s in an <a href="chains">EnhancementChain</a>. Together with the ContentItem API the EnhancementStructure is the key enabler for the cooperation of the different engines. It ensures that enhancements created by one engine can be consumed by the following engines (e.g. the first engine detects the language of the parsed text; the second consumes the language to select the correct NER (named entity recognition) model and create enhancements describing Named Entities contained in the text; the third Engine consumes those Named Entity annotations and creates suggestions for Entities part of an controlled vocabulary).</li>
-<li>
-<p>Consumption of extracted Features: The knowledge structure standardized by this Ontology aims to allow users to consume/process the features extracted from the parsed content. This includes things like:</p>
-<ul>
+<li>Consumption of extracted Features: The knowledge structure standardized by this Ontology aims to allow users to consume/process the features extracted from the parsed content. This includes things like:<ul>
<li>list all suggested Entities (accept/reject Tags)</li>
<li>list all suggested Topics (content classification)</li>
<li>group Entity suggestion based on detected "Named Entities" (disambiguation support)</li>
<li>show the occurrence of detected Entities within the analyzed text (similar to spell checker UIs)</li>
</ul>
-<p>The last section of this document provides a more detailed look at those usage scenarios.</p>
</li>
</ol>
-<p>This document follows a similar structure. While the first part goes into the detail of the Stanbol Enhancement Structure as integral part of the Stanbol Enhancer the second part focuses on the consumption of the EnhancementResults.</p>
-<p>While the first part is intended to be read by Developers that want to extend the Stanbol Enhancer (e.g. implement there own <a href="engines">EnhancementEngine</a>s) the target audience of the second part are typical users of the Stanbol Enhancer.</p>
-<h1 id="part-1-the-stanbol-enhancement-structure">PART 1: The Stanbol Enhancement Structure</h1>
+<p>While this document focuses on the first Engine and provides details on how the Stanbol Enhancement Structure it the integral part of the Stanbol Enhancer there is also a <a href="../consumningenhancements.html">Usage Scenario</a> available that focuses on how the Enhancements can be consumed by Stanbol Enhancer users.</p>
+<h2 id="overview-on-the-stanbol-enhancement-structure">Overview on the Stanbol Enhancement Structure</h2>
<p>The Stanbol Enhancement Structure is a central part of the <a href="index.html">Stanbol Enhancer</a> architecture as it represents the binding element between the <a href="contentitem.html">ContentItem</a> analyzed by the the <a href="engines">EnhancementEngine</a>s as configured by an <a href="chains">EnhancementChain</a>. Together with the <a href="content item.html#content-parts">ContentParts</a> it represents the state that is constantly updated during the enhancement process.</p>
<p>The following graphic provides an overview on how the EnhancementStructure is used by the Stanbol Enhancer to formally represent the enhancement results.</p>
<p><img alt="EnhancementStructure Overview" src="enhancementstructure.png" title="Overview of the Stanbol Enhancement Structure showing 'Bob Marley' recognized as Person within the parsed Text with two suggested Entities 'Bob Marley' the musician and 'Bob Marley' the comedian" /></p>
@@ -196,168 +192,6 @@
<li><strong>entityhub:site</strong> (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}".</li>
</ul>
-<h1 id="part-2-using-the-stanbol-enhancement-structure">Part 2: Using the Stanbol Enhancement Structure</h1>
-<h2 id="entity-tagging">Entity Tagging</h2>
-<p>Entity Tagging is about suggesting Users Entities instead of Strings to tag their Documents. The difference is very easy to explain. Lets assume a Blogger that uses the tag "Bob Marley" to tag a blog entry. Tagging is all about structuring content - so by tagging it with "Bob Marley" he can not easily find all Documents that uses that tag. However most likely he would also want to create a category of Documents about Reggae music and most likely he would like that Documents tagged with "Bob Marley" are part of that group. </p>
-<p>But while the knowledge that "Bob Marley" is related to "Reggae music" might be obvious for the Blogger it can not be known by the Blgging Tool he uses. So typically the only way to active this is that the Blogger tags the document with both tags.</p>
-<p>Entity Tagging tries to work around that by linking Documents with Entities defined by a knowledge base. The fact that Bob Marley is related to Reggae music is nothing novel. <a href="http://dbpedia.org">DBpedia</a> - the Wikipedia database - does know that and a lot more about - the Entity - <a href="dbpedia.org/resource/Bob_Marley">dbpedia:Bob_Marley</a>. So if the blogger tags his Document with "dbpedia:Bob_Marley" he does not only tag it with "Bob Marley" but also with all the other contextual information provided by DBPedia - including the fact that Bob_Marley was an Reggae interpret.</p>
-<p>But this does not only work with famous people, big cities ⦠nowadays the web <a href="http://linked-data.org">links data</a> of different domains. However this is not only about the Web - it works even better if you also can use Entities relevant to yourself and/or your working environment (Products, CRM information, â¦).</p>
-<h3 id="suggest-entities-with-the-stanbol-enhancer">Suggest Entities with the Stanbol Enhancer</h3>
-<p>Requesting the Stanbol Enhancer to analyze a text requires to send an POST the the <a href="enhancerrest.html">RESTful API</a> of the Stanbol Enhancer.</p>
-<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">X</span> <span class="n">POST</span> <span class="o">-</span><span class="n">H</span> <span class="s">"Accept: application/rdf+xml"</span> <span class="o">-</span><span class="n">H</span> <span class="s">"Content-type: text/plain"</span> <span class="o">\</span>
- <span class="o">--</span><span class="n">data</span> <span class="s">"The Stanbol enhancer can detect famous cities such as \</span>
-<span class="s"> Paris and people such as Bob Marley."</span> <span class="n">http:</span><span class="sr">//</span><span class="p">{</span><span class="n">host</span><span class="p">}:{</span><span class="n">port</span><span class="p">}</span><span class="o">/</span><span class="n">enhancer</span>
-</pre></div>
-
-
-<p>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. </p>
-<p>The following Figure shows how extracted entities are described in the enhancement results.
-<img alt="'fise:EntityAnnotation' example" src="es_entityannotation.png" title="This Example shown an EntityAnnotation that suggests the Entity 'dbpedia:Bob_Marley' for the TextAnnotation" /></p>
-<p>In principle there are two Resources that are of interest for the Entity tagging use case:</p>
-<ol>
-<li>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. </li>
-<li>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.</li>
-</ol>
-<h3 id="process-suggested-entities">Process Suggested Entities</h3>
-<p>The following steps are typically needed to acquire the information needed to implement an entity tagging user interface:</p>
-<ol>
-<li>Iterate over all suggested Entities: This are all resources such as "{entity-annotation} rdf:type fise:EntityAnnotation"</li>
-<li>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.<ul>
-<li>URI of the suggested Entity: {entity-annotation} fise:entity-reference {entity}</li>
-<li>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}</li>
-<li>Types: Tha value of the fise:entity-type property of the {entity-annotation} are the same as the rdf:type values of the {entity}.</li>
-<li>Confidence: The 'fise:confidence' value represent how confident the Stanbol Enhancer is about this suggestion. Values are in the range [0..1] where 0 means very uncertain and 1 represent a high certainly.</li>
-</ul>
-</li>
-<li>Dereferenced {entity}: Some EnhancementEngines support to add also information about suggested Entities to the enhancement results - in other words: to dereference suggested entities. In this case additional information about the {entity} can be retrieved directly from the enhancement results. Most important those information include all available labels (in all languages) of the Entity.</li>
-<li>Dereferencing suggested Entities: If the suggested Entity is available via the Stanbol Entityhub the {entity-anntotation} does have the 'entityhub:site' property. The value of this property is the name of the ReferencedSite of the Entityhub. To dereference the Entity a GET request to "{stanbol-root-URL}/entityhub/site/{site-name}/entity?id={entity}" need to be used. The "Accept" header of the request need to be set to the according RDF serialization (e.g. "application/rdf+json").</li>
-</ol>
-<h3 id="process-content-categorizations">Process Content Categorizations</h3>
-<p>'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.</p>
-<p>Typically a entity tagging UI will want to distinguish between Categories and Entities because:</p>
-<ul>
-<li>Categories are used to group Content (e.g. Blog posts about Work and private things)</li>
-<li>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")</li>
-</ul>
-<p>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.</p>
-<p>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.</p>
-<h2 id="entity-disambiguation">Entity Disambiguation</h2>
-<p>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.</p>
-<p><img alt="Entity Disambiguation" src="es_entitydisambiguation.png" title=""Bob Marley as spotted in the Text may refer to two different persons in DBpedia.org" /></p>
-<p>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 <a href="#entity-tagging">Entity Tagging</a> 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 <a href="http:dbpedia.org/resource/Bob_Marley">'dbpedia:Bob_Marley'</a> and (2) for <a href="http://dbpedia.org/resource/Bob_Marley_%28comedian%29">dbpedia:Bob_Marley_(comedian)</a>. 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.</p>
-<p>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. </p>
-<h3 id="grouping-suggested-entities">Grouping suggested Entities</h3>
-<p>The goal of the Entity Tagging UI with disambiguation support is to show only a single tag suggestion for all Entities suggested for the same section in the analyzed text. To active this we need to follow the link between 'fise:EntityAnnotation' and 'fise:TextAnnotation'.</p>
-<p>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 <a href="#entity-tagging">Entity Tagging</a> interface.</p>
-<ol>
-<li>Iterate over all 'fise:EntityAnnotation' instances. This refers to all resources such as "{entity-annotation} rdf:type fise:EntityAnnotation". <ul>
-<li>For more information on how to collect information for extracted Entities see the <a href="#process-suggested-entities">according section</a> in the simple <a href="#entity-tagging">Entity Tagging</a> interface.</li>
-</ul>
-</li>
-<li>Retrieve the 'fise:TextAnnotation' referenced by processed 'fise:EntityAnnotation's. For that one needs to retrieve the value(s) of the 'dc:relation' property.</li>
-<li>While iterating over the 'fise:EntityAnnotation's establish a mapping 'fise:TextAnnotation' -> 'fise:EntityAnnotation','fise:EntityAnnotation, ...<ul>
-<li>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.</li>
-</ul>
-</li>
-<li>Suggest tags based on 'fise:TextAnnotation's - keys in the mapping created in step (3).<ul>
-<li>Allow users to easily accept the Entity with the highest rank - <a href="http:dbpedia.org/resource/Bob_Marley">'dbpedia:Bob_Marley'</a> in the above example. Especially if the confidence of the first suggestion is high (e.g. >= 0.8) and considerable higher as confidence values of other options.</li>
-<li>Provide users with the possibility to inspect further suggested options - to disambiguate between different options.</li>
-</ul>
-</li>
-</ol>
-<h3 id="showing-the-extraction-context">Showing the extraction Context</h3>
-<p>To allow users to more easily disambiguate between the suggested Entities it is important to provide them with information about the extraction context of the suggested entities. This is of special importance if content is not completely visible to the user (e.g. because it is to long to fit on the screen or the content is of a type that can not be rendered within the browser).</p>
-<p>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.</p>
-<p>The following information of the TextAnnotation can be used for this task:</p>
-<ul>
-<li>'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</li>
-<li>'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</li>
-<li>'fise:start' and 'fise:end' values could be also used to determine the location however because those offset are relative to the start of the content it is typically easier to use the occurrences of the selected text within the selection context.</li>
-</ul>
-<h2 id="occurrence-based-annotation">Occurrence based Annotation</h2>
-<p>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 <a href="http://hallojs.org">hallo.js</a> combined with the <a href="https://github.com/szabyg/annotate.js">annotate.js</a> plugin (see the <a href="http://hallojs.org/annotate.html">Demo here</a> <small>(last accessed 2012-05-30)</small> - click in the Text and press the "annotate" button).</p>
-<p><img alt="Occurrence based Annotation UI" src="hallo-annotate_scrrenshot.png" title="hallo.js with the annotate.js plugin used to implement an text occurrence based annotation UI" /></p>
-<p>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.</p>
-<h3 id="visualise-occurrences-of-extracted-features">Visualise Occurrences of extracted features</h3>
-<p>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.</p>
-<p><img alt="'fise:TextAnnotation'" src="es_textannotation.png" title="This figure shows a TextAnnotation describing the occurrence of "Bob Marley" located from character 59 to 69 in the given text" /></p>
-<p>Applications that want to visualize extracted features will need to follow/implement the following steps:</p>
-<p>Typically the following steps are required to correctly show extracted features within the content.</p>
-<ol>
-<li>Query for/iterate over 'fise:TextAnnotation's of the enhancement results.<ul>
-<li>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.</li>
-</ul>
-</li>
-<li>Determine the exact occurrence of the TextAnnoations<ul>
-<li>in case of plain text content this can be easily done by using the values of 'fise:start' and 'fise:end'</li>
-<li>in case the content includes additional markup the char indexes of 'fise:start'/'fise:end' will not match. In such cases the preferred way is to first search the occurrence of'fise:selection-context' and thann the occurrence of 'fise:selected-text' within.</li>
-</ul>
-</li>
-<li>Retrieve the suggestions ('fise:TextAnnoation' instances) for a given TextAnnotation. For that one needs to search for "?suggestion dc:relation {text-annotation}" where '{text-annotation}' refers to the URI of the current TextAnnotation. Note that:<ul>
-<li>Not every TextAnnotation will have suggestions</li>
-<li>One and the same suggestion might be linked with several TextAnnotations.</li>
-</ul>
-</li>
-</ol>
-<p>The following SPARQL query could be used to select all the required information. However the use of SPARQL is optional as the required information can be also easily retrieved by other means (e.g. the filtered Iteratros as typically provided by RDF frameworks). </p>
-<div class="codehilite"><pre><span class="nb">select</span> <span class="o">*</span>
-<span class="n">from</span> <span class="p">{</span>
- <span class="p">?</span><span class="n">textAnnotation</span> <span class="n">rdfs:type</span> <span class="n">fise:TextAnnotation</span>
- <span class="p">?</span><span class="n">textAnnotation</span> <span class="n">fise:selected</span><span class="o">-</span><span class="n">text</span> <span class="p">?</span><span class="n">selected</span>
- <span class="p">?</span><span class="n">textAnnotation</span> <span class="n">fise:selection</span><span class="o">-</span><span class="n">context</span> <span class="p">?</span><span class="n">context</span>
- <span class="p">?</span><span class="n">textAnnotation</span> <span class="n">fise:start</span> <span class="p">?</span><span class="n">startIndex</span>
- <span class="p">?</span><span class="n">textAnnotation</span> <span class="n">fise:end</span> <span class="p">?</span><span class="n">endIndex</span>
- <span class="p">?</span><span class="n">textAnnotation</span> <span class="n">dc:type</span> <span class="p">?</span><span class="n">nature</span>
- <span class="n">optional</span> <span class="p">{</span>
- <span class="p">?</span><span class="n">suggestions</span> <span class="n">dc:relation</span> <span class="p">?</span><span class="n">textAnnotation</span>
- <span class="p">}</span>
-<span class="p">}</span>
-</pre></div>
-
-
-<p><em>Tips and Tricks:</em></p>
-<ul>
-<li>Applications that want to differentiate between different types of extracted entities (e.g. applying different stylesheets for persons, organizations and places) can use the value of the 'dc:type' for that purpose. See the section for <a href="#fisetextannotation">fise:TextAnnotation</a> for detailed information. </li>
-</ul>
-<h3 id="interact-with-suggested-entities">Interact with suggested Entities</h3>
-<p>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 <a href="http:dbpedia.org/resource/Bob_Marley">'dbpedia:Bob_Marley'</a> for the TextAnnotation used in the example of the previous section.</p>
-<p><img alt="'fise:EntityAnnotation' example" src="es_entityannotation.png" title="This Example shown an EntityAnnotation that suggests the Entity 'dbpedia:Bob_Marley' for the TextAnnotation" /></p>
-<p>The main purpose of EntityAnnotations is to suggest Entities (e.g. <a href="http:dbpedia.org/resource/Bob_Marley">'dbpedia:Bob_Marley'</a> 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:</p>
-<ol>
-<li><strong>No suggestion</strong>: 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<ul>
-<li>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).</li>
-<li>Create a new Entity based on the current TextAnnotation. In this case the 'fise:selected-text' should be suggested as 'rdfs:label' and the 'dc:type' value could be used for the 'rdf:type'. New Entities can be added to the knowledge base by sending a "POST http://{host}:{port}/entityhub/entity" with the RDF data of the Entity as content (see the WebUI of your Stanbol instance for the detailed documentation).</li>
-</ul>
-</li>
-<li><strong>Distinct suggestion</strong>: This means that there is only a single suggestion with a high 'fise:confidence'. Also multiple suggestions where the first one as a high confidence and additional suggestions come with low confidence values may fit this description. In such situations <ul>
-<li>the UI might want to automatically accept the suggestion</li>
-<li>allow users to show additional suggestion on request.</li>
-<li>undo automatic acceptance of the suggestion.</li>
-</ul>
-</li>
-<li><strong>Ambiguous Suggestions</strong>: This situation is satisfied if multiple entities are suggested with a medium to high 'fise:confidence'. This also applies to situations where there is no suggestion with an high 'fise:confidence' value. In those cases typically the user must provide additional input by<ul>
-<li>selecting the correct entity</li>
-<li>rejecting all suggestions</li>
-<li>also manually searching and/or creating a new Entity as described for (1) would be possible interaction</li>
-</ul>
-</li>
-</ol>
-<p>The required data for for the described interaction patters are available within the enhancement results as follows:</p>
-<p>The following assumes {text-annotation} - the URI of the current 'fise:TextAnnotation' - as context</p>
-<ol>
-<li>Query for/iterate over all entity suggestions: The suggestions for {text-annotation} can be acquired by using "?entityAnnotation dc:relation {text-annotation}<ul>
-<li>only results with the the 'rdf:type' 'fise:EntityAnnotation' should be processed. However typically all results will be any way of that type.</li>
-<li>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 <a href="engines/list.html">EnhancementEngines managed by the Stanbol community</a> do provide confidence information.</li>
-</ul>
-</li>
-<li>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.</li>
-<li>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:<ul>
-<li>As this is a rather common use case the <a href="">EntityLinkingEngine</a> and <a href="">KeywordLinkingEngine</a> 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.</li>
-<li>If a 'fise:EntityAnnotation' has the 'entityhub:site' property Entities can be dereferenced by using the Stanbol Entityhub (see the section for <a href="#fiseentityannotation">fise:EntityAnnotation</a> for details)</li>
-<li>In all other cases the URI of the suggested entity need to be used for dereferencing. If the referenced Entity is part of the <a href="http://linkeddata.org/">Linked Data</a> cloud this is often possible by the <a href="http://www.w3.org/TR/cooluris/">CoolURI</a> - basically sending a "GET -h "Accept: application/json+rdf" {entity-uri}".</li>
-</ul>
-</li>
-</ol>
</div>
<div id="footer">