From 8b2c3e8d40307a50c8f986cc86292dfaf5c7fe73 Mon Sep 17 00:00:00 2001 From: militarpancho Date: Tue, 28 Mar 2017 12:34:39 +0200 Subject: [PATCH] Update readthedocs. Mainly Api and What is senpy section --- docs/api.rst | 235 ++++++++++++++++++++++------------------ docs/architecture.rst | 17 +++ docs/conf.py | 3 - docs/installation.rst | 14 ++- docs/plugins.rst | 2 + docs/senpy.rst | 37 ++----- docs/specifications.rst | 8 ++ 7 files changed, 179 insertions(+), 137 deletions(-) create mode 100644 docs/architecture.rst create mode 100644 docs/specifications.rst diff --git a/docs/api.rst b/docs/api.rst index 8dedebd..f891894 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -22,38 +22,32 @@ NIF API Content-Type: text/javascript { - "@context": [ - "http://127.0.0.1/static/context.jsonld", - ], - "analysis": [ - { - "@id": "SentimentAnalysisExample", - "@type": "marl:SentimentAnalysis", - "dc:language": "en", - "marl:maxPolarityValue": 10.0, - "marl:minPolarityValue": 0.0 - } - ], - "domain": "wndomains:electronics", - "entries": [ - { - "opinions": [ - { - "prov:generatedBy": "SentimentAnalysisExample", - "marl:polarityValue": 7.8, - "marl:hasPolarity": "marl:Positive", - "marl:describesObject": "http://www.gsi.dit.upm.es", - } - ], - "nif:isString": "I love GSI", - "strings": [ - { - "nif:anchorOf": "GSI", - "nif:taIdentRef": "http://www.gsi.dit.upm.es" - } - ] - } - ] + "@context":"http://127.0.0.1/api/contexts/Results.jsonld", + "@id":"_:Results_11241245.22", + "@type":"results" + "analysis": [ + "plugins/sentiment-140_0.1" + ], + "entries": [ + { + "@id": "_:Entry_11241245.22" + "@type":"entry", + "emotions": [], + "entities": [], + "sentiments": [ + { + "@id": "Sentiment0", + "@type": "sentiment", + "marl:hasPolarity": "marl:Negative", + "marl:polarityValue": 0, + "prefix": "" + } + ], + "suggestions": [], + "text": "This text makes me sad.\nwhilst this text makes me happy and surprised at the same time.\nI cannot believe it!", + "topics": [] + } + ] } :query i input: No default. Depends on informat and intype @@ -92,58 +86,59 @@ NIF API .. sourcecode:: http - { - "@context": { - ... - }, - "@type": "plugins", - "plugins": [ - { - "name": "sentiment140", - "is_activated": true, - "version": "0.1", - "extra_params": { - "@id": "extra_params_sentiment140_0.1", - "language": { - "required": false, - "@id": "lang_sentiment140", - "options": [ - "es", - "en", - "auto" - ], - "aliases": [ - "language", - "l" - ] - } - }, - "@id": "sentiment140_0.1" - }, { - "name": "rand", - "is_activated": true, - "version": "0.1", - "extra_params": { - "@id": "extra_params_rand_0.1", - "language": { - "required": false, - "@id": "lang_rand", - "options": [ - "es", - "en", - "auto" - ], - "aliases": [ - "language", - "l" - ] - } - }, - "@id": "rand_0.1" - } - ] - } - + { + "@id": "plugins/sentiment-140_0.1", + "@type": "sentimentPlugin", + "author": "@balkian", + "description": "Sentiment classifier using rule-based classification for English and Spanish. This plugin uses sentiment140 data to perform classification. For more information: http://help.sentiment140.com/for-students/", + "extra_params": { + "language": { + "@id": "lang_sentiment140", + "aliases": [ + "language", + "l" + ], + "options": [ + "es", + "en", + "auto" + ], + "required": false + } + }, + "is_activated": true, + "maxPolarityValue": 1.0, + "minPolarityValue": 0.0, + "module": "sentiment-140", + "name": "sentiment-140", + "requirements": {}, + "version": "0.1" + }, + { + "@id": "plugins/ExamplePlugin_0.1", + "@type": "sentimentPlugin", + "author": "@balkian", + "custom_attribute": "42", + "description": "I am just an example", + "extra_params": { + "parameter": { + "@id": "parameter", + "aliases": [ + "parameter", + "param" + ], + "default": 42, + "required": true + } + }, + "is_activated": true, + "maxPolarityValue": 1.0, + "minPolarityValue": 0.0, + "module": "example", + "name": "ExamplePlugin", + "requirements": "noop", + "version": "0.1" + } .. http:get:: /api/plugins/ @@ -162,30 +157,60 @@ NIF API .. sourcecode:: http { - "@id": "rand_0.1", - "@type": "sentimentPlugin", - "extra_params": { - "@id": "extra_params_rand_0.1", - "language": { - "@id": "lang_rand", - "aliases": [ - "language", - "l" - ], - "options": [ - "es", - "en", - "auto" - ], - "required": false - } - }, - "is_activated": true, - "name": "rand", - "version": "0.1" + "@context": "http://127.0.0.1/api/contexts/ExamplePlugin.jsonld", + "@id": "plugins/ExamplePlugin_0.1", + "@type": "sentimentPlugin", + "author": "@balkian", + "custom_attribute": "42", + "description": "I am just an example", + "extra_params": { + "parameter": { + "@id": "parameter", + "aliases": [ + "parameter", + "param" + ], + "default": 42, + "required": true + } + }, + "is_activated": true, + "maxPolarityValue": 1.0, + "minPolarityValue": 0.0, + "module": "example", + "name": "ExamplePlugin", + "requirements": "noop", + "version": "0.1" } + + + + + + + + + + + + + + + + + + + + + + + + + + + .. http:get:: /api/plugins/default Return the information about the default plugin. diff --git a/docs/architecture.rst b/docs/architecture.rst new file mode 100644 index 0000000..af412be --- /dev/null +++ b/docs/architecture.rst @@ -0,0 +1,17 @@ +Architecture +============ + +The main component of a sentiment analysis service is the algorithm itself. However, for the algorithm to work, it needs to get the appropriate parameters from the user, format the results according to the defined API, interact with the user whn errors occur or more information is needed, etc. + +Senpy proposes a modular and dynamic architecture that allows: + +* Implementing different algorithms in a extensible way, yet offering a common interface. +* Offering common services that facilitate development, so developers can focus on implementing new and better algorithms. + +The framework consists of two main modules: Senpy core, which is the building block of the service, and Senpy plugins, which consist of the analysis algorithm. The next figure depicts a simplified version of the processes involved in an analysis with the Senpy framework. + +.. image:: senpy-architecture.png + :height: 400px + :width: 800px + :scale: 100 % + :align: center diff --git a/docs/conf.py b/docs/conf.py index e9a9823..6c356ee 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -60,10 +60,7 @@ copyright = u'2016, J. Fernando Sánchez' # built documents. # # The short X.Y version. -with open('../senpy/VERSION') as f: - version = f.read().strip() # The full version, including alpha/beta/rc tags. -release = version # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/installation.rst b/docs/installation.rst index a33664a..381c26c 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -22,6 +22,16 @@ If you want to install senpy globally, use sudo instead of the ``--user`` flag. Docker Image ************ -Build the image or use the pre-built one: ``docker run -ti -p 5000:5000 gsiupm/senpy --host 0.0.0.0 --default-plugins``. +Build the image or use the pre-built one: + + ``docker run -ti -p 5000:5000 gsiupm/senpy --host 0.0.0.0 --default-plugins`` + +To add custom plugins, add a volume and tell senpy where to find the plugins: + + ``docker run -ti -p 5000:5000 -v :/plugins gsiupm/senpy --host 0.0.0.0 --default-plugins -f /plugins`` + + +Note: There is a Senpy version for python2 too. + + ``docker run -ti -p 5000:5000 gsiupm/senpy-python2.7 --host 0.0.0.0 --default-plugins`` -To add custom plugins, add a volume and tell senpy where to find the plugins: ``docker run -ti -p 5000:5000 -v :/plugins gsiupm/senpy --host 0.0.0.0 --default-plugins -f /plugins`` diff --git a/docs/plugins.rst b/docs/plugins.rst index 3c12242..2ea48d7 100644 --- a/docs/plugins.rst +++ b/docs/plugins.rst @@ -2,6 +2,8 @@ Developing new plugins ---------------------- This document describes how to develop a new analysis plugin. For an example of conversion plugins, see :doc:`conversion`. +There is also a tutorial for developing new plugins with slides `here `__ + Each plugin represents a different analysis process.There are two types of files that are needed by senpy for loading a plugin: - Definition file, has the ".senpy" extension. diff --git a/docs/senpy.rst b/docs/senpy.rst index bbf4a1d..e2287dc 100644 --- a/docs/senpy.rst +++ b/docs/senpy.rst @@ -1,35 +1,18 @@ What is Senpy? -------------- -Senpy is an open source reference implementation of a linked data model for sentiment and emotion analysis services based on the vocabularies NIF, Marl and Onyx. +Senpy is a framework to build semantic sentiment and emotion analysis services. Using Senpy you can easy develop and publish your own analysis algorithms. -The overall goal of the reference implementation Senpy is easing the adoption of the proposed linked data model for sentiment and emotion analysis services, so that services from different providers become interoperable. With this aim, the design of the reference implementation has focused on its extensibility and reusability. +If you use Senpy, please cite `Senpy: A Pragmatic Linked Sentiment Analysis Framework `__ (`BibTex `__): -A modular approach allows organizations to replace individual components with custom ones developed in-house. Furthermore, organizations can benefit from reusing prepackages modules that provide advanced functionalities, such as algorithms for sentiment and emotion analysis, linked data publication or emotion and sentiment mapping between different providers. +.. code-block:: text -Specifications -============== + Sánchez-Rada, J. F., Iglesias, C. A., Corcuera, I., & Araque, Ó. (2016, October). + Senpy: A Pragmatic Linked Sentiment Analysis Framework. + In Data Science and Advanced Analytics (DSAA), + 2016 IEEE International Conference on (pp. 735-742). IEEE. -The model used in Senpy is based on the following specifications: +.. toctree:: + specifications + architecture -* Marl, a vocabulary designed to annotate and describe subjetive opinions expressed on the web or in information systems. -* Onyx, which is built one the same principles as Marl to annotate and describe emotions, and provides interoperability with Emotion Markup Language. -* NIF 2.0, which defines a semantic format and APO for improving interoperability among natural language processing services - -Architecture -============ - -The main component of a sentiment analysis service is the algorithm itself. However, for the algorithm to work, it needs to get the appropriate parameters from the user, format the results according to the defined API, interact with the user whn errors occur or more information is needed, etc. - -Senpy proposes a modular and dynamic architecture that allows: - -* Implementing different algorithms in a extensible way, yet offering a common interface. -* Offering common services that facilitate development, so developers can focus on implementing new and better algorithms. - -The framework consists of two main modules: Senpy core, which is the building block of the service, and Senpy plugins, which consist of the analysis algorithm. The next figure depicts a simplified version of the processes involved in an analysis with the Senpy framework. - -.. image:: senpy-architecture.png - :height: 400px - :width: 800px - :scale: 100 % - :align: center diff --git a/docs/specifications.rst b/docs/specifications.rst new file mode 100644 index 0000000..fdcee72 --- /dev/null +++ b/docs/specifications.rst @@ -0,0 +1,8 @@ +Specifications +============== + +The model used in Senpy is based on the following specifications: + +* Marl, a vocabulary designed to annotate and describe subjetive opinions expressed on the web or in information systems. +* Onyx, which is built one the same principles as Marl to annotate and describe emotions, and provides interoperability with Emotion Markup Language. +* NIF 2.0, which defines a semantic format and APO for improving interoperability among natural language processing services