---
title: "Panel graphical VAR: temporal, contemporaneous, and between-person networks"
author: "Written by [Mohammed Saqr](https://saqr.me) and [Sonsoles López-Pernas](https://sonsoles.me)"
output:
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 2
vignette: >
  %\VignetteIndexEntry{Panel graphical VAR: temporal, contemporaneous, and between-person networks}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r options, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.width = 11,
                      fig.height = 4.4, dpi = 110, out.width = "100%")
has_cograph <- requireNamespace("cograph", quietly = TRUE)
```

Panel studies measure the same people on a few occasions, for instance weekly
during a course. Two different questions can be asked of such data. The
between-person question is whether students who are generally more efficacious
also plan more. The within-person question is whether a student who feels more
efficacious than usual in one week plans more than usual, in the same week or
in the next. The answers can differ, and a cross-sectional network of the
pooled data mixes them. The panel graphical vector-autoregressive model
(panel-GVAR; Epskamp, 2020) separates each person's scores into a stable
personal level and weekly deviations from it, and estimates three networks:
a temporal network of lagged effects between the deviations, a contemporaneous
network of deviations that move together within a week, and a between-person
network of the stable levels.

This article fits the model to a four-wave panel of five self-regulated
learning indicators, reads the three networks with their uncertainty, selects
a sparser model by two methods, and evaluates the fit, the numerical solution
and the division of variance between and within persons.

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

## Data

`srl_panel` is a synthetic panel of 100 students measured in four consecutive
weeks. It was simulated from a panel-GVAR whose structure was taken from real
experience-sampling data (see `?srl_panel`), so it is realistic and can be
shared without restriction. The data are in long format, one row per student
per week.

- **Person:** `student`, the student identifier.
- **Occasion:** `week`, from 1 to 4.
- **Nodes:** five indicators on 0–100 scales: `efficacy`, `planning`,
  `effort`, `enjoyment` and `anxiety`.

```{r data}
head(srl_panel)
vars <- c("efficacy", "planning", "effort", "enjoyment", "anxiety")
```

## The model

For person $p$ at wave $t$, the vector of scores is decomposed as

$$
\mathbf{y}_{pt} = \boldsymbol\mu + \boldsymbol\eta_p + \mathbf{w}_{pt},
\qquad
\mathbf{w}_{pt} = \mathbf{B}\,\mathbf{w}_{p,t-1} + \boldsymbol\zeta_{pt},
$$

where $\boldsymbol\mu$ is the grand mean, $\boldsymbol\eta_p$ the person's
stable deviation from it, and $\mathbf{w}_{pt}$ the person's deviation from
their own level at wave $t$. The three networks are:

- **temporal:** the matrix $\mathbf{B}$ of lag-1 regression effects between
  deviations. Edges are directed; a self-loop is an autoregressive effect,
  the carry-over of a deviation to the next wave;
- **contemporaneous:** the partial correlations of the innovations
  $\boldsymbol\zeta_{pt}$, the deviations that occur together within a wave
  after the lagged effects are accounted for;
- **between-person:** the partial correlations of the stable levels
  $\boldsymbol\eta_p$.

The parameters are estimated by maximum likelihood, and each edge has a
standard error and a Wald test. The model assumes that the means do not change
across waves.

## What do the three networks show?

`panel_gvar()` takes the data with the names of the variables, the person
identifier and the wave. By default every edge is estimated and kept, and an
edge is flagged as significant at $p < 0.01$.

```{r full}
fit <- panel_gvar(srl_panel, vars = vars, id = "student", wave = "week")
fit
```

The model has 100 students in 4 waves. Of the 20 lagged effects between
variables, 1 is significant, and 4 of the 5 autoregressive effects are; 5 of
the 10 contemporaneous and 2 of the 10 between-person edges are significant.
The edge table has one row per edge, with its standard error, p-value and 95%
Wald interval:

```{r full-edges}
head(as.data.frame(fit), 8)
summary(fit)
```

`summary()` gives one row per network. The contemporaneous and between-person
edges are on average larger in absolute value (0.188 and 0.183) than the
temporal ones (0.105). `plot()` draws the three networks on one layout:
solid edges are significant, dashed edges are not, blue is positive and
vermillion negative, and the weight is printed on each edge.

```{r plot-full, eval = has_cograph}
plot(fit)
```

```{r full-numbers, include = FALSE}
edges <- as.data.frame(fit)
ar <- subset(edges, network == "temporal" & from == to & significant)
cross <- subset(edges, network == "temporal" & from != to & significant)
contemporaneous <- subset(edges, network == "contemporaneous" & significant)
between <- subset(edges, network == "between" & significant)
show <- function(d, sep) paste(sprintf("%s%s%s (%.2f)", d$from, sep, d$to,
                                       d$weight), collapse = ", ")
```

The significant edges answer the two questions separately:

- **Temporal.** `r nrow(ar)` of the 5 autoregressive effects are significant
  (`r show(ar, " -> ")`): a student who is above their own level in one week
  tends to stay above it the next. One lagged effect between variables is
  significant, `r show(cross, " -> ")`: a week of more effort than usual is
  followed by a week of higher efficacy than usual.
- **Contemporaneous.** `r nrow(contemporaneous)` edges
  (`r show(contemporaneous, "-")`): in weeks when a student's efficacy,
  planning, effort or enjoyment is above their usual level, the others tend to
  be too. Anxiety is not connected.
- **Between-person.** `r nrow(between)` edges (`r show(between, "-")`):
  `r paste(sprintf("students with a higher personal level of %s tend to have a %s personal level of %s", between$from, ifelse(between$weight > 0, "higher", "lower"), between$to), collapse = "; ")`.
  These edges rest on only 100 personal levels and carry more uncertainty than
  the within-person ones.

## Which edges should a sparser model keep?

Flagging significance leaves the model unchanged. Two methods select a sparser
model.

`select = "prune"` removes every edge with $p > 0.01$, refits, and then adds
edges back one at a time while each addition significantly improves the fit
and lowers the BIC (step-up search). The step-up stage matters because edges
can substitute for each other: an autoregressive effect and a correlated
lagged effect may each look unnecessary while the other is present, and a
single pruning pass would remove both.

```{r prune}
pruned <- panel_gvar(srl_panel, vars = vars, id = "student", wave = "week",
                     select = "prune")
