library(ferx)
packageVersion("ferx")
#> [1] '0.4.0.9000'Installing ferx
ferx is an R package with a compiled Rust engine (ferx-core) inside. Installing it compiles that engine from source, so you need a Rust toolchain and the first install takes a long time. The ferx-r README notes that later installs are faster.
Requirements
-
R with a working build toolchain. The package’s
SystemRequirementsare GNU make, Cargo and rustc (>= 1.70). - Rust: a standard stable toolchain installed with rustup. No custom toolchain is required.
- Windows: Rtools matching your R version, plus the GNU-ABI Rust toolchain. See the Windows notes in the ferx-r README.
Installing the pinned build
This book documents one specific ferx-r commit, 16614e2 (package version 0.4.0.9000, engine ferx-core a959f4b6). Every output in the book was produced with it. To get exactly the same behaviour, install that commit:
install.packages("pak")
pak::pak("FeRx-NLME/ferx-r@16614e242b95305c99228471c92d3729f38c358d")Installing without a commit gives you the latest development version. That is fine for your own work, but its output can differ from what this book shows:
pak::pak("FeRx-NLME/ferx-r")Which version do you have?
The pinned build is newer than the last ferx-r release, 0.4.0. packageVersion("ferx") (below) tells you which one you have. With 0.4.0 most of the book runs as shown, with three kinds of difference:
- Features newer than 0.4.0. Some functions, arguments, settings and examples do not exist in the release. Newer than ferx-r 0.4.0 lists them, and each chapter that uses one says so in a callout titled “Needs ferx-r newer than 0.4.0”: Estimation methods and controlling the fit, Diagnosing the model, Parameter uncertainty, Simulating scenarios, Reproducibility and sharing, Structural models: analytical and ODE, Covariate modeling, Time-to-event models, Adaptive dosing and TDM strategies, Model-based meta-analysis, Experimental features.
- Behaviour that changed after 0.4.0. A callout titled “Changed after ferx-r 0.4.0” marks it where the book relies on it: Preparing and checking the analysis dataset, Initial estimates and a first fit, Estimation methods and controlling the fit, Diagnosing the model, Parameter uncertainty, Reproducibility and sharing, Variability: random effects, residual error and IOV, PK/PD and multiple endpoints, Binary endpoints, Time-to-event models, Adaptive dosing and TDM strategies, Experimental features.
- Numbers. The engine changed too, so your results can differ from the printed ones. FOCE fits move most: the FOCE objective changed after 0.4.0, which shifts their OFVs and, slightly, their estimates.
To get the book’s output, install the pinned commit above. To stay on the release, install its tag, pak::pak("FeRx-NLME/ferx-r@v0.4.0"), and read the callouts.
Using Docker (no Rust needed)
If you would rather not install Rust, or you need ferx somewhere other than your own machine, run it in a container. ferx-r has two images:
| Slim image | RStudio image | |
|---|---|---|
| What it holds | R, ferx and the ferx command-line tool |
R, the tidyverse, ferx, the ferx tool, Rust and RStudio Server |
| Where it comes from | published: ghcr.io/ferx-nlme/ferx-r
|
not published: you build it from the ferx-r repository |
| Platforms |
linux/amd64, linux/arm64
|
whatever you build it on |
| You use it from | the command line, scripts, CI | a web browser |
| Good for | scripts, servers, clusters, CI, reproducible and validated work | interactive work, workshops, people without a local R or Rust setup |
The commands below run in a shell, not in R. The book itself is rendered without Docker, so their output is not shown.
The slim image
The slim image is public on the GitHub Container Registry, so no login is needed to pull it:
docker pull ghcr.io/ferx-nlme/ferx-r:latestMount your project at /work, the image’s working directory, and run an R script, the ferx command-line tool, or an interactive R console there:
docker run --rm -v "$PWD:/work" ghcr.io/ferx-nlme/ferx-r:latest Rscript fit.Rdocker run --rm -v "$PWD:/work" ghcr.io/ferx-nlme/ferx-r:latest ferx model.ferx --data data.csvdocker run --rm -it -v "$PWD:/work" ghcr.io/ferx-nlme/ferx-r:latestOn a cluster without Docker, Apptainer (formerly Singularity) runs the same image straight from the registry, for example apptainer exec docker://ghcr.io/ferx-nlme/ferx-r:latest Rscript fit.R.
Threads
By default the engine uses the available cores minus one, but at least 2 when there are two or more cores, and at most 8. Inside a container, “available” honours a CPU quota (docker run --cpus 4, a Kubernetes CPU limit) and CPU pinning (--cpuset-cpus). It does not honour a Kubernetes CPU request without a limit, or a Slurm allocation that is not enforced through cgroups: there the engine sees every core of the node. When several jobs share a node, set the count yourself, with threads = in ferx_fit() or --threads N for the command-line tool, to match what each job was given.
User and file ownership
The container runs as an unprivileged user ferx with uid 1000, so on most single-user Linux machines the files it writes to /work belong to you. If your uid differs and the outputs must be yours, run it as your own user:
docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" ghcr.io/ferx-nlme/ferx-r:latest Rscript fit.RAdding packages
The image carries ferx’s hard dependencies only (no suggested packages such as xpose), and the default user cannot write to the site library. Add the packages your pipeline needs in a derived image. The ferx-r README uses pak, which also installs the system libraries a binary package needs:
FROM ghcr.io/ferx-nlme/ferx-r:<sha>
USER root
RUN R -q -e 'install.packages("pak"); pak::pkg_install(c("targets", "crew"))' \
&& rm -rf /var/lib/apt/lists/*
USER ferxMost chapters of this book also load dplyr and ggplot2, so add those to run them in the image.
The RStudio image
The RStudio image is not published: you build it from the Dockerfile at the root of the ferx-r repository. The build compiles ferx from source inside the image, so the first build takes a while; later builds reuse Docker’s layer cache.
git clone https://github.com/FeRx-NLME/ferx-r.git
cd ferx-r
docker build -t ferx:latest .Then start RStudio Server with a password you choose:
docker run --rm -p 127.0.0.1:8787:8787 -e PASSWORD='<your password>' ferx:latestOpen http://localhost:8787 and sign in as user rstudio with that password. The image contains no password: RStudio Server sets it from PASSWORD when the container starts.
Keep the 127.0.0.1: prefix unless you mean to serve RStudio to your network. Without it, Docker publishes the port on every network interface, so anyone who can reach your machine can try to log in, and Docker’s published ports can bypass a host firewall.
The image builds from whatever ferx-r commit you cloned. To match this book, check out the pin first: git checkout 16614e242b95305c99228471c92d3729f38c358d.
Checking the installation
Load the package and confirm the version:
The package ships example models and datasets, so a real fit is the quickest end-to-end check. It exercises the model parser, the data reader and the estimation engine:
ex <- ferx_example("warfarin")
fit <- ferx_fit(ex$model, ex$data, verbose = FALSE)
fit$converged
#> [1] TRUEIf this prints TRUE, ferx is installed and working. A complete analysis in one chapter walks through the same example as a full analysis.
ferx_fit() checks for R interrupts while it runs, so Ctrl-C (or RStudio’s stop button) cancels a fit. The call then ends with an error saying the fit was cancelled. The ferx-core installation page describes the behaviour in detail.
Reference
- ferx-r: README: installation, including Windows and Docker
- Docker images:
ghcr.io/ferx-nlme/ferx-r(slim),Dockerfile(RStudio) - ferx-core: installation
- R help:
?ferx_example,?ferx_fit