---
title: "Chapter 00: Introduction"
output:
  rmarkdown::html_vignette:
    toc: true
    number_sections: true
bibliography: REFERENCES.bib
reference-section-title: References
vignette: >
  %\VignetteIndexEntry{Chapter 00: Introduction}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(glmbayes)
```

# Chapter 00: Introduction

This vignette introduces **glmbayes**, a package for fitting Bayesian generalized linear models via efficient envelope-based sampling. The vignette series is organized into five main parts and a set of technical appendices. You will move from basic installation and first models, through linear and generalized linear models (with optional **`bayestestR`** summaries and external **`bayesplot`** graphics), to advanced prior structures, dispersion modeling, and GPU-accelerated computation. The appendices document the underlying simulation methods and implementation details. The envelope sampling methodology builds on the likelihood subgradient framework of [@Nygren2006].

## Part 1: An Introduction

These chapters provide a high-level overview of the package, its design philosophy, conjugate Bayesian building blocks for single parameters, and the basic workflow for fitting Bayesian linear and generalized linear models.

- **Chapter 00 - Introduction**  
  Overview of the vignette structure, major modeling capabilities, and how the different parts fit together.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-00.html>

- **Chapter 01 - Getting Started with glmbayes**  
  Install and load `glmbayes`, fit your first Bayesian GLM using `glmb()`, and interpret posterior summaries (means, credible intervals) via an interface that mirrors base `glm()`.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-01.html>

- **Chapter 02 — Conjugate inference for single parameters** (series)  
  Conceptual introduction and worked conjugate updates before multivariate regression with `lmb()` and `glmb()`:
  - **Chapter 02-S01** — Introduction and overview  
    <https://knygren.r-universe.dev/articles/glmbayes/Chapter-02-S01.html>
  - **Chapter 02-S02** — Normal–Normal conjugacy for one mean  
    <https://knygren.r-universe.dev/articles/glmbayes/Chapter-02-S02.html>
  - **Chapter 02-S03** — Beta–Binomial conjugacy for one proportion  
    <https://knygren.r-universe.dev/articles/glmbayes/Chapter-02-S03.html>
  - **Chapter 02-S04** — Gamma–Poisson conjugacy for one count rate  
    <https://knygren.r-universe.dev/articles/glmbayes/Chapter-02-S04.html>
  - **Chapter 02-S05** — Gamma–Gamma conjugacy for one response rate  
    <https://knygren.r-universe.dev/articles/glmbayes/Chapter-02-S05.html>

## Part 2: Bayesian regression models

This part focuses on Bayesian **linear** regression (Gaussian family, identity link): model fitting with `lmb()`, tailoring priors via `Prior_Setup()`, and tools for predictions, posterior predictive checks (optional **bayesplot**; see **`legacy_code/`**), deviance residuals, and model comparison.

- **Chapter 03 — Estimating Bayesian linear models**  
  Work with the Gaussian identity-link case using `lmb()`. Draw from the multivariate normal posterior, compare Bayesian estimates to classical least squares, and explore shrinkage behavior.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-03.html>

- **Chapter 04 — Tailoring priors — leveraging the Prior_Setup function**  
  Construct multivariate normal priors via `Prior_Setup()`. Specify prior mean vectors and covariance matrices, and study how these hyperparameters influence posterior inference and regularization.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-04.html>

- **Chapter 05 — Model predictions and posterior predictive checks**  
  Generate fitted values and posterior predictive draws; optional **bayesplot** `ppc_*` examples are commented out (see **`legacy_code/pp_check.glmb.R`**).  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-05.html>

- **Chapter 06 — Deviance residuals, model statistics and posterior inference (+ bayestestR)**  
  Compute deviance residuals, review model-fit summaries (e.g. deviance-based measures, DIC comparisons), and relate discussion to **bayestestR**-style posterior summaries where relevant.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-06.html>

## Part 3: Generalized Linear Models

This part presents Bayesian GLMs across the major likelihood families, including Binomial, quasi-Binomial, Poisson, quasi-Poisson, and Gamma models. It emphasizes link functions, log-concavity, and practical posterior interpretation, then shows how to **summarize** posterior distributions with **bayestestR** and optionally **visualize** fits with **bayesplot** (install separately; Chapter 12 code is commented out).

- **Chapter 07 — Foundations of GLMs — families, links, and log-concave likelihoods**  
  Review exponential-family GLMs, canonical and non-canonical link functions, and the log-concave likelihood property that enables envelope-based accept-reject sampling.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-07.html>

- **Chapter 08 — Estimating Bayesian generalized linear models**  
  Move beyond Gaussian models and fit Binomial, Poisson, and Gamma GLMs with `glmb()`. See how the envelope engine adapts to each family and compare posterior summaries under different links.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-08.html>

- **Chapter 09 — Models for the Binomial family**  
  Work with logistic and probit regressions. Handle binomial outcomes, specify informative priors, and interpret posterior distributions for classification and proportion-type data.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-09.html>

- **Chapter 10 — Models for the Poisson family**  
  Fit count models with a log link. Explore overdispersion diagnostics, zero-inflation checks, and the impact of prior choice on rate parameters.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-10.html>

- **Chapter 11 — Models for the Gamma family**  
  Model positive continuous outcomes using Gamma regression. Combine regression and dispersion modeling, and interpret overdispersion in applications such as insurance claims or reaction-time data.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-11.html>

- **Chapter 12 — Visualizing posteriors with bayesplot (optional)**  
  Prepares `glmb` draws and replicated responses; **bayesplot** plotting examples are commented out in the source unless you install **bayesplot** from CRAN and restore those blocks.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-12.html>

- **Chapter 13 — Bayesian inference and decision making with bayestestR**  
  Summarize posterior samples with **bayestestR** utilities (e.g. central tendency, credible intervals, region of practical equivalence) applied to coefficient draws from **`glmb()`** fits.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-13.html>

## Part 4: Advanced Topics

These chapters explore more complex modeling scenarios and computational strategies, including informative priors, unknown dispersion parameters, linear and generalized linear mixed-effects (hierarchical) models, and GPU-accelerated envelope construction.

- **Chapter 14 — Informative priors — centering and differential prior weights**  
  Construct more flexible priors by centering on domain-specific values and assigning variable-specific scales. Examine how differential prior weights influence shrinkage and interpretability.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-14.html>

- **Chapter 15 — Estimating models with unknown dispersion parameters**  
  Extend envelope-based methods to models with unknown dispersion (e.g., Gamma and quasi-families). Use dedicated dispersion samplers to obtain joint posterior draws and quantify overdispersion uncertainty.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-15.html>

- **Chapter 16 — Large models: GPU acceleration using OpenCL**  
  Scale Bayesian GLMs to higher-dimensional settings by offloading key computations to the GPU. Configure OpenCL, tune envelope construction for large models, and benchmark performance gains.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-16.html>

- **Chapter 17 — Linear mixed-effects models**  
  Fit hierarchical (random effects) linear models using block Gibbs sampling with `rlmb`. Covers dispersion-and-coefficients sampling (e.g., Dobson plant weight) and the Eight Schools example with conjugate and non-conjugate priors.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-17.html>

- **Chapter 18 — Generalized linear mixed-effects models**  
  Extend mixed-effects modeling to non-Gaussian families. Implements a two-block Gibbs sampler for Poisson regression with observation-level random effects using the BikeSharing dataset and `rglmb`.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-18.html>

## Part 5: Simulation Methods and Technical Implementation

The appendices document the mathematical and algorithmic foundations of the samplers used in **glmbayes**, including likelihood subgradient methods, envelope construction, and accept-reject schemes for both regression and dispersion parameters.

- **Chapter A01: A detailed overview of the glmbayes package**  
  Present the mathematical foundations behind each sampler, including derivations of the posterior, the structure of enveloping functions, and bounds on expected draws per acceptance.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-A01.html>

- **Chapter A02: Overview of Estimation Procedures**  
  Present the mathematical foundations behind each sampler, including derivations of the posterior, the structure of enveloping functions, and bounds on expected draws per acceptance. 
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-A02.html>

- **Chapter A03 - Methods Available in glmbayes**  
  Summarize the key functions, samplers, and diagnostics implemented in the package, with a focus on how they relate to the underlying estimation framework.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-A03.html>

- **Chapter A04 - Directional Tail Diagnostics for Prior-Posterior Disagreement**  
  Document the directional tail diagnostic, its theoretical interpretation as a Bayesian analogue to t- and F-style evidence, scalar and multivariate decompositions, and its use in summary output.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-A04.html>

- **Chapter A05: Simulation Methods - Likelihood Subgradient Densities**  
  Detail the likelihood-subgradient approach for non-Gaussian families. Show how subgradients define tangent envelopes and explain why this yields valid accept-reject sampling for log-concave likelihoods.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-A05.html>

- **Chapter A06 - Accept-Reject Sampling for Dispersion in Gamma Regression**  
  Describe the specialized accept-reject scheme for dispersion parameters in Gamma regression, including envelope design, proposal choices, and efficiency considerations.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-A06.html>

- **Chapter A07 - Accept-Reject Sampling for Gaussian Regression Models with Independent Normal-Gamma Priors**  
  Detail the accept-reject-based approach for Gaussian regression with independent normal-gamma priors, including the structure of the joint prior, conditional distributions, and sampler efficiency.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-A07.html>

- **Chapter A08 - Overview of Envelope Related Functions**  
  Provide a central overview of the envelope-related functions. Consolidate the theoretical foundations, function map, and workflow for users and developers.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-A08.html>

- **Chapter A09 - Parallel Sampling Implementation using RcppParallel**  
  Describe the parallel sampling implementation, pilot logic, and interactive safeguards.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-A09.html>

- **Chapter A10 - Accelerated EnvelopeBuild Implementation using OpenCL**  
  Document the OpenCL implementation for accelerating envelope construction on the GPU.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-A10.html>

- **Chapter A11 - Implementation Companion for Independent Normal-Gamma**  
  Document the implementation workflow for independent Normal-Gamma sampling, with a deep dive into `rIndepNormalGammaReg`, `EnvelopeOrchestrator`, `EnvelopeDispersionBuild`, and the standardized accept-reject sampler.  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-A11.html>

- **Chapter A12 - Technical Derivations for Priors Returned by `Prior_Setup()`**  
  Full mathematical derivations for Gaussian calibration, Normal--Gamma and independent Normal--Gamma prior pieces, and the objects returned by `Prior_Setup()` (including `compute_gaussian_prior`).  
  <https://knygren.r-universe.dev/articles/glmbayes/Chapter-A12.html>

## Companion textbooks

Several vignettes include optional **appendices** that reproduce examples from [@JohnsonLauEtAl2022] using **glmbayes** syntax (`lmb()`, `glmb()`, `Prior_Setup()`, `dNormal()`).  Those appendices require the suggested package **`bayesrules`** (for data only); the main chapter body knits without it.  Posterior **comparison tables** use coefficient summaries **printed in the book** (not live `rstanarm` fits).

| glmbayes vignette | Main teaching example | Bayes Rules! book | Appendix |
|-------------------|----------------------|-------------------|----------|
| **Chapter 02-S04** | Gamma–Poisson conjugacy (daily counts) | Ch. 12 (conjugate illustration) | **Appendix A** — Albert / `LearnBayes` heart transplants |
| **Chapter 03** | Dobson plant weight (`lmb`) | **Ch. 9** — `bikes`, `rides ~ temp_feel` | **Appendix A** |
| **Chapter 08** | Menarche (`glmb`, prior construction) | **Ch. 13** — `weather_perth`, logistic priors | **Appendix A** |
| **Chapter 09** | Menarche (logit / probit / cloglog) | **Ch. 13** — `weather_perth`, `raintomorrow ~ humidity9am` | **Appendix A** |
| **Chapter 10** | Dobson randomized controlled trial (RCT) Poisson counts | **Ch. 12** — `equality_index`, `laws ~ percent_urban + historical` | **Appendix A** |
| **Chapter 11** | `carinsca` Gamma regression | *(no full Gamma-regression chapter)* | **Appendix A** — scope note + Ch. 02-S05 pointer |

**Priors.**  Use **informative** Bayes Rules! priors only where the book is **fully** informative on the coefficients you fit (e.g. Ch. 9 bike ridership, Ch. 13 Perth rain).  Where the book is **only partially** informative (e.g. Ch. 12 Poisson intercept informative, slopes weak / `autoscale`), the appendix uses **`Prior_Setup()`** defaults for **`glmb()`** / **`lmb()`**.  Encode fully informative book beliefs on the **link scale** as `dNormal(mu, Sigma)`; fixed dispersion at the MLE where the main chapter does (see Chapters 03, 08, 11).

**Other texts.**  Chapter 01 and Chapter 03 §6.1 map sections to @Agresti2015.  Chapter 02-S04 Appendix A maps to @Albert2009 / `LearnBayes`.  Additional textbook appendices may be added in the same pattern.

---

Together, these chapters and appendices form a coherent progression: from basic usage and model specification, through applied Bayesian GLMs, to the mathematical and computational details that underlie the envelope-based samplers and GPU-accelerated implementations in **glmbayes**.
