Introduction

In the area of open science, making reproducible analyses is a strong prerequisite. But sometimes it is difficult 1) to find the good structure to organize files and 2) to set up the whole project. The aim of the package rcompendium is to make easier the creation of R package/research compendium (i.e. a predefined files/folders structure) so that users can focus on the code/analysis instead of wasting time organizing files.


A full ready-to-work structure will be set up with the following features:

  • Initialization of the GIT version control.
  • Creation of a minimal R package structure (DESCRIPTION and NAMESPACE files, and R/ and man/ folders).
  • Creation of additional files (LICENSE.md, inst/CITATION, etc.).
  • Creation of a Get started vignette in vignettes/.
  • Setting the units tests process.
  • Creation of a README.Rmd with HexSticker (template) and badges.
  • Autocompletion of maintainer information.
  • Creation of a GitHub repository.
  • Configuration of GitHub Actions to automatically:
    • check and test package (R CMD Check);
    • report the code coverage (covr);
    • build and deploy website (pkgdown).


The strength of rcompendium is to create the whole structure in one command line by using the function new_package(). The default settings will produce the following structure (where pkg is the name of the package):

pkg
│
├── pkg.Rproj                   # (optional) Created by user 
│
├── .git/                       # GIT tracking folder
├── .gitignore                  # Specific to R packages
|
├── .github/                    # (optional) GitHub Actions settings
│   └── workflows/
│       ├── pkgdown.yaml        # Configuration file to build & deploy website
│       ├── R-CMD-check.yaml    # Configuration file to check & test package
│       └── test-coverage.yaml  # Configuration file to build & deploy website
│
├── _pkgdown.yaml               # (optional) User website settings
│
├── R/                          # R functions
│   ├── fun-demo.R              # Example of an R function
│   └── pkg-package.R           # Dummy R file for package-level documentation
│
├── man/                        # R functions helps (automatically updated)
│   ├── print_msg.Rd            # Documentation of the demo R function
│   ├── pkg-package.Rd          # Package-level documentation
│   └── figures/                # Figures for the README 
│       └── hexsticker.png      # Template R package HexSticker
│
├── tests/
│   ├── testthat.R              # Units tests settings
│   └── testthat/               # Units tests folder
│       └── test-demo.R         # Units tests for the function print_msg()
|
├── vignettes/
│   └── pkg.Rmd                 # (optional) Package tutorial              [*]
│
├── DESCRIPTION                 # Project metadata                         [*]
├── NAMESPACE                   # Automatically generated
├── .Rbuildignore               # List of files/folders to be ignored while 
│                               # checking the package
├── inst/
│   └── CITATION                # BiBTeX entry to cite the R package       [*]
│
├── LICENSE                     # (optional) If License = MIT
├── LICENSE.md                  # Content of the chosen license
│
├── README.md                   # GitHub README (automatically generated)
└── README.Rmd                  # GitHub README (to knit)                  [*]


[*] These files are automatically edited but user needs to add manually 
    some information (title, description, version, etc.).


The second main function of rcompendium is new_compendium(). It will add the following files/folders to the previous content:

...
├── data/                       # User raw data (.csv, .gpkg, etc.)        
├── rscripts/                   # R scripts (no functions) to run analyses 
├── outputs/                    # Outputs created by R scripts             
├── figures/                    # Figures created by R scripts             
└── paper/                      # Article based on analyses                
│
└── make.R                      # Master R scripts to run all analyses     

The folder analysis/ and the file make.R will be added to the .Rbuildignore so that some parts of the compendium (essentially the R functions) can be installed as an R package (with devtools::install()). Installing the package is optional.


Installation

You can install the development version from GitHub with:

## Install < remotes > package (if not already installed) ----
if (!requireNamespace("remotes", quietly = TRUE)) {
  install.packages("remotes")
}

## Install dev version of < rcompendium > from GitHub ----
remotes::install_github("FRBCesab/rcompendium")


Prerequisites

Before using the package rcompendium you must follow these three steps.

GIT configuration

First ensure that GIT is correctly installed on your machine and linked to RStudio. Read the Chapter 6 of Happy Git and GitHub for the useR.

You also need to store your GIT credentials locally (i.e. for the project) or globally (recommended). Run gh::gh_whoami() to see if your git and associated credentials are correctly configured. If so you should see something like:

