---
title: "10. Clean-room design"
output:
  rmarkdown::html_vignette:
    toc: true
bibliography: references.bib
link-citations: true
vignette: >
  %\VignetteIndexEntry{10. Clean-room design}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE, comment = "#>", message = FALSE, warning = FALSE,
  fig.width = 7, fig.height = 5.5
)
library(idiographic)
data(srl)
has_cograph <- requireNamespace("cograph", quietly = TRUE)
```

`idiographic` is designed as a clean-room implementation of common idiographic network estimators. The package exposes a uniform R interface and tidy accessors while keeping the estimands aligned with the external methods it validates against: ordinary VAR, graphical VAR, mlVAR, Bayesian/DSEM, uSEM/GIMME, rolling windows, model comparison, stability, and forecasting. This vignette documents the design logic rather than introducing a new estimator.

# Design principles

A clean-room implementation should reproduce the statistical estimand without copying an external package's internals. For `idiographic`, that means explicit lag construction, standardized accessors, shared print and plot conventions, and tests against reference behaviour where possible. The package separates temporal, contemporaneous, and between-person layers because their interpretations differ [@epskamp2018mlvar].

The accessor contract is deliberately small. `summary()` reports network-level density and signed-edge counts. `edges()` returns one row per edge. `coefs()` includes full coefficient cells when available. `nodes()` summarizes strength, out-strength, in-strength, and self-loops. `matrices()` returns the estimator matrices. This common surface makes estimator differences visible without erasing them.

# Method coverage

Ordinary VAR is the unregularized single-person baseline [@bringmann2013]. Graphical VAR adds LASSO and graphical-lasso regularization with EBIC model selection. mlVAR estimates average within-person temporal and contemporaneous layers plus a between-person network [@epskamp2018mlvar]. Bayesian VAR and DSEM add posterior uncertainty and Mplus-oriented dynamic SEM links. uSEM and GIMME use SEM path vocabularies, with GIMME searching for group and individual paths.

# Worked validation surface

The same `srl` input can be audited and passed to multiple estimators through a common interface.

```{r audit}
vars <- c("efficacy", "value", "planning", "monitoring", "effort")
audit <- preprocess(srl, vars = vars, id = "name", min_obs = 100)
audit
```

The audit reports 5548 retained lagged pairs and no unit-root or zero-variance flags. Grace is used below because none of her five series receives any audit flag; the selection is based on the input diagnostics, not on which fitted network looks best. This is the common preprocessing surface for the estimator vignettes.

```{r fit-two}
var_fit <- fit_var(srl, vars = vars, id = "name", subject = "Grace",
                   scale = TRUE)
gvar_fit <- fit_graphical_var(srl, vars = vars, id = "name", subject = "Grace",
                              n_lambda = 8)
summary(var_fit)
summary(gvar_fit)
```

The two summaries expose the design contrast. OLS reports full temporal and contemporaneous density with mean absolute weights 0.075 and 0.160. Graphical VAR reports zero temporal edges and three contemporaneous edges. The same accessor shape makes the regularization consequence explicit.

```{r matrices}
head(edges(var_fit), 8)
edges(gvar_fit)
```

The ordinary VAR edge table contains small lagged effects such as monitoring to later value (−0.160) and planning to later effort (0.159). The graphical VAR retains only contemporaneous monitoring–effort, efficacy–monitoring, and planning–effort edges. A temporal edge `from -> to` means `from` at occasion $t-1$ predicts `to` at occasion $t$; a contemporaneous graphical VAR edge is an undirected partial correlation.

# Validation boundaries

The package can validate deterministic estimators against external results more directly than stochastic or external-backend estimators. Bayesian estimators require Monte Carlo tolerances. Mplus-backed functions require licensed software and file-based workflows. uSEM and GIMME depend on SEM convergence and search behaviour. Stability and forecast helpers are experimental diagnostics without a single canonical reference implementation.

# Visualization

```{r plot-var, eval=has_cograph}
plot(var_fit)
```

The ordinary VAR plot shows the full two-layer network used as the transparent baseline.

```{r plot-gvar, eval=has_cograph}
plot(gvar_fit, layer = "contemporaneous")
```

The graphical VAR plot shows the sparse selected contemporaneous layer, making the clean-room regularization result visually inspectable.

# Caveats

Uniform accessors do not imply identical estimands. A GIMME prevalence edge, an mlVAR fixed effect, a graphical VAR partial correlation, and a forecast residual answer different questions. Clean-room validation should therefore be read layer by layer and estimator by estimator, with the primary literature defining the target of reproduction.

# References