---
title: "7. Unified SEM"
output:
  rmarkdown::html_vignette:
    toc: true
bibliography: references.bib
link-citations: true
vignette: >
  %\VignetteIndexEntry{7. Unified SEM}
  %\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)
vars <- c("efficacy", "value", "planning", "monitoring", "effort")
has_cograph <- requireNamespace("cograph", quietly = TRUE)
has_lavaan <- requireNamespace("lavaan", quietly = TRUE)
can_fit_usem <- has_lavaan && !is.na(parallel::detectCores())
```

Unified structural equation modelling (uSEM) specifies a person-specific
structural model for a single individual's multivariate time series, in which
each variable at the current occasion is regressed simultaneously on the lagged
values of all variables — its own and the others' — and on the other variables
measured at the same occasion. It is an idiographic
model, built on the premise that within-person dynamics need not match the
between-person structure of the group: every coefficient
describes how one person's process unfolds around that person's own means, not
how people differ from one another. Like the other lag-one estimators in this
package, it presumes weak stationarity — constant mean, variance, and
autocovariance across the observation window — linear lag-one dynamics, and
equally spaced occasions; to these it adds the identification requirements of a
structural model, since the within-occasion paths must be estimable for each
person, which constrains how many paths can be entertained relative to the
length of the series.

The model yields three networks over the same variables. The temporal network
is directed and within-person: an edge `from -> to` states that the person's
value of `from` at occasion $t-1$ predicts their value of `to` at occasion $t$,
holding the other lagged variables constant. The contemporaneous network
collects the within-occasion relations, and this layer is what separates uSEM
from VAR and graphical VAR: where those models summarize same-occasion
association as undirected partial correlations among residuals, uSEM resolves
each within-occasion relation into a *directed* structural path, so an edge
`from -> to` records a directed same-occasion coefficient from `from` to `to`
for that person.
What the directed paths leave unexplained is carried by the third
layer, an undirected residual-covariance network among the innovations. The
directed contemporaneous reading is warranted when theory or design implies a
within-occasion ordering among the indicators; where no ordering is defensible,
the undirected graphical-VAR contemporaneous network is the more conservative
summary. GIMME, treated in the next vignette, extends the uSEM equation with a
group-level search that recovers paths shared across people.

`fit_usem()` estimates one SEM per selected person and returns temporal,
directed contemporaneous, and residual-covariance networks. With one selected
person, as below, every coefficient is idiographic. With multiple people the
function also averages across converged fits; that average summarizes the
sample and is not any one person's model. Failed fits are reported rather than
silently included.

# Data and preprocessing

The estimator takes the same long-format panel as the other estimators: one row
per person-occasion, an id column, and numeric time-varying indicators ordered
within person. The bundled `srl` data hold self-regulated-learning indicators
for 36 students measured over 156 occasions each; this vignette fits Grace on
five indicators: `efficacy`, `value`, `planning`, `monitoring`, and `effort`.
Grace is chosen because her five series pass the input audit, not because of the
network returned later. Because uSEM is a dynamic lag-one model that absorbs assumption
violations silently — a trending series inflates its lagged coefficients rather
than producing an error — the stationarity screen precedes the fit.

```{r audit}
preprocess(srl, vars = vars, id = "name", subject = "Grace")
```

Grace's 156 rows yield 155 complete lagged pairs. None of the five series trips
the trend, high-autoregression, mean-shift, variance-shift, unit-root, or
zero-variance screen, so the series is fitted as supplied.

# Fitting the model

The substantive arguments are `time` (orders occasions within `id`), `temporal`
(`"ar"` for autoregressions only, `"all"` for candidate cross-lags),
`contemporaneous` (`"none"` or `"all"` candidate directed same-occasion paths),
and `trim`. A reciprocal all-path same-occasion model is not identified as a
final SEM. Therefore `trim = TRUE` starts from an identified base model and uses
the documented fit and significance criteria to add and prune candidate paths;
the vignette does not present the underidentified untrimmed model as a result.
The fit and all accessors below are evaluated when the suggested `lavaan`
package is installed and the build environment permits core detection. This
second guard handles restricted builders where lavaan cannot initialize its
options; no static output is substituted when execution is unavailable.

```{r fit, eval=can_fit_usem}
usem_fit <- fit_usem(srl, vars = vars, id = "name", time = "day",
                     subject = "Grace", temporal = "all",
                     contemporaneous = "all", trim = TRUE)
usem_fit
```

Grace's model converges on 155 usable lagged pairs. The search retains three
directed contemporaneous paths and no temporal or residual-covariance edges.
That zero is an executed selection result: it says no candidate temporal path
survived this uSEM search for Grace, not that the temporal layer was disabled.

# Reading the output

The `summary()` method reports one row per network layer, with the edge count,
density, and mean absolute weight.

```{r summary, eval=can_fit_usem}
summary(usem_fit)
```

The contemporaneous network has three of the 20 possible directed edges
(density 0.15) and mean absolute weight 0.409. The temporal and residual layers
have zero selected edges.

```{r edges-temporal, eval=can_fit_usem}
edges(usem_fit, network = "temporal", n = 5)
```

The empty table makes the selection outcome explicit. It should not be read as
proof of no lagged process; a different candidate set, trimming rule, or person
can give a different selected model.

```{r edges-contemp, eval=can_fit_usem}
edges(usem_fit, network = "contemporaneous", n = 5)
```

The directed contemporaneous network retains monitoring to effort (0.456),
efficacy to monitoring (0.424), and effort to planning (0.348). These arrows are
directed SEM coefficients conditional on the selected specification; causal
interpretation still requires a defensible within-occasion ordering.

```{r nodes, eval=can_fit_usem}
nodes(usem_fit)
```

Because the contemporaneous layer is directed, `nodes()` separates outgoing
from incoming weight. Monitoring has the largest total contemporaneous strength
(0.880); it receives the efficacy path and sends the effort path. The full path
and residual matrices are available from `coefs()` and `matrices()`.

```{r matrices, eval=can_fit_usem}
matrices(usem_fit)
```

# Visualizing the network

The temporal layer is already documented as empty, so the vignette does not
draw an empty showcase panel. The contemporaneous panel draws the three selected
directed paths, with edge width scaled to absolute weight and colour encoding
sign.

```{r plot-contemporaneous, eval=can_fit_usem && has_cograph}
plot(usem_fit, layer = "contemporaneous")
```

The within-occasion structure can also be drawn as a mixed network. Directed
contemporaneous paths appear as curved arrows and any residual covariances as
straight edges.

```{r plot-mixed, eval=can_fit_usem && has_cograph}
plot(usem_fit, mixed = TRUE)
```

The monitoring-to-effort arrow is the largest retained coefficient. No residual
covariance survives this search. The direction of each arrow is only as credible
as the within-occasion ordering assumption behind it,
which is the consideration that should govern the choice between uSEM and the
undirected graphical-VAR contemporaneous summary.

# References