---+DataTXT Metacartridge Configuration guidelines

%TOC%

---++ Migration from Spaziodati

Since the end of March, 2014, the old Spaziodati Metacartridge has been 
replaced with dataTXT to reflect the change of service-name upstream. If you 
are new to dataTXT, you don't need to worry about migrating from Spaziodati; 
just proceed with the regular documentation below. Otherwise,

   * The Spaziodati Metacartridge will be disabled and its description updated with a warning
   * Your old appid and appkey parameters are no longer valid; you need to generate a new account with dataTXT
   * Some old API parameters have undergone a slight change in meaning or been renamed
   * Some new API parameters have been added
   * The new dataTXT Metacartridge has reasonable defaults reflecting the upstream API; just generate and add your appid and appkey
      * if you had specifically customized the options with Spaziodati you will need to review the dataTXT settings.
   
References: 
   * [[https://dandelion.eu/docs/api/datatxt/nex/migration-guide/][Migration Guide]]
   * [[https://dandelion.eu/docs/api/datatxt/nex/v1/][Full API documentation]]

---++Getting Started with dataTXT

---+++Overview

   1. Register and log in to [[https://dandelion.eu/][dandelion/dataTXT]]
   1. From the dashboard, copy your appid and appkey
   1. In the Virtuoso Conductor, edit the dataTXT Metacartridge options and add the appid and appkey
   1. review the other options while you're there.

---+++Screenshots

Registering with dandelion: go to the [[https://dandelion.eu/][dandelion/dataTXT registration page]] and fill in your details.

<img src="%ATTACHURLPATH%/dataTXT-1.png" style="wikiautogen"/>

Log in

<img src="%ATTACHURLPATH%/dataTXT-2.png" style="wikiautogen"/>

Go to the dashboard

<img src="%ATTACHURLPATH%/dataTXT-3.png" style="wikiautogen"/>

The <nowiki>AppID</nowiki> and <nowiki>AppKey</nowiki> will be presented.

<img src="%ATTACHURLPATH%/dataTXT-4.png" style="wikiautogen"/>

In another tab, open the Virtuoso Conductor (<nowiki>http://localhost:8890/conductor/</nowiki>).

Navigate the menus to Linked Data / Sponger / Metacartridges.

Ensure the dataTXT metacartridge is enabled, and click the apply button at the bottom of the list.

<img src="%ATTACHURLPATH%/dataTXT-5.png" style="wikiautogen"/>


Edit the dataTXT metacartridge and set the options to taste, adding the AppID and AppKey from the dataTXT-NEX dashboard.

<img src="%ATTACHURLPATH%/dataTXT-6.png" style="wikiautogen"/>

---+++Metacartridge Options

<verbatim>
app_id=
app_key=
</verbatim>
These identify you and the Sponger application with the dataTXT-NEX service.

<verbatim>
include_types=true
include_categories=false
include_lod=false
</verbatim>

These enable links to DBPedia and LOD categories where possible.

<verbatim>
parse_hashtag=true
</verbatim>

This enables parsing of hashtags, e.g. in tweet source texts.

<verbatim>
abstract=true
</verbatim>

This allows the inclusion of an abstract of the text in the returned annotations.

<verbatim>
min_confidence=0.6
</verbatim>
A lower bound: entities with a confidence less than this will not be returned. 

<verbatim>
min_length=2
</verbatim>

Entities whose spot is a string shorter than this number of characters will not be returned.

<verbatim>
epsilon=0.3
</verbatim>

Epsilon controls the balance between choosing contexts biassed toward the local document (low values) or more globally common contexts (higher values).

<verbatim>
max-entities=50
</verbatim>

An overall limit on the number of entities (by decreasing confidence) to be included per document being sponged.