Package 'rcompendium'

Description

This function creates a CITATION file in the folder ⁠inst/⁠. This file contains a BiBTeX entry to cite the package as a manual. User will need to edit by hand some information (title, version, etc.).

Usage

add_citation(
  given = NULL,
  family = NULL,
  organisation = NULL,
  open = TRUE,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

No return value.

See Also

Other create files: add_code_of_conduct(), add_codeowners(), add_compendium(), add_contributing(), add_description(), add_dockerfile(), add_license(), add_makefile(), add_package_doc(), add_readme_rmd(), add_renv(), add_testthat(), add_vignette()

Examples

## Not run: 
add_citation()
readCitationFile("inst/CITATION")

## End(Not run)

Description

This function creates a CODE_OF_CONDUCT.md file adapted from the Contributor Covenant, version 2.1 available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

Usage

add_code_of_conduct(
  email = NULL,
  open = TRUE,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

No return value.

See Also

Other create files: add_citation(), add_codeowners(), add_compendium(), add_contributing(), add_description(), add_dockerfile(), add_license(), add_makefile(), add_package_doc(), add_readme_rmd(), add_renv(), add_testthat(), add_vignette()

Examples

## Not run: 
add_code_of_conduct()

## End(Not run)

Description

This function adds a Code coverage badge to the README.Rmd, i.e. the percentage of code cover by units tests. This percentage is computed by the codecov.io service.

Note: this service must be manually activated for the package by visiting https://about.codecov.io/.

Make sure that 1) a README.Rmd file exists at the project root and 2) it contains a block starting with the line ⁠<!-- badges: start -->⁠ and ending with the line ⁠<!-- badges: end -->⁠.

Don't forget to re-render the README.md.

Usage

add_codecov_badge(organisation = NULL, quiet = FALSE)

Arguments

Value

A badge as a markdown expression.

See Also

Other adding badges: add_cran_downloads_badge(), add_cran_total_download_badge(), add_cran_version_badge(), add_dependencies_badge(), add_github_actions_check_badge(), add_github_actions_codecov_badge(), add_github_actions_pkgdown_badge(), add_license_badge(), add_lifecycle_badge(), add_repostatus_badge()

Examples

## Not run: 
add_codecov_badge()

## End(Not run)

Description

This function creates a CODEOWNERS file in the folder ⁠.github/⁠. This file is used to define individual that is responsible for code in the repository.

Usage

add_codeowners(
  github_user = NULL,
  open = FALSE,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

No return value.

See Also

Other create files: add_citation(), add_code_of_conduct(), add_compendium(), add_contributing(), add_description(), add_dockerfile(), add_license(), add_makefile(), add_package_doc(), add_readme_rmd(), add_renv(), add_testthat(), add_vignette()

Examples

## Not run: 
add_codeowners()

## End(Not run)

Description

This function creates a compendium, i.e. additional folders to a package structure. By default, the following directories are created: data, ⁠analyses/⁠, ⁠outputs/⁠, and ⁠figures/⁠. A README.md is added to each folder and must be edited. The argument compendium allows user to hoose its own compendium structure. All theses folders are added to the .Rbuildignore file.

Usage

add_compendium(compendium = NULL, quiet = FALSE)

Arguments

Value

No return value.

See Also

Other create files: add_citation(), add_code_of_conduct(), add_codeowners(), add_contributing(), add_description(), add_dockerfile(), add_license(), add_makefile(), add_package_doc(), add_readme_rmd(), add_renv(), add_testthat(), add_vignette()

Examples

## Not run: 
add_compendium()
add_compendium(compendium = "paper")
add_compendium(compendium = c("data", "outputs", "code", "manuscript"))

## End(Not run)

Description

This function creates a CONTRIBUTING.md file providing general guidelines outlining the best way to contribute to the project (need to be adapted).

Usage

add_contributing(
  email = NULL,
  organisation = NULL,
  open = TRUE,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

No return value.

See Also

Other create files: add_citation(), add_code_of_conduct(), add_codeowners(), add_compendium(), add_description(), add_dockerfile(), add_license(), add_makefile(), add_package_doc(), add_readme_rmd(), add_renv(), add_testthat(), add_vignette()

Examples

## Not run: 
add_contributing()

## End(Not run)

Description

This function adds a CRAN monthly downloads badge to the README.Rmd.

Make sure that 1) a README.Rmd file exists at the project root and 2) it contains a block starting with the line ⁠<!-- badges: start -->⁠ and ending with the line ⁠<!-- badges: end -->⁠.

Don't forget to re-render the README.md.

Usage

add_cran_downloads_badge(quiet = FALSE)

Arguments

Value

