interprobe: Probe interactions robustly to nonlinearities
In statuser: Statistical Tools Designed for End Users

interprobe

R Documentation

Probe interactions robustly to nonlinearities

Description

Probes an interaction by estimating (or accepting) a model and computing: - simple slopes ("spotlights") using predicted values - Johnson-Neyman ("jn") curves using marginal effects

Usage

interprobe(
  x = NULL,
  z = NULL,
  y = NULL,
  model = NULL,
  data = NULL,
  moderator.on.x.axis = TRUE,
  k = NULL,
  spotlights = NULL,
  spotlight.labels = NULL,
  histogram = TRUE,
  max.unique = 11,
  n.bin.continuous = 10,
  n.max = 50,
  xlab = "",
  ylab1 = "",
  ylab2 = "",
  cols = c("red4", "dodgerblue", "green4"),
  main1 = "GAM Simple Slopes",
  main2 = "GAM Johnson-Neyman",
  legend.round = c(1, 4),
  draw = "both",
  save.as = NULL,
  xlim = NULL,
  ylim1 = NULL,
  ylim2 = NULL,
  x.ticks = NULL,
  y1.ticks = NULL,
  y2.ticks = NULL,
  legend.simple.slopes = NULL,
  legend.jn = NULL,
  quiet = FALSE,
  probe.bins = 100
)

Arguments

`x`	The focal predictor. Can be a name (bare or quoted) when 'data' or 'model' is provided, or a numeric/factor vector when probing from vectors.
`z`	The moderator. Same options as 'x'.
`y`	The dependent variable. Same options as 'x'. Not required when 'model' is supplied.
`model`	By default 'interprobe' estimates a GAM model predicting 'y' with 'x' and 'z'. You can instead probe a linear interaction by setting model=linear. You can also probe a model of your choice by running it separately, saving the output, and submitting it as the model argument to interprobe. This is the way to include covariates for a probed interaction.
`data`	Optional data frame containing 'x', 'z', and 'y'.
`moderator.on.x.axis`	Logical. If TRUE (default), moderator ('z') is shown on the x-axis.
`k`	Integer. Smoothness parameter passed to 'mgcv::gam()' when estimating with the default GAM engine.
`spotlights`	Numeric vector of length 3. Values at which curves are computed.
`spotlight.labels`	Character vector of length 3. Labels for the legend.
`histogram`	Logical. If TRUE (default), show sample size distribution under the plot.
`max.unique`	Integer. Threshold for treating a variable as continuous vs discrete.
`n.bin.continuous`	Integer. Number of bins used in histogram when binning continuous values.
`n.max`	Integer. Sample size at which line darkness/width saturates.
`xlab`	Character. X-axis label.
`ylab1`	Character. Y-axis label for simple slopes panel.
`ylab2`	Character. Y-axis label for JN panel.
`cols`	Character vector of length 3. Colors for the three curves.
`main1`	Character. Title for simple slopes panel.
`main2`	Character. Title for JN panel.
`legend.round`	Integer vector length 2. Min/max decimals in legend.
`draw`	Which plots to draw: '"both"' (default), '"simple slopes"' (or legacy '"simple.slopes"'), or '"jn"'.
`save.as`	Optional file path to save plot ('.png' or '.svg').
`xlim`	Numeric vector length 2. X-axis limits.
`ylim1`	Numeric vector length 2. Y-axis limits for simple slopes.
`ylim2`	Numeric vector length 2. Y-axis limits for JN.
`x.ticks`	Optional custom x-axis ticks.
`y1.ticks`	Optional custom y-axis ticks for panel 1.
`y2.ticks`	Optional custom y-axis ticks for panel 2.
`legend.simple.slopes`	Optional legend title for simple slopes.
`legend.jn`	Optional legend title for JN.
`quiet`	Logical. If TRUE, reduces console output.
`probe.bins`	Integer. Resolution for probing curves (larger = smoother/slower).

Details

Designed for GAM models but works with any model supported by 'marginaleffects' (including 'lm', 'glm', 'mgcv::gam', and 'lm2' / 'estimatr::lm_robust').

Value

Invisibly returns a list with:

simple.slopes: data.frame of predicted values and confidence intervals
johnson.neyman: data.frame of marginal effects and confidence intervals
frequencies: data.frame with bin frequencies used for shading/histogram
gam_results: the fitted GAM model when estimated inside interprobe()
gam_results_testing: when interprobe() estimates a GAM internally and x has exactly 2 unique values, a separate GAM fit used for interaction testing (with a ti() term and numeric coding of x)
lm2_results: when interprobe() estimates a GAM internally, also returns the corresponding linear fit lm2(y ~ x * z) (or NULL if package estimatr is not installed)