Add README.md

README.md

+# SAPIS
+StilLett API Service
+
+'SAPIS' is a restful web service based on Java Spring, implementing an API with 
+the ability to interpret options and input data as variables in an input JSON 
+object, passed to the 'SAPIS' service in a HTTP request. The open access of the 
+API allows for distribution of any web service uploaded to the same server 
+domain.
+
+The API service can be reached from a server located at: http://www.ida.liu.se/projects/scream/services/sapis/service/, accepting POST requests.
+
+## Current services
+The current services implemented in 'SAPIS' are chosen from the research projects presented by Falkenjack et al., 2013 and Rennes and Jönsson, 2015.
+1. The SurfaceMetrics (Falkenjack et al., 2013) service provides simple readability metrics such as LIX, OVIX, Nominal ratio, Mean sentence length and Mean word length.
+2. The LexicalMetrics (Falkenjack et al., 2013) service provides a categorized frequency analysis from word occurrences in the basic Swedish vocabulary SweVoc dictionary.
+3. The StructuralMetrics (Falkenjack et al., 2013) provides syntactic and morpho-syntactic features based on part-of-speech tags (openNLP) and dependency tags (MaltParser).
+4. StilLett (Rennes and Jönsson, 2015), a rule-based automatic text simplification tool for Swedish, using part-of-speech tags (Stagger) and phrase structure tags (MaltParser 1.2) to identify textual difficulties and execute simplifications as node operations.
+5. Rule-based text simplification based on dependency parsed sentences 
+
+For a further description of these research projects, see *Features indicating readability in Swedish
+text*, by Johan Falkenjack, Katarina Heimann Mühlenbock, and Arne Jönsson 2013 and *A tool for
+automatic simplification of Swedish texts*, by Evelina Rennes and Arne Jönsson 2015.
+
+## HTTP request
+'SAPIS' requires the input to be a JSON object containing the two variables options and
+document, where options specifies the choice of services and document specifies the string of
+text to be analyzed/simplified. The chosen services are started in parallel and the result of each
+service is merged into one single response.
+
+The output response is a JSON object containing all possible variables (even though most values
+are not always calculated). A suggestion is to print the response of the HTTP request to the
+console of your browser (in java script by using console.log()) in order to easily investigate the
+response JSON object and the values that is calculated.
+
+### Java script examples
+This section contains two examples on how to use 'SAPIS' with the services for calculating readability metrics and text simplification.
+
+This is an HTTP request, using jQuery.ajax, to 'SAPIS' and the services generating readability
+metrics: LexicalMetrics, SurfaceMetrics and StructuralMetrics.
+
+    var sapis_url = ’http://www.ida.liu.se/projects/scream/services/sapis/service/';
+    var scream_response;
+    jQuery.ajax({
+    headers: {
+    'Accept': 'application/json',
+    'Content-Type': 'application/json'},
+    'type': 'POST',
+    'url': sapis_url,
+    'data': JSON.stringify({
+    options : ”LexicalMetrics()\tSurfaceMetrics()\tStructuralMetrics()”,
+    document : [input text as string]
+    }),
+    'dataType': 'json',
+    'success': function(resp) {
+    console.log(resp);
+    scream_response = resp;
+    },
+    'error': function(xhr, textStatus, errorThrown) {
+    alert(xhr.responseText);
+    }
+    });
+
+This is an HTTP request, using jQuery.ajax, to Sapis and the service StilLett to generate a text
+simplification. StilLett requires the user to specify options regarding pre-processing, analysis and
+post-processing. These options are further described in A tool for automatic simplification of
+Swedish texts, by Evelina Rennes and Arne Jönsson 2015.
+
+    var sapis_url = 'http://www.ida.liu.se/projects/scream/services/sapis/service/';
+    var stillett_response;
+    jQuery.ajax({
+    headers: {
+    'Accept': 'application/json',
+    'Content-Type': 'application/json'
+    },
+    'type': 'POST',
+    'url': sapis_url,
+    'data': JSON.stringify({
+    options : "StilLett(pre{\n" +
+    "-stagger\n" +
+    "-suc2negra\n" +
+    "-phraseStructParser\n" +
+    "}\n" +
+    "feedback{\n" +
+    "-straightOrder\n" +
+    //Straight word order, Subject-Verb-Object
+    "-pass2act\n" +
+    //Rewrite from Passive to Active form.
+    "-decker\n" +
+    //Remove information. Sometimes too much.
+    "-split\n" +
+    //Split sentences.
+    "}\n" +
+    //Which rules to use in text simplification (simplifiedText in the JSON return object)
+    "easy{\n" +
+    "-straightOrder\n" +
+    "-pass2act\n" +
+    "-syntax\n" +
+    "-proximation\n" +
+    "-split\n" +
+    "-quoteInvert\n" +
+    "-decker\n" +
+    //
+    "-synonyms\n" + // Time consuming
+    "}\n" +
+    "post{\n" +
+    "-cleanNoHTML\n" +
+    "})",
+    document : [input text as string]
+    }),
+    'dataType': 'json',
+    'success': function(resp) {
+    console.log(resp);
+    stillett_response = resp;
+    },
+    'error': function(xhr, textStatus, errorThrown) {alert(xhr.responseText);
+    }
+    });
+
+When finished; a simplified version of the input text can be found in the simplifiedText variable
+of the response JSON object.
+
+## NEW!
+To use dependency parsed sentences change the feedback option to:
+
+    options: "Feedback(-split -pass2act -svo -quoteInv -prox)"
+
+If the dependency parser is used the output format is instead a JSON object with JSON objects för
+each suggested simplification:
+
+    "_suggestions":{
+    ”[simplification rule]_[sentence number]": {
+    "original": [original sentence]
+    "sent_suggestion": [simplified sentence]
+    "suggestion": [textual explanation on how to simplify the sentence]
+    }
+    }
+
+StilLett is implemented in Sapis with the extended functionality of generate feedback strings. This
+functionality is not described by Rennes and Jönsson, 2015 but is defined with the same set of
+rules as described by them. The string:
+
+    "feedback{\n" +
+    "-straightOrder\n" +
+    "-pass2act\n" +
+    "-decker\n" +
+    "-split\n" +
+    ”}\n"
+
+describes which feedback module to use. The variable suggestions of the response JSON
+object contains the feedback as a list with a suggestion on how to rewrite a sentence. Each
+suggestion is given as a string on the form:
+
+    ”[original sentence] FEEDBACK: [suggestion]”.
+
+NOTE: All services can be reached in one single HTTP request, but it is currently recommended to
+make a separate request to the StilLett service due to its time consuming pre-processing.
+## Contact
+Hampus Arvå, hamli364@student.liu.se, for technical support.
+## References
+1. Johan Falkenjack, Katarina Heimann Mühlenbock, and Arne Jönsson. 2013. Features
+indicating readability in Swedish text. In Proceedings of the 19th Nordic Conference of
+Computational Linguistics (NoDaLiDa-2013), Oslo, Norway.
+2. Evelina Rennes and Arne Jönsson. 2015. A tool for automatic simplification of Swedish texts. In
+Proceedings of the 20th Nordic Conference of Computational Linguistics (NoDaLiDa-2015),
+Vilnius, Lithuania.