A badge as a markdown expression.

See Also

Other adding badges: add_codecov_badge(), add_cran_total_download_badge(), add_cran_version_badge(), add_dependencies_badge(), add_github_actions_check_badge(), add_github_actions_codecov_badge(), add_github_actions_pkgdown_badge(), add_license_badge(), add_lifecycle_badge(), add_repostatus_badge()

Examples

## Not run: 
add_cran_downloads_badge()

## End(Not run)

Description

This function adds a CRAN total download badge to the README.Rmd.

Make sure that 1) a README.Rmd file exists at the project root and 2) it contains a block starting with the line ⁠<!-- badges: start -->⁠ and ending with the line ⁠<!-- badges: end -->⁠.

Don't forget to re-render the README.md.

Usage

add_cran_total_download_badge(quiet = FALSE)

Arguments

Value

A badge as a markdown expression.

See Also

Other adding badges: add_codecov_badge(), add_cran_downloads_badge(), add_cran_version_badge(), add_dependencies_badge(), add_github_actions_check_badge(), add_github_actions_codecov_badge(), add_github_actions_pkgdown_badge(), add_license_badge(), add_lifecycle_badge(), add_repostatus_badge()

Examples

## Not run: 
add_cran_total_download_badge()

## End(Not run)

Description

This function adds a CRAN Status (i.e. CRAN version) badge to the README.Rmd. If the package is not hosted on the CRAN the badge will indicate not published on the CRAN.

Make sure that 1) a README.Rmd file exists at the project root and 2) it contains a block starting with the line ⁠<!-- badges: start -->⁠ and ending with the line ⁠<!-- badges: end -->⁠.

Don't forget to re-render the README.md.

Usage

add_cran_version_badge(quiet = FALSE)

Arguments

Value

A badge as a markdown expression.

See Also

Other adding badges: add_codecov_badge(), add_cran_downloads_badge(), add_cran_total_download_badge(), add_dependencies_badge(), add_github_actions_check_badge(), add_github_actions_codecov_badge(), add_github_actions_pkgdown_badge(), add_license_badge(), add_lifecycle_badge(), add_repostatus_badge()

Examples

## Not run: 
add_cran_version_badge()

## End(Not run)

Description

This function creates a dependabot.yaml file (configuration file) in the ⁠.github/⁠ directory. This GitHub Action will be triggered once a week to check for dependency updates (used by any GitHub Action of the repository). If an update is available, this bot will open a Pull Request and user will be invited to review changes.

This function is called by add_github_action() to automatically create this configuration file if any GitHub Action is used.

Usage

add_dependabot(overwrite = FALSE, quiet = FALSE)

Arguments

Value

No return value.

See Also

Other development functions: add_dependencies(), add_github_action(), add_issue_template(), add_r_depend(), add_to_buildignore(), add_to_gitignore()

Examples

## Not run: 
add_dependabot()

## End(Not run)

Description

This function detects external dependencies used in ⁠R/⁠, NAMESPACE, and ⁠@examples⁠ sections of roxygen2 headers and automatically adds these dependencies in the Imports section of the DESCRIPTION file.

In the NAMESPACE this function detects dependencies mentioned as import(pkg) and importFrom(pkg,fun).

In the ⁠R/⁠ folder it detects functions called as pkg::fun() in the code of each R files. In ⁠@examples⁠ sections it also detects packages attached by library() or require().

The ⁠vignettes/⁠ folder is also inspected and detected dependencies (pkg::fun(), library() or require()) are added to the Suggests field of the DESCRIPTION file (in addition to the packages knitr and rmarkdown).

If the project is a research compendium user can also inspect additional folder(s) with the argument compendium to add dependencies to the Imports section of the DESCRIPTION file. The detection process is the same as the one used for ⁠vignettes/⁠.

The ⁠tests/⁠ folder is also inspected and detected dependencies (pkg::fun(), library() or require()) are added to the Suggests field of the DESCRIPTION file (in addition to the package testthat).

Usage

add_dependencies(compendium = NULL)

Arguments

Value

No return value.

See Also

Other development functions: add_dependabot(), add_github_action(), add_issue_template(), add_r_depend(), add_to_buildignore(), add_to_gitignore()

Examples

## Not run: 
add_dependencies()

## End(Not run)

Description

This function adds or updates the Dependencies badge to the README.Rmd. The first number corresponds to the direct dependencies and the second to the recursive dependencies.

Note: this function can work with packages not published on the CRAN and is based on the function gtools::getDependencies(). See also the function get_all_dependencies().

Make sure that 1) a README.Rmd file exists at the project root and 2) it contains a block starting with the line ⁠<!-- badges: start -->⁠ and ending with the line ⁠<!-- badges: end -->⁠.

