---
title: "Dyad-Individual Model"
author: "Pascal Küng"
description: >
  Construction and interpretation of DIM predictors, including their
  relationship to APIM effects in dyadic multilevel models for exchangeable
  dyads.
bibliography: references.bib
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Dyad-Individual Model}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

diagram_helper <- if (file.exists("diagram-helpers.Rinc")) {
  "diagram-helpers.Rinc"
} else {
  file.path("vignettes", "diagram-helpers.Rinc")
}
sys.source(diagram_helper, envir = knitr::knit_global())

dim_grid_helper <- if (file.exists("dim-grid.Rinc")) {
  "dim-grid.Rinc"
} else {
  file.path("vignettes", "dim-grid.Rinc")
}
sys.source(dim_grid_helper, envir = knitr::knit_global())

diagram_device <- .vignette_diagram_device()
knitr::opts_chunk$set(dev = diagram_device, fig.ext = diagram_device)
```

```{r setup}
library(dyadMLM)
has_glmmTMB <- requireNamespace("glmmTMB", quietly = TRUE)
has_htmltools <- requireNamespace("htmltools", quietly = TRUE)
dim_fitted_alt <- "Fitted DIM diagram unavailable."
```

This vignette focuses on the Dyad-Individual Model (DIM) for dyadic multilevel
models and its relationship to the exchangeable Actor-Partner Interdependence
Model (APIM). The DIM separates a predictor into the dyad's shared level and
each member's deviation from that level. While the APIM expresses effects in
terms of two interdependent individuals, the DIM expresses them in terms of the
dyad's shared level and the contrast between partners.

Under exchangeability constraints, the reduced, label-invariant DSM is also
equivalent to the DIM, as discussed below. For the broader package workflow and
an overview of the available model-specific vignettes, including the
[Actor-Partner Interdependence Model](apim.html) and
[Dyadic Score Model](dsm.html), see the
[online package overview](https://pascal-kueng.github.io/dyadMLM/).

## Cross-Sectional Gaussian DIM

The current DIM implementation needs one exchangeable dyad composition.
Exchangeability means that swapping the two member labels does not
change the model [@kenny2006dyadic]. Whether roles can and should be treated as
exchangeable is a substantive assumption (see [Testing distinguishability in the APIM vignette](apim.html#testing-distinguishability)).

Here, we retain the female-female dyads with `keep_compositions`. Because both
members have the same role, this gives us one genuinely exchangeable dyad
composition. Omitting `role` is another option when all dyads should be treated
as one exchangeable composition. Refer to the
[Getting Started vignette](getting-started.html) for how to retain, pool, and
constrain dyad compositions.

```{r prepare-cross-exchangeable}
cross_exchangeable_data <- dyadMLM::prepare_dyad_data(
  dyads_cross,
  dyad = coupleID,
  member = personID,
  role = gender,
  predictors = provided_support,
  # Create both APIM and DIM columns for comparison.
  model_types = c("apim", "dim"),
  # All three observed compositions in `dyads_cross` are detected and retained by
  # default. This example focuses on `female-female` dyads, so we restrict the
  # analysis here.
  keep_compositions = "female-female",
  seed = 123
)

