EulerX Toolkit Overview

Introduction

Euler is an open source toolkit (mostly written in Python) for merging taxonomies (taxonomical organized datasets) and visualizing the results. See Euler Toolkit Wiki for more information.

We have all the EulerFO source code, EulerASP source code, and a bunch of use cases in this toolkit. EulerFO is a modified version of CleanTax which was firstly developed by Dave Thau. CleanTax/EulerFO are built upon Prover9/Mace4 reasoning software. EulerASP is a brand new taxonomy reasoning tool that Mingmin built from scratch. EulerASP is built based on popular ASP reasoners DLV and Potassco. This readme page is mainly focusing on the use of EulerASP.

Euler is designed for UNIX-like operating systems (Linux, Mac, etc). If you are running on Windows, you need to install a virtual machine to run Euler.

Structure of This Toolkit

DIRECTORIES	Description
.git/	internal git folder
ASP/	some ASP test code
bbox-lattice/	subroutine for blackbox lattice generation
default-stylesheet/	stylesheet files that are used by default
example/	subfolders with all Euler use cases
projects/	side tools and implementations
regress/	for Regression testing
src-ct/	EulerFO source code
src-el/	EulerASP source code
src-gu/	source code from Gonzaga University
src-tmp/	temporary or deprecated code

FILES	Description
README.md	file used on Github homepage
installCheck.sh	installation requirements check
src-ct/main.py	main entry of CleanTax++ source code
src-el/euler	main entry of EulerASP source code
src-el/euler2	main entry of EulerASP source code using new commland line interface
example/runct.sh	shell script to run EulerFO

Installation Instructions For Users

1. First-time user for git

Before using Euler/X, you need to download it from this git repo. You can first check the installation of git.

$ git —-version

If you are a first-time user for git, please download and install it [http://git-scm.com/downloads/].

2. Download the source.

The latest version is v2.0. Download it from the release page.

To use the development version, which has the latest code, clone the master branch:

$ git clone -b master https://github.com/EulerProject/EulerX.git

3. Check the installation of Python

Euler/X is written in Python, so it requires Python2.X or later installed in your computer.

$ python --version
Python 2.7.8

Installation of Python2 can be found at [https://www.python.org/downloads/].

4. Check the installation of reasoner

Euler/X use either DLV or Clingo as underlining reasoner. Please install them and make sure they are in your PATH:

$ dlv --version
DLV [build BEN/Dec 17 2012   gcc 4.2.1 (Apple Inc. build 5666) (dot 3)]

usage: dlv {FRONTEND} {OPTIONS} [filename [filename [...]]]

Specify -help for more detailed usage information.


$ clingo -v
clingo version 5.2.0
Address model: 64-bit

libgringo version 5.2.0
Configuration: without Python, with Lua 5.3.4

libclasp version 3.3.0 (libpotassco version 1.0.0)
Configuration: WITH_THREADS=1
Copyright (C) Benjamin Kaufmann

License: The MIT License <https://opensource.org/licenses/MIT>

To install DLV, please use the version static no ODBC support from DLV download page. To install Clingo, please use the version 5.2.0. Note: You do not need to install all to use Euler/X, either DLV or Clingo will do the job.

5. Install Graphviz visualization tool

All knowledge products generated by Euler/X use Graphviz for rendering visualizations, to check the installation of it:

$ dot -V
dot - graphviz version 2.36.0 (20140111.2315)

Installation of Graphviz can be found at [http://www.graphviz.org/].

6. Install parser module (If you want to use new commandline interface euler2)

The Euler/X command line interface 2.0 use python module docopt as the parser generator. Use pip to install it:

$ pip install docopt==0.6.1

Installation of pip can be found at [https://pip.pypa.io/en/latest/installing.html]. To get more about docopt, please check [http://docopt.org/].

7. Install stylesheet module

Euler/X use python module yaml for representing graph and stylesheet files. Install it by pip:

$ pip install pyyaml

See other installation methods here.

8. [IMPORTANT] You need to make sure your machine has met the minimal software requirements before run Euler.

Please run installCheck.sh and make sure the minimal dependency check passes before running this toolkit. Make sure all commands of running softwares before and main entry of source code (e.g. src-el/ of EulerASP) are in your PATH env. Note: Prover9/Mace4 is not necessary to install if you do not want to use EulerFO.

Examples of Running Euler2 with new command line interface.

Use example abstract4

1. Show the available commands

List all usage commands.

$ euler2 -h

2. Check the input file

Check the validity of input file, including “multiple roots per taxonomy”, “multiple parents per child”, “unmatched leaves (leaves that are not involved in any articulations)”.

$ euler2 check abstract4.txt

3. Run taxonomic alignment problem

The main task for Euler/X, you can suggest the encoding method, the reasoning tool, options to switch on/off coverage and sibling disjointness, et al.

$ euler2 align abstract4.txt

4. Show the input visualization

TO show the input visualization of the last run (the same as the following show commands), need to do “euler2 align” first. The result will be in 0-Input/ folder.

$ euler2 show iv

5. Show the possible worlds

The result will be in 4-PWs/ folder

$ euler2 show pw

6. Show the summary view

The result will be in 5-Aggregates/ folder

$ euler2 show sv

Examples of Running EulerASP (old command line interface)

Still under example/ directory (assuming src-el/ is in your PATH env, and gringo, claspD, dlv in your PATH env),

0. euler -h or euler --help wil give you the options that you have
1. euler -i example/abstract4.txt -e vr, you will get all the mir relations in the generated output file using binary encoding.
2. euler -i example/abstract4.txt -e vrpw, you will get all the possible worlds in the console using binary encoding.
3. euler -i example/abstract4.txt -e vrve, you will get all the valid euler regions in the console using binary encoding.
4. euler -i example/abstract4.txt -e mn, you will get all the mir relations in the generated output file using polynomial encoding.
5. euler -i example/abstract4.txt -e mnpw, you will get all the possible worlds in the console using polynomial encoding.
6. euler -i example/abstract4.txt -e mnve, you will get all the valid euler regions in the console using polynomial encoding.

Examples of Running EulerFO (need to install Prover9/Mace4)

Here are examples under example/ directory,

1. cd to example/ directory
2. run ./test.sh, you will find the output files in output/test/
3. ./runct.sh abstract, you will find the output files in output/abstract/
4. ./runct.sh abstract2, you will find the output files in output/abstract2/
5. ./runct.sh abstract3, you will find the output files in output/abstract3/
6. ./runct.sh abstract3b, you will find the output files in output/abstract3b/, it is the "Bertram" mode for abstract3.
7. ./runct.sh abstract2c, you will find the output files in output/abstract2c/, it is the test case with articulation confidence for abstract2.

Contact

If you have any question or comments, please contact Bertram Ludäscher at ludaesch@illinois.edu.