In booysej/cridfdata: Store CRIDF data

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.

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='[e-mail]', 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.

booysej/cridfdata documentation built on May 13, 2019, 12:34 a.m.