Don't forget to re-render the README.md.

Usage

add_dependencies_badge(quiet = FALSE)

Arguments

Value

A badge as a markdown expression.

See Also

Other adding badges: add_codecov_badge(), add_cran_downloads_badge(), add_cran_total_download_badge(), add_cran_version_badge(), add_github_actions_check_badge(), add_github_actions_codecov_badge(), add_github_actions_pkgdown_badge(), add_license_badge(), add_lifecycle_badge(), add_repostatus_badge()

Examples

## Not run: 
add_dependencies_badge()

## End(Not run)

Description

This function creates a DESCRIPTION file at the root of the project. This file contains metadata of the project. Some information (title, description, version, etc.) must be edited by hand. For more information: https://r-pkgs.org/description.html. User credentials can be passed as arguments but it is recommended to store them in the .Rprofile file of the project with set_credentials().

Usage

add_description(
  given = NULL,
  family = NULL,
  email = NULL,
  orcid = NULL,
  organisation = NULL,
  open = TRUE,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

No return value.

See Also

Other create files: add_citation(), add_code_of_conduct(), add_codeowners(), add_compendium(), add_contributing(), add_dockerfile(), add_license(), add_makefile(), add_package_doc(), add_readme_rmd(), add_renv(), add_testthat(), add_vignette()

Examples

## Not run: 
add_description(organisation = "MySociety")

## End(Not run)

Description

This function creates a Dockerfile at the root of the project based on a template. The Docker image is based on rocker/rstudio. The whole project will be copied in the image and R packages will be installed (using renv::restore() or remotes::install_deps()).

In addition a .dockerignore file is added to ignore some files/folders while building the image.

User can customize this Dockerfile (e.g. system dependencies). He/she can also use a different default Docker image (i.e. tidyverse, verse, geospatial, etc.). For more information: https://github.com/rocker-org/rocker-versioned2

By default the versions of R and renv (if applicable) specified in the Dockerfile are the same as the local system.

Once the project is ready to be released, user must build the Docker image by running: ⁠docker build -t "image_name" .⁠

Then to run a container, user must run: ⁠docker run --rm -p 127.0.0.1:8787:8787 -e DISABLE_AUTH=true image_name⁠

A new instance of RStudio Server is available on the Web browser at the URL: ⁠127.0.0.1:8787⁠.

Usage

add_dockerfile(
  given = NULL,
  family = NULL,
  email = NULL,
  open = TRUE,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

No return value.

See Also

Other create files: add_citation(), add_code_of_conduct(), add_codeowners(), add_compendium(), add_contributing(), add_description(), add_license(), add_makefile(), add_package_doc(), add_readme_rmd(), add_renv(), add_testthat(), add_vignette()

Examples

## Not run: 
add_dockerfile()

## End(Not run)

Description

This function sets up a continuous integration (CI) for an R project hosted on GitHub. It creates a configuration file (.yaml) to setup a specific GitHub Action (see below).

Available workflows are derived from https://github.com/r-lib/actions/tree/v2-branch/examples and are hosted on a different repository https://github.com/FRBCesab/r-templates/tree/main/actions.

Configuration files will be written in ⁠.github/workflows/⁠.

Usage

add_github_action(name, open = FALSE, overwrite = FALSE, quiet = FALSE)

Arguments

Details

Here is a list of commonly used GitHub Actions that will be triggered after each push or pull request:

• R-CMD-check: check the package integrity on three major operating systems (Ubuntu, macOS, and Windows) using the latest release of R. The package is also checked on Ubuntu (latest version) using the development and previous versions of R.

• test-coverage: compute and report the code coverage (i.e. the proportion of R code covered by unit tests) to https://about.codecov.io/.

• pkgdown: build and publish the pkgdown website of the package on a dedicated gh-pages branch. The repository may need further configuration (see usethis::use_pkgdown_github_pages()).

• check-format: set up the Air formatter for R and check the code format. This action will fail if any files need to be reformatted with Air.

• render-README: render the README.Rmd only if it has been modified. This action will commit and push the updated README.md to the main branch. User need to fetch the new version.

• update-Rd-files: update the package documentation files (Rd files and NAMESPACE). This action will commit and push the updated files to the main branch. User need to fetch the new version.

• update-citation-cff: update the CITATION.cff, a human- and machine-readable citation information file. This action is triggered if the DESCRIPTION file and/or the inst/CITATION file is modified. This action will commit and push the updated CITATION.cff to the main branch. User need to fetch the new version.

• update-codemeta: update the codemeta.json, a standardized metadata file for software (not only R packages). This action is triggered if the DESCRIPTION file and/or the inst/CITATION file and/or the README.md is modified. This action will commit and push the updated codemeta.json to the main branch. User need to fetch the new version.

If one of these GitHub Actions is added to the project, this function will also create a dependabot.yaml file in ⁠.github/⁠. This action will be triggered once a week to check for dependency updates (used by any GitHub Action of the repository). If an update is available, this bot will open a Pull Request and user will be invited to review changes.

Value

No return value.

See Also

Other development functions: add_dependabot(), add_dependencies(), add_issue_template(), add_r_depend(), add_to_buildignore(), add_to_gitignore()

Examples

## Not run: 
add_github_action(name = "R-CMD-check")

## End(Not run)

Description

This function adds a R CMD Check badge to the README.Rmd. This function must be run after add_github_action() which will setup GitHub Actions to check and test the package.

Make sure that 1) a README.Rmd file exists at the project root and 2) it contains a block starting with the line ⁠<!-- badges: start -->⁠ and ending with the line ⁠<!-- badges: end -->⁠.

