Scaffold a reproducible study analysis

Writes a complete, runnable analysis project: a targets pipeline that recomputes only what changed, R scripts split along the stages every user study goes through (read, clean, score, model, plot), a Quarto report, and a directory the generated LaTeX lands in so a manuscript can \input{} the numbers instead of having them re-typed.

Usage

use_study_project(
  path,
  name = NULL,
  questionnaires = c("nasa_tlx", "sus"),
  renv = requireNamespace("renv", quietly = TRUE),
  git = TRUE,
  overwrite = FALSE,
  quiet = FALSE
)

Arguments

path: Directory to create the project in. Created if it does not exist.
name: Project name, used in the README and the report title. Defaults to the directory name.
questionnaires: Character vector of instrument keys the study uses, e.g. c("nasa_tlx", "sus"). The scoring script is generated with one call per instrument. See list_questionnaires().
renv: Logical. Initialise renv in the project, pinning the package versions this analysis was run with. Default TRUE when renv is installed. This is what makes the project still run in three years, and what makes it a usable open-science artifact.
git: Logical. Write a .gitignore suited to an R analysis project. Default TRUE.
overwrite: Logical. Replace files that already exist. Default FALSE, so running this on a live project adds missing pieces without touching your work.
quiet: Logical. Suppress the per-file messages.

Value

Invisibly, the normalised project path.

Details

The generated pipeline is wired to this package: scoring goes through score_questionnaire(), model choice and fitting through fit_recommended(), sentences and tables through the report_* functions, and figures through save_paper_figure(). It runs as written against the example data it ships with, so the first thing you do in a new project is see a green pipeline, then replace the example data with yours.

Why a pipeline rather than a script

A study analysis is re-run many times – after a data fix, after a reviewer asks for one more contrast, after a co-author changes a factor label. With a script, that means re-running everything and hoping nothing stale is left in the workspace; targets tracks which step depends on what and recomputes only the affected ones, which also means the pipeline is a machine-checkable record of how each number was produced.

Examples

# \donttest{
project <- file.path(tempdir(), "driving-study")
use_study_project(project, questionnaires = c("nasa_tlx", "sus"), renv = FALSE)
#> Creating study project 'driving-study' in /tmp/Rtmp2Ft8yp/driving-study
#>   wrote: /tmp/Rtmp2Ft8yp/driving-study/_targets.R
#>   wrote: /tmp/Rtmp2Ft8yp/driving-study/R/read.R
#>   wrote: /tmp/Rtmp2Ft8yp/driving-study/R/prepare.R
#>   wrote: /tmp/Rtmp2Ft8yp/driving-study/R/analysis.R
#>   wrote: /tmp/Rtmp2Ft8yp/driving-study/R/figures.R
#>   wrote: /tmp/Rtmp2Ft8yp/driving-study/report/report.qmd
#>   wrote: /tmp/Rtmp2Ft8yp/driving-study/README.md
#>   wrote: /tmp/Rtmp2Ft8yp/driving-study/.gitignore
#>   wrote: /tmp/Rtmp2Ft8yp/driving-study/data-raw/example-study.csv
#>   wrote: /tmp/Rtmp2Ft8yp/driving-study/data-raw/README.md
#>   wrote: /tmp/Rtmp2Ft8yp/driving-study/paper/generated/README.md
#>   wrote: /tmp/Rtmp2Ft8yp/driving-study/output/figures/README.md
#>   wrote: /tmp/Rtmp2Ft8yp/driving-study/paper/colleyRstats.sty
#> 
#> Done. Next:
#>   1. setwd("/tmp/Rtmp2Ft8yp/driving-study")
#>   2. targets::tar_make()            # runs end to end on the example data
#>   3. replace data-raw/example-study.csv with yours, then edit R/read.R
#>   4. targets::tar_visnetwork()      # see what is out of date
list.files(project, recursive = TRUE)
#>  [1] "R/analysis.R"               "R/figures.R"               
#>  [3] "R/prepare.R"                "R/read.R"                  
#>  [5] "README.md"                  "_targets.R"                
#>  [7] "data-raw/README.md"         "data-raw/example-study.csv"
#>  [9] "output/figures/README.md"   "paper/colleyRstats.sty"    
#> [11] "paper/generated/README.md"  "report/report.qmd"         
# }