# Print the first two dyads.
print(cross_exchangeable_data, n = 4)
```

For the exchangeable random-effects specification,
`dyadMLM::prepare_dyad_data()` creates a member-difference contrast `.dy_member_contrast_*`,
coded as `+1` for one partner and `-1` for the other. Because these member labels
are arbitrary, setting `seed` makes their assignment reproducible.

### Example DIM Model

For member \(i \in \{1, 2\}\) of dyad \(j\), define the dyad mean and
within-dyad member deviation as:

$$
\bar{x}_j = \frac{x_{1j} + x_{2j}}{2}, \qquad
x_{\mathrm{dev},ij} = x_{ij} - \bar{x}_j.
$$

The model uses $\bar{x}_j-\mu_x$, the grand-mean-centered dyad mean.

The deviations of the two partners have equal magnitude and opposite signs:
\(x_{\mathrm{dev},1j} = -x_{\mathrm{dev},2j}\). Outcome means and deviations
are defined analogously. The variables that enter the DIM fixed effects then
separate two associations:

1. The **between-dyad effect**, $b_{\mathrm{mean}}$: whether dyads with a
   higher dyad mean than other dyads also have a higher outcome mean.
2. The **within-dyad effect**, $b_{\mathrm{dev}}$: whether the member who is
   above the dyad's predictor mean is also above the dyad's outcome mean. With
   two members, each deviation is half the corresponding signed partner difference.

The dyad mean varies between dyads, whereas member deviations vary within a
dyad. Accordingly, the upper path is the between-dyad effect and the lower path
is the within-dyad effect.
Switching members reverses both deviations and therefore leaves the pooled
$b_{\mathrm{dev}}$ unchanged.

```{r conceptual-dim-diagram, echo=FALSE, fig.width=9, fig.height=4.8, out.width="100%", fig.cap="Cross-sectional DIM. The dyad mean has a between-dyad effect, and the within-dyad member deviation has a within-dyad effect. Mean and deviation residuals are uncorrelated under exchangeability. Both members' residuals and their correlation can be obtained from these residuals.", fig.alt="Path diagram for a cross-sectional Dyad-Individual Model. The grand-mean-centered dyad mean predicts the outcome mean through the between-dyad effect b mean. Member i's within-dyad member deviation predicts the same member's outcome deviation through the within-dyad effect b dev. There are no cross-paths, and only the outcome-mean equation has intercept b zero."}
draw_dim_diagram()
```

Uncorrelated $r_{\mathrm{m}}$ and $r_{\mathrm{d},i}$ in the conceptual representation do not imply
that the member residuals are independent: the two component variances together
determine the covariance between the members' residuals.

The second diagram translates the same decomposition to the individual-member
rows used by the long-format multilevel model. Each member's outcome is predicted
by the dyad mean and that member's own within-dyad member deviation. Both members
share the same two coefficients, so estimation pools information across members
under the exchangeability assumptions.

```{r conceptual-dim-member-diagram, echo=FALSE, fig.width=9, fig.height=5.2, out.width="100%", fig.cap="Individual-level representation of the cross-sectional DIM used for the long-format multilevel model.", fig.alt="Path diagram for two arbitrarily labelled members of an exchangeable dyad. For each member, the grand-mean-centered dyad mean and the member's own within-dyad member deviation predict the individual outcome. Both members share the same between-dyad and within-dyad coefficients and residual standard deviation, while their outcome residuals are correlated."}
draw_dim_member_diagram()
```

The resulting estimated fixed effects are a reparameterization of the APIM actor
and partner effects [@Bolger2025Unified]. And just like the exchangeable APIM,
the random-effects structure comprises a dyad-level intercept
and a dyad-level difference contrast indexed by `.dy_member_contrast_female_x_female_arbitrary`.
In `glmmTMB`, with `dispformula = ~ 0`, these random effects represent the two
members' Gaussian residual variance and covariance.

The intercept and difference contrast are specified as separate random-effects
terms. No additional correlation is needed because the two residual variances already
determine the partners' residual correlation. Under exchangeability, the
mean-deviation residual correlation is therefore fixed to zero
[@delrosarioPracticalGuideSpecifying2025].

The full model can be estimated as:

```{r fit-cross-dim, eval=has_glmmTMB}

dim_1 <- glmmTMB::glmmTMB(
  closeness ~

    # Pooled fixed intercept
    1 +

    # Between-dyad effect
    .dy_provided_support_dyad_mean_gmc +

    # Within-dyad effect
    .dy_provided_support_within_dyad_dev +

    # Residual Gaussian covariance structure
    us(1 | coupleID) +
    us(0 + .dy_member_contrast_female_x_female_arbitrary | coupleID)
  , dispformula = ~ 0
  , family = gaussian()
  , data = cross_exchangeable_data
)

summary(dim_1)
```

The same mean-and-deviation diagram can now be labelled with the estimated
fixed effects and residual-component standard deviations:

```{r prepare-fitted-dim-diagram, include=FALSE, eval=has_glmmTMB}
dim_diagram_values <- .extract_dim_diagram_values(dim_1)
dim_diagram_estimates <- dim_diagram_values$estimates
dim_diagram_residuals <- dim_diagram_values$residuals