Don't forget to re-render the README.md.

Usage

add_github_actions_check_badge(organisation = NULL, quiet = FALSE)

Arguments

Value

A badge as a markdown expression.

See Also

Other adding badges: add_codecov_badge(), add_cran_downloads_badge(), add_cran_total_download_badge(), add_cran_version_badge(), add_dependencies_badge(), add_github_actions_codecov_badge(), add_github_actions_pkgdown_badge(), add_license_badge(), add_lifecycle_badge(), add_repostatus_badge()

Examples

## Not run: 
add_github_actions_check_badge()

## End(Not run)

Description

This function adds a Test coverage badge to the README.Rmd. This function must be run after add_github_action() which will setup GitHub Actions to report the percentage of code cover by units tests.

Make sure that 1) a README.Rmd file exists at the project root and 2) it contains a block starting with the line ⁠<!-- badges: start -->⁠ and ending with the line ⁠<!-- badges: end -->⁠.

Don't forget to re-render the README.md.

Usage

add_github_actions_codecov_badge(organisation = NULL, quiet = FALSE)

Arguments

Value

A badge as a markdown expression.

See Also

Other adding badges: add_codecov_badge(), add_cran_downloads_badge(), add_cran_total_download_badge(), add_cran_version_badge(), add_dependencies_badge(), add_github_actions_check_badge(), add_github_actions_pkgdown_badge(), add_license_badge(), add_lifecycle_badge(), add_repostatus_badge()

Examples

## Not run: 
add_github_actions_codecov_badge()

## End(Not run)

Description

This function adds a Website badge to the README.Rmd. This function must be run after add_github_action() which will setup GitHub Actions to build and deploy the package website.

Make sure that 1) a README.Rmd file exists at the project root and 2) it contains a block starting with the line ⁠<!-- badges: start -->⁠ and ending with the line ⁠<!-- badges: end -->⁠.

Don't forget to re-render the README.md.

Usage

add_github_actions_pkgdown_badge(organisation = NULL, quiet = FALSE)

Arguments

Value

A badge as a markdown expression.

See Also

Other adding badges: add_codecov_badge(), add_cran_downloads_badge(), add_cran_total_download_badge(), add_cran_version_badge(), add_dependencies_badge(), add_github_actions_check_badge(), add_github_actions_codecov_badge(), add_license_badge(), add_lifecycle_badge(), add_repostatus_badge()

Examples

## Not run: 
add_github_actions_pkgdown_badge()

## End(Not run)

Description

This function creates an Issue template file (md) in the directory .github/ISSUE_TEMPLATE. These files preformat a GitHub Issue. Contributors can use these templates when they open new issues. For instance, you can format issue related to bug report, feature request, etc.

Usage

add_issue_template(name, open = FALSE, overwrite = FALSE, quiet = FALSE)

Arguments

Value

No return value.

See Also

Other development functions: add_dependabot(), add_dependencies(), add_github_action(), add_r_depend(), add_to_buildignore(), add_to_gitignore()

Examples

## Not run: 
add_issue_template(name = "feature_request")

## End(Not run)

Description

This function adds a license to the project. It will add the license name in the License field of the DESCRIPTION file and write the content of the license in a LICENSE.md file.

Usage

add_license(license = NULL, given = NULL, family = NULL, quiet = FALSE)

Arguments

Value

No return value.

See Also

Other create files: add_citation(), add_code_of_conduct(), add_codeowners(), add_compendium(), add_contributing(), add_description(), add_dockerfile(), add_makefile(), add_package_doc(), add_readme_rmd(), add_renv(), add_testthat(), add_vignette()

Examples

