Home

Awesome

<!-- README.md is generated from README.Rmd. Please edit that file -->

Travis-CI Build Status Coverage Status

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!?"

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.

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:

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:

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.

Manuscript elements