1 Before You Begin: Setup
Total core time: about 30 minutes, most of it waiting for packages to install.
| Section | Time | Type |
|---|---|---|
| What you will install | 10 min | Hands-on |
| Get the course repository | 5 min | Hands-on |
| Restore the course library | 10 min | Hands-on |
| Check you are ready | 5 min | Hands-on |
Do this once. Everything else in the course assumes it is done.
1.1 What You Will Install
Four tools, in this order. If you already have one, skip it.
| Tool | Why | Where |
|---|---|---|
| R 4.4.x | The language everything is written in | cran.r-project.org |
| RStudio or Positron | An IDE. Either works; the course shows RStudio | posit.co/downloads |
| Quarto | Renders the book and runs the code chunks | quarto.org/docs/get-started |
| Git | Gets you the repository and its history | git-scm.com |
renv.lock pins package versions that were built for R 4.4, and the package manager serves precompiled binaries per R version. On R 4.5 or newer, those binaries do not exist and every package is compiled from source instead: a fast setup becomes a slow and failure-prone one.
If you already run a newer R, that is fine, but expect the restore to take substantially longer.
Only if something has to be built from source. With R 4.4.x this should not happen, but it is worth having in place before you start.
- Windows: install Rtools44, matching R 4.4.x, from cran.r-project.org/bin/windows/Rtools. If you run a different R version, install the matching Rtools instead; a mismatched Rtools is the same as having none.
- macOS: install the Xcode Command Line Tools by running
xcode-select --installin Terminal. - Linux: you already have a compiler, but you may need system development libraries. Your distribution’s
r-base-devpackage (or equivalent) covers most of them.
Without these, a package that needs compiling fails with an error that does not obviously say why.
1.2 Why This Course Pins Its Packages
In regulated clinical work, “it worked on my machine” is not a defence. A submission has to be reproducible years after it was built, by somebody who is not you, on a machine that does not exist yet. That is not a nice-to-have. It is what the whole apparatus of standards, define.xml and reviewer guides exists to support.
So this course practises what it teaches. It uses renv to record the exact version of every package it depends on in a file called renv.lock. When you restore that lockfile, you get the same package versions the author had, not whatever CRAN is serving today.
renv.lock is a teaching artifact, not overhead. It is the smallest honest example of the thing the rest of the course is about: a result you can hand to someone else and have them reproduce exactly.
1.3 Get the Course Repository
Clone it, or download it as a ZIP from github.com/sufyansuleman/cdisc-with-r.
git clone https://github.com/sufyansuleman/cdisc-with-r.git
cd cdisc-with-rThen open cdisc-with-r.Rproj in RStudio. This matters more than it looks: opening the project sets R’s working directory to the project root, which is what every code chunk in the course assumes. Paths in the sessions are written as data/sdtm/dm.csv, not ../data/sdtm/dm.csv. They only resolve if you are at the root.
If you use Positron or run R from a terminal, cd to the repository root before starting R, and confirm with:
getwd() # should end in /cdisc-with-r1.4 Restore the Course Library
Opening the project runs .Rprofile, which activates renv and points your session at Posit Public Package Manager for precompiled binaries. You will usually see renv announce itself, and often a note that the library is out of sync, that is expected on a fresh clone.
Run this once, in the R console at the project root:
renv::restore()renv lists what it is about to install and asks you to confirm. Say yes.
What to expect. Several minutes, and a lot of output. Precompiled binaries make this fast on Windows and macOS, and on Linux too: renv rewrites the repository URL to match your distribution automatically.
The .Rprofile points at a dated snapshot of the package manager rather than at latest. That is deliberate, and it is the same idea as the lockfile. latest only serves binaries for whatever CRAN is shipping today, so a course pinned to older versions would quietly degrade into compiling everything from source as CRAN moved on. A dated snapshot keeps the pinned versions available as binaries indefinitely.
If it does start compiling from source and crawling, that is a signal something is off with your configuration rather than with you. See the troubleshooting section below.
A successful restore ends quietly, with no error, and:
renv::status()
#> No issues found -- the project is in a consistent state.That message is the goal. If you get anything else, fix it here rather than discovering it three sessions in.
1.5 Check You Are Ready
Run this snippet. It loads what the course loads, reads a file the way the sessions read files, and checks the controlled-terminology package can answer a question:
library(tidyverse)
library(sdtm.terminology)
# 1. the data ships with the repo. This should print 401 rows
dm_raw <- read_csv("data/raw/dm_raw.csv", show_col_types = FALSE)
nrow(dm_raw)
# 2. controlled terminology is available
ct("list") |> dplyr::filter(term == "SEX")
# 3. Quarto is on your PATH
Sys.which("quarto")You are ready when all three run without error: the read returns 401 rows (yes, 401, 400 subjects and one duplicate enrolment, which you will meet in Why Standards), the codelist lookup returns the SEX codelist C66731, and Sys.which() returns a path rather than an empty string.
To confirm Quarto can execute a session end to end, render a single one in a terminal at the project root:
quarto render sessions/why-standards.qmdThat should finish without error and write an HTML file. It is the real test: it runs R code, reads the data and produces output.
quarto render yet
Rendering the whole book will fail at this stage, and the failure is not your setup.
Three sessions - Define-XML, Define-XML from a Specification Workbook and Dataset-JSON - execute code against CDISC reference material that cannot be redistributed with this repository. You download it yourself when you reach those sessions, and each one tells you how. Until then a full-book render stops on the first of them.
Everything up to Define-XML renders on a fresh clone with no extra downloads.
1.6 If Something Went Wrong
renv::restore() fails on Windows, mentioning compilation. Rtools44 is missing or does not match your R version. Install it, restart R, try again.
Packages compile from source and take forever. Two causes, in order of likelihood. First, check you are on R 4.4.x with R.version.string; on a newer R there are no matching binaries and everything is built from source. Second, check the repository is set:
getOption("repos")[["P3M"]]
#> "https://packagemanager.posit.co/cran/2026-09-01"If that is missing or says something else, you probably opened R somewhere other than the project root, so .Rprofile never ran.
renv::restore() reports nothing to do, but library(tidyverse) then fails. The lockfile and your library disagree. Run renv::status() first and read what it says before installing anything by hand, that message is the diagnosis.
A code chunk says it cannot find data/raw/dm_raw.csv. Your working directory is not the project root. Run getwd() and, if needed, reopen cdisc-with-r.Rproj.
Everything installs but the book will not render. Check Quarto is on your PATH with quarto --version in a terminal. RStudio bundles its own Quarto, which can differ from the one your terminal sees.
A render fails in Define-XML, Define-XML from a Specification Workbook, or Dataset-JSON. Expected until you download the CDISC reference material those sessions use; each says how. Render individual sessions, or the ones before Define-XML, until then.
Ask in GitHub Discussions, with the output of renv::status() and sessionInfo(). Those two together identify almost every setup problem.
If you are confident it is a fault in the course rather than in your machine, open an issue instead.