## Not run: 
add_license(license = "MIT")
add_license(license = "GPL (>= 2)")

## End(Not run)

Description

This function adds or updates the License badge to the README.Rmd. This function reads the License field of the DESCRIPTION file. Ensure that this field is correctly defined. See add_license() for further detail.

This function requires the presence of a DESCRIPTION file at the project root. See add_description() for further detail.

Make sure that 1) a README.Rmd file exists at the project root and 2) it contains a block starting with the line ⁠<!-- badges: start -->⁠ and ending with the line ⁠<!-- badges: end -->⁠.

Don't forget to re-render the README.md.

Usage

add_license_badge(quiet = FALSE)

Arguments

Value

A badge as a markdown expression.

See Also

Other adding badges: add_codecov_badge(), add_cran_downloads_badge(), add_cran_total_download_badge(), add_cran_version_badge(), add_dependencies_badge(), add_github_actions_check_badge(), add_github_actions_codecov_badge(), add_github_actions_pkgdown_badge(), add_lifecycle_badge(), add_repostatus_badge()

Examples

## Not run: 
add_license_badge()

## End(Not run)

Description

This function adds or updates the Life Cycle badge to the README.Rmd. It is based on the standard defined at https://lifecycle.r-lib.org/articles/stages.html.

Make sure that 1) a README.Rmd file exists at the project root and 2) it contains a block starting with the line ⁠<!-- badges: start -->⁠ and ending with the line ⁠<!-- badges: end -->⁠.

Don't forget to re-render the README.md.

Usage

add_lifecycle_badge(lifecycle = "experimental", quiet = FALSE)

Arguments

Details

The project can have the following life cycle stage:

• Experimental - An experimental project is made available so user can try it out and provide feedback, but come with no promises for long term stability.

• Stable - A project is considered stable when the author is happy with its interface, does not see major issues, and is happy to share it with the world.

• Superseded - A superseded project has a known better alternative, and it is not going away. Superseded project will not receive new features, but will receive any critical bug fixes needed to keep it working.

• Deprecated - A deprecated project has a better alternative available and is scheduled for removal.

Value

A badge as a markdown expression.

See Also

Other adding badges: add_codecov_badge(), add_cran_downloads_badge(), add_cran_total_download_badge(), add_cran_version_badge(), add_dependencies_badge(), add_github_actions_check_badge(), add_github_actions_codecov_badge(), add_github_actions_pkgdown_badge(), add_license_badge(), add_repostatus_badge()

Examples

## Not run: 
add_lifecycle_badge()
add_lifecycle_badge(lifecycle = "stable")

## End(Not run)

Description

This function creates a Make-like R file (make.R) at the root of the project based on a template. To be used only if the project is a research compendium. The content of this file provides some guidelines. See also create_new_compendium() for further information.

Usage

add_makefile(
  given = NULL,
  family = NULL,
  email = NULL,
  open = TRUE,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

No return value.

See Also

Other create files: add_citation(), add_code_of_conduct(), add_codeowners(), add_compendium(), add_contributing(), add_description(), add_dockerfile(), add_license(), add_package_doc(), add_readme_rmd(), add_renv(), add_testthat(), add_vignette()

Examples

## Not run: 
add_makefile()

## End(Not run)

Description

This function adds a package-level documentation file (pkg-package.R) in the ⁠R/⁠ folder. This file will make help available to the user via ?pkg (where pkg is the name of the package). It a good place to put general directives like ⁠@import⁠ and ⁠@importFrom⁠.

Usage

add_package_doc(open = TRUE, overwrite = FALSE, quiet = FALSE)

Arguments

Value

No return value.

See Also

Other create files: add_citation(), add_code_of_conduct(), add_codeowners(), add_compendium(), add_contributing(), add_description(), add_dockerfile(), add_license(), add_makefile(), add_readme_rmd(), add_renv(), add_testthat(), add_vignette()

Examples

## Not run: 
add_package_doc()

## End(Not run)

Description

This function adds the minimal R version to the Depends field of the DESCRIPTION file. This version corresponds to the higher version of R among all dependencies. If no dependencies mentions minimal R version, the DESCRIPTION is not modified.

Usage

add_r_depend()

Value

No return value.

See Also

Other development functions: add_dependabot(), add_dependencies(), add_github_action(), add_issue_template(), add_to_buildignore(), add_to_gitignore()

Examples

## Not run: 
add_r_depend()

## End(Not run)

Description

This function creates a README.Rmd file at the root of the project based on a template. Once edited user needs to knit it into a README.md.

Usage

add_readme_rmd(
  type = "package",
  given = NULL,
  family = NULL,
  organisation = NULL,
  open = TRUE,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

No return value.

See Also

Other create files: add_citation(), add_code_of_conduct(), add_codeowners(), add_compendium(), add_contributing(), add_description(), add_dockerfile(), add_license(), add_makefile(), add_package_doc(), add_renv(), add_testthat(), add_vignette()

Examples

## Not run: 
add_readme_rmd(type = "package")

## End(Not run)

Description

This function initializes an renv environment for the project by running renv::init(). See https://rstudio.github.io/renv/ for further detail.

Usage

add_renv(quiet = FALSE)

Arguments

Value

No return value.

See Also

Other create files: add_citation(), add_code_of_conduct(), add_codeowners(), add_compendium(), add_contributing(), add_description(), add_dockerfile(), add_license(), add_makefile(), add_package_doc(), add_readme_rmd(), add_testthat(), add_vignette()

Examples

## Not run: 
add_renv()

## End(Not run)

Description

This function adds or updates the Repository Status badge of the project to the README.Rmd. It is based on the standard defined by the https://www.repostatus.org project.

Make sure that 1) a README.Rmd file exists at the project root and 2) it contains a block starting with the line ⁠<!-- badges: start -->⁠ and ending with the line ⁠<!-- badges: end -->⁠.

