% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/interprobe.R
\name{interprobe}
\alias{interprobe}
\title{Probe interactions robustly to nonlinearities}
\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{
\item{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.}

\item{z}{The moderator. Same options as `x`.}

\item{y}{The dependent variable. Same options as `x`. Not required when `model` is supplied.}

\item{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.}

\item{data}{Optional data frame containing `x`, `z`, and `y`.}

\item{moderator.on.x.axis}{Logical. If TRUE (default), moderator (`z`) is shown on the x-axis.}

\item{k}{Integer. Smoothness parameter passed to `mgcv::gam()` when estimating with the default
GAM engine.}

\item{spotlights}{Numeric vector of length 3. Values at which curves are computed.}

\item{spotlight.labels}{Character vector of length 3. Labels for the legend.}

\item{histogram}{Logical. If TRUE (default), show sample size distribution under the plot.}

\item{max.unique}{Integer. Threshold for treating a variable as continuous vs discrete.}

\item{n.bin.continuous}{Integer. Number of bins used in histogram when binning continuous values.}

\item{n.max}{Integer. Sample size at which line darkness/width saturates.}

\item{xlab}{Character. X-axis label.}

\item{ylab1}{Character. Y-axis label for simple slopes panel.}

\item{ylab2}{Character. Y-axis label for JN panel.}

\item{cols}{Character vector of length 3. Colors for the three curves.}

\item{main1}{Character. Title for simple slopes panel.}

\item{main2}{Character. Title for JN panel.}

\item{legend.round}{Integer vector length 2. Min/max decimals in legend.}

\item{draw}{Which plots to draw: `"both"` (default), `"simple slopes"` (or legacy `"simple.slopes"`), or `"jn"`.}

\item{save.as}{Optional file path to save plot (`.png` or `.svg`).}

\item{xlim}{Numeric vector length 2. X-axis limits.}

\item{ylim1}{Numeric vector length 2. Y-axis limits for simple slopes.}

\item{ylim2}{Numeric vector length 2. Y-axis limits for JN.}

\item{x.ticks}{Optional custom x-axis ticks.}

\item{y1.ticks}{Optional custom y-axis ticks for panel 1.}

\item{y2.ticks}{Optional custom y-axis ticks for panel 2.}

\item{legend.simple.slopes}{Optional legend title for simple slopes.}

\item{legend.jn}{Optional legend title for JN.}

\item{quiet}{Logical. If TRUE, reduces console output.}

\item{probe.bins}{Integer. Resolution for probing curves (larger = smoother/slower).}
}
\value{
Invisibly returns a list with:
\itemize{
  \item \code{simple.slopes}: data.frame of predicted values and confidence intervals
  \item \code{johnson.neyman}: data.frame of marginal effects and confidence intervals
  \item \code{frequencies}: data.frame with bin frequencies used for shading/histogram
  \item \code{gam_results}: the fitted GAM model when estimated inside \code{interprobe()}
  \item \code{gam_results_testing}: when \code{interprobe()} estimates a GAM internally and \code{x}
    has exactly 2 unique values, a separate GAM fit used for interaction testing (with a \code{ti()}
    term and numeric coding of \code{x})
  \item \code{lm2_results}: when \code{interprobe()} estimates a GAM internally, also returns the
    corresponding linear fit \code{lm2(y ~ x * z)} (or \code{NULL} if package \code{estimatr}
    is not installed)
}
}
\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
}
\details{
Designed for GAM models but works with any model supported by `marginaleffects`
(including `lm`, `glm`, `mgcv::gam`, and `lm2` / `estimatr::lm_robust`).
}