pruned
```

The pruned model keeps 4 autoregressive effects, 2 lagged effects between
variables, and 5 contemporaneous and 4 between-person edges. The step-up
search re-added 3 edges that pruning had removed. The sparser model still fits
well (CFI = 0.969, RMSEA = 0.037), so the removed edges were not needed to
reproduce the data. Its edge table:

```{r prune-edges}
as.data.frame(pruned)
```

Both lagged effects lead into efficacy: a week of more effort than usual
(0.27) or more enjoyment than usual (0.18) is followed by higher efficacy than
usual. The contemporaneous edges are those of the full model, and the
between-person network gains two edges of planning, with effort (0.31) and
enjoyment (0.36), which were not significant at $p < 0.01$ in the full model
but are significant once the other between-person edges are removed.

```{r plot-prune, eval = has_cograph}
plot(pruned)
```

`select = "ebic"` instead shrinks the edges with a lasso penalty chosen by the
extended BIC, the panel counterpart of the graphical lasso. Weak edges become
exactly zero in one estimation. The estimates are penalized and therefore have
no p-values; `refit = TRUE` refits the selected network without the penalty. A
path of 20 penalty values keeps the example short.

```{r ebic}
lasso <- panel_gvar(srl_panel, vars = vars, id = "student", wave = "week",
                    select = "ebic", nlambda = 20)
summary(lasso)
as.data.frame(lasso)
```

The lasso keeps the same two lagged effects into efficacy and the same five
contemporaneous edges as pruning, and no between-person edge. It also keeps
all five autoregressive effects, two of them close to zero (anxiety 0.011,
efficacy 0.019). The two methods therefore agree on the within-person
structure. With 100 students, the penalty
is more conservative than significance-based selection for the between-person
network.

## How well does the model fit?

The fit indices compare the model with the saturated model, which reproduces
the observed covariances exactly, and with a baseline without temporal or
network structure.

```{r fit-indices}
as.data.frame(fit, what = "fit")
```

The chi-square test rejects exact fit ($\chi^2(170) = 207.19$, $p = 0.027$),
as is common for a sample of this size, but the approximate indices show good
fit: CFI = 0.957, TLI = 0.946 and RMSEA = 0.047. The model reproduces the
covariances across the four waves well.

## Is the estimate the maximum-likelihood solution?

The likelihood of the panel-GVAR is not convex, so the optimizer is started
from three different points. At a maximum the gradient of the log-likelihood
(the score) is zero; the largest remaining score is the certificate, and a
value near zero shows that the estimate is a maximum. The diagnostics also
report whether any parameter lies on the boundary of its admissible range,
whether standard errors could be computed, and how many starts reached the
same optimum.

```{r diagnostics}
as.data.frame(fit, what = "diagnostics")
```

The largest score is below $10^{-11}$, no parameter is on a boundary, standard
errors are available, and all three starts reached the same optimum. The
estimate is therefore the maximum-likelihood solution, and its standard errors
can be used.

## How much of each variable is stable between persons?

The variance of each variable is divided into the variance of the personal
levels (between) and of the weekly deviations (within).

```{r variance}
as.data.frame(fit, what = "variance")
```

Between 45% (enjoyment) and 62% (anxiety) of the variance lies between
students. About half of the variation in each indicator is a stable difference
between students and half a fluctuation from week to week, so both the
between-person and the within-person networks describe a substantial part of
the data.

## What if the wave means drift?

The model assumes that the mean of each variable is the same in every wave. If
the means drift, for instance a steady decline over a term,
`standardize = "z_per_wave"` standardizes every variable within every wave,
which removes the drift; the edges are then on a standardized scale.

```{r standardize}
z_fit <- panel_gvar(srl_panel, vars = vars, id = "student", wave = "week",
                    standardize = "z_per_wave")
subset(as.data.frame(z_fit, what = "fit"), select = c(chisq, df, cfi, rmsea))
```

On these data, which were simulated with stable means, standardizing within
waves gives a similar and slightly better fit (CFI = 0.985, RMSEA = 0.027).
On data with drifting means the difference would be larger, and the
standardized model would be the one to report.

## Assumptions and when to use the panel-GVAR

- The model is for panel data with a few waves, measured at equal intervals,
  on many persons. For long time series of one or a few persons, intensive
  longitudinal models such as the graphical VAR or the multilevel VAR apply.
- The means are stable across waves, and the lagged effects are the same at
  every wave; `standardize = "z_per_wave"` handles drifting means.
- With few waves, the between-person and within-person parts are separated
  only approximately, and the between-person edges rest on the number of
  persons, not of observations. Fits with three waves often reach a boundary,
  which is reported in the diagnostics.
- The full model reports every edge with its uncertainty. Pruning with
  step-up gives a sparse model with p-values; the lasso gives a sparse model
  without them.
- Temporal edges are lagged predictions within persons, not causal effects.

## Reference

Epskamp, S. (2020). Psychometric network models from time-series and panel
data. *Psychometrika*, 85(1), 206-231.
[doi:10.1007/s11336-020-09697-3](https://doi.org/10.1007/s11336-020-09697-3)
