---
title: "Introduction to statwitness"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to statwitness}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

`statwitness` creates model-aware validation certificates across computational integrity, numerical stability, design adequacy, assumption screening, and influence stability. The package changes inputs in ways that should have known consequences, refits the model, and compares the observed response with the registered expectation.

## Linear model

```{r}
library(statwitness)
dat <- transform(mtcars, transmission = factor(am))
audit <- statwitness(mpg ~ transmission + wt + hp, data = dat, focus = "transmission")
audit
```

## Mixed-effects model

The following example runs only when `lme4` is installed.

```{r, eval = requireNamespace("lme4", quietly = TRUE)}
dat <- lme4::sleepstudy
dat$criterion <- factor(rep(c("A", "B"), length.out = nrow(dat)))
dat$model <- factor(rep(c("M1", "M2"), each = 2, length.out = nrow(dat)))
dat$rater <- dat$Subject

audit <- statwitness(
  Reaction ~ criterion * model + (1 | rater),
  data = dat,
  focus = "criterion:model",
  exclude = "optimizer_agreement",
  audit_level = "core"
)
audit
```

The interaction is treated as an omnibus term. Standard mixed-model audits also inspect fixed-design conditioning, convergence, singularity, random-effect boundaries, alternative-optimizer agreement, possible omitted within-rater random slopes, residual behavior, and feasible leave-one-rater-out influence.

## Repeated-measures ANOVA

Use `statwitness_repeated()` with long-format data. It requires `afex` and applies the same audit domains with repeated-design-specific checks.

```{r, eval = FALSE}
statwitness_repeated(
  data = dataset,
  outcome = "score",
  id = "rater",
  within = c("criterion", "model"),
  focus = "criterion:model",
  audit_level = "standard"
)
```

## Scope

A passing certificate validates behavior under registered computational tests. It does not prove that the design, estimand, causal interpretation, or data-generating assumptions are scientifically correct.