Installation

You can install the R package with

install.packages("iai")

The iai 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 R package from CRAN. There are two options for doing this.

Option 1: Automatically install Julia and IAI

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

iai::install_julia()
iai::install_system_image()

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

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.

Important

On macOS, a bug in Julia 1.6 prevents accessing this version of Julia from R. For the time being, please use an pre-1.6 version of Julia if you would like to use the R interface on macOS.

Warning

For the R interface, we recommend replacing the default system image as this simplifies the R 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, R 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.

Using the R package

After configuring Julia following one of the two options above, you can begin using the iai package. The first time you use an IAI function in an R session, it will automatically initialize the connection to Julia.

Troubleshooting

Julia not correctly configured or not on the PATH

You may receive the following error if Julia is not correctly configured:

Error in JuliaCall::julia_setup(...) : Julia is not found.
In addition: Warning message:
running command ''bash' -l -c 'which julia'' had status 1

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

Error: Error happens in Julia.
error compiling do_add!: error compiling #add#25: error compiling #update_registries#139: could not load library "libgit2"
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.

Problem with Julia dependencies

If you are using an older version of the IAI system image, you might see the following error:

Loading setup script for JuliaCall...
ERROR: LoadError: UndefVarError: levels not defined
Stacktrace:
  ...
 Error happens when you try to execute command Base.include(Main,".../JuliaCall/julia/setup.jl") in Julia.
                       To have more helpful error messages,
                       you could considering running the command in Julia directly
Calls: <Anonymous> -> <Anonymous> -> <Anonymous>
Execution halted
Julia exit.

To resolve this, you should run the following commands in Julia:

julia> using Pkg

julia> Pkg.add(PackageSpec(name="StatsModels", version="0.6.6"))

julia> Pkg.pin("StatsModels")

You can then restart the R session and proceed as usual.

IAI not present in Julia installation

You may see the following error when using the package for the first time:

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.

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.

1. Specifying location of Julia using IAI_JULIA

You can set the environment variable IAI_JULIA to point to the julia executable. You can then proceed with installing and using the package as usual.

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)

2. Specifying location of Julia using JULIA_HOME

Warning

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

You can also specify the location to Julia by setting the JULIA_HOME variable to point to the folder containing the julia executable.

If you are unsure about which directory to use for JULIA_HOME, you can find the directory by running the following command inside Julia:

julia> Sys.BINDIR

An easy way of specifying JULIA_HOME is using your .Renviron file, which can be configured via the usethis package:

install.packages("usethis")
usethis::edit_r_environ(scope = "user")

This will bring up your environ file, which you can edit to specify JULIA_HOME:

JULIA_HOME="the folder that contains the julia executable"

Once you restart R, the change will take effect

There are other options for setting JULIA_HOME that might better suit some scenarios, you can refer to the "Julia is not found" section in the JuliaCall documentation to see all options.

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. You can then proceed with installing and importing the package as usual.

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_path argument. This will need to be done in every R session as the first step:

iai::iai_setup(sysimage_path = "path/to/sys")

Advanced: Development builds of iai

Development builds of the iai package can be installed with the following command:

install.packages("devtools")
devtools::install_url("https://iai-r-interface.s3.amazonaws.com/iai_latest.tar.gz")

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