{
"name": "John Doe",
"login": "jdoe",
"html_url": "https://github.com/jdoe",
(...)
}

Otherwise you might need to run:

gert::git_config_global(name = "user.name",   value = "John Doe")
gert::git_config_global(name = "user.email",  value = "john.doe@@domain.com")
gert::git_config_global(name = "github.user", value = "jdoe")

See gert::git_config() for further information.

Creating a GitHub repo

To create the GitHub repository directly from R, the package rcompendium uses the function usethis::use_github(), a client to the GitHub REST API. The interaction with this API requires an authentication method: a GITHUB PAT (Personal Access Token).

If you don’t have a GITHUB PAT locally stored, you must:

  1. Obtain a new one from your GitHub account. Make sure to select at least the first two scopes (private repository and workflow)
  2. Store this token in the .Renviron file by using usethis::edit_r_environ() and adding the following line: GITHUB_PAT='99z9...z9'

Run usethis::gh_token_help() for more information about getting and configuring a GITHUB PAT.

If everything is well configured, after calling gh::gh_whoami() you should see something like:

{
"name": "John Doe",
"login": "jdoe",
"html_url": "https://github.com/jdoe",
"scopes": "delete_repo, repo, workflow",
"token": "99z9...z9"
}

Then you will be able to create a GitHub repository directly from R!

Managing credentials

You can use the arguments given, family, email, and orcid directly with the function new_package() (and others). But an alternative is to use ONCE AND FOR ALL the function set_credentials() to permanently store this information in the .Rprofile file. If these arguments are set to NULL (default) each function of the package rcompendium will search in this .Rprofile file. It will save you a lot of time (that is the purpose of this package).

Even if you have stored your information in the .Rprofile file you will always be able to modify them on-the-fly (i.e. by using arguments of the new_package() and others) or permanently by re-running set_credentials().


Usage

The recommended workflow is:

  1. IMPORTANT - Create an empty RStudio project.
  2. Store your credentials with set_credentials() (if not already done).
  3. Run new_package() or new_compendium() to create a new package/research compendium structure (and the GitHub repository if required).
  4. Edit metadata in DESCRIPTION, CITATION, and README.Rmd.
  5. Implement, document & test functions.
  6. Update the project with refresh(). This will:
  • update .Rd files and NAMESPACE;
  • update external dependencies in DESCRIPTION;
  • update badges and re-knit README.Rmd;
  • check and test package (devtools::check());
  • run make.R if the project is a research compendium (optional because some analyses might be time consuming).
  1. Repeat steps 5 and 6 while working on the project.


In addition to these four setup functions (set_credentials(), new_package(), new_compendium(), and refresh()), the package rcompendium offers 29 other functions. These can be grouped as:

  • add_*(): functions to add/update/overwrite files, configuration settings, dependencies, badges, etc.;
  • get_*(): functions to retrieve some information (available licenses, R version, etc.).

Visit the Reference page for further details.


To sum up:

library(rcompendium)

## Define **ONCE FOR ALL** your credentials ----

set_credentials(given = "John", family = "Doe", 
                email = "john.doe@@domain.com", 
                orcid = "9999-9999-9999-9999", protocol = "ssh")

## Create an R package structure ----

new_package()


## Then... 
## ... implement and document R functions in R/
## ... write units tests in tests/testthat/


## Update package (documentation, dependencies, README, check) ----

refresh()


## Update Repository Status (example) ----

add_repostatus_badge(status = "active")


## Change LICENSE (example) ----

get_licenses()
add_license(license = "MIT")


## Update package (documentation, dependencies, README, check) ----

refresh()

And do not forget to commit changes and to push to GitHub to enjoy GitHub Actions!

N.B. Users can also use functions from the package usethis to add some missing features (e.g. data/ and package release tools).


Contributing

You are welcome to contribute to the rcompendium project. Please read our Contribution Guidelines.

Please note that the rcompendium project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.


Colophon

This package is the result of intense discussions and feedback from the training course Data Toolbox for Reproducible Research in Computational Ecology (in French).

rcompendium is largely inspired by the package rrtools developed by Ben Marwick et al. and tries to respect the standard defined by the community. Special thanks to these developers!