cboettig/template

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='[email protected]', 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:

• Add the now-required LICENSE template data
• add covr to 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 add_travis())
• 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.yml manually, e.g. under r_binary_packages:, r_github_packages, or r_packages
• add additional data with use_data() or possibly use_raw_data() (for scripts that import and clean data first)

Manuscript elements

• Recent developments in 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.