Don't forget to re-render the README.md.

Usage

add_repostatus_badge(status = "concept", quiet = FALSE)

Arguments

Details

The project can have the following status:

• Concept - Minimal or no implementation has been done yet, or the repository is only intended to be a limited example, demo, or proof-of-concept.

• WIP - Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.

• Suspended - Initial development has started, but there has not yet been a stable, usable release; work has been stopped for the time being but the author(s) intend on resuming work.

• Abandoned - Initial development has started, but there has not yet been a stable, usable release; the project has been abandoned and the author(s) do not intend on continuing development.

• Active - The project has reached a stable, usable state and is being actively developed.

• Inactive - The project has reached a stable, usable state but is no longer being actively developed; support/maintenance will be provided as time allows.

• Unsupported - The project has reached a stable, usable state but the author(s) have ceased all work on it. A new maintainer may be desired.

Value

A badge as a markdown expression.

See Also

Other adding badges: add_codecov_badge(), add_cran_downloads_badge(), add_cran_total_download_badge(), add_cran_version_badge(), add_dependencies_badge(), add_github_actions_check_badge(), add_github_actions_codecov_badge(), add_github_actions_pkgdown_badge(), add_license_badge(), add_lifecycle_badge()

Examples

## Not run: 
add_repostatus_badge()
add_repostatus_badge(status = "active")

## End(Not run)

Description

This function initializes units tests settings by running usethis::use_testthat() and by adding an example units tests file tests/testthat/test-demo.R. The sample file will test a demo function created in R/fun-demo.R.

Usage

add_testthat()

Value

No return value.

See Also

Other create files: add_citation(), add_code_of_conduct(), add_codeowners(), add_compendium(), add_contributing(), add_description(), add_dockerfile(), add_license(), add_makefile(), add_package_doc(), add_readme_rmd(), add_renv(), add_vignette()

Examples

## Not run: 
add_testthat()

## End(Not run)

Description

This function adds files/folders to the .Rbuildignore file. If a .Rbuildignore is already present, files to be ignored while checking package are just added to this file. Otherwise a new file is created.

Usage

add_to_buildignore(x, open = FALSE, quiet = FALSE)

Arguments

Value

No return value.

See Also

Other development functions: add_dependabot(), add_dependencies(), add_github_action(), add_issue_template(), add_r_depend(), add_to_gitignore()

Examples

## Not run: 
add_to_buildignore(open = TRUE)
add_to_buildignore(".DS_Store")

## End(Not run)

Description

This function creates a .gitignore file at the root of the project based on a template (specific to R). If a .gitignore is already present, files to be untracked by git are just added to this file.

Usage

add_to_gitignore(x, open = FALSE, quiet = FALSE)

Arguments

Value

No return value.

See Also

Other development functions: add_dependabot(), add_dependencies(), add_github_action(), add_issue_template(), add_r_depend(), add_to_buildignore()

Examples

## Not run: 
add_to_gitignore(open = TRUE)
add_to_gitignore(".DS_Store")

## End(Not run)

Description

This function adds a vignette in the folder ⁠vignettes/⁠. It also adds dependencies knitr and rmarkdown in the field Suggests of the DESCRIPTION file (if not already present in fields Imports).

Usage

