Clarify the commentary around the Q&A Example.

DavidPratten · Jan 11, 2023 · 62e60bb · 62e60bb
1 parent a2598d8
commit 62e60bb
Show file tree

Hide file tree

Showing 2 changed files with 63 additions and 23 deletions.
diff --git a/Goal_seeking_covid_vaccination_and_work.ipynb b/Goal_seeking_covid_vaccination_and_work.ipynb
@@ -2,7 +2,7 @@
  "cells": [
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": 2,
    "metadata": {
     "collapsed": true
    },
@@ -14,25 +14,38 @@
   {
    "cell_type": "markdown",
    "source": [
-    "# Interviewing using Intensionally Defined Relations\n",
-    "Intensionally defined relations support goal directed question and answer with users. This notebook shows this working for arbitrary columns in the ```covid_vaccinations_and_work``` relation.\n",
+    "# Interactive Q&A with COVID Rules for Workplaces\n",
+    "Intensionally defined relations support goal directed question and answer with users. This notebook shows how to find the values in any column in the [covid_vaccinations_and_work](COVID_vaccinations_and_work.ipynb) relation through Q&A.\n",
+    "\n",
+    "Goal seeking is begun by nominating the relation being searched and the list of columns that are sought.  Jetisu chooses the sequence of questions to ask that will give the answer in the fewest questions.\n",
+    "\n",
+    "# Am I required to have COVID Vaccinations for my work?\n",
+    "The ```COVID vaccinations and work``` relation has two columns that show whether a worker is required to have one or more COVID vaccinations. The ```%%jetisu_seek_goal``` notebook cell accepts the name of a relation (table) and the columns that are sought.\n",
     "\n",
-    "Goal seeking is begun by nominating the relation being searched and the list of columns that are sought.  Jetisu chooses the questions to ask that will give the fastest answer. The principles involved in choosing the columns to query are explained below, but first here is an example.\n",
+    "When the following cell is run, the user will be asked for information about their role and the required number of vaccinations will be found.\n",
     "\n",
-    "_To see this in action, you will need to [run the example notebooks](docs/run_notebooks.md) for yourself._"
+    "_To see this in action, you will need to [run the example notebooks](docs/run_notebooks.md) for yourself._\n"
    ],
    "metadata": {
     "collapsed": false
    }
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 3,
    "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Finding covid_vaccination_work_recommended_doses, covid_vaccination_work_mandatory, please answer the following questions ...\n",
+      "\n"
+     ]
+    },
     {
      "data": {
       "text/plain": "<IPython.core.display.Markdown object>",
-      "text/markdown": "## Answer\n|covid_vaccination_work_recommended_doses|covid_vaccination_work_mandatory|\n|----|----|\n|3|True|\n### Because\nwork_sector='aged_care' and work_location='new_south_wales' and aged_care_facility\n\n### Along the way, the following additional values were determined:\n|disability_worker_in_school|\n|----|\n|False|\n\n|nsw_health_worker|\n|----|\n|False|\n\n|specialist_school|\n|----|\n|False|\n\n\n### And the following values were under-determined:\n|private_home_only|\n|----|\n|False|\n|True|\n\n"
+      "text/markdown": "## Answer\n|covid_vaccination_work_recommended_doses|covid_vaccination_work_mandatory|\n|----|----|\n|3|True|\n### Because\nwork_sector='aged_care' and work_location='new_south_wales' and aged_care_facility\n\n### Along the way, the following additional values were determined:\n|specialist_school|\n|----|\n|False|\n\n|nsw_health_worker|\n|----|\n|False|\n\n|disability_worker_in_school|\n|----|\n|False|\n\n\n### And the following values were under-determined:\n|private_home_only|\n|----|\n|False|\n|True|\n\n"
      },
      "metadata": {},
      "output_type": "display_data"
@@ -51,33 +64,43 @@
    "metadata": {
     "collapsed": false,
     "tags": [
-        "skip-execution"
-      ]
+     "skip-execution"
+    ]
    }
   },
   {
    "cell_type": "markdown",
    "source": [
-    "# What sequence are questions asked?\n",
-    "The best column to ask next is computed 'on-the-fly' by jetisu using the following scoring system:\n",
-    "- The more values in the column, the higher the column's score.\n",
-    "- If the column is a cross-product of the other columns the score is lower.\n",
-    "- The more equal the distribution of values in the column the higher the score.\n",
+    "# How does jetisu determine which questions to ask and in what sequence?\n",
+    "The next question to ask is computed 'on-the-fly' by jetisu. Of the columns containing unknown values, the best column to ask a question about is found by using the following scoring system:\n",
+    "- The more values in a column, the higher the column's score. e.g. The ```work_sector``` column has 7 values so will be higher scored that a True/False column like ```private_home_only```\n",
+    "- If the column is a cross-product of the other columns the score is lower. (Still working on a compelling illustration of this heuristic.)\n",
+    "- The more equal the distribution of values in the column the higher the score. e.g. if a column has three values, but 90% of the rows have just one value and the remaining two values share 10% of the rows, then this will score lower than a column of three values where the distribution is more equal.\n",
     "\n",
-    "Here is another example which will interview the person to find their work sector based on the Covid rules."
+    "Here is another example ...\n",
+    "\n",
+    "# Based on the COVID rules, what is my work sector?"
    ],
    "metadata": {
     "collapsed": false
    }
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 5,
    "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Finding work_sector, please answer the following questions ...\n",
+      "\n"
+     ]
+    },
     {
      "data": {
       "text/plain": "<IPython.core.display.Markdown object>",
-      "text/markdown": "## Answer\n|work_sector|\n|----|\n|aged_care|\n### Because\ncovid_vaccination_work_recommended_doses=3 and work_location='western_australia' and aged_care_facility\n\n### Along the way, the following additional values were determined:\n|covid_vaccination_work_mandatory|\n|----|\n|True|\n\n|private_home_only|\n|----|\n|False|\n\n|disability_worker_in_school|\n|----|\n|False|\n\n|nsw_health_worker|\n|----|\n|False|\n\n|specialist_school|\n|----|\n|False|\n\n\n### And the following values were under-determined:\n"
+      "text/markdown": "## Answer\n|work_sector|\n|----|\n|custodial|\n|disability_services|\n|emergency_services|\n|healthcare|\n### Because\ncovid_vaccination_work_recommended_doses=3 and work_location='victoria' and not aged_care_facility and not specialist_school and not private_home_only\n\n### Along the way, the following additional values were determined:\n|covid_vaccination_work_mandatory|\n|----|\n|True|\n\n|nsw_health_worker|\n|----|\n|False|\n\n|disability_worker_in_school|\n|----|\n|False|\n\n\n### And the following values were under-determined:\n"
      },
      "metadata": {},
      "output_type": "display_data"
@@ -95,8 +118,8 @@
    "metadata": {
     "collapsed": false,
     "tags": [
-        "skip-execution"
-      ]
+     "skip-execution"
+    ]
    }
   },
   {
@@ -106,7 +129,24 @@
     "You can edit and re-run this example workbook by following the instructions here:\n",
     "[How to run the example notebooks](https://github.com/DavidPratten/jetisu/blob/main/docs/run_notebooks.md)\n",
     "\n",
-    "You could, for example seek the ```work_location``` column."
+    "You could, for example seek the ```work_location``` column using the cell below."
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "%%jetisu_seek_goal\n",
+    "{\n",
+    "    \"table_name\": \"covid_vaccinations_and_work\",\n",
+    "    \"goal_list\": [\n",
+    "        \"work_location\"\n",
+    "    ]\n",
+    "}"
    ],
    "metadata": {
     "collapsed": false

diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@ Jetisu is a toolset for modelling with __intensionally defined relations__.
 Jetisu is understood to be the first implementation of intensionally defined relations. If you are aware of an earlier implementation, please raise an issue.
 
 ## Querying Rules As Code
-The examples are chosen to illustrate the benefits (and/or challenges) of using intensionally defined relations to model rules as code.
+The examples are chosen to illustrate the benefits (and/or challenges) of querying intensionally defined relations to model rules as code.
 - [ACT Conveyance Duty](ACT_Conveyance_Duty.ipynb)
 - [Australian GST](Australian_GST.ipynb)
 - [Birthday Money](Birthday%20Money.ipynb)
@@ -15,8 +15,8 @@ The examples are chosen to illustrate the benefits (and/or challenges) of using
 - [Range](Range.ipynb)
 
 ## Interactive Q&A with Rules as Code
-This example shows user Q&A using the same rule-set as the above "Australian COVID vaccinations mandatory for work roles" example:
-- [Tell me my status for mandatory vaccinations](Goal_seeking_covid_vaccination_and_work.ipynb)
+This example shows interactive Q&A using the same rule-set as the above "Australian COVID vaccinations mandatory for work roles" example:
+- [Am I required to have COVID vaccinations?](Goal_seeking_covid_vaccination_and_work.ipynb)
 
 ## Edit and re-run the example notebooks
 You can  ```docker run``` the example Jupyter notebooks for yourself.