This repository provides the current template I use for new research projects.
Why an R package structure?
Academic research isn't software development, and there are many other templates for how to organize a research project. So why follow an R package layout? Simply put, this is because the layout of an R package is familiar to a larger audience and allows me to leverage a rich array of tools that don't exist for more custom approaches.
"But"", you say, "a paper doesn't have unit tests, or documented functions! Surely that's a lot of needless overhead in doing this!?"
While there is certainly no need to use all the elements of a package in every research project, or even to have a package that can pass
devtools::check() or even
devtools::install() for it to be useful. Most generic layout advice starts sounding like an R package pretty quickly: have a directory for
data/, a separate one for
R/ scripts, another one for the manuscript files, and so forth. Temple Lang and Gentleman (2007) advance the proposal for using the R package structure as a "Research Compendium," an idea that has since caught on with many others.
As a project grows in size and collaboration, having the more rigid structure offered by a package format becomes increasingly valuable. Packages can automate installation of dependencies, perform checks that changes have not broken code, and provide a modular and highly tested framework for collecting together the three essential elements: data, code, and manuscript-quality documentation, in a powerful and feature-rich environment.
Steps to create the template
To use this template, I will usually clone this repo and just remove the
.git record, starting off a new project accordingly. Here I document the steps used to set up this template from scratch, which permits a slightly more modular approach. If this were fully automated it would be preferable to copying, but has not yet reached that stage.
The template can be initialized with functions from devtools:
Configure some default options for
options(devtools.name = "Carl Boettiger", devtools.desc.author = "person('Carl', 'Boettiger', email@example.com', role = c('aut', 'cre'))", devtools.desc.license = "MIT + file LICENSE")
Run devtools templating tools
setup() use_testthat() use_vignette("intro") use_travis() use_package_doc() use_cran_comments() use_readme_rmd()
Additional modifications and things not yet automated by
- Add the now-required LICENSE template data
covrto the suggests list
writeLines(paste("YEAR: ", format(Sys.Date(), "%Y"), "\n", "COPYRIGHT HOLDER: ", getOption("devtools.name"), sep=""), con="LICENSE") use_package("covr", "suggests") write( " r_binary_packages: - testthat - knitr r_github_packages: - jimhester/covr after_success: - Rscript -e 'library(covr); coveralls()'", file=".travis.yml", append=TRUE)
Further steps that aren't automated
Further steps aren't yet automated in devtools or by me; as it's easier to add these manually to the template and then use the template when starting a new project.
- add the travis shield to README, (as prompted to do by
- Turn on repo at coveralls.io and add the shield to README
- adding additional dependencies to DESCRIPTION with
use_package, and also add to
.travis.ymlmanually, e.g. under
- add additional data with
use_raw_data()(for scripts that import and clean data first)
- Recent developments in
rticlespackages greatly faciliates using vignettes as full manuscripts. The above step adds only a basic HTML templated vignette. This package includes a template for a latex/pdf manuscript using these tools. The actual template appropriate for a project may be better selected from (possibly my fork of) the