--- title: "blockr.stats: statistical blocks and their engine functions" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{blockr.stats: statistical blocks and their engine functions} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include = FALSE} knitr::opts_chunk$set(collapse = TRUE, comment = "#>") library(blockr.stats) ``` ## What this package is `blockr.stats` extends [blockr.core](https://github.com/blockr-org/blockr.core) with no-code statistical blocks. Every block does one thing and every block ends in the same place: a **tidy data frame** that blockr.core's generic renderers (drilldown table, coefficient plot, scatter, step curve) draw without any block-specific plotting code. There are six blocks: * **Model** -- `lm` / `glm` fitting from a formula * **Model summary** -- a fitted model rendered as a card: model facts line plus a coefficient table with an inline forest. It calls `broom::tidy()` and `broom::glance()` itself, so it needs no adapter in between, and its own value is the tidy coefficient frame * **Broom adapter** -- any fitted model to a tidy frame * **Statistical test** -- one adaptive block covering the `stats` test family * **Correlate** -- pairwise correlation matrix, rendered as a heatmap table * **Survival** -- Kaplan-Meier, Cox, competing risks, kept as a single separable cluster so it can later move to a dedicated domain package Descriptive tables (per-variable summaries, counts, crosstabs) are deliberately absent: `blockr.viz::new_summary_table_block()` already produces them for mixed types with by-group columns, and blockr.dplyr covers the rest. Every block emits **standard R** -- `stats::lm()`, `survival::survfit()`, `broom::tidy()`, and so on -- so a generated pipeline reads as ordinary code you could run without blockr loaded. ## Architecture: model objects flow, broom adapts, renderers draw The key design decision is the **renderer boundary**. Two kinds of block exist: 1. **Model-fitting blocks** (`new_model_block()`, `new_survival_block()`) emit a *fitted model object* (an `lm`, `glm`, `coxph`, `survfit`, `cuminc`). Their own preview is a generic `summary()`. 2. **Tidying blocks** -- the **model summary** (`new_model_summary_block()`) and the **broom adapter** (`new_broom_block()`) -- consume a fitted model upstream and emit a tidy data frame. The summary block also draws that frame as a card; the adapter hands it on untouched, and adds `augment()` for per-observation output. The blocks that produce a table directly (the adaptive tests, correlate) skip step 1 and emit tidy frames straight away. The result: no block carries plotting code. A coefficient plot is just the generic drilldown reading `estimate`, `conf.low`, `conf.high`; a survival curve is the generic step renderer reading `time`, `estimate`, `group`. ``` data ─▶ [model block] ─▶ fitted object ─▶ [broom adapter] ─▶ tidy df ─▶ renderer data ─▶ [test / correlate] ───────────────────────────────▶ tidy df ─▶ renderer ``` ## Regress: a model object, then the broom adapter Fit an ordinary model the normal way; the broom adapter block then emits **standard `broom` code** -- `broom::tidy()` / `glance()` / `augment()` -- to turn *any* fitted model into a tidy frame for the renderers. ```{r broom-tidy} fit <- lm(mpg ~ wt + hp, data = mtcars) broom::tidy(fit, conf.int = TRUE) ``` `output = "tidy"` is the coefficient table (with `conf.low` / `conf.high` so the generic drilldown can draw a coefficient plot). The other two outputs: ```{r broom-glance} broom::glance(fit) ``` ```{r broom-augment} head(broom::augment(fit)) ``` The block inlines a couple of conveniences into the generated expression without leaving standard R: when QQ columns are switched on, `augment` gains `.qq_theoretical` / `.qq_sample` (from `stats::qqnorm()`) so a QQ plot becomes a plain scatter; and the `tidy` frame gets model-aware column `label` attributes the renderers display. This is why a single `new_broom_block()` serves `lm`, `glm`, `aov`, Cox and competing-risks alike -- the renderer only ever sees a tidy frame. ## Advanced: survival The survival block emits **standard R** -- `survival::survfit()` / `coxph()` for Kaplan-Meier and Cox, and an inline `cmprsk::cuminc()` for competing risks. The broom adapter tidies the fitted object downstream like any other model. ```{r survival-km} lung <- survival::lung # event = 1, censor = 0; lung codes 2 = death, 1 = censor lung$dead <- lung$status - 1L km <- survival::survfit(survival::Surv(time, dead) ~ sex, data = lung) class(km) ``` `tidy()` (broom's `survfit` method) turns the curve into long `time` / `estimate` / `strata` points -- a drilldown line+step: ```{r survival-tidy} km_tidy <- broom::tidy(km) head(km_tidy[, c("time", "estimate", "n.risk", "strata")]) ``` A Cox model flows the same way -- `survival::coxph(...)` returns a `coxph`, and the broom adapter's `tidy` yields hazard ratios with CIs (a coefficient plot via the same generic renderer). Competing-risks emits `cmprsk::cuminc(...)`; broom has no method for it, so the package ships `tidy.cuminc()`, emitting long `group` / `time` / `estimate` so cumulative-incidence curves render with the same step renderer as Kaplan-Meier. ## Putting it together in a board In an interactive blockr board you would not call these functions directly. You would compose the registered blocks -- e.g. a data block, then `new_model_block()`, then `new_broom_block()`, then a generic plot block -- and blockr.core would wire the reactive graph. The functions in this vignette are the *contract*: whatever a block produces is one of the frames shown above, which is what makes a single set of generic renderers enough for the whole package. ```{r registry} # the blocks this package registers ls("package:blockr.stats", pattern = "^new_.*_block$") ```