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 = 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
)
A character vector specifying the folders to be created.
See add_compendium()
for further information.
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).
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()
.
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()
.
A logical value. If TRUE
(default) adds a
CONTRIBUTING.md
file and ISSUE_TEMPLATES
. See add_contributing()
for
further information.
A logical value. If TRUE
(default) adds a
CODE_OF_CONDUCT.md
file. See add_code_of_conduct()
for further
information.
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
.
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
.
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()
.
A logical value. If TRUE
creates a private repository on
user GitHub account (or organisation). Default is private = FALSE
.
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
.
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
.
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
.
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
.
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
.
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()
.
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()
.
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()
.
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()
.
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).
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
.
A logical value. If TRUE
creates an Dockerfile
for
the project. See add_dockerfile()
for further detail. Default is FALSE
.
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.
A logical value. If TRUE
messages are deleted. Default is
FALSE
.
No return value.
Other setup functions:
new_package()
,
refresh()
,
set_credentials()
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()
}