--- 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. - **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()`. - **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 - **Chapter 02-S02** — Normal–Normal conjugacy for one mean - **Chapter 02-S03** — Beta–Binomial conjugacy for one proportion - **Chapter 02-S04** — Gamma–Poisson conjugacy for one count rate - **Chapter 02-S05** — Gamma–Gamma conjugacy for one response rate ## 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. - **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. - **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`**). - **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. ## 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. - **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. - **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. - **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. - **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. - **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. - **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. ## 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. - **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. - **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. - **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. - **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`. ## 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. - **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. - **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. - **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. - **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. - **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. - **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. - **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. - **Chapter A09 - Parallel Sampling Implementation using RcppParallel** Describe the parallel sampling implementation, pilot logic, and interactive safeguards. - **Chapter A10 - Accelerated EnvelopeBuild Implementation using OpenCL** Document the OpenCL implementation for accelerating envelope construction on the GPU. - **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. - **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`). ## 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**.