Skip to contents

Getting Started with rfp

Source: vignettes/setup.Rmd
setup.Rmd

Installation

Install rfp from GitHub:

pak::pak("NewGraphEnvironment/rfp")

System dependencies

rfp wraps command-line tools for spatial data processing and field project management. These need to be installed separately.

GDAL

GDAL provides ogr2ogr for vector data conversion. It’s also required by R’s sf package.

# macOS
brew install gdal

# Linux (Debian/Ubuntu)
apt install gdal-bin

Python CLI tools

rfp calls two Python command-line tools: mergin-client (Mergin Maps sync) and rasterio (the lateral-habitat raster clip). Install them with uv:

pip install uv
uv tool install mergin-client
uv tool install rasterio

rfp resolves each tool independently, in this order:

  1. getOption("rfp.python_venv"), if you point it at a venv of your own
  2. the package’s own venv, which exists only in a source checkout
  3. any uv tool install
  4. your PATH

So a uv tool install works whether you installed rfp from GitHub or cloned it. If you are working from a checkout you can instead build the package venv with uv sync --project inst/python; note that syncing into an installed package directory works once and is then deleted by the next pak::pkg_install(), so uv tool install is the durable option.

To point rfp at an environment you already manage:

options(rfp.python_venv = "~/venvs/gis/.venv")

Docker

rfp uses Docker for headless QGIS operations (style application, map rendering). Install Docker Desktop from docker.com.

The first time you run a style or rendering function, Docker will pull the qgis/qgis image (~2 GB). Subsequent runs use the cached image.

rfp asks for a pinned version of that image rather than :latest, so a render or a style is reproducible instead of following whatever the rolling tag was last re-pushed to. It is the same image rfp’s own tests and reference-authoring scripts run.

On an Apple Silicon Mac, pull it with an explicit platform. qgis/qgis publishes linux/amd64 only, so a pull without the flag fails with no matching manifest for linux/arm64/v8:

docker pull --platform linux/amd64 qgis/qgis:4.2

rfp passes --platform for you whenever it starts the official qgis/qgis image, so this matters mainly if you pull by hand. It does not claim a platform for an image it knows nothing about — a private mirror, or your own build — because a caller running an arm64-native build must not have emulation forced on them. If you point image = at a mirror of the amd64-only image, pull it with --platform yourself. The image then runs under emulation, which is slower than native but works.

Verify dependencies

Check that everything is available:

library(rfp)
rfp_check_deps()
#> ✔ ogr2ogr
#> ✔ wget
#> ✔ unzip
#> ✔ docker
#> ✔ mergin at ~/.local/share/uv/tools/mergin-client/bin/mergin
#> ℹ   from uv tool 'mergin-client'
#> ✔ rio at ~/.local/share/uv/tools/rasterio/bin/rio
#> ℹ   from uv tool 'rasterio'
#> ✔ All external dependencies found.

The Python tools are reported with the path rfp will actually call and the tier it came from, so a “works in the terminal but not in RStudio” difference is visible here — a GUI R session inherits launchd’s PATH, which usually excludes ~/.local/bin.

Mergin Maps authentication

To push projects to Mergin Maps for mobile field collection, set your credentials as environment variables. Add these to your ~/.Renviron:

MERGIN_USERNAME=your_username
MERGIN_PASSWORD=your_password

Or use a bearer token:

MERGIN_AUTH=Bearer your_token_here

Get a token by running mergin login in a terminal.