JuliaCall

JuliaCall: an R package for seamless integration between R and Julia - Published in JOSS (2019)

https://github.com/JuliaInterop/JuliaCall

Keywords

Keywords from Contributors

Scientific Fields

Repository

Embed Julia in R

README.Rmd

---
output: github_document
---



# JuliaCall for Seamless Integration of R and Julia

[![R build status](https://github.com/JuliaInterop/JuliaCall/workflows/R-CMD-check/badge.svg)](https://github.com/JuliaInterop/JuliaCall/actions)
[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/JuliaCall)](https://cran.r-project.org/package=JuliaCall)
[![](https://cranlogs.r-pkg.org/badges/JuliaCall)](https://cran.r-project.org/package=JuliaCall)
[![](https://cranlogs.r-pkg.org/badges/grand-total/JuliaCall)](https://cran.r-project.org/package=JuliaCall)
[![DOI](http://joss.theoj.org/papers/10.21105/joss.01284/status.svg)](https://doi.org/10.21105/joss.01284)


**[Table of Contents]**


- [JuliaCall for Seamless Integration of R and Julia](#juliacall-for-seamless-integration-of-r-and-julia)
  - [Installation](#installation)
  - [Basic Usage](#basic-usage)
  - [Troubleshooting and Ways to Get Help](#troubleshooting-and-ways-to-get-help)
  - [JuliaCall for R Package Developers](#juliacall-for-r-package-developers)
  - [Suggestion, Issue Reporting, and Contributing](#suggestion-issue-reporting-and-contributing)
  - [Other Interfaces Between R and Julia](#other-interfaces-between-r-and-julia)

Package `JuliaCall` is an R interface to `Julia`, 
which is a high-level, high-performance dynamic programming language
for numerical computing, see  for more information.
Below is an image for [Mandelbrot set](https://en.wikipedia.org/wiki/Mandelbrot_set).
JuliaCall brings **more than 100 times speedup** of the calculation!
See  for more information.

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
```

![](https://JuliaInterop.github.io/JuliaCall/articles/mandelbrot.png)

## Installation

You can install `JuliaCall` just like any other R packages by

```{r eval=FALSE}
install.packages("JuliaCall")
```

To use `JuliaCall` you must have a working installation of Julia.
This can be easily done via:

```{r eval=FALSE}
library(JuliaCall)
install_julia()
```

which will automatically install and setup a version of Julia specifically
for use with JuliaCall. Or you can do

```{r eval=FALSE}
library(JuliaCall)
julia_setup(installJulia = TRUE)
```

which will invoke `install_julia` automatically if Julia is not found 
and also do initialization of `JuliaCall`.

You can also setup Julia manually by downloading a generic binary from 
 and add it to your path. Currently 
`Julia v0.6.x` and the `Julia v1.x` releases are all supported by 
`JuliaCall`.

You can get the development version of `JuliaCall` by

```{r eval=FALSE}
devtools::install_github("JuliaInterop/JuliaCall")
```

## Basic Usage

Before using `JuliaCall`, you need to do initial setup by function `julia_setup()` for automatic type conversion, Julia display systems, etc. 
It is necessary for every new R session to use the package.
If not carried out manually, it will be invoked automatically before other `julia_xxx` functions.
Solutions to some common error in `julia_setup()` are documented in the [troubleshooting section](#troubleshooting-and-ways-to-get-help).

```{r}
library(JuliaCall)
julia <- julia_setup()

## If you want to use `Julia` at a specific location, you could do the following:
## julia_setup(JULIA_HOME = "the folder that contains Julia binary").
## You can also set JULIA_HOME in command line environment or use `options(...)`.

## Different ways of using Julia to calculate sqrt(2)

# julia$command("a = sqrt(2);"); julia$eval("a")
julia_command("a = sqrt(2);"); julia_eval("a")
julia_eval("sqrt(2)")
julia_call("sqrt", 2)
julia_eval("sqrt")(2)
julia_assign("x", sqrt(2)); julia_eval("x")
julia_assign("rsqrt", sqrt); julia_call("rsqrt", 2)
2 %>J% sqrt

## You can use `julia$exists` as `exists` in R to test
## whether a function or name exists in Julia or not

julia_exists("sqrt")
julia_exists("c")

## Functions related to installing and using Julia packages

julia_install_package_if_needed("Optim")
julia_installed_package("Optim")
julia_library("Optim")
```

## Troubleshooting and Ways to Get Help

### Julia is not found

Make sure the `Julia` installation is correct.
`JuliaCall` can find `Julia` on PATH,
and there are three ways for `JuliaCall` to find `Julia` not on PATH.

- Use `julia_setup(JULIA_HOME = "the folder that contains julia binary")`
- Use `options(JULIA_HOME = "the folder that contains julia binary")`
- Set `JULIA_HOME` in command line environment.

### libstdc++.so.6: version `GLIBCXX_3.4.xx' not found

Such problems are usually on Linux machines.
The cause for the problem is that R cannot find the libstdc++ version needed by `Julia`.
To deal with the problem, users can export "TheFolderContainsJulia/lib/julia" to R_LD_LIBRARY_PATH.

### RCall not properly installed

The issue is usually caused by updates in R, and it can be typically solved by setting `rebuild` argument to `TRUE` in `julia_setup()` as follows.

```{r eval=FALSE}
JuliaCall::julia_setup(rebuild = TRUE)
```

### `ERROR: could not load library "/usr/lib/x86_64-linux-gnu/../bin/../lib/x86_64-linux-gnu/julia/sys.so"`

This error happens when Julia is built/installed with `MULTIARCH_INSTALL=1`, as
it is on e.g. Debian. It is caused by [the bindir-locating code in jl\_init not
being multiarch-aware](https://github.com/JuliaLang/julia/issues/32614#issuecomment-656787386).
To work around it, try setting `JULIA_BINDIR=/usr/bin` in [`.Renviron`](https://rstats.wtf/r-startup.html#renviron).

### How to Get Help

- One way to get help for Julia functions is just using `julia$help` as the following example:

```{r}
julia_help("sqrt")
```

- The GitHub Pages for this repository host the documentation for the development version of `JuliaCall`: .

- Also, you are more than welcome to contact me about `JuliaCall` at  or .

## JuliaCall for R Package Developers

If you are interested in developing an `R` package which is an interface for
a `Julia` package, `JuliaCall` is an ideal choice.
You only need to find the `Julia` function or `Julia` module you want to have in `R`, `using` the module, and `julia_call` the function.
There are some examples:

- [`diffeqr`](https://github.com/SciML/diffeqr) is a package for solving differential equations in `R`. It utilizes [DifferentialEquations.jl](https://diffeq.sciml.ai/latest/) for its core routines to give high performance solving of ordinary differential equations (ODEs), stochastic differential equations (SDEs), delay differential equations (DDEs), and differential-algebraic equations (DAEs) directly in `R`.
- [`convexjlr`](https://github.com/Non-Contradiction/convexjlr) is an `R` package for Disciplined Convex Programming (DCP) by providing a high level wrapper for `Julia` package [`Convex.jl`](https://github.com/jump-dev/Convex.jl). `convexjlr` can solve linear programs, second order cone programs, semidefinite programs, exponential cone programs, mixed-integer linear programs, and some other DCP-compliant convex programs through `Convex.jl`.
- [`ipoptjlr`](https://github.com/Non-Contradiction/ipoptjlr) provides an `R` interface to the `Ipopt` nonlinear optimization solver. It provides a simple high-level wrapper for `Julia` package [`Ipopt.jl`] (https://github.com/jump-dev/Ipopt.jl).
- [`FixedEffectjlr`](https://github.com/FixedEffects/FixedEffectjlr) uses the `Julia` package [`FixedEffectModels.jl`](https://github.com/matthieugomez/FixedEffectModels.jl) to estimate large fixed effects models in `R`.
- [Julia MixedModels from R](http://rpubs.com/dmbates/377897) illustrates how to use `JuliaCall` and `Julia` package [`MixedModels.jl`](https://github.com/JuliaStats/MixedModels.jl) to build mixed models in `R`.
- [`autodiffr`](https://github.com/Non-Contradiction/autodiffr) provides automatic differentiation to native `R` functions by wrapping `Julia` packages [`ForwardDiff.jl`](https://github.com/JuliaDiff/ForwardDiff.jl) and [`ReverseDiff.jl`](https://github.com/JuliaDiff/ReverseDiff.jl) through `JuliaCall`, which is a work in progress.

If you have any issues in developing an `R` package using `JuliaCall`,
you may report it using the link: , or email me at  or .

## Suggestion, Issue Reporting, and Contributing

`JuliaCall` is under active development now.
Any suggestion or issue reporting is welcome!
You may report it using the link: , or email me at  or .
You are welcome to use the [issue template](https://github.com/JuliaInterop/JuliaCall/blob/master/.github/ISSUE_TEMPLATE/bug_report.md)
and the [pull request template](https://github.com/JuliaInterop/JuliaCall/blob/master/.github/pull_request_template.md).
The [contributing guide](https://github.com/JuliaInterop/JuliaCall/blob/master/.github/CONTRIBUTING.md) provides some guidance for making contributions.

### Checking `JuliaCall` Package

To check and test the `JuliaCall` package, you need to have the source package. You can 

- download the source of `JuliaCall` from Github,
- open `JuliaCall.Rproj` in your RStudio or open `R` from the downloaded directory,
- run `devtools::test()` to see the result of the test suite.
- run `devtools::check()` or click the `Check` button in the RStudio Build panel in the upper right to see the result of `R CMD check`.

## Other Interfaces Between R and Julia

- [`RCall.jl`](https://github.com/JuliaInterop/RCall.jl) is a `Julia` package which embeds `R` in `Julia`. `JuliaCall` is inspired by `RCall.jl` and depends on `RCall.jl` for many functionalities like type conversion between `R` and `Julia`.
- [`XRJulia`](https://github.com/johnmchambers/XRJulia) is an `R` package based on John Chambers' `XR` package and allows for structured integration of `R` with `Julia`. It connects to `Julia` and uses JSON to transfer data between `Julia` and `R`. A simple performance comparison between `XRJulia` and `Julia` can be found in [`JuliaCall` JOSS paper](https://doi.org/10.21105/joss.01284).
- [`RJulia`](https://github.com/armgong/rjulia) is an `R` package which embeds `Julia` in `R` as well as `JuliaCall`. It is not on CRAN yet, and I haven't tested it.

## License

`JuliaCall` is licensed under [MIT](https://cran.r-project.org/web/licenses/MIT).

## Code of Conduct

Please note that the `JuliaCall` project is released with a [Contributor Code of Conduct](https://github.com/JuliaInterop/JuliaCall/blob/master/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms.

## Citing

If you use `JuliaCall` in research that resulted in publications, then please cite the `JuliaCall` paper using the following BibTeX entry:
```
@Article{JuliaCall,
    author = {Changcheng Li},
    title = {{JuliaCall}: an {R} package for seamless integration between {R} and {Julia}},
    journal = {The Journal of Open Source Software},
    publisher = {The Open Journal},
    year = {2019},
    volume = {4},
    number = {35},
    pages = {1284},
    doi = {10.21105/joss.01284},
  }
```

Owner

GitHub Events

Committers

Last synced: 7 months ago

Issues and Pull Requests

Last synced: 6 months ago

Packages