The R Rapp package

CLI applications from simple R scripts

A few days ago, Posit announced the release of Rapp 0.3.0, which is an R package that makes it “straightforward to build polished CLI applications from simple R scripts,” which I find very useful, even if I don’t have a use case for it right now, but I know I will eventually.

The target audience sounds like a very specialized group, since the post claims that this “tool is built specifically for R users who need to move beyond interactive sessions and IDEs into automated, terminal-based workflows (useful for automating cron jobs, chain R scripts together with other tools, and more).” While automation is certainly welcome, I believe its strength in my case will be the ability to make tools for colleagues and clients who do not specialize in R workflows.

Last year I put together a Python CLI using the Typer library that estimates above ground carbon content by overlaying different raster and vector layers, and matching those against specialized lookup tables. The idea was that this CLI should be easy for other members of the team that hired me to use without specialized Python knowledge (or my presence). I went with Python, because it is more prevalent in the GIS world, but I could have as easily gone with R, since both use the same underlying libraries through wrappers.

The Typer experience was not as smooth as I thought it would be. There’s a lot of orchestration that easily breaks during development, which can get frustrating at times, but the end product was quite satisfying. A simple command line instruction my_tool --parameters and that’s it; instant raster maps and above ground carbon tables. Typer has a lot of bells and whistles, which were overkill for this project, but which you can’t really skip, like the help entries for your parameters and entry points.

In retrospect, I am a lot more fluent in R than Python and I prefer to build tools and pipelines with it, and this is where I believe Rapp could come in handy. It is much easier to turn a script into a command line application (CLI) with a few lines. Rapp’s README is a little bit confusing, but once you get the hang of it, it has a lot of potential.

I’m running Linux, but Rapp promises to be cross-platform. The first thing you need to do is install Rapp and add it to your PATH so that it becomes a system command.

# Install the package
install.packages("Rapp")

# Add Rapp to your PATH
Rapp::install_pkg_cli_apps("Rapp")

I tried it out with a simple example script which I named print-numbers.R and it’s important that you get those first two lines right. In the first one, you tell your script where Rapp lives at, and in the second one you describe what your app does.

#!/usr/bin/env Rapp
#| description: Prints numbers to the screen up to specified integer.

n <- 1L
for (i in seq_len(n)) {
  cat(paste(i), "\n")
}

At this point Right now you have Rapp installed, the launcher installed (Rapp command exists) and the script works via Rapp::run(), but your script is not yet exposed to the shell as a command. That means this works from your R prompt:

Rapp::run("print-numbers.R", c("--n=7"))

Which isn’t very useful if what you want is not to fire up R to run your command line application. However, from the directory where your script lives, this works as well, which is way cooler:

Rapp print-numbers.R --n=7
1 
2 
3 
4 
5 
6 
7 

However, the endgame here is that your colleagues should be able to just run print-numbers --n=7 without anything else. For that to happen, you need to expose your app to your shell as a command. If you want to make it available system wide you check your PATH and take note of the first option it gives you:

echo $PATH
# which will output something like:
# /home/you/.local/bin

You then symlink it to your PATH and make sure the actual file is executable.

# Create a symlink
ln -s print-numbers.R ~/.local/bin/print-numbers

# Make it executable
chmod +x print-numbers.R

And that’s it, now you can run it from your command line anywhere on your machine like:

print-numbers --n=7
1 
2 
3 
4 
5 
6 
7 

This is a simple example, but I think that it is very promising. You can build processing scripts that your colleagues can use without having to get R training, which they should still get, but, you know. Its intended use is with custom R packages, so I’ll keep exploring how I can put it to good use.

Any typos you find here are actually on purpose.