% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/applicability.R
\name{applicability_check}
\alias{applicability_check}
\title{Check whether the flexible-margin copula-VAR is appropriate for the data}
\usage{
applicability_check(
  fit,
  reference = NULL,
  atom_tol = 0.05,
  delta_tol = 0.98,
  phi_collapse_tol = 0.1,
  ols_clear_tol = 0.2,
  rhat_tol = 1.01
)
}
\arguments{
\item{fit}{A \code{dcvar_constant_fit}.}

\item{reference}{Optional normal-margin \code{dcvar_constant_fit} on the same
variables and number of observations. When supplied, the dynamics-collapse
signal compares the fitted self-lags against this reference fit's self-lags
in addition to the OLS VAR(1) anchor (which is always used). If \code{NULL}
(default), only the OLS VAR(1) anchor is used.}

\item{atom_tol}{Minimum fraction at a bound to flag a point mass (default \code{0.05}).}

\item{delta_tol}{Magnitude of the skew-normal slant treated as a boundary value
(default \code{0.98}).}

\item{phi_collapse_tol}{Self-lag magnitude treated as collapsed (default \code{0.10}).}

\item{ols_clear_tol}{Anchor self-lag magnitude treated as clear
autoregression when detecting a dynamics collapse (default \code{0.20}).}

\item{rhat_tol}{Split-Rhat threshold (default \code{1.01}).}
}
\value{
An object of class \code{dcvar_applicability}: a list with the \code{verdict}
(\code{"suitable"}, \code{"caution"}, or \code{"unsuitable"}), a \code{recommendation}, the
triggered \code{reasons}, the variable names (\code{vars}) and \code{margins}, the
boundary-atom fractions (\code{atom}, \code{atom_min}, \code{atom_max}), the fitted and
OLS self-lags (\code{fit_self_lag}, \code{ols_self_lag}, plus \code{reference_self_lag}
when a reference is supplied), the skew-normal slant means (\code{delta}, or
\code{NULL}), the convergence \code{diagnostics}, and the \code{thresholds} used. Has a
\code{print} method.
}
\description{
Screens a fitted constant copula-VAR for the floor/ceiling pile-up pathology.
When a non-trivial point mass of observations sits exactly at a scale bound
(a floor or ceiling effect, common for raw single-item slider or Likert
responses), a flexible skewed margin (skew-normal, gamma, exponential) can
reproduce that pile-up only by concentrating the innovations at the bound,
which is achieved when the autoregressive prediction is flat. The margin then
absorbs the marginal shape and the VAR coefficients collapse toward zero, even
when the series is clearly autocorrelated. The decision whether the approach
suits a dataset cannot be made from the response format (a visual analog scale
looks continuous yet can have a heavy floor pile-up); it must be made from the
realized data and the fit.
}
\details{
Three signals are combined:
\enumerate{
\item \strong{Boundary atom}: the fraction of observations exactly at each
series minimum and maximum, counted only when at least two observations
coincide at the bound (a lone extreme value is not a point mass). A
continuous margin cannot reproduce a point mass, so a non-trivial atom is
a warning sign.
\item \strong{Dynamics collapse}: the fitted self-lags against an OLS VAR(1)
anchor (and, when supplied, a normal-margin reference fit). A
flexible-margin fit whose self-lags collapse toward zero while an anchor
shows clear autoregression (in either direction) is the signature of the
pathology.
\item \strong{Boundary and convergence flags}: a skew-normal slant estimated
at its boundary, divergent transitions, or elevated split-Rhat.
}
}
\examples{
\donttest{
sim <- simulate_dcvar(
  n_time = 60,
  rho_trajectory = rho_constant(60, rho = 0.4),
  margins = "skew_normal",
  skew_params = list(alpha = c(4, 4)),
  seed = 1
)
fit <- dcvar_constant(
  sim$Y_df, vars = c("y1", "y2"), margins = "skew_normal",
  chains = 2, iter_warmup = 500, iter_sampling = 500, refresh = 0, seed = 1
)
applicability_check(fit)
}
}
\seealso{
\code{\link[=dcvar_constant]{dcvar_constant()}}, \code{\link[=dcvar_diagnostics]{dcvar_diagnostics()}}, \code{\link[=var_params]{var_params()}}.
}
