Getting Started
July 21, 2017Welcome to the world of abductive reasoning! In this tutorial, you will learn how to use software called Etcetera Abduction, a form of logical abduction that finds assumptions that logically entail a given set of observations, and orders them by their probability.
This technology has lots of potential applications, including:
- interpreting the intended meaning of natural language text
- explaining people's observable behavior in terms of their beliefs, plans, and goals
- weighing competing theories in light of the available evidence
- inferring the situational context that explains the presence of objects in a visual scene
- generating creative narratives from novel combinations of characters, objects, and actions
All of these tasks can be described as interpretation problems. They all involve the disambiguation of ambiguous inputs, the combination of associations to establish coherence, and are subject to the biases and beliefs of the reasoner. Interpretation problems don't have a single right answer: the best solution is, by definition, open to interpretation.
Etcetera Abduction solves interpretation problems by combining a little bit of logical reasoning and a little bit of probability theory. You don't need to be an expert in either in order to use this technology. I recommend that you just dive in, and figure out what you need to learn along the way.
Installing Etcetera Abduction
Unlike other programs on your computer, Etcetera Abduction does not have a graphical user interface; you have to use via a command-line interface. On an Apple Macintosh, you can use the Terminal.app program in the Utilities subdirectory of your Applications directory. On Windows, type "cmd" in the search field of the Start menu.
If you've never used a command-line interface before, you should start by reading an online tutorial, such as this one, or this one, or this one. For Windows, learn how to use the DOS prompt from a tutorial like this one.
There are several different implementations of Etcetera Abduction available, but for this tutorial we are going to be using EtcAbductionPy, a reference implementation of Etcetera Abduction written in Python. To use it, you'll need Python installed on your machine. Either Python 2.7 or Python 3.6 should work fine - and one of these is likely already installed on your computer. On Windows, you'll need to install Python directly, which you can find here.
The code for Etcetera Abduction in Python is available online in a GitHub repository, at this address:
If you're a GitHub expert, then just clone this repository to get started. If you're a novice, then find the "Clone or download" button on this EtcAbductionPy webpage, and then click it to see the "Download ZIP" option. Clicking this will download a .zip file with all of the code, which you can double-click to unpack, creating a folder called "EtcAbductionPy-master" that you can put on your desktop or wherever you like to keep your files. However, if you are confortable with git, then clone the repository instead to make it easier to stay current with updates. You can find git for Windows and other operating systems here.
Next, open up your Terminal window and navigate to the EtcAbductionPy-master/ directory. From inside this directory, you can run the command-line interface directly, using the -m flag to invoke the module:
$ cd EtcAbductionPy-master/
$ python -m etcabductionpy -h
usage: [-h] [-i [INFILE]] [-o [OUTFILE]] [-k [KB]] [-n NBEST] [-g]
[-s SOLUTION] [-d DEPTH] [-a] [-f]
Etcetera Abduction in Python
optional arguments:
-h, --help show this help message and exit
-i [INFILE], --infile [INFILE]
Input file of observed literals as lisp s-expressions,
defaults to STDIN
-o [OUTFILE], --outfile [OUTFILE]
Output file, defaults to STDOUT
-k [KB], --kb [KB] Knowledge base of definite clauses as lisp
s-expressions
-n NBEST, --nbest NBEST
Generate NBEST-best proofs, defaults to 10
-g, --graph Output graph of solution in .dot format
-s SOLUTION, --solution SOLUTION
Graph the SOLUTION-best solution, defaults to 1
-d DEPTH, --depth DEPTH
Backchain to depth DEPTH, defaults to 5
-a, --all Generate all solutions
-f, --forward Forward chain from INFILE with KB
-c, --incremental Use incremental abduction
-v, --variables Leave variables in solutions rather than Skolem
constants
-w WINDOW, --window WINDOW
Incremental abduction window-size, defaults to 4
-b BEAM, --beam BEAM Incremental abduction beam-size, defaults to 10
Did this work? Congratulations! You've now got everything you need to start using Etcetera Abduction.
Authoring an input file
The EtcAbductionPy software takes as input some knowledge and some observations, and spits out as output a list of sets of assumptions that logically entail the observations, ordered by their probability.
When working through the examples in this tutorial, you should encode the knowledge and observations together in a single text file, and provide that text file as input to the etcabductionpy script.
To author these input files, you'll need to use a plain text editor, like Emacs, or Vim, or Sublime Text, or Notepad++. On an Apple Macintosh, you could even use the "TextEdit.app" utility, but if you do, please make sure that you save as a "Plain Text" file rather than a "Rich Text" file. There is an option under the "Format" menu to "Make Plain Text" if you find that you are editing the wrong type. On Windows, you can use Notepad++.
Let's create a minimal input file, with the following contents, and save it inside the EtcAbductionPy-master/ directory with the name "minimal.lisp". The file extension ".lisp" may allow your editing program to help you with formatting your input file, such that lines beginning with semicolons are treated as comments to be ignored, and that parentheses should be balanced.
;; minimal.lisp ;; Observable: (explosion E) ;; Prior probability: (if (etc 0.001 x) (explosion x))
All blank lines and lines that begin with a semicolon are ignored by the Etcetera Abduction software, so this file only contains two items of interest: an observation and a piece of knowledge.
This file has enough information in it to serve as an input to Etcetera Abduction. We can see the results by specifying it as the input using the "--input" (or just "-i") flag, as follows:
$ python -m etcabductionpy -i minimal.lisp ((etc 0.001 E)) 1 solutions.
Did it work? Congratulations! You have just used Etcetera Abduction to do probability-ordered logical abduction. Yes, but what did it do exactly?! Well, precisely, it identified all possible sets of assumptions that would logically entail the observation given the knowledge base provided, and ordered them according to their probability. Actually, here there is only one set of assumptions that entails the observation, namely its prior probability. Confused? Don't worry, this tutorial is designed to explain it all to you step-by-step, and show you how to use this technology for amazing applications.
Creating graphs of solutions
In the minimal example, above, Etcetera Abduction has told us that there is only one set of assumptions that logically entail the observations, and that this set has only one assumption in it, namely (etc 0.001 E).
Would you like to see exactly how this assumption entails the observation? EtcAbductionPy includes a nice utility that will present the proof of this entailment as a directed graph. To produce this graph, just add the "--graph" (or just "-g") flag to the command.
$ python -m etcabductionpy -i minimal.lisp -g
digraph proof {
graph [rankdir="TB"]
n0 [label="etc 0.001"];
n1 [shape=box peripheries=2 label="(explosion E)"];
n0 -> n1
{rank=same n1}
}
The output is encoded in a special format called "DOT", which you can read about here. This encoding describes a graphical layout, which various other programs can use to generate the corresponding visual images.
If you want to keep things simple, and you don't want to install any more software on your computer, then you can use an online tool to convert DOT descriptions into graphical images. Here is one that I like to use:
See the graph, copy and paste the output directly into the input box on this webpage, and press the "Generate Graph!" button. You'll see the following result:
If you'd prefer to generate these graphs locally on your own machine, then you'll need to ensure that some appropriate graph-making software is installed. Personally, I like the standard dot program that is included with the graphviz software package.
If you are like me, and use an Apple Macintosh, then you can install the whole graphviz package, including the dot utility, using the HomeBrew package manager.
$ brew install graphviz
If you are using Windows or don't use HomeBrew, then download the graphviz suite of programs from here.
After that, you can pipe the output of etcabductionpy to dot, to generate nice scalable vector graphics (svg) files, as follows:
$ python -m etcabductionpy -i minimal.lisp -g | dot -Tsvg > minimal.svg
I do this so often that I wrote a handy utility that generates the .svg file in a temp directory, and opens it up in the Safari browser. If you are using a Mac, you can try this utility yourself by piping the graph to ./util/dot2safari as follows:
python -m etcabductionpy -i minimal.lisp -g | ./util/dot2safari
Getting help
If you have made it this far, then you are ready to start learning how to use Etcetera Abduction to solve interpretation problems. I have prepared a few examples to work through, by way of a tutorial, which you should take a look at next.
Etcetera Abduction is a research technology, and it's not without its warts. Some aspects you may find annoying or cumbersome, but I encourage you to stick with it.
I also want to encourage you to reach out to me directly if you run into problems that you can't figure out for yourself. Also, I'd be happy to hear any suggestions that you have for improving the usability of the software tools, or any corrections that you would like to make to the tutorial examples. You can reach me by email at: gordon@ict.usc.edu