add_vignette(
  filename = NULL,
  title = NULL,
  open = TRUE,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

No return value.

See Also

Other create files: add_citation(), add_code_of_conduct(), add_codeowners(), add_compendium(), add_contributing(), add_description(), add_dockerfile(), add_license(), add_makefile(), add_package_doc(), add_readme_rmd(), add_renv(), add_testthat()

Examples

## Not run: 
## Default vignette ----
add_vignette()

## Default vignette ----
add_vignette(filename = "pkg", title = "Get started")

## End(Not run)

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 create_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

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

Arguments

Value

No return value.

See Also

Other setup functions: create_new_package(), set_credentials()

Examples

## Not run: 
library(rcompendium)

## Define **ONCE FOR ALL** your credentials ----
set_credentials(
  given = "John",
  family = "Doe",
  email = "[email protected]",
  orcid = "9999-9999-9999-9999",
  github_user = "jdoe",
  protocol = "ssh"
)

## Create an R package ----
create_new_compendium()

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

## End(Not run)

Description

This function creates a new R package structure according to the current best practices. Essential features of an R package are created (DESCRIPTION and NAMESPACE files, and ⁠R/⁠ and ⁠man/⁠ folders). The project is also versioned with git and a generic R .gitignore is added.

IMPORTANT - Before using this function user needs to create a new folder (or a new project if using RStudio) and run this function inside this folder (by using setwd() or by opening the Rproj in a new RStudio session). The name of the package will be the same as the name of this folder. Some rules must be respected: https://r-pkgs.org/workflow101.html#name-your-package.

Some fields of the DESCRIPTION file (maintainer information, package name, license, URLs, and roxygen2 version) are automatically filled but others (like title and description) need to be edited manually.

Additional features are also created: a CITATION file, a README.Rmd, and ⁠tests/⁠ and ⁠vignettes/⁠ folders (optional). See the vignette Get started for a complete overview of the full structure.

A GitHub repository can also be created (default) following the "GitHub last" workflow (https://happygitwithr.com/existing-github-last.html). Configuration files for GitHub Actions to automatically 1) check the package, 2) test and report code coverage, and 3) deploy the website using pkgdown will be added in the ⁠.github/⁠ folder. See below the section Creating a GitHub repo.

Usage

create_new_package(
  license = "GPL (>= 2)",
  status = NULL,
  lifecycle = NULL,
  contributing = TRUE,
  code_of_conduct = TRUE,
  code_owners = TRUE,
  vignette = TRUE,
  test = TRUE,
  create_repo = TRUE,
  private = FALSE,
  issue_templates = TRUE,
  gh_check = TRUE,
  codecov = TRUE,
  website = TRUE,
  gh_render = TRUE,
  gh_citation = TRUE,
  gh_codemeta = TRUE,
  given = NULL,
  family = NULL,
  email = NULL,
  orcid = NULL,
  github_user = NULL,
  organisation = NULL,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

Value

No return value.

Recommended workflow

The purpose of the package rcompendium is to make easier the creation of R package/research compendium so that user can focus on the code/analysis instead of wasting time organizing files.

The recommended workflow is:

1. Create an empty RStudio project;

2. Store your credentials with set_credentials() (if not already done);

3. Run create_new_package() to create a new package structure (and the GitHub repository);

4. Edit some metadata in DESCRIPTION, CITATION, and README.Rmd;

5. Implement, document & test functions (the fun part);

6. Update the project (update .Rd files, NAMESPACE, external dependencies in DESCRIPTION, re-knit README.Rmd, and check package integrity);

7. Repeat steps 5 and 6 while developing the package.

Managing credentials

You can use the arguments given, family, email, and orcid directly with the function create_new_package() (and others). But if you create a lot a projects (packages and/or compendiums) it can be frustrating in the long run.

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 your time (it's 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 create_new_package()) or permanently by re-running set_credentials().

Configuring git

First run gh::gh_whoami() to see if your git is 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_set(name  = "user.name",
                            value = "John Doe")

gert::git_config_global_set(name  = "user.email",
                            value = "[email protected]")

gert::git_config_global_set(name  = "github.user",
                            value = "jdoe")

See gert::git_config_global_set() for further information.

Creating a GitHub repo

To create the GitHub repository directly from R, the package rcompendium uses the function usethis::use_github(), an client to the GitHub REST API. The interaction with this API required 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 it in the ⁠~/.Renviron⁠ file by using usethis::edit_r_environ() and adding the following line: GITHUB_PAT='ghp_99z9...z9'

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

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

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

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

See Also

Other setup functions: create_new_compendium(), set_credentials()

Examples

## Not run: 
library(rcompendium)

## Define **ONCE FOR ALL** your credentials ----
set_credentials(
  given = "John",
  family = "Doe",
  email = "[email protected]",
  orcid = "9999-9999-9999-9999",
  github_user = "jdoe",
  protocol = "ssh"
)

## Create an R package ----
create_new_package()

## Start developing functions ----
## ...

## End(Not run)

Description

This function gets all the external packages that the project needs. It is used the generate the Dependencies badge (add_dependencies_badge()).

Usage

get_all_dependencies(pkg = NULL)

Arguments

Value

A list of three vectors:

• base_deps, a vector of base packages;

• direct_deps, a vector of direct packages;

• all_deps, a vector of all dependencies (recursively obtained).

See Also

Other utilities functions: get_all_functions(), get_available_gh_actions(), get_available_issue_templates(), get_available_licenses(), get_minimal_r_version()

Examples

## Not run: 
## Update dependencies ----
add_dependencies()

## Get all dependencies ----
deps <- get_all_dependencies()
unlist(lapply(deps, length))

## Can be used for a CRAN package ----
deps <- get_all_dependencies("usethis")
unlist(lapply(deps, length))

## End(Not run)

Description

This function returns a list of all the functions (exported and internal) available with the project. As this function scans the NAMESPACE and the ⁠R/⁠ folder, it is recommended to:

• store all the functions in the ⁠R/⁠ folder

• run devtools::document() before to update the NAMESPACE

Usage

get_all_functions()

Value

A list of two vectors:

• external, a vector of exported functions name;

• internal, a vector of internal functions name.

See Also

Other utilities functions: get_all_dependencies(), get_available_gh_actions(), get_available_issue_templates(), get_available_licenses(), get_minimal_r_version()

Examples

## Not run: 
## Update NAMESPACE ----
devtools::document()

## List all implemented functions ----
get_all_functions()

## End(Not run)

Description

This function returns a list of the name of all available GitHub Actions. This is particularly useful to get the right spelling of the GitHub Action to be passed to add_github_action().

Usage

get_available_gh_actions()

Value

A character vector with the name of the available GitHub Actions in rcompendium.

See Also

Other utilities functions: get_all_dependencies(), get_all_functions(), get_available_issue_templates(), get_available_licenses(), get_minimal_r_version()

Examples

## Not run: 
get_available_gh_actions()

## End(Not run)

Description

This function returns a list of the name of all available Issue Templates. This is particularly useful to get the right spelling of the Issue Templates to be passed to add_issue_template().

Usage

get_available_issue_templates()

Value

A character vector with the name of the available Issue Templates in rcompendium.

See Also

Other utilities functions: get_all_dependencies(), get_all_functions(), get_available_gh_actions(), get_available_licenses(), get_minimal_r_version()

Examples

## Not run: 
get_available_issue_templates()

## End(Not run)

Description

This function returns a list of all available licenses. This is particularly useful to get the right spelling of the license to be passed to create_new_package(), create_new_compendium(), or add_license().

Usage

get_available_licenses()

Value

A data.frame with the following two variables:

• tag, the license name to be used with add_license();

• url, the URL of the license description.

See Also

Other utilities functions: get_all_dependencies(), get_all_functions(), get_available_gh_actions(), get_available_issue_templates(), get_minimal_r_version()

Examples

get_available_licenses()

Description

This function detects the minimal required R version for the project based on minimal required R version of its dependencies. It can be used to update the Depends field of the DESCRIPTION file.

Usage

get_minimal_r_version(pkg = NULL)

Arguments

Value

A character with the minimal required R version.

See Also

Other utilities functions: get_all_dependencies(), get_all_functions(), get_available_gh_actions(), get_available_issue_templates(), get_available_licenses()

Examples

## Not run: 
## Update dependencies ----
add_dependencies()

## Minimal R version of a project ----
get_minimal_r_version()

## Minimal R version of a CRAN package ----
get_minimal_r_version("usethis")

## End(Not run)

Description

This function is used to store user credentials (given and family names, email, ORCID, GitHub username, etc.) in the .Rprofile file. This function is useful to store user credentials once for all especially if the user creates a lot of R projects and/or if the user manually calls the ⁠add_*()⁠ functions.

This function will create the .Rprofile file if it does not exist. Then, the user needs to paste the content of the clipboard to this file (open by the function).

Usage

set_credentials(
  given = NULL,
  family = NULL,
  email = NULL,
  orcid = NULL,
  github_user = NULL,
  protocol = "https",
  open = TRUE
)

Arguments

Value

No return value.

See Also

Other setup functions: create_new_compendium(), create_new_package()

Examples

## Not run: 
set_credentials(
  given = "John",
  family = "Doe",
  email = "[email protected]",
  orcid = "9999-9999-9999-9999",
  github_user = "jdoe",
  protocol = "https",
  open = TRUE
)

## End(Not run)