{cards} and {cardx} — Interactive R Tutorial

Hands-on learnr tutorial covering {cards} and {cardx} R packages — from basic continuous/categorical summaries to regression modeling with {broom} and {parameters}, with live exercises on real pharmaverse datasets.

A ten-chapter interactive course that takes a clinical R programmer from "what is Analysis Results Data (ARD)?" all the way to writing custom statistics, handling model tidying, exporting MS Word deliverables, and mapping flat ARD records directly to the CDISC ARS JSON schema.

Every chapter mixes narrative theory with runnable code exercises (graded with {gradethis}) and knowledge-check quizzes. All exercises use real pharmaverse ADaM datasets (adsl, adtte) and a sample ARD JSON file (data/adsl_demog_ard.json).

---

Who This Is For

• Clinical R programmers who want to learn the standard pharmaverse packages for generating Analysis Results Data (ARD).
• Lead programmers and statisticians preparing for ARS-conformant submissions and standardized reporting workflows.
• R package authors building downstream reporting tools (like {gtsummary} or {rtables}) that consume statistical outputs.

---

Chapter Overview

#	Chapter	What you learn / build
01	Intro to ARD and {cards}	The concept of Analysis Results Data (ARD); unrounded raw values vs formatted values; standard ARD schema.
02	Core {cards} Operations	Generating statistics for continuous, categorical, and dichotomous variables, plus denominators (N) and missingness.
03	Stacking and Formatting	Combining multiple ARD tables using bind_ard() or ard_stack(); resolving duplicate rows; applying custom decimal formatting.
04	Extended Stats with {cardx}	Generating ARDs for hypothesis tests (t-tests, Fisher's exact, CMH) and Kaplan-Meier survival analysis.
05	Models, {broom}, and {parameters}	Slicing complex R model objects; the roles of {broom} and {parameters}; generating regression ARDs with ard_regression().
06	Consuming ARD	Passing pre-calculated ARDs to downstream rendering tools like {gtsummary} (tbl_ard_summary()) and {rtables}.
07	Exporting and MS Word Styling	Bridging gtsummary to MS Word using flextable and officer; managing clinical page layouts, margins, and headers.
08	Advanced Workflows	Implementing custom statistics (geometric mean/CV); mapping flat ARD columns directly to CDISC ARS OperationResult structures.
09	ARD Structure Reference	Standing reference for the full ARD column layout, list-columns, and the ARD → SAS ODS output mapping.
10	Broom vs. Parameters Tidiers	Side-by-side comparison of {broom} and {parameters}; the reference-row problem; {broom.helpers} as the Rosetta Stone; overriding tidy_fun in ard_regression().

The original chapter study materials live in materials/.

---

Quick Start

1 — Install the R dependencies

Option A: Reproducible Setup with {renv} (Recommended)

This project uses {renv} to manage reproducible R package environments. To automatically initialize renv and restore all required packages (including {cards}, {cardx}, {gtsummary}, and {gradethis}) from the lockfile:

1. Open R or RStudio in the cards_tutorial folder.
2. Run the setup script:

   source("setup_renv.R")

Option B: Manual Installation

If you prefer to install packages in your user library manually:

install.packages(c(
  "learnr",           # interactive tutorial engine
  "gradethis",        # exercise grading
  "pharmaverseadam",  # ADaM datasets (ADSL, ADAE, ADTTE, etc.)
  "dplyr",            # data manipulation
  "cards",            # core ARD generation
  "cardx",            # extended ARD calculations
  "gtsummary",        # tables from ARD
  "broom",            # model tidying
  "parameters",       # model parameters
  "jsonlite",         # JSON reading/writing
  "glue",
  "survival"          # survival analysis models
))

If pharmaverseadam is not on CRAN in your region, install it from GitHub:

remotes::install_github("pharmaverse/pharmaverseadam")

2 — Run a chapter

In R:

rmarkdown::run("cards_tutorial_ch01.Rmd")

Or in RStudio: open any cards_tutorial_ch*.Rmd and click "Run Document" in the editor toolbar.

Each chapter opens in your browser as a self-contained interactive tutorial with a violet-accented sidebar, code boxes with live evaluation, hints, solutions, and quizzes.

---

Repository Structure

cards_tutorial/
├── cards_tutorial_ch01.Rmd     ← Chapter 1: Intro to ARD and cards
├── cards_tutorial_ch02.Rmd     ← Chapter 2: Core cards Operations
├── cards_tutorial_ch03.Rmd     ← Chapter 3: Stacking and Formatting
├── cards_tutorial_ch04.Rmd     ← Chapter 4: Extended Stats with cardx
├── cards_tutorial_ch05.Rmd     ← Chapter 5: Models, broom, and parameters
├── cards_tutorial_ch06.Rmd     ← Chapter 6: Consuming ARD with gtsummary
├── cards_tutorial_ch07.Rmd     ← Chapter 7: Exporting and MS Word Styling
├── cards_tutorial_ch08.Rmd     ← Chapter 8: Advanced Workflows
├── cards_tutorial_ch09.Rmd     ← Chapter 9: ARD Structure Reference
├── cards_tutorial_ch10.Rmd     ← Chapter 10: Broom vs. Parameters Tidiers
│
├── data/
│   └── adsl_demog_ard.json     ← Sample flat ARD JSON
│
├── www/
│   └── custom.css            ← White background, violet accents
│
├── materials/                  ← Study guide markdown files
│   ├── 00_README.md
│   ├── 01_Intro_to_ARD_and_Cards.md
│   ├── 02_Core_Cards_Operations.md
│   ├── 03_Stacking_and_Formatting.md
│   ├── 04_Extended_Stats_with_Cardx.md
│   ├── 05_Models_Broom_and_Parameters.md
│   ├── 06_Consuming_ARD.md
│   ├── 07_Flextable_Export.md
│   ├── 08_Advanced_Workflows.md
│   ├── 09_ARD_Structure_Reference.md
│   ├── 10_Broom_vs_Parameters_Tidiers.md
│   └── 11_Common_Custom_Functions.md
│
├── setup_renv.R                ← Renv initialization script
├── renv.lock                   ← Renv locked dependencies file
├── .gitignore
├── .Rprofile
└── README.md                   ← This documentation file

---

License

This tutorial is released under the MIT License.