What If? - Lecture Notes

Lecture notes based on https://miguelhernan.org/whatifbook

Overview

This repository serves two purposes:

1. R Package: Structured as an R package for easy installation and distribution
2. Quarto Website: Contains lecture notes, slides, and handouts in multiple formats

Installation as R Package

To install this package from GitHub:

# Install devtools if not already installed
install.packages("devtools")

# Install the win package
devtools::install_github("ucdavis/win")

The package uses renv for dependency management. After cloning the repository, restore dependencies with:

# Install renv if not already installed
install.packages("renv")

# Restore package dependencies from renv.lock
renv::restore()

Multi-Format Rendering

This Quarto website project is configured to render each chapter in multiple formats:

1. HTML Website: Traditional website layout with navigation navbar
2. RevealJS Slides Format: Presentation slides for each chapter
3. PDF Handouts: PDF documents for each chapter
4. DOCX Documents: Microsoft Word format documents for each chapter

Structure

The project uses Quarto's multi-format rendering capability with profile-based configuration:

• Default profile: website (generates HTML, RevealJS, PDF, and DOCX in _site/)
• RevealJS profile: standalone slides rendering (generates slides in _slides/)
• Handout profile: standalone PDF rendering (generates PDFs in _handouts/)

Files

• _quarto.yml: Main configuration file with shared settings and default profile
• _quarto-website.yml: Website configuration with HTML, RevealJS, PDF, and DOCX formats
• _quarto-revealjs.yml: Standalone RevealJS slides configuration
• _quarto-handout.yml: Standalone PDF handouts configuration
• index.qmd: Website homepage
• chapters/: Directory containing chapter files
• styles.css: Custom CSS for the HTML format

Rendering

Note: PDF rendering requires TinyTeX to be installed. If you don't have TinyTeX installed, you can:

• Install it with: quarto install tinytex --no-prompt
• Or skip PDF rendering by using --to html,revealjs,docx flag

To render the default website with all formats (HTML, RevealJS, PDF, and DOCX):

quarto render

This will generate in _site/ directory:

• HTML pages: index.html, chapters/01-introduction.html, etc.
• RevealJS slides: index-slides.html, chapters/01-introduction-slides.html, etc.
• PDF handouts: index-handout.pdf, chapters/01-introduction-handout.pdf, etc. (requires TinyTeX)
• DOCX documents: index.docx, chapters/01-introduction.docx, etc.

To render without PDF:

quarto render --to html,revealjs,docx

To render only slides:

QUARTO_PROFILE=revealjs quarto render

To render only PDF handouts:

QUARTO_PROFILE=handout quarto render

Chapter Structure

Each chapter uses conditional content blocks to provide format-specific content:

::: {.content-visible when-format="html"}
Detailed content for website format
:::

::: {.content-visible when-format="revealjs"}
Concise content for slides
:::

This allows the same source file to generate comprehensive HTML pages, focused presentation slides, PDF handouts, and DOCX documents.

R Package Structure

This repository is structured as a standard R package:

• DESCRIPTION: Package metadata and dependencies
• NAMESPACE: Package namespace (managed by roxygen2)
• R/: R source code files
• man/: Documentation files (generated by roxygen2)
• LICENSE: MIT license file
• .Rbuildignore: Files to exclude from package builds
• win.Rproj: RStudio project configuration with package build settings

The Quarto website components (chapters, configuration files, etc.) are excluded from the R package build via .Rbuildignore, allowing the repository to function both as a package and as a Quarto website project.

Development

When working on this repository in RStudio, the project is configured with:

• Build type: Package
• Package development tools enabled
• Code indexing for better navigation
• UTF-8 encoding
• 2 spaces for tabs (following tidyverse style)

GitHub Copilot Instructions

This repository includes comprehensive GitHub Copilot instructions in .github/copilot-instructions.md to help Copilot provide better assistance with:

• Project-specific development setup and workflows
• Quarto multi-format rendering requirements
• R package structure and conventions
• Build, test, and lint commands
• Common issues and solutions

Copilot will automatically use these instructions when working on this repository.

Building and Checking the Package

To build and check the package:

# Build the package
devtools::build()

# Check the package
devtools::check()

# Generate documentation
devtools::document()