Installation

Warning

The interpretableai Python package is only compatible with Python 3

You can install the Python package with

$ pip install interpretableai

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. There are two options for doing this.

Option 1: Automatically install Julia and IAI

The interpretableai package can automatically download and configure a working Julia installation with the IAI system image. To do this, simply run the following commands in Python:

import interpretableai
interpretableai.install_julia()
interpretableai.install_system_image()

After running these commands, you will need to restart Python.

Option 2: Using a separate Julia installation

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 as this simplifies the Python setup. If you choose not to replace the default image, you will need to follow the instructions to specify a system image.

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. It is also possible to specify the location of Julia manually if preferred.

Once installed, you need to run the following command in Python to configure the connection to Julia for access the IAI algorithms. This only needs to be run the first time following installation of the interpretableai package:

import interpretableai
interpretableai.install()

Using the Python package

After configuring Julia following one of the two options above, you can begin using the interpretableai package. You can access the IAI algorithms in any Python session by loading the package with the following command:

from interpretableai import iai

The first time the package is loaded, you will receive a message that there is no license file, along with a machine ID. Please follow the instructions to obtain a license file.

Tip

If you are using a Jupyter Notebook, this message may not be visible in the notebook. If this is the case, we recommend conducting this step directly in a terminal.

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 may 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 may receive the following error if Julia is not correctly configured:

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

On Windows only, you may also see a message similar to the following about being unable to load a library:

WARNING: Error during initialization of module PCRE:
ErrorException("could not load library "libpcre2-8"
The specified module could not be found.
")

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

There are two options to resolve this error:

  1. Set the enviroment variable IAI_DISABLE_COMPILED_MODULES to True, e.g. in Python:

     import os
     os.environ['IAI_DISABLE_COMPILED_MODULES'] = 'True'
     from interpretableai import iai

    You will need to make sure that this variable is defined in every Python session before importing iai.

  2. Manually initialize the connection to Julia and pass compiled_modules=False before importing iai:

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

    This initialization step will need to be done in every Python session.

IAI not present in Julia installation

You may see the following error when importing the package:

IAI is not present in your Julia installation.

Make sure you have followed the instructions for installing the IAI system image so that the IAI module is present in your Julia installation.

Architecture mismatch between Python and Julia

On macOS with ARM (M-series) processors, you may see an error similar to the following when importing the package:

OSError: dlopen(/Applications/Julia-1.8.app/Contents/Resources/julia/lib/libjulia.1.8.dylib, 0x000A):
tried: '/Applications/Julia-1.8.app/Contents/Resources/julia/lib/libjulia.1.8.dylib'
(mach-o file, but is an incompatible architecture (have (arm64), need (x86_64)))

This indicates that the architecture of the Julia executable (indicated by have in the error message) does not match the architecture of the Python executable (indicated by need). You will need to reinstall Julia and/or Python to ensure they have the same architecture, either Intel (x86_64) or ARM (arm64).

Advanced: Specifying location of Julia

If julia is not on the system PATH, or you would like to use another Julia executable, there are two additional ways to specify the location of 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)

1. Specifying location of Julia using IAI_JULIA

You can set the environment variable IAI_JULIA to point to the julia executable, e.g. in Python:

import os
os.environ['IAI_JULIA'] = 'path/to/julia'

You can then proceed with installing and importing the package as usual, making sure that this variable is defined in every Python session before importing iai.

2. Specifying location of Julia manually

Warning

Specifying the location of Julia manually does not work on Windows. You must either add Julia to the PATH or set IAI_JULIA to point to your Julia installation.

If you would like to specify the location of Julia without using environment variables, you can pass the path to a Julia executable to install:

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

You will also need to take an additional step in order to manually initialize the connection to Julia with the path to julia as the runtime argument. This will need to be done 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 location of system image

If you do not replace the default Julia system image, there are two additional ways to specify the location of the system image.

1. Specifying location of system image using IAI_SYSTEM_IMAGE

You can set the environment variable IAI_SYSTEM_IMAGE to point to the location of the system image, e.g. in Python:

import os
os.environ['IAI_SYSTEM_IMAGE'] = 'path/to/sys'

You can then proceed with installing and importing the package as usual, making sure that this variable is defined in every Python session before importing iai.

2. Specifying location of system image manually

If you would like to specify the location of the system image without using environment variables, you will need to manually initialize the connection to Julia with the path to the system image as the sysimage argument. This will need to be done 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

Advanced: Development builds of interpretableai

Development builds of the interpretableai package are uploaded to the Test PyPI repository, and can be installed with the following command:

$ pip install --upgrade --extra-index-url https://test.pypi.org/simple/ interpretableai

There is no need to use these development builds unless directed to do so.