mlm_surface: Contour plot of predicted outcomes over the predictor x...

In mlmoderator: Probing, Plotting, and Interpreting Multilevel Interaction Effects

Contour plot of predicted outcomes over the predictor x moderator space

Description

Plots iso-outcome contour lines of \hat{Y}(x, w) over the full joint space of pred (x-axis) and modx (y-axis). This is the most direct geometric representation of a two-way interaction:

Usage

mlm_surface(
  model,
  pred,
  modx,
  grid = 80L,
  n_contours = 10L,
  fill = TRUE,
  probe_lines = TRUE,
  x_label = NULL,
  y_label = NULL,
  legend_title = NULL
)

Arguments

model	An lmerMod object with a two-way interaction between pred and modx in the fixed effects.
pred	Character scalar. Focal predictor (x-axis).
modx	Character scalar. Moderator (y-axis).
grid	Integer. Grid resolution (points per axis). Default 80.
n_contours	Integer. Number of contour levels to draw. Default 10.
fill	Logical. Fill contour bands with colour? Default TRUE.
probe_lines	Logical. Overlay horizontal lines at mean – 1 SD of modx? Default TRUE.
x_label	x-axis label. Defaults to pred.
y_label	y-axis label. Defaults to modx.
legend_title	Legend title. Defaults to the outcome variable name.

Details

• No interaction: contour lines are perfectly straight and parallel — the effect of pred does not depend on modx.

• Positive interaction: contour lines fan outward (rotate clockwise) — higher modx steepens the pred slope.

• Negative interaction: contour lines fan inward (rotate counter-clockwise).

The degree of non-parallelism among contours is a direct visual index of interaction strength: the larger \beta_3, the more the lines rotate.

An optional overlay draws the three standard simple-slope evaluation lines (mean – 1 SD of modx) as horizontal reference lines, connecting the plot to mlm_probe() output.

Predicted values are computed from fixed effects only (re.form = NA), with all covariates held at their means or reference levels. The surface therefore represents the population-average predicted outcome, not any specific cluster.

Reading the plot: Pick any contour line. Its slope in the pred direction tells you how fast the outcome changes with pred at that modx value. If the contour slopes steeply up-right, pred has a strong positive effect there. If contours become more horizontal as modx increases, the pred effect is weakening. If they rotate from positive to flat to negative, you have a sign-changing interaction — and the modx value where they are perfectly horizontal is the Johnson-Neyman boundary.

Value

A ggplot object.

Examples

set.seed(1)
dat <- data.frame(
  y   = rnorm(200), x = rnorm(200),
  m   = rep(rnorm(20), each = 10),
  grp = factor(rep(1:20, each = 10))
)
dat$y <- dat$y + dat$x * dat$m
mod <- lme4::lmer(y ~ x * m + (1 | grp), data = dat,
                  control = lme4::lmerControl(optimizer = "bobyqa"))
mlm_surface(mod, pred = "x", modx = "m")
mlm_surface(mod, pred = "x", modx = "m", fill = FALSE, n_contours = 15)

mlmoderator documentation built on April 4, 2026, 1:07 a.m.