dim_fitted_alt <- sprintf(
  paste(
    "Fitted DIM. Intercept %.2f, between-dyad effect %.2f, within-dyad",
    "effect %.2f, and mean/deviation residual SDs %.2f and %.2f; their",
    "correlation is fixed at zero."
  ),
  dim_diagram_estimates[["b0"]],
  dim_diagram_estimates[["b_mean"]],
  dim_diagram_estimates[["b_dev"]],
  dim_diagram_residuals[["sd_mean"]],
  dim_diagram_residuals[["sd_difference"]]
)
```

```{r fitted-dim-diagram, echo=FALSE, eval=has_glmmTMB, fig.width=9, fig.height=4.8, out.width="100%", fig.cap="Estimated fixed effects and residual-component standard deviations from the cross-sectional Gaussian DIM in its mean-and-deviation representation. The intercept belongs to the outcome-mean equation.", fig.alt=dim_fitted_alt}
draw_dim_diagram(
  model = dim_1,
  effect_unit = "dyad",
  labels = c(predictor = "provided support", outcome = "closeness")
)
```

Under these exchangeability constraints, the Gaussian DIM is algebraically
equivalent to the reduced, label-invariant Dyadic Score Model (DSM)
[@iidaModelsInterdependentIndividuals2018]. Compared to a full DSM, the DIM's
exchangeability constraints fix the outcome-deviation intercept and both
cross-paths to zero and constrain the mean and deviation residual components to
be uncorrelated (see the diagrams here and compare them with the
[conceptual DSM diagrams](dsm.html#cross-sectional-gaussian-dsm)).

### Model interpretation

Therefore, each coefficient has both an individual-member interpretation and an
equivalent dyad mean/difference interpretation.

In this Gaussian model, fixed coefficients are
interpreted in units of the outcome, here closeness:

- The intercept (about 5.95) is the expected closeness of either member,
  and therefore the expected couple-average closeness, when both members'
  provided support equals the sample grand mean.

- The between-dyad effect estimate (about 1.55) means that, comparing couples with the
  same support difference between partners, a one-point higher
  couple-average provided-support level is associated with a 1.55-point higher
  expected couple-average closeness. Equivalently, each member's expected
  closeness is 1.55 points higher.

- The within-dyad effect estimate (about 0.90) means that a one-point difference
  in provided support between partners is associated with a 0.90-point difference
  in their expected closeness, holding their average support constant.
  In member terms, suppose one member is 0.5 points above the dyad
  mean and the other is 0.5 points below it. Their expected closeness is then
  about 0.45 points above and below the couple's predicted mean, respectively,
  so they are expected to differ by 0.90 points in closeness.

Because the Gaussian DIM is the exchangeability-constrained version of the full
DSM, exchangeability can also be tested by comparing these nested models. This
is equivalent to the comparison shown in [Testing distinguishability in the APIM vignette](apim.html#testing-distinguishability).

### Demonstrating model equivalence to APIM

The same model can be written in APIM form. Since we have requested both sets of
variables from `dyadMLM::prepare_dyad_data()`, we can fit one directly. For more
guidance on APIM specifications and different models, see the
[Actor-Partner Interdependence Model vignette](apim.html).

```{r fit-cross-apim, eval = has_glmmTMB}

apim_1 <- glmmTMB::glmmTMB(
  closeness ~ 1 +

    # Fixed effects APIM
    .dy_provided_support_actor + .dy_provided_support_partner +

    # Since both models are equivalent, the same random-effects structure
    # can be used. See the APIM vignette to learn how to back-transform
    # these blocks to a full actor-partner covariance matrix.
    us(1 | coupleID) +
    us(0 + .dy_member_contrast_female_x_female_arbitrary | coupleID)
  , dispformula = ~ 0
  , family = gaussian()
  , data = cross_exchangeable_data
)

