TS4NLE.ipynb

{
  "nbformat": 4,
  "nbformat_minor": 0,
  "metadata": {
    "colab": {
      "name": "TS4NLE.ipynb",
      "provenance": []
    },
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3"
    },
    "language_info": {
      "name": "python"
    }
  },
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "pkyGUVmIRfh1"
      },
      "source": [
        "# TS4NLE: a Template System for Natural Language Explanations\n",
        "TS4NLE converts the explanation of an eXplainable AI (XAI) system into natural language utterances comprehensible by humans. Moreover, the XAI explanation can be enhanced with a domain and a user model that allow the natural language rendering to be tailored to the particular user.\n",
        "\n",
        "TS4NLE has been tested with real users for providing persuasive explanations for the adherance to the Mediterranean diet, see the main paper [here](https://www.sciencedirect.com/science/article/pii/S0933365719310140) and the [SEMEX4ALL tutorial](https://horus-ai.fbk.eu/semex4all/) at [ISWC2020](https://iswc2020.semanticweb.org/program/tutorials/).\n",
        "\n",
        "\n",
        "## Installation\n",
        "The source code of TS4NLE can be retrieved [here](https://github.com/ivanDonadello/TS4NLE). It requires Node.js and Python languages and it is mainly based on [RosaeNLG](https://rosaenlg.org/): a Natural Language Generation library for node.js, based on the [Pug template engine](https://pugjs.org/). Once Node.js, Python and the nmp package manager have been installed, TS4NLE can be easily installed by installing, as first step, the [Graphviz](https://graphviz.org/) library for graph visualization:"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "m1w35dYEfMNr"
      },
      "source": [
        "!apt-get install graphviz graphviz-dev\n",
        "!pip install pygraphviz"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Py2g_qsHfTcP"
      },
      "source": [
        "then install the repository with:"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "r5L7uhEgRhKf"
      },
      "source": [
        "!git clone https://github.com/radu1690/Explanations.git\n",
        "%cd Explanations\n",
        "!npm install"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "7KEoOb-qR9E5"
      },
      "source": [
        "Remove the initial characters `!`, `%` when running in a shell.\n",
        "\n",
        "\n",
        "## Citing TS4NLE\n",
        "If you use TS4NLE in your research, please use the following BibTeX entry.\n",
        "```\n",
        "@article{DragoniDE20,\n",
        "  author    = {Mauro Dragoni and\n",
        "               Ivan Donadello and\n",
        "               Claudio Eccher},\n",
        "  title     = {Explainable {AI} meets persuasiveness: Translating reasoning results into behavioral change advice},\n",
        "  journal   = {Artif. Intell. Medicine},\n",
        "  volume    = {105},\n",
        "  pages     = {101840},\n",
        "  year      = {2020}\n",
        "}\n",
        "```\n",
        "\n",
        "\n",
        "## Using TS4NLE\n",
        "TS4NLE requires as input:\n",
        "- An explanation graph provided by XAI techniques that contains all the information necessary to provide a justification for the output of an Artificial Intelligence system. Notice that TS4NLE is agnostic to the underlying AI system (no matter what whether it is a Machine-Learning based or a reasoning-based one) as it is solely based on the explanation graph.\n",
        "- The templates that encode the rules on how the explanation graph has to be rendered in natural language. They can be intepreted as a bridge between the explanation graph and the consequent natural language explanation. They both contain chunks of text and the link/rules to the nodes and relations in the explanation graph.\n",
        "\n",
        "The following sections contain howtos about the encoding of explanation graphs and of the templates.\n",
        "\n",
        "\n",
        "## How to encode the explanation graphs for TS4NLE\n",
        "The graphs are stored in `.csv` files (with tab 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 edge. Every XAI method is responsible to provide the right semantics to the triple `<subject, predicate, object>`. For example, the bars provided by the Lime explanator can be encoded with nodes having connections with the root (the output) and with their children that encode the numeric values associated with the features.\n",
        "\n",
        "According to the current implementation, the explanation graph must be in the form of a tree: a direct acyclic graph where children nodes have only one parent. The subject of the first row in the `.csv` file is the root of the explanation graph. Here a small example of an explanation graph detecting a bad diet behavior:\n",
        "```\n",
        "explanation outputClassification badBehavior \n",
        "explanation\tentity\tRedMeat\n",
        "explanation\ttiming\tWeek\n",
        "RedMeat\tquantity\t7\n",
        "RedMeat\tNutrient\tAnimalLipid\n",
        "AnimalLipid\tcons\tincrement of cardiovascular disease risk\n",
        "AnimalLipid\tcons\tincrement of cholesterol in the blood\n",
        "explanation hasUser Mario\n",
        "Mario hasAge 65\n",
        "Mario hasRecidivityFor RedMeat\n",
        "RedMeat recidivityLevel high\n",
        "```\n",
        "The root of the graph is the concept of `explanation` linked with the output of our classifier: `badBehavior` (first line). What follows is the explanation for the detected bad behavior (lines 2-7): a too much consumption of red meat in only one week. Lines 5-7 contain information from a domain model stating what are the medium-term consequences of a high consumption of red meat. Lines 8-10 contain the user model, that is, information about the user diet habits. This can be used to tailor the natural language rendering of the explanation.\n",
        "\n",
        "The following commad will show a graphical representation of the explanation graph:\n",
        "```\n",
        "python csv2graphviz.py <graph.csv>\n",
        "```\n",
        "\n",
        "### Parsing the explanation graph\n",
        "The script `graphToObject.js` will parse the `.csv` file into an `explanation` Javascript object that can be inspected in the Pug template, see the next section for more details. Such a script can be embedded into a main file with the following code:\n",
        "```\n",
        "graph2Object.main(dir_explanationGraph)\n",
        ".then(data =>{\n",
        "    var output = rosaenlgPug.renderFile(dir_template, {\n",
        "        language: rosae_language,\n",
        "        explanation: data,\n",
        "        pluralize: pluralize,\n",
        "        random: randomElement\n",
        "    });\n",
        "    console.log(output)\n",
        "})\n",
        ".catch(err => console.error(err))\n",
        "```\n",
        "According to the current implementation, the fields of the `explanation` object can be only single-value fields or arrays.\n",
        "\n",
        "\n",
        "## How to write your own TS4NLE templates\n",
        "The TS4NLE templates follow the Pug syntax (see the main website [here](https://pugjs.org/) for more information) and are rendered with RosaeNLG engine. Here we describe the basics of Pug and RosaeNLG, for a complete tutorial with advanced features see the main website [here](https://rosaenlg.org/rosaenlg/3.0.0/tutorials/tutorial_en_US.html).\n",
        "\n",
        "\n",
        "### Rendering plain text\n",
        "Templates are textual files in `.pug` format. To just render some plain text use the pipe character (`|`) followed by the text you want to render:  \n",
        "```\n",
        "|Pay attention at your diet!\n",
        "```\n",
        "with output: \"Pay attention at your diet!\". Spaces between different plain texts (except only punctuation) are automatically inserted, so:\n",
        "```\n",
        "|Pay attention\n",
        "|at your diet\n",
        "|!\n",
        "```\n",
        "will still output: \"Pay attention at your diet!\".\n",
        "\n",
        "### Rendering explanation fields\n",
        "Once the explanation graph has been parsed and transformed into an `explanation` Javascript object, it is possible to access its fields in the Pug template. The access to the single fields can be done in two ways:\n",
        " - `#[+value(explanation.field)]` that throws an error if the field does not exists;\n",
        " - `!{explanation.field}` that prints an empty string if the field does not exists.\n",
        "\n",
        "For example, rendering the English label of a food entity is simply performed by accessing the relative field:  \n",
        "```\n",
        "|You ate #[+value(explanation.entity.enLabel)].\n",
        "```\n",
        "with output: \"You ate red meat.\"\n",
        "\n",
        "\n",
        "### Rendering conditionals\n",
        "If-then-else statements are allowed in the templates and can encode some rules of rendering according to the content of the explanation graph. For example, one can select the more appropriate textual content according to the kind of food he has consumed:\n",
        "```\n",
        "if explanation.constraint == 'less'\n",
        "\t|You ate too much\n",
        "else \n",
        "\t|You did not eat enough\n",
        "|#[+value(explanation.entity.enLabel)].\n",
        "```  \n",
        "with output: \"You ate too much red meat.\" if `explanation.constraint` is `less` and `explanation.entity.enLabel` is `red meat`. Other values for these fields can lead to the following output: \"You did not eat enough vegetables.\" Notice that the use of the `#[+value()]` or the `!{}` notations is not allowed inside the `if`, `else` conditions.  \n",
        "\n",
        "### Redering Javascript code\n",
        "The Pug templates allow the writing of Javascript code. Here we just show the definition of simple variables that can be used in the template. Variables are defined with the following syntax:\n",
        "```\n",
        "- let variable_name = \"variable value\"\n",
        "```\n",
        "and accessed by `!{variable_name}`. The following template\n",
        "```\n",
        "- let food = \"Red meat\"\n",
        "- let nutrient = [\"animal proteins\", \"animal lipids\"]\n",
        "\n",
        "|!{food} contains a lot of !{nutrient[0]}\n",
        "```\n",
        "will output \"Red meat contains a lot of animal proteins\".\n",
        "\n",
        "\n",
        "### Rendering loop iterations\n",
        "For loops are useful when inspecting an array field in the explanation. Loops are performed with the `eachz` operator from RosaeNLG:\n",
        "```\n",
        "-let nutrients = [\"animal lipids\", \"animal proteins\"]\n",
        "eachz element in nutrients\n",
        "    |explanation.entity !{element}\n",
        "```\n",
        "with output: \"Red meat contains animal lipids, animal proteins\". However, this sentence is not formatted in a proper English. It should have an \"and\" instead of the comma and should end with a dot. This can be correct by using [additional parameters](https://rosaenlg.org/rosaenlg/3.0.0/mixins_ref/eachz_itemz.html) supported by the `eachz` operator. The previous template can be modified as this:\n",
        "```\n",
        "-let nutrients = [\"animal lipids\", \"animal proteins\"]\n",
        "eachz element in nutrients with {separator: \",\", last_separator: \"and\", end: \".\"} \n",
        "    |explanation.entity !{element}\n",
        "```\n",
        "with output: \"Red meat contains animal lipids and animal proteins.\".\n",
        "\n",
        "\n",
        "## Functions\n",
        "Javascript functions can be directly used in your templates. Here we provide two examples: the first involves a function of the standard Javascript library, the second a custom function.\n",
        "\n",
        "### Pluralize\n",
        "[Pluralize](https://www.npmjs.com/package/pluralize) is Javascript module that pluralize and singularize any given word. Use `pluralize(<word>)` or `pluralize.singular(<word>)` in a template to either pluralize or singularize a word. Use `pluralize.isSingular()` and `pluralize.isPlural()` to check if a word is either singular or plural. This example:  \n",
        "```\n",
        "if pluralize.isSingular(explanation.entity)\n",
        "\t|contains\n",
        "else\n",
        "\t|contain\n",
        "```  \n",
        "will output \"contains\" if the entity field is singular (e.g., \"red meat\") or \"contain\" if the entity field is plural (e.g., \"vegetables\").\n",
        "\n",
        "\n",
        "### Random\n",
        "Random is a custom function that returns a random element of an array (if the argument is an array) or the argument itself if it is not an array. Here how to call the function in a template:  \n",
        "```\n",
        "- let nutrient = random(explanation.entity.negative)\n",
        "- let consequence = random(nutrient.cons_en)\n",
        "\n",
        "|High consumption of !{explanation.entity} for long time could cause !{consequence}.\n",
        "```\n",
        "with output \"High consumption of red meat could cause cardiovascular diseases\". Here the implementation of such a function in the `explanations.js` file:\n",
        "```\n",
        "function randomElement(items){\n",
        "    if(Array.isArray(items)){\n",
        "        return items[Math.floor(Math.random()*items.length)]\n",
        "    }else{\n",
        "        return items\n",
        "    }\n",
        "}\n",
        "```\n",
        "\n",
        "\n",
        "### How to add a function\n",
        "Functions need to be passed to the RosaeNLG engine in your main file (`explanations.js` in our case):\n",
        "```\n",
        "graph2Object.main(dir_explanationGraph)\n",
        "\t.then(data =>{\n",
        "\t\tvar output = rosaenlgPug.renderFile(dir_template, {\n",
        "\t\t\tlanguage: rosae_language,\n",
        "\t\t\texplanation: data,\n",
        "\t\t\tpluralize: pluralize,\t//pluralize function\n",
        "\t\t\trandom: randomElement\t//random function\n",
        "\t\t});\n",
        "\t\tconsole.log(output)\n",
        "\t})\n",
        "```"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "cPqDqWK1bX4b"
      },
      "source": [
        "## Run TS4NLE\n",
        "You can run TS4NLE with:  \n",
        "```\n",
        "node explanations.js <template> <graph>\n",
        "```\n",
        "where `template` is the `.pug` file of the template and `graph` the `.csv` explanation graph file. Here some examples in the repository:"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "WNdPHAL-R-S8",
        "outputId": "d1038f8a-e996-49c9-c8ea-978d44e21d13"
      },
      "source": [
        "node explanations.js templates/english/argument.pug graphs/exp_graph_1_en.csv"
      ],
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "text": [
            "Red meat contains animal protein which can cause the increment of cancer risk!\n"
          ],
          "name": "stdout"
        }
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "gviJLYJgSF-m"
      },
      "source": [
        "You can specify the language, English or Italian (the default is English), like in the following example:"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "1ZCDpNQRSGtM",
        "outputId": "574ed335-323e-4ceb-8202-116b6be28d7c"
      },
      "source": [
        "!node explanations.js templates/italian/feedback.pug graphs/exp_graph_1_it.csv italian"
      ],
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "text": [
            "Hai consumato una grande quantità di carne rossa (3 su un massimo di 2)\n"
          ],
          "name": "stdout"
        }
      ]
    }
  ]
}