Biodiversity Horizons

Biodiversity Horizons is an R-based project for processing climate data and analyzing primate distributions. It can be used locally (in R/RStudio) or run inside a Docker container for consistent dependencies across systems.

Installation

You can install the development version of biodiversityhorizons like so:

# Install devtools if not already installed
install.packages("devtools")

# Install biodiversityhorizons package
devtools::install_github("uw-ssec/biodiversity-horizons")

Example

This is a basic example which shows you how to solve a common problem:

library(biodiversityhorizons)
## basic example code

For more advanced usage, refer to our Contributing Guidelines

Docker Usage

We provide a Docker image so you can run the data processing scripts in a containerized environment, ensuring consistent R dependencies.

1. Prerequisites

• Install Docker: Refer to Install Docker Desktop Guide

2. Pull the Docker Image

docker pull ghcr.io/uw-ssec/biodiversity-horizons:latest

If this succeeds, the image is downloaded locally.

(Optional) GitHub Container Registry Authentication:

If pulling fails with a “denied” error, generate a Personal Access Token (classic) with read:packages scope and run:

echo YOUR_TOKEN | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin

3. Obtain or Prepare your data-raw/ folder

• Option A: Using Your Own Data

  If you already have .rds files:

  • Create a local folder (e.g., ~/my_data) and place your .rds files there.
  • That folder will be mounted as /home/biodiversity-horizons/data-raw in the container.

• Option B: Cloning This Repo for Sample Data

  If you need sample .rds files provided by this project (in data-raw/):

  1. Clone this repository:

  git clone https://github.com/uw-ssec/biodiversity-horizons.git
  

  cd biodiversity-horizons
  

  2. Use the included data-raw/ folder. It contains sample .rds files.

4. Run the Container Using run_container.sh

We recommend using the script run_container.sh for simplicity. It mounts your data and output folders to the container and executes the main R script.

• Ensure the script is executable:

  chmod +x run_container.sh
  

• Identify your directories:

  • A data folder with .rds files (either your own or the cloned data-raw/)
  • An outputs directory for script results

• Run the container:

  ./run_container.sh /absolute/path/to/data-raw /absolute/path/to/outputs
  

  • Replace /absolute/path/to/data-raw or /absolute/path/to/data-outputs with the paths on your machine.

  • This mounts your local data-raw folder into the container and runs the default script.

5. Passing Additional Arguments

You can pass custom arguments (e.g., parallel plan, workers), example:

./run_container.sh /absolute/path/to/data-raw /absolute/path/to/outputs multisession 4

These extra arguments are forwarded to the R script inside the container.

Setup and Run Apptainer

Step 1: Navigate to the biodiversity-horizons project directory

cd ~/Desktop/biodiversity-horizons  # Adjust this path as needed

Step 2: Run Docker with Apptainer inside an AMD64 environment

docker run --rm -it --privileged \
  --platform linux/amd64 \
  -v $(pwd):/mnt \
  godlovedc/apptainer bash

Inside Docker Container:

Step 3: Pull and convert the Docker image into a .sif file for Apptainer

apptainer pull /mnt/biodiversity-horizons.sif docker://ghcr.io/uw-ssec/biodiversity-horizons:latest

Step 4: Verify the .sif file was created

ls -l /mnt/biodiversity-horizons.sif

Step 5: Run Apptainer shell and mount required directories

apptainer shell --bind /mnt/data-raw:/home/biodiversity-horizons/data-raw /mnt/biodiversity-horizons.sif

Inside Apptainer Shell:

Step 6: Move to the correct working directory

cd /home/biodiversity-horizons

Step 7: Run the R script

Rscript /home/biodiversity-horizons/scripts/VISS_Sample_Data.R /home/biodiversity-horizons/data-raw

(Optional) Step 8: Run the R script with custom arguments (e.g., using 2 workers)

Rscript /home/biodiversity-horizons/scripts/VISS_Sample_Data.R /home/biodiversity-horizons/data-raw multisession 2

Running and Developing

Instructions to run and contribute to the portal can be found in Contributing Guidelines

Please follow our UW-SSEC Code of Conduct in all interactions. For questions or issues, open an Issue or contact the maintainers.