```

The two models have identical fit statistics:

```{r compare-cross-fit, eval=has_glmmTMB}
data.frame(
  model = c("DIM", "APIM"),
  AIC = c(AIC(dim_1), AIC(apim_1)),
  BIC = c(BIC(dim_1), BIC(apim_1)),
  logLik = c(as.numeric(logLik(dim_1)), as.numeric(logLik(apim_1)))
)
```

This demonstrates that the same statistical model is being estimated with different
parameterizations and coefficient interpretations.

Once APIM estimates are present, one can easily obtain DIM estimates, and
the other way around. Let $b_{\mathrm{actor}}$ and $b_{\mathrm{partner}}$
denote the APIM actor and partner slopes, and let $b_{\mathrm{mean}}$ and
$b_{\mathrm{dev}}$ denote the DIM between-dyad and within-dyad slopes.
They relate as follows:

$$
b_{\mathrm{mean}} = b_{\mathrm{actor}} + b_{\mathrm{partner}}
$$

and

$$
b_{\mathrm{dev}} = b_{\mathrm{actor}} - b_{\mathrm{partner}}
$$

Conversely:

$$
b_{\mathrm{actor}}
= \frac{b_{\mathrm{mean}} + b_{\mathrm{dev}}}{2}
$$

and

$$
b_{\mathrm{partner}}
= \frac{b_{\mathrm{mean}} - b_{\mathrm{dev}}}{2}
$$


In this example we can see that the transformations work:

```{r compare-cross-coefficients, echo = TRUE, eval = has_glmmTMB}
apim_coef <- glmmTMB::fixef(apim_1)$cond
dim_coef <- glmmTMB::fixef(dim_1)$cond

b_actor <- apim_coef[[".dy_provided_support_actor"]]
b_partner <- apim_coef[[".dy_provided_support_partner"]]

b_mean <- dim_coef[[".dy_provided_support_dyad_mean_gmc"]]
b_dev <- dim_coef[[".dy_provided_support_within_dyad_dev"]]


cat("From APIM model:\n",
     "  actor effect:                  ", round(b_actor, 3), "\n",
     "  partner effect:                ", round(b_partner, 3), "\n\n",

     "DIM transformation:\n",
     "  b_mean = b_actor + b_partner:  ", round(b_actor + b_partner, 3), "\n",
     "  b_dev = b_actor - b_partner:   ", round(b_actor - b_partner, 3), "\n\n",

     "From DIM model:\n",
     "  between-dyad effect:           ", round(b_mean, 3), "\n",
     "  within-dyad effect:            ", round(b_dev, 3), "\n"
)

```

The DIM and APIM intercepts are not expected to be equal because the DIM dyad
mean is grand-mean centered, whereas the APIM predictors retain their original
scale.


### Why Are These Models Equivalent? Exploring the Reparameterization

An intuitive way to think about this is:

- When the dyad mean goes up by 1 unit while the difference between partners
  remains stable, both partners' values must go up by 1. Both the actor and
  partner effects therefore contribute, which is why the between-dyad effect is
  the actor effect + the partner effect.

- When a person's deviation from the dyad mean goes up by 1 unit while the dyad
  mean remains constant, the other partner's value must go **down** by 1 unit.
  The actor value therefore changes by +1 and the partner value by -1, which is
  why the within-dyad effect is the actor effect - the partner effect.

The grid below shows the same predictor values in both coordinate systems. The
horizontal and vertical axes are actor and partner values centered at the
sample grand mean. The diagonal axes are their dyad mean and within-dyad member
deviation.

The displayed actor and partner slopes are read from the fitted APIM. The DIM
slopes are their exact sum-and-difference transformation; the directly fitted
DIM estimates above confirm the equivalence. Both forms therefore make the same
change in the linear predictor relative to the grand-mean reference. The
intercept is omitted from both displayed equations.

```{r interactive-dim-grid, echo=FALSE, eval=has_htmltools}
dim_reparameterization_grid(
  if (has_glmmTMB && exists("apim_1")) apim_1 else NULL,
  predictor_label = "Provided support",
  outcome_label = "the linear predictor",
  limit = 5
)
```

### Random-effect transformation

The DIM and APIM models above already use the same sum-and-difference
random-effects parameterization [@delrosarioPracticalGuideSpecifying2025]. See
the [exchangeable residual-structure section of the APIM vignette](apim.html#exchangeable-residual-structure)
for the derivation and back-transformation to the member-level covariance matrix.

## Intensive Longitudinal DIM

For longitudinal DIM, predictors are decomposed into within-person and
between-person components before the dyadic decomposition
[@bolgerIntensiveLongitudinalMethods2013;
@gistelinckMultilevelAutoregressiveDyadic2020]. The default `"auto"` selects
`"2l"` when both `time` and `predictors` are supplied. It also
retains raw dyad-occasion means and within-dyad member deviations. The decomposed
columns used below are:

1. The `cwp` dyad mean captures a shared occasion-specific shift from the two
   members' usual levels (shared occasion-level variation).
2. The `cwp` within-dyad member deviation captures which member is further above or
   below their own usual level on that occasion.
3. The `cbp` dyad mean captures the dyad's shared usual level relative to the
   sample's grand mean (stable between-dyad differences).
4. The `cbp` within-dyad member deviation captures each member's stable difference
   from the dyad's usual level.

The `cbp` terms use each member's mean across the observed occasions to
estimate that member's longer-run usual level. With few occasions (small
\(T\)), especially when the predictor has low stability over time, these person
means can be unreliable. The associated between-person estimates can therefore
be biased or imprecise, so they should be interpreted cautiously
[@gottfredsonStraightforwardApproachCoping2019].

Use `temporal_decomposition = "none"` to construct only the raw
dyad-occasion mean and within-dyad member deviation.

```{r prepare-ild-exchangeable}
ild_exchangeable_data <- dyadMLM::prepare_dyad_data(
  dyads_ild,
  dyad = coupleID,
  member = personID,
  role = gender,
  time = diaryday,
  predictors = provided_support,
  model_types = c("apim", "dim"),
  keep_compositions = "female-female",
  seed = 123
)

