Installation

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.

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 R interface, you must replace the default system image (Option 1) as there is no way to specify a custom image from inside R

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.

Installing the R package

You can install the R package with

install.packages("iai")

You can start using the iai package immediately. The first time you use an IAI function in a new 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.

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 JuliaCall documentation to see all options.

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.