new_compendium: Create an R compendium structure

Description Usage Arguments Value See Also Examples

View source: R/new_compendium.R

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:

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
new_compendium(
  compendium = ".",
  license = "GPL (>= 2)",
  status = NULL,
  lifecycle = NULL,
  vignette = FALSE,
  test = FALSE,
  create_repo = TRUE,
  private = FALSE,
  gh_check = TRUE,
  codecov = FALSE,
  website = TRUE,
  given = NULL,
  family = NULL,
  email = NULL,
  orcid = NULL,
  organisation = NULL,
  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 below the section Creating a GitHub repo.

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 (default) 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.

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 (default) 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.

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).

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

None

See Also

Other setup functions: new_package(), refresh(), set_credentials()

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
## 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)

rcompendium documentation built on March 24, 2021, 5:06 p.m.