From c8d485cc1f3b342285dc4331927c39eaf35d6068 Mon Sep 17 00:00:00 2001
From: Radu Loghin <radu.loghin@studenti.unitn.it>
Date: Mon, 21 Jun 2021 13:28:52 +0200
Subject: [PATCH] Updated readme and moved graphviz

---
 README.md                           | 127 +++++++++++++---------------
 graphToObject.js                    |   8 +-
 graphviz/graphviz.py => graphviz.py |   0
 graphviz/README.md                  |  18 ----
 graphviz/exp_graph_1_en.csv         |  31 -------
 templates/italian/consequences.pug  |   2 +-
 6 files changed, 64 insertions(+), 122 deletions(-)
 rename graphviz/graphviz.py => graphviz.py (100%)
 delete mode 100644 graphviz/README.md
 delete mode 100644 graphviz/exp_graph_1_en.csv

diff --git a/README.md b/README.md
index 30028cf..1da2e5b 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,9 @@
 # ExplanationsGraph
 This is a simple program that retrieves the information from an explanation graph and uses [RosaeNLG](https://rosaenlg.org/) and [Pug templates](https://pugjs.org/) to generate text.  
 
-## Installation
+## Installation  
+Install [NodeJs](https://nodejs.org/en/download/)  
+
 Clone the repository and install dependecies
 ```
 git clone https://github.com/radu1690/Explanations.git
@@ -13,7 +15,7 @@ You can run the program with:
 ```
 node explanations.js <template> <graph>
 ``` 
-Template is the location of the pug template while graph is a graph in csv format (with "," as delimiter). Example:  
+Template is the location of the pug template while graph is a graph in csv format (with "\t" as delimiter). Example:  
 ```
 node explanations.js templates/english/argument.pug graphs/exp_graph_1_en.csv
 ``` 
@@ -23,7 +25,35 @@ You can specify the language, English or Italian (the default is English), like
 node explanations.js templates/italian/feedback.pug graphs/exp_graph_1_it.csv italian
 ```  
 
-# Basic Tutorial for Templates
+## Graphviz
+You can generate a visual reppresentation of a graph with [Graphviz](https://graphviz.org/).  
+Install requirements:
+```
+!apt-get install graphviz graphviz-dev
+!pip install pygraphviz
+```
+
+The graph must be in a csv file with ```\t``` delimiter.  
+
+Run with: 
+```python graphviz.py <graph> ```  
+
+Example:
+```
+!python graphviz.py graphs/exp_graph_1_en.csv
+```
+will generate a pdf file named exp_graph_1_en.pdf with the reppresentation of the graph.
+
+# Explanation graph format
+The graphs are stored in csv file (with \t delimiter) where each row contains a triple in the form of "subject - predicate - object": subject is the parent node, object is the child node and predicate is the arc label.  
+In every graph the following must be true:
+* the subject of the first row is the head node of the graph
+* the graph does not contain cycles
+* a child node has only one parent node
+
+# Basic templates and RosaeNLG tutorial
+For all the features in Pug templates you can check the [Pug main website](https://pugjs.org/).  
+A complete tutorial with advanced features of RosaeNLG can be found [here](https://rosaenlg.org/rosaenlg/3.0.0/tutorials/tutorial_en_US.html).
 ## Plain text
 To insert some plain text you can use the pipe character (`|`) followed by the text you want to write:  
 ```
@@ -40,42 +70,7 @@ Spaces between different plain texts (except only punctuation) are automatically
 will still output: ```Hello world!``` 
 
 ## Variables  
-The object passed to RosaeNLG (after the graph has been processed) is an explanation. The following is the object generated from graphs/exp_graph_1_en.csv:
-```
-{
-  timestamp: '1541622487915',
-  startTime: '1541440506117',
-  endTime: '1541622487915',  
-  quantity: '3',
-  expectedQuantity: '2',     
-  priority: '1',
-  level: '3',
-  history: '1',
-  explanationId: 'explanation_1yfzqe9kjrdmm0sc349qj3x7loeal6tzw7amlhhphpl5z78051_mr-diet-018-nweek_1541622487915',
-  user: '1yfzqe9kjrdmm0sc349qj3x7loeal6tzw7amlhhphpl5z78051',
-  ruleId: 'mr-diet-018-nweek',
-  entityType: 'foodcategory',
-  entity: {
-    enLabel: 'red meat',
-    negative: [
-        {   enLabel: 'animal protein', 
-            cons_en: [ 'intestinal inflammation', 'the increment of cancer risk' ] 
-        },
-        {   enLabel: 'animal lipids',
-            cons_en: [
-                'increment of cardiovascular disease risk',
-                'increment of cholesterol in the blood'
-            ]
-        }
-    ],
-    alternatives: [ { enLabel: 'processed legumes' }, { enLabel: 'fish' } ]
-  },
-  timing: 'week',
-  meals: [ 'meal-meal-1541440506117', 'meal-meal-1541440506118' ],
-  goals: 'sp-goal-d-114',
-  constraint: 'less'
-}
-```
+The object passed to RosaeNLG (after the graph has been processed) is an explanation.  
 To print a field, you write ```#[+value(explanation.field)]``` or ```!{explanation.field}```. For example, the value of explanation.entity.enLabel is "red meat":  
 ```
 |You ate #[+value(explanation.entity.enLabel)].
@@ -98,7 +93,7 @@ else
 will output: ```You ate too much, enough meat!```  
 Note that to use an explanation field in an if-else statement you must not use the ```#[+value()]``` or the ```!{}``` notation.  
 
-## Javascript code and Functions
+## Javascript code, iteration and functions
 You can write javascript code in a template by starting the line with the "```-```" character,for example here i declare two variables and then I use them in the template:
 ```
 - let nutrient = "cheese"
@@ -107,6 +102,26 @@ You can write javascript code in a template by starting the line with the "```-`
 |the !{food} contains a lot of !{nutrient}
 ```
 This will output ```The pie contains a lot of cheese```
+
+## Iteration
+You can do loop with the ```eachz``` operator from RosaeNLG:
+```
+-let data = ["fruits", "vegetables", "meat"]
+eachz element in data
+    |!{data}
+```
+will output: ```fruits vegetables meat```
+
+The ```eachz``` operator can accept some [parameters](https://rosaenlg.org/rosaenlg/3.0.0/mixins_ref/eachz_itemz.html) which are useful in Natural Language Generation. Example:
+```
+-let data = ["fruits", "vegetables", "meat"]
+|I bought
+eachz element in data with {separator: ",", last_separator: "and", end: "."} 
+    |!{element}
+```
+will output: ```I bought fruits, vegetables and meat.```
+
+## Functions
 ### Pluralize
 You can use ```pluralize.isSingular()``` and ```pluralize.isPlural()``` in a template to check if a word is either singular or plural. Example:  
 ```
@@ -124,31 +139,9 @@ The random function will return a random element of an array (if the argument is
 - let consequence = random(nutrient.cons_en)
 ```
 
-You can also add your own functions to pug (this is explained bellow in the RosaeNLG tutorial)  
-
-For other advanced features in Pug you can check the [Pug main website](https://pugjs.org/).  
-
-# RosaeNLG tutorial
-A complete tutorial with advanced features can be found [here](https://rosaenlg.org/rosaenlg/3.0.0/tutorials/tutorial_en_US.html)
-## Import library
-```
-var rosae = require('rosaenlg');
-```  
-
-## Usage
-```
-var output = rosae.renderFile(dir_template, {
-        language: 'en_US',
-        explanation: processedGraph,
-        pluralize: pluralize
-    });
-```
-```dir_template``` is the location of the pug template.  
-```language``` is the locale code of the language to be used by RosaeNLG.  
-The rest are data (objects or arrays) and functions to be used in the template. Here I pass the function ```pluralize``` and the object called ```processedGraph``` in my js file which will be accessible as ```!{explanation}``` in the template.  
-
-## Functions example
-If I want to use my own function from the template which for example will print the input text two times, I can do it like this:
+## Functions customization
+You can also add your own javascript functions to use in pug templates.  
+Here I create a function in my JS file which will print the input text two times and then I pass it to RosaeNLG:
 ### JS file
 ```
 var rosae = require('rosaenlg');
@@ -160,14 +153,12 @@ function customFunction(input){
 
 console.log( rosae.renderFile('testNLG.pug', {
     language: 'en_US',
-    data: ['apples', 'bananas', 'apricots'],
     double : customFunction
 }) );
 ```  
 ### PUG template testNLG.pug
 ```
+-let data = ['apples', 'bananas', 'apricots']
 |!{double(data[0])}
 ```  
 This will output: ```Apples apples```. 
-
-
diff --git a/graphToObject.js b/graphToObject.js
index 5484ca5..94f9159 100644
--- a/graphToObject.js
+++ b/graphToObject.js
@@ -30,8 +30,8 @@ function graphToObject(graph){
   }
   var nodes = graphlib.alg.postorder(graph, graphName)
   //console.log(nodes)
-  var json = {}
-  var f = false
+  /* var json = {}
+  var f = false */
   for (n in nodes){
     //console.log(graph.node(nodes[n]))
     //console.log(graph.successors(nodes[n]))
@@ -41,10 +41,10 @@ function graphToObject(graph){
       //console.log(graph.node(nodes[n]))
       //this is object
       var children = graph.successors(nodes[n])
-      if(f){
+      /* if(f){
         console.log(children)
         f=false;
-      }
+      } */
       var obj = {}
       for (child in children){
         //console.log(graph.node(children[child]))
diff --git a/graphviz/graphviz.py b/graphviz.py
similarity index 100%
rename from graphviz/graphviz.py
rename to graphviz.py
diff --git a/graphviz/README.md b/graphviz/README.md
deleted file mode 100644
index b558f1f..0000000
--- a/graphviz/README.md
+++ /dev/null
@@ -1,18 +0,0 @@
-# Graphviz
-You can generate a visual reppresentation of a graph with [Graphviz](https://graphviz.org/).  
-Install requirements:
-```
-!apt-get install graphviz graphviz-dev
-!pip install pygraphviz
-```
-
-The graph must be in a csv file with ```\t``` delimiter.  
-
-Run with: 
-```python graphviz.py <graph> ```  
-
-Example:
-```
-!python graphviz.py exp_graph_1_en.csv
-```
-will generate a pdf file named exp_graph_1_en.pdf with the reppresentation of the graph.
\ No newline at end of file
diff --git a/graphviz/exp_graph_1_en.csv b/graphviz/exp_graph_1_en.csv
deleted file mode 100644
index 4e7f3ec..0000000
--- a/graphviz/exp_graph_1_en.csv
+++ /dev/null
@@ -1,31 +0,0 @@
-explanation	explanationId	explanation_1yFZqe9kJrDmM0SC349QJ3X7loEAL6TZw7aMLhhphpl5z78051_MR-DIET-018-NWEEK_1541622487915
-explanation	user	1yFZqe9kJrDmM0SC349QJ3X7loEAL6TZw7aMLhhphpl5z78051
-explanation	ruleId	MR-DIET-018-NWEEK
-explanation	timestamp	1541622487915
-explanation	startTime	1541440506117
-explanation	endTime	1541622487915
-explanation	entityType	FOODCATEGORY
-explanation	entity	RedMeat
-RedMeat	enLabel	Red Meat
-RedMeat	negative	AnimalProtein
-RedMeat	negative	AnimalLipid
-AnimalLipid	enLabel	Animal Lipids
-AnimalLipid	cons_en	increment of cardiovascular disease risk
-AnimalLipid	cons_en	increment of cholesterol in the blood
-AnimalProtein	enLabel	Animal Protein
-AnimalProtein	cons_en	intestinal inflammation
-AnimalProtein	cons_en	the increment of cancer risk
-RedMeat	alternatives	LegumesAndLegumeProducts
-RedMeat	alternatives	Fish
-Fish	enLabel	Fish
-LegumesAndLegumeProducts	enLabel	Processed Legumes
-explanation	timing	Week
-explanation	quantity	3
-explanation	expectedQuantity	2
-explanation	meals	MEAL-meal-1541440506117
-explanation	meals	MEAL-meal-1541440506118
-explanation	goals	SP-GOAL-D-114
-explanation	priority	1
-explanation	level	3
-explanation	constraint	less
-explanation	history	1
diff --git a/templates/italian/consequences.pug b/templates/italian/consequences.pug
index d55de1c..d1bdf31 100644
--- a/templates/italian/consequences.pug
+++ b/templates/italian/consequences.pug
@@ -14,7 +14,7 @@ if explanation.entity.negative != null
         else
             |!{explanation.entity.negative.cons_it}
     |.
-if explanation.entity.positive !=null
+if explanation.entity.positive != null
     |The long-term benefits of a regular assumption of !{explanation.entity.itLabel} can be:
     if Array.isArray(explanation.entity.positive)
         eachz positive in explanation.entity.positive with { separator: ',',}