% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/janusplot.R
\name{janusplot_data}
\alias{janusplot_data}
\title{Raw GAM fits and per-cell metrics for a smoothed-association matrix}
\usage{
janusplot_data(
  data,
  vars = NULL,
  adjust = NULL,
  method = "REML",
  k = -1L,
  bs = "tp",
  na_action = c("pairwise", "complete"),
  parallel = FALSE,
  keep_fits = FALSE,
  derivatives = integer(),
  derivative_ci = c("pointwise", "none", "simultaneous"),
  derivative_ci_nsim = 1000L,
  n_grid = NULL,
  shape_cutoffs = janusplot_shape_cutoffs(),
  ...
)
}
\arguments{
\item{data}{A data frame with numeric columns to include.}

\item{vars}{Character vector of column names to use. \code{NULL} (default)
uses all numeric columns in \code{data}. Non-numeric columns trigger an
error listing offenders.}

\item{adjust}{A one-sided formula RHS giving additional covariates
and/or random effects to include in every pairwise GAM. For example,
\code{adjust = ~ s(age) + s(site, bs = "re")} fits
\code{gam(y ~ s(x) + s(age) + s(site, bs = "re"))} for each pair.
Default \code{NULL} fits unadjusted pairwise smooths.}

\item{method}{Smoothing-parameter estimation method passed to
\code{\link[mgcv:gam]{mgcv::gam()}}. Default \code{"REML"} per mgcv recommendation.}

\item{k}{Integer, or named list mapping variable names to integers.
Basis dimension for \code{s()}. Default \code{-1L} (mgcv's automatic choice).}

\item{bs}{Basis type for \code{s()}. Default \code{"tp"} (thin plate).}

\item{na_action}{One of \code{"pairwise"} (default; per-cell complete
observations) or \code{"complete"} (listwise; all cells use the same
rows).}

\item{parallel}{Logical. If \code{TRUE}, use \code{future.apply::future_mapply()}
to fit pairs in parallel. Requires the \code{future.apply} package and a
user-configured \code{future::plan()}. Default \code{FALSE}.}

\item{keep_fits}{Logical. If \code{TRUE}, retain full \code{\link[mgcv:gam]{mgcv::gam()}} model
objects in the return (large memory footprint for \code{k} above ~15).
Default \code{FALSE} — retains summary metrics and prediction grids only.}

\item{derivatives}{Integer vector of derivative orders to compute
on every pair (subset of \code{1:2}). Default \code{integer()} — no
derivatives. Unlike \code{janusplot()}, the data companion can
return multiple orders from a single call for programmatic
analysis; pass \code{c(1L, 2L)} to surface both.}

\item{derivative_ci}{One of \code{"none"} (default), \code{"pointwise"}, or
\code{"simultaneous"}. Controls whether — and how — a 95\%
confidence ribbon is drawn underneath the derivative curve when
\code{display \%in\% c("d1", "d2")}. Ignored when \code{display = "fit"}.
\itemize{
\item \code{"none"} — no ribbon. The curve and the zero reference line
are all you see. Default, because pointwise ribbons overshoot
nominal coverage as a joint region and can invite
over-reading of local features.
\item \code{"pointwise"} — 95\% pointwise ribbon from
\eqn{\sqrt{\mathrm{diag}(D V_p D^\top)}} (Wood 2017 §7.2.4).
Valid marginally; not a simultaneous statement.
\item \code{"simultaneous"} — 95\% simultaneous band via the Monte Carlo
construction of Ruppert, Wand & Carroll (2003) popularised for
GAMs by Simpson (2018, \emph{Frontiers Ecol. Evol.} 6:149): draw
\eqn{B} samples \eqn{\tilde{\boldsymbol\beta} \sim
    \mathcal{N}(\hat{\boldsymbol\beta}, V_p)}, compute
\eqn{\max_x |D_i(\tilde{\boldsymbol\beta} -
    \hat{\boldsymbol\beta})| / \mathrm{se}_i}, and use the
\eqn{(1-\alpha)} quantile as a critical multiplier on the
pointwise SE. Valid for feature localisation ("where is
\eqn{\hat f'(x)} significantly non-zero").
}}

\item{derivative_ci_nsim}{Integer. Number of Monte Carlo samples
used when \code{derivative_ci = "simultaneous"}. Default \code{1000L} —
a compromise between coverage accuracy (Simpson 2018 uses
10000) and CPU budget across every pair in a medium-sized
matrix. Ignored for any other \code{derivative_ci}.}

\item{n_grid}{Integer or \code{NULL}. Number of equally-spaced points
used to evaluate each fitted smooth (and its derivatives).
Default \code{NULL} resolves to \code{100} when \code{display = "fit"} and
\code{200} otherwise, because finite-difference second derivatives
visibly degrade below \eqn{\sim 150} points on moderate-\code{k}
smooths. Supplying \code{n_grid} directly overrides both defaults.
Larger grids shift the numerical shape-metric values
(\eqn{M}, \eqn{C}, turning / inflection counts) slightly
because they are computed on this same grid. Shapes and
asymmetry are the primary reading; \code{M}, \code{C} and the counts are
secondary diagnostics and the grid-induced drift is tolerable.}

\item{shape_cutoffs}{Named list of classification thresholds used to
map the continuous shape indices (\code{monotonicity_index},
\code{convexity_index}) into discrete
\code{shape_category} labels. Defaults from \code{\link[=janusplot_shape_cutoffs]{janusplot_shape_cutoffs()}}.}

\item{...}{Additional arguments passed to \code{\link[mgcv:gam]{mgcv::gam()}}.}
}
\value{
A list with components:
\describe{
\item{\code{vars}}{Character vector of variables used, in plotted order.}
\item{\code{pairs}}{List of per-pair results. Each element has \code{i}, \code{j},
\code{var_i}, \code{var_j}, \code{fit_yx}, \code{fit_xy} (NULL if \code{keep_fits = FALSE}),
\code{pred_yx}, \code{pred_xy} (data frames with \code{x}, \code{fit}, \code{se}, \code{lo},
\code{hi}), \code{edf_yx}, \code{edf_xy}, \code{pvalue_yx}, \code{pvalue_xy}, \code{dev_exp_yx},
\code{dev_exp_xy}, \code{n_used}, \code{asymmetry_index}, plus Pearson /
Spearman / Kendall correlations (\code{cor_pearson}, \code{cor_spearman},
\code{cor_kendall}), the maximum tie ratio across \code{x} and \code{y}
(\code{tie_ratio}), and per-direction shape descriptors
(\code{monotonicity_index_yx}, \code{convexity_index_yx},
\code{monotonicity_index_xy}, \code{convexity_index_xy},
\code{n_turning_yx}, \code{n_inflect_yx}, \code{n_turning_xy},
\code{n_inflect_xy}, \code{shape_yx}, \code{shape_xy}).
When \code{derivatives} is non-empty, each pair additionally
carries \code{deriv_yx} and \code{deriv_xy}, each a named list keyed by
order (\code{"1"}, \code{"2"}) whose entries are data frames with
columns \code{x}, \code{fit}, \code{se}, \code{lo}, \code{hi}, \code{ci_type} matching the
schema of \code{pred_yx} / \code{pred_xy}. The \code{ci_type} column records
whether the \code{lo} / \code{hi} columns are \code{"pointwise"} (default),
\code{"simultaneous"} (Ruppert--Wand--Carroll / Simpson 2018
critical-multiplier bands), or \code{"none"}. When
\code{derivative_ci = "simultaneous"}, each derivative frame also
carries a \code{"crit_multiplier"} attribute giving the MC-derived
critical multiplier used.
See \code{\link[=janusplot_shape_metrics]{janusplot_shape_metrics()}} for the definition of the
monotonicity and convexity indices.}
\item{\code{call}}{Match call.}
}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}

Companion to \code{\link[=janusplot]{janusplot()}} returning the raw list of GAM fits plus
per-cell metrics (EDF, F-test p-value, deviance explained, asymmetry
index, pairwise correlations, shape descriptors) without constructing
the ggplot. Useful for custom rendering or downstream analysis.
}
\examples{
# Per-pair fits + metrics on a small mtcars slice
out <- janusplot_data(mtcars[, c("mpg", "hp", "wt")])
out$pairs[[1L]]$asymmetry_index
out$pairs[[1L]]$cor_spearman
out$pairs[[1L]]$shape_yx
}
\seealso{
\code{\link[=janusplot]{janusplot()}} for the ggplot front-end,
\code{\link[=janusplot_shape_metrics]{janusplot_shape_metrics()}} for the shape-metric primitives.

Other smooth-associations: 
\code{\link{janusplot}()}
}
\concept{smooth-associations}
