Template Repository for R Projects and Scripts

A template repository for modern R development with renv using R6 classes, validation with checkmate, logging with lgr, argument parsing with optparse, and a Shiny web app interface. Formatted with Air, linted with Jarl, and tested with testthat using GitHub Actions.

Checklist

• Replace YOURUSERNAME and IMAGENAME in .github/workflows/docker-image.yml [or delete file].
• Replace data in data with your own (test) data [or delete if you don't have data].
• Adjust .gitattributes according to your needs [or delete file].
• Adjust .gitignore according to your needs.
• Setup your CITATION.cff according to your needs [or delete file].
• Update attribution in Dockerfile and write image instructions, see also Docker.
• Replace copyright name in LICENSE.
• Update the main script in lib/main.R.
• Delete example .R files in lib/ [and create your own].
• Check if tests/testthat.R needs updating.
• Write tests in tests/testthat/.
• Document your code inline using roxygen2 style.
• Document your code/script by writing a documentation page, see Documentation.
• Adjust this README.md to your needs!

Managing R Installations

It's recommended to use rig - the R Installation Manager.

Helpful Commands

• rig:
  • Install a specific R version, e.g. 4.6.1:

    rig add 4.6.1

  • Set a default R version, e.g. 4.6.1:

    rig default 4.6.1

• renv:
  • Restore an R environment:

    Rscript -e "renv::restore()"

    or

    renv::restore()

  • Snapshot an R environment:

    Rscript -e "renv::snapshot()"

    or

    renv::snapshot()

  • Install a package:

    Rscript -e "renv::install('pkg')"

    or

    renv::install("pkg")

  • Install a package from Bioconductor:

    Rscript -e "renv::install('bioc::pkg')"

    or

    renv::install("bioc::pkg")

• Air:
  • Format files:

    air format

  • Alternatively, setup air editor integration as described here.
  • Check if files are properly formatted:

    air format --check

• Jarl:
  • Lint with jarl:

    jarl check .

• testthat:
  • Test with testthat:

    Rscript -e "source('tests/testthat.R')"

• Run application:
  • CLI mode (example for this application):

    Rscript run.R -f data/characters.csv

  • Shiny mode (example for this application):

    Rscript run.R -s

Documentation

This template features inline documentation using roxygen2 syntax. For setting up an online documentation page there is a VitePress template included in docs. It uses the Catppuccin theme.

Adjusting the Documentation

• Adjust the docs/.vitepress/config.mts file to your needs.
• Update the markdown files in docs/md/.
• The documentation is automatically built via GitHub Actions using this workflow, but you can see a live preview or build it locally by doing the following:
  • Install Node.js.
  • Install pnpm.
  • Navigate to the docs/ directory:

    cd docs

  • Install dependencies with pnpm:

    pnpm i

  • Show a live preview:

    pnpm docs:dev

  • Build the site locally:

    pnpm docs:build

Alternatives for Documentation

Quarto would be a possible and recommended alternative for building documentation pages. If you write an R package you might also want to consider pkgdown.

Docker

If you want to containerize your R project with Docker there are a few things to keep in mind, as pointed out below. You may also find it helpful to read through this renv documentation.

Installing System Dependencies

Depending on your R environment you will need to install additional system dependencies in your Docker file. This mostly involves some trial and error but boils down to the following steps:

• Checking the output of renv::sysreqs(), e.g. using:

  renv::sysreqs(distro = "ubuntu:24.04", report = TRUE, collapse = TRUE)

• Checking the output of renv::restore() on the first image build.
• Debugging the build error messages you get.

Managing Build Context

It's recommended to build the image using a clean repository state, e.g. using:

git clean -f -d -X

Alternatively consider using a .dockerignore file.

Getting Help

• Help for this template:
  • rig: R installation manager.
  • renv: R project and dependency management.
  • Air: R formatter and language server.
  • Jarl: R linter.
  • testthat: R testing suit.
  • GitHub Actions: Used for running the above automatically.
• Contact: micha.birklbauer@gmail.com

Important

The below sections should be adjusted and updated by you!

Known Issues

List of known issues

Citing

If you are using PLACEHOLDER please cite:

Very important title
Important Author, and Another Important Author
Journal of Cool Stuff 2023 12 (3), 4567-4589
DOI: 12.3456/cool-stuff

License

• MIT

Contact

• your.mail@mail.com