This repository provides the current template I use for new research projects.
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!?"
Exactly...
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.
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.
knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.path = "README-" )
The template can be initialized with functions from devtools:
devtools::install_github("hadley/devtools") library("devtools")
Configure some default options for devtools
, see package?devtools
:
options(devtools.name = "Carl Boettiger", devtools.desc.author = "person('Carl', 'Boettiger', email='cboettig@gmail.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 devtools
:
covr
to the suggests listwriteLines(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 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_travis()
)use_package
, and also add to .travis.yml
manually, e.g. under r_binary_packages:
, r_github_packages
, or r_packages
use_data()
or possibly use_raw_data()
(for scripts that import and clean data first)rmarkdown
, knitr
and rticles
packages 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 rticles
templates.Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.