---
title: "Core 01: Overview of the glmbayesCore package"
author: "Kjell Nygren"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Core 01: Overview of the glmbayesCore package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

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

# Core 01: Overview of the glmbayesCore package

**glmbayesCore** is the compiled sampling engine behind **glmbayes** (formula
interface: `glmb()`, `lmb()`) and the in-development **lmebayes** mixed-model
package. End users normally install **glmbayes**; this vignette orients
developers and advanced users to what lives in Core and how the engine
vignettes are numbered.

Appendix-style **`Chapter-A*`** labels belong to **glmbayes** Part 5 only.
Engine documentation here uses consecutive **`Core-01`** … **`Core-11`**
topics (see table below). Formula-centric package overview and demos:
**`vignette("Chapter-A01", package = "glmbayes")`**.

## Ecosystem

| Package | Role |
|---------|------|
| **glmbayesCore** | C++/OpenCL samplers, `pfamily`, `Prior_Setup()`, `rglmb()` / `rlmb()`, envelope pipeline |
| **glmbayes** | User-facing GLM/LM Bayesian fits, S3 methods, tutorials (Chapters 00–18, appendices A01–A12) |
| **lmebayes** *(dev)* | Mixed models: `lmerb()` / `glmerb()`. Setup layer in **glmbayesCore** (Part 4, Core-20); Gibbs engines staged in **lmebayesCore** |

## Primary R entry points

- **`Prior_Setup()`**, **`Prior_Check()`** — default and custom priors (`prior.R`).
- **`pfamily`** constructors (`dNormal`, `dNormal_Gamma`, …) — pair **`simfun`**
  and **`pfun`** for posterior and prior draws.
- **`rglmb()`**, **`rlmb()`** — matrix-input i.i.d. posterior samplers used by
  **glmbayes** and block-Gibbs extensions.
- **`glmbfamfunc()`**, **`EnvelopeBuild()`**, … — envelope construction and
  simulation pipeline (`simulationpipeline.R`, `envelopeorchestrator.R`).

Extension checklist (not yet a vignette): **`system.file("ADDING_PFAMILY.md", package = "glmbayesCore")`**.

## Vignette index by Part

The vignettes are grouped into Parts, as in **glmbayes**. Numbers are
permanent identifiers, so a Part need not use consecutive numbers.
Subsections use the `Core-NN-S0M` pattern.

**Part 1: Orientation**

| Vignette | Topic |
|----------|--------|
| **Core-01** | This overview |

**Part 2: Estimation and accept–reject sampling**

| Vignette | Topic |
|----------|--------|
| **Core-02** | Estimation architecture; simfunctions and families |
| **Core-03** | Likelihood subgradient densities; `.rNormalGLM_cpp` pipeline |
| **Core-04** | Accept–reject: Gamma dispersion |
| **Core-05** | Accept–reject: Gaussian regression, independent normal–gamma |
| **Core-09** | Implementation companion (independent normal–gamma) |
| **Core-10** | Prior derivations for **`Prior_Setup()`** |

**Part 3: Envelopes, parallel CPU, and OpenCL**

| Vignette | Topic |
|----------|--------|
| **Core-06** | Envelope-related functions (overview) |
| **Core-07** | Parallel sampling (RcppParallel) |
| **Core-08** | OpenCL-accelerated `EnvelopeBuild` |
| **Core-11** | OpenCL backend installation; large-model **`rglmb()`** |

**Part 4: Mixed-model design and priors (enabling `lmerb()`)**

| Vignette | Topic |
|----------|--------|
| **Core-20** | Overview: two-block structure, package-wide lineage chart, file map, helper naming |
| **Core-20-S01** | `model_setup()`, `check_identifiability()` |
| **Core-20-S02** | `Prior_Setup_GLMM()`: Block 1 / Block 2 prior calibration |
| **Core-20-S03** | `pfamily_list()`, `dGamma_list()` |
| **Core-20-S04** | `Prior_SetupGroup()`, `normalize_group()`, `rNormal_reg_group()`, `rNormalGLM_reg_group()` |

**Part 5: Two-block Gibbs engines** (reserved; see below)

In R after install: `browseVignettes("glmbayesCore")`,
`vignette("Core-06", package = "glmbayesCore")` for the envelope overview, or
`vignette("Core-20", package = "glmbayesCore")` for the mixed-model setup.

## Legacy map (glmbayes appendices → Core)

Historical **glmbayes** Part 5 appendix labels map to Core vignettes as follows:

| glmbayes appendix | glmbayesCore |
|-------------------|--------------|
| A02 | Core-02 |
| A05 | Core-03 |
| A06 | Core-04 |
| A07 | Core-05 |
| A08 | Core-06 |
| A09 | Core-07 |
| A10 | Core-08 |
| A11 | Core-09 |
| A12 | Core-10 |
| *(backend OpenCL install)* | Core-11 |

**glmbayes-only appendices:** A01 (package overview), A03 (methods vs `glm`),
A04 (directional tail diagnostics). User OpenCL tutorial with **`glmb()`**:
**`vignette("Chapter-16", package = "glmbayes")`**.

## Reserved numbers (future)

- **Core-12** — planned knitted guide from **`ADDING_PFAMILY.md`** (extension
  authors), Part 1.
- **Core-21–Core-24** — further Part 4 material as needed.
- **Core-25–Core-29** — Part 5, the two-block Gibbs engines (`rlmerb()`,
  `rglmerb()`, `rLMM_reg*`, `rGLMM_reg*`, `two_block_*`) once they move back
  from **lmebayesCore** (user tutorials stay in glmbayes Ch 17–18).

No placeholder `.Rmd` files are shipped for these slots; this section records intent only.