Skip to content

Latest commit

 

History

History
212 lines (147 loc) · 5.71 KB

CONTRIBUTING.md

File metadata and controls

212 lines (147 loc) · 5.71 KB

Contributing to Biodiversity Horizons

Thank you for your interest in contributing to Biodiversity Horizons! This guide provides step-by-step instructions to set up the project locally, run the R scripts, and use Docker for containerized execution. Follow these guidelines to get started.

Read our Code of Conduct to keep our community approachable and respectable.

Getting Started

Prerequisites

Ensure the following tools are installed on your system:

  • R (version >= 4.0.0)
  • RStudio (optional, but recommended for development)
  • Docker (if you want to use the Docker setup)
  • Git (for version control)

Step 1: Clone the Repository

To start using the package, clone the repository and navigate into the project directory:

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

Step 2: Install Dependencies

The package requires several dependencies to function. Use the following commands in your R console or RStudio to install them:

  1. Install devtools if you don't already have it:
install.packages("devtools")
  1. Install all dependencies from the DESCRIPTION file:
devtools::install_deps()

Using the Package Locally

The primary script for running the project is located at scripts/VISS_Sample_Data.R. Follow these steps to use it.

Step 1: Execute the Script Locally

Run the script using the Rscript command in your terminal. Here are examples of how to use it:

Rscript scripts/VISS_Sample_Data.R

This will use:

  • path ="data-raw/"
  • plan_type ="multisession"
  • workers =availableCores() - 1

Pass Custom Arguments: Specify custom arguments (path, plan, workers):

Rscript scripts/VISS_Sample_Data.R /path/to/data multicore 4

Step 2: Output Files

The script processes the data and saves the output files in the outputs/ directory. The primary result file is res_final.rds.

Using the Package with Docker

If you prefer a containerized setup, you can use Docker to run the project.

Step 1: Build the Docker Image

Use the provided Dockerfile to build the image:

docker build -t biodiversity-horizons .

Step 2: Run the Docker Container

Run with Defaults

Run the container and mount your local data directory to the container’s data-raw/ directory:

docker run --rm \
  -v /path/to/data-raw/:/home/biodiversity-horizons/data-raw/ \
  biodiversity-horizons

This will:

  • Mount your local data-raw/ directory to /home/biodiversity-horizons/data-raw/ inside the container.
  • Execute the script using the default arguments.

Pass Custom Arguments

You can pass custom arguments to the script by appending them to the docker run command. For example:

docker run --rm \
  -v /path/to/data-raw/:/home/biodiversity-horizons/data-raw/ \
  -v /path/to/outputs/:/home/biodiversity-horizons/outputs/ \
  biodiversity-horizons \
  Rscript scripts/VISS_Sample_Data.R /home/biodiversity-horizons/data-raw multicore 4

This command:

  • Mounts local data-raw/ directory to /home/biodiversity-horizons/data-raw/ inside the container.
  • Mounts local outputs/ directory to /home/biodiversity-horizons/outputs/ inside the container.
  • Passes custom arguments to the script:
    • /home/biodiversity-horizons/data-raw: Path to the data directory.
    • multicore: Parallelization plan.
    • 4: Number of workers.

Note:

If your current working directory already contains the data-raw/ folder, you can simplify the command by replacing /path/to/data-raw/ with $(pwd)/data-raw/:

Example:

docker run --rm \
  -v $(pwd)/data-raw/:/home/biodiversity-horizons/data-raw/ \
  biodiversity-horizons

Pull Requests

We welcome contributions! Please follow these guidelines when submitting a Pull Request:

  • It may be helpful to review this tutorial on how to contribute to open source projects. A typical task workflow is:

    • Fork the code repository specified in the task and clone it locally.
    • Review the repo's README.md and CONTRIBUTING.md files to understand what is required to run and modify this code.
    • Create a branch in your local repo to implement the task.
    • Commit your changes to the branch and push it to the remote repo.
    • Create a pull request, adding the task owner as the reviewer.

  • Please follow the Conventional Commits naming for pull request titles.

Your contributions make this project better—thank you for your support! 🚀

Configuring Precommit

PRs will fail style and formatting checks as configured by precommit, but you can set up your local repository such that precommit runs every time you commit. This way, you can fix any errors before you send out pull requests!!

To do this, install Pixi using either the instructions on their website, or the commands below:

MacOS/Linux:

curl -fsSL https://pixi.sh/install.sh | bash

Windows: Check the website

Configure Precommit to run on every commit

Then, once Pixi is installed, run the following command to set up precommit checks on every commit

pixi run precommit-install

Manually run precommit on non-committed files

pixi run precommit

Manually run precommit on all files

pixi run precommit-all