Create an R compendium structure

This function creates a research compendium (i.e. a predefined files/folders structure) to help user organizing files/folders to run analysis.

In addition to common R packages files/folders (see new_package() for further information) this function will created these following folders:

data/: a folder to store raw data. Note that these data must never be modified. If user want to modify them it is recommended to export new data in outputs/.
analyses/: a folder to write analyses instructions, i.e. R scripts. If user need to create R functions it is recommended to write them in the R/ folder.
outputs/: a folder to store intermediate and final outputs generated by the R scripts.
figures/: a folder to store figures generated by the R scripts.

This function also creates a Make-like R file (make.R). This file contains two main lines:

devtools::install_deps(): downloads the external dependencies required by the project (an alternative to install.packages()). Ideal for sharing;
devtools::load_all(): loads external dependencies and R functions (an alternative to library() and source() respectively).

As the user writes R scripts he/she can add the following line in this file: source(here::here("rscripts", "script_X.R")). Then he/she can source the entire make.R to run analysis. The function add_dependencies() can be used to automatically add external dependencies in the DESCRIPTION file.

It is recommended, for a better reproducibility, to call external dependencies as pkg::fun() or with @import or @importFrom in R functions instead of using library().

All these files/folders are added to the .Rbuildignore so the rest of the project (e.g. R functions) can be used (or installed) as a R package.

new_compendium(
  compendium = ".",
  license = "GPL (>= 2)",
  status = NULL,
  lifecycle = NULL,
  vignette = FALSE,
  test = FALSE,
  create_repo = TRUE,
  private = FALSE,
  gh_check = FALSE,
  codecov = FALSE,
  website = FALSE,
  gh_render = FALSE,
  given = NULL,
  family = NULL,
  email = NULL,
  orcid = NULL,
  organisation = NULL,
  renv = FALSE,
  dockerfile = FALSE,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

compendium

A character vector of length 1. By default, compendium folders are created at the root of the project. User can change their location with this argument. For instance, if compendium = 'analysis', compendium folders will be created inside the directory analysis/.

license

A character vector of length 1. The license to be used for this project. Run get_licenses() to choose an appropriate one. Default is license = 'GPL (>= 2)'

The license can be changed later by calling add_license() (and add_license_badge() or refresh() to update the corresponding badge in the README).

status

A character vector of length 1. The status of the project according to the standard defined by the https://www.repostatus.org project. One among 'concept', 'wip', 'suspended', 'abandoned', 'active', 'inactive', or 'unsupported'. See add_repostatus_badge() for further information.

This argument is used to add a badge to the README.Rmd to help visitors to better understand your project. Default is status = NULL.

This status can be added/changed later by using add_repostatus_badge().

lifecycle

A character vector of length 1. The life cycle stage of the project according to the standard defined at https://lifecycle.r-lib.org/articles/stages.html. One among 'experimental', 'stable', 'deprecated', or 'superseded'. See add_lifecycle_badge() for further information.

This argument is used to add a badge to the README.Rmd to help visitors to better understand your project. Default is lifecycle = NULL.

This stage can be added/changed later by using add_lifecycle_badge().

vignette

A logical value. If TRUE creates a vignette in vignettes/. Packages knitr and rmarkdown are also added to the Suggests field in the DESCRIPTION file. Default is FALSE.

test

A logical value. If TRUE initializes units tests by running usethis::use_testthat(). Package testthat is also added to the Suggests field in the DESCRIPTION file. Default is FALSE.

create_repo

A logical value. If TRUE (default) creates a repository (public if private = FALSE or private if private = TRUE) on GitHub. See the section Creating a GitHub repo of the help page of new_package().

private

A logical value. If TRUE creates a private repository on user GitHub account (or organisation). Default is private = FALSE.

gh_check

A logical value. If TRUE configures GitHub Actions to automatically check and test the package after each push. This will run R CMD check on the three major operating systems (Ubuntu, macOS, and Windows) on the latest release of R. See add_github_actions_check() for further information.

If create_repo = FALSE this argument is ignored. Default is FALSE.

codecov

A logical value. If TRUE configures GitHub Actions to automatically report the code coverage of units tests after each push. See add_github_actions_codecov() for further information.

If create_repo = FALSE this argument is ignored. Default is FALSE.

website

A logical value. If TRUE configures GitHub Actions to automatically build and deploy the package website (using pkgdown) after each push. A gh-pages branch will be created using usethis::use_github_pages() and the GitHub repository will be automatically configured to deploy website.

If create_repo = FALSE this argument is ignored. Default is FALSE.

gh_render

A logical value. If TRUE configures GitHub Actions to automatically knit the README.Rmd after each push. See add_github_actions_render() for further information.

If create_repo = FALSE this argument is ignored. Default is FALSE.

given

A character vector of length 1. The given name of the maintainer of the package. If NULL (default) the function will try to get this value by reading the .Rprofile file.

For further information see set_credentials().

family

A character vector of length 1. The family name of the maintainer of the package. If NULL (default) the function will try to get this value by reading the .Rprofile file.

For further information see set_credentials().

email

A character vector of length 1. The email address of the maintainer of the package. If NULL (default) the function will try to get this value by reading the .Rprofile file.

For further information see set_credentials().

orcid

A character vector of length 1. The ORCID of the maintainer of the package. If NULL (default) the function will try to get this value by reading the .Rprofile file.

For further information see set_credentials().

organisation

A character vector of length 1. The GitHub organisation to host the repository. If defined it will overwrite the GitHub pseudo.

Default is organisation = NULL (the GitHub pseudo will be used).

renv

A logical value. If TRUE initializes an renv environment for the project by running renv::init(). Package renv is also added to the Imports field in the DESCRIPTION file. Default is FALSE.

dockerfile

A logical value. If TRUE creates an Dockerfile for the project. See add_dockerfile() for further detail. Default is FALSE.

overwrite

A logical value. If TRUE files written from templates and modified by user are erased. Default is overwrite = FALSE. Be careful while using this argument.

quiet

A logical value. If TRUE messages are deleted. Default is FALSE.

Value

No return value.

Examples

if (FALSE) {
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 ----
new_compendium()

## Start adding data and developing functions and scripts ----
## ...

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

Arguments

Value

See also

Examples