Installation

Installation

The interpretableai package is a wrapper around the Julia implementation of IAI algorithms, so you need to configure a working Julia installation in addition to installing the Python package from PyPI.

Installing Julia and IAI modules

Follow the instructions for installing the IAI system image to get a working Julia installation with the IAI modules included.

Warning

For the Python interface, we recommend replacing the default system image (Option 1) as this simplifies the Python setup. If you choose Option 2, you will need to follow the instructions to specify a system image each time you load the iai module in Python.

In order to use Julia to run the IAI algorithms, Python also needs to know where to find Julia on your computer. By default, it will look for an executable on the system PATH named julia.

Installing the Python package

You can install the Python package with

$ pip install interpretableai

Once installed, you need to run the following command so that Python knows how to access the IAI algorithms from Julia:

import interpretableai
interpretableai.install()

Inside Python, you can load the package with the following command (assuming julia is on your system PATH):

from interpretableai import iai

After this, all of the package functionality is available under the iai module.

Troubleshooting

Below is a list of errors you might receive when setting up the package and how to resolve them. If none of the suggestions fix the problem, you can also refer to the PyJulia troubleshooting guide.

Julia not correctly configured or not on the PATH

When running interpretableai.install(), you will receive the following error if Julia is not correctly configured:

julia.core.JuliaNotFound: Julia executable `julia` cannot be found.

If you have installed Julia, make sure Julia executable is in the
system PATH.  Alternatively, specify file path to the Julia executable
using `julia` keyword argument.

If you have not installed Julia, download Julia from
https://julialang.org/downloads/ and install it.

When running from interpretableai import iai, you will receive the following error if Julia is not correctly configured:

FileNotFoundError: [Errno 2] No such file or directory: 'julia': 'julia'

In each case, you will either need to add julia to the system PATH, or follow the steps to specify the path to Julia.

Python distribution is incompatible with PyJulia

For certain Python distributions (e.g Anaconda, Ubuntu), you may see the following error when initializing Julia:

RuntimeError: It seems your Julia and PyJulia setup are not supported.

Julia executable:
    julia
Python interpreter and libpython used by PyCall.jl:
    /usr/bin/python3
    /usr/lib/x86_64-linux-gnu/libpython3.6m.so.1.0
Python interpreter used to import PyJulia and its libpython.
    /usr/bin/python3
    /usr/lib/x86_64-linux-gnu/libpython3.6m.so.1.0

Your Python interpreter "/usr/bin/python3"
is statically linked to libpython.  Currently, PyJulia does not fully
support such Python interpreter.

The easiest workaround is to pass `compiled_modules=False` to `Julia`
constructor.  To do so, first *reboot* your Python REPL (if this happened
inside an interactive session) and then evaluate:

    >>> from julia.api import Julia
    >>> jl = Julia(compiled_modules=False)

Another workaround is to run your Python script with `python-jl`
command bundled in PyJulia.  You can simply do:

    $ python-jl PATH/TO/YOUR/SCRIPT.py

See `python-jl --help` for more information.

For more information, see:

    https://pyjulia.readthedocs.io/en/latest/troubleshooting.html

As the message indicates, the easiest way to resolve this problem is restart your Python session and manually initialize the connection to Julia while passing compiled_modules=False before importing iai:

from julia import Julia
Julia(compiled_modules=False)
from interpretableai import iai

This initialization step needs to be done in every Python session.

Advanced: Specifying path to Julia

If julia is not on the system PATH, or you would like to use another Julia executable, you can pass the path to a Julia executable to install:

import interpretableai
interpretableai.install(runtime='path/to/julia')

If you are unsure of the path to your Julia installation, you can get the path to the julia executable by running the following command in Julia:

julia> unsafe_string(Base.JLOptions().julia_bin)

You will also need to take an additional step in order to manually initialize the connection to Julia with the path to julia in every Python session before importing iai:

from julia import Julia
Julia(runtime='path/to/julia')  # and any other parameters as needed
from interpretableai import iai

Advanced: Specifying system image

If you do not replace the default Julia system image, you will need to manually initialize the connection to Julia with the path to the system image in every Python session before importing the iai module:

from julia import Julia
Julia(sysimage='path/to/sys')  # and any other parameters as needed
from interpretableai import iai