print(ild_exchangeable_data)
```

The example below estimates same-day associations between support and closeness
and includes `diaryday` to adjust for a linear trend across the study.

```{r fit-ild-dim, eval = has_glmmTMB}

dim_ILD <- glmmTMB::glmmTMB(
  closeness ~
    1 +

    diaryday +

    # Within-person DIM
    .dy_provided_support_cwp_dyad_mean +
    .dy_provided_support_cwp_within_dyad_dev +

    # Between-person DIM
    .dy_provided_support_cbp_dyad_mean +
    .dy_provided_support_cbp_within_dyad_dev +

    # Stable exchangeable dyad-level covariance
    us(1 | coupleID) +
    us(0 + .dy_member_contrast_female_x_female_arbitrary | coupleID) +

    # Residual (same-day) exchangeable dyad-level covariance
    us(1 | coupleID:diaryday) +
    us(0 + .dy_member_contrast_female_x_female_arbitrary | coupleID:diaryday)

  , dispformula = ~ 0
  , family = gaussian()
  , data = ild_exchangeable_data
)

summary(dim_ILD)

```

### Interpretation of concurrent ILD DIM coefficients

The same mean-and-deviation interpretation applies longitudinally. Coefficients
of dyad means describe both expected individual outcomes and expected
couple-average outcomes. Coefficients of within-dyad member deviations describe
both members' deviations and their expected difference.

- The `cbp` dyad-mean estimate (about 1.55) means that, comparing couples whose
  average usual support differs by one point while holding the stable difference
  between partners constant, expected couple-average closeness is 1.55 points
  higher for the higher-support couple. Equivalently, each member is expected to
  report 1.55 points higher closeness.

- The `cwp` dyad-mean estimate (about 0.49) means that when both members are one
  point above their respective usual support levels, each member's expected
  closeness is 0.49 points higher than when both are at their usual levels,
  holding the difference between their momentary deviations constant.
  Equivalently, expected couple-average closeness is 0.49 points higher on that
  occasion.

- The `cbp` within-dyad member-deviation estimate (about 0.90) means that if
  partners differ by one point in their usual support levels, they are expected
  to differ by 0.90 points in closeness, holding the couple's average usual
  support and the other predictors constant. In member terms, suppose one member
  is 0.5 points above the couple's average usual support and the other is 0.5
  points below it. Their expected closeness is then about 0.45 points above and below
  the couple's predicted mean, respectively.

- The `cwp` within-dyad member-deviation estimate (about -0.01) is close to zero.
  If one partner's momentary deviation from usual support is one point higher
  than the other partner's deviation, there is essentially no expected
  closeness difference between them from this term, holding the
  occasion-specific dyad mean and the other predictors constant.

### Equivalence of APIM and DIM in ILD

The equivalent APIM uses actor and partner effects on both levels, as shown in
the [concurrent ILD APIM example](apim.html#concurrent-ild-gaussian-apim-for-exchangeable-dyads).
The APIM and DIM again estimate the same model with different coefficients.

The equivalence holds separately for the within-person (`cwp`) and
between-person (`cbp`) predictor components. For the within-person component:

$$
b_{\mathrm{cwp,mean}}
= b_{\mathrm{cwp,actor}} + b_{\mathrm{cwp,partner}}
$$

$$
b_{\mathrm{cwp,dev}}
= b_{\mathrm{cwp,actor}} - b_{\mathrm{cwp,partner}}
$$

For the between-person component:

$$
b_{\mathrm{cbp,mean}}
= b_{\mathrm{cbp,actor}} + b_{\mathrm{cbp,partner}}
$$

$$
b_{\mathrm{cbp,dev}}
= b_{\mathrm{cbp,actor}} - b_{\mathrm{cbp,partner}}
$$

An APIM parameterization can therefore be used on one level and a DIM
parameterization on the other. This mixed parameterization changes the
coefficients, but still estimates the same model.

### Including Random Slopes

Random slopes can be included in the DIM by adding the corresponding
within-person effects to the stable dyad-level random-effect blocks. The shared
block contains the DIM intercept, dyad-mean slope, and within-dyad
member-deviation slope. The `.dy_member_contrast_*` block contains their
member-difference counterparts. Together, these blocks allow the two members
to have different random slopes while preserving exchangeability.

#### Transforming DIM random slopes to APIM slopes

Applying the same transformation to the random-slope coefficients proceeds in
two steps. First, transform the DIM dyad-mean and within-dyad member-deviation random
slopes into APIM actor and partner random slopes. Random effects use $u$, with
subscripts that write out `actor`, `partner`, `mean`, and `dev`. For the shared
block,

$$
u_{\mathrm{actor},j}
= \frac{u_{\mathrm{mean},j} + u_{\mathrm{dev},j}}{2},
\qquad
u_{\mathrm{partner},j}
= \frac{u_{\mathrm{mean},j} - u_{\mathrm{dev},j}}{2},
$$

and for the `.dy_member_contrast_*` block, marked by a tilde,

$$
\widetilde{u}_{\mathrm{actor},j}
= \frac{\widetilde{u}_{\mathrm{mean},j} + \widetilde{u}_{\mathrm{dev},j}}{2},
\qquad
\widetilde{u}_{\mathrm{partner},j}
= \frac{\widetilde{u}_{\mathrm{mean},j} - \widetilde{u}_{\mathrm{dev},j}}{2}.
$$

The shared and `.dy_member_contrast_*` random intercepts remain unchanged.

We now have the shared and `.dy_member_contrast_*` actor and partner effects which are then
back-transformed into the complete and more readily interpretable member-specific
actor-partner covariance matrix. This is described in the
[exchangeable random-slope back-transformation in the APIM vignette](apim.html#exchangeable-random-slope-back-transformation).
The APIM vignette also shows how to
[test constraints on these random effects](apim.html#fitted-constraints-and-omitted-blocks).

### Dynamic ILD models

Dynamic dyadic models are most directly expressed in APIM terms: a member's own
lagged outcome represents stability, whereas the partner's lagged outcome
represents influence. See the
[dynamic ILD APIM example](apim.html#dynamic-models) for data preparation, a
fitted model, and important cautions about outcome lags in short time series.

Under exchangeability, the same fixed effects can be reparameterized as lagged
DIM effects. The lagged dyad mean describes how the members' shared prior
outcome level relates to their current outcomes, while the lagged within-dyad
member deviation describes how their prior difference relates to their current
difference. This changes the coefficient parameterization, not the fitted
values.

---

Return to the [Actor-Partner Interdependence Model vignette](apim.html), see
the [Dyadic Score Model vignette](dsm.html) for a related model specification,
or return to the
[online package overview](https://pascal-kueng.github.io/dyadMLM/).

## References

::: {#refs}
:::
