R: Create an R compendium structure

new_compendium {rcompendium}

R Documentation

Create an R compendium structure

Description

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.

Usage

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

Arguments

`compendium`	A character vector specifying the folders to be created. See `add_compendium()` for further information.
`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()`.
`contributing`	A logical value. If `TRUE` (default) adds a `CONTRIBUTING.md` file and `ISSUE_TEMPLATES`. See `add_contributing()` for further information.
`code_of_conduct`	A logical value. If `TRUE` (default) adds a `CODE_OF_CONDUCT.md` file. See `add_code_of_conduct()` for further information.
`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`.
`gh_citation`	A logical value. If `TRUE` configures GitHub Actions to automatically update the `CITATION.cff` file. See `add_github_actions_citation()` 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

## Not run: 
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()

## End(Not run)