% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/modelling.R
\name{checkConsistency}
\alias{checkConsistency}
\title{Check the consistency of the norm data model}
\usage{
checkConsistency(
  model,
  minAge = NULL,
  maxAge = NULL,
  minNorm = NULL,
  maxNorm = NULL,
  minRaw = NULL,
  maxRaw = NULL,
  stepAge = NULL,
  stepNorm = 1,
  method = c("analytic", "grid"),
  warn = FALSE,
  silent = FALSE,
  minDip = 0.01
)
}
\arguments{
\item{model}{The model from the bestModel function or a cnorm object}

\item{minAge}{Age to start with checking}

\item{maxAge}{Upper end of the age check}

\item{minNorm}{Lower end of the norm value range}

\item{maxNorm}{Upper end of the norm value range}

\item{minRaw}{clipping parameter for the lower bound of raw scores}

\item{maxRaw}{clipping parameter for the upper bound of raw scores}

\item{stepAge}{Stepping parameter for the age check. If NULL, 8 equidistant
age points are used. Lower values indicate higher precision.}

\item{stepNorm}{Stepping parameter for the norm table check within age
(only used with \code{method = "grid"})}

\item{method}{Monotonicity cgeck. Either "analytic" (default; exact within
age via polynomial derivative roots) or "grid" (numerical check on a norm
score grid)}

\item{warn}{Retained for backwards compatibility (violations below numerical
tolerance are always suppressed)}

\item{silent}{turn off messages}

\item{minDip}{Tolerance for monotonicity check. Allow small violations
(default: .01 or 1% of the raw score range). Decrease e. g. to 1e-6
for strict checking.}
}
\value{
Boolean, indicating model violations (TRUE) or no problems (FALSE)
}
\description{
While abilities increase and decline over age, within one age group, the
norm scores always have to show a monotonic increase or decrease with
increasing raw scores. Violations of this assumption are an indication for
problems in modeling the relationship between raw and norm scores. There are
several reasons, why this might occur:
\enumerate{
  \item Vertical extrapolation: Choosing extreme norm scores, e. g. values
  -3 <= x and x >= 3. In order to model these extreme values, a large sample
  dataset is necessary.
  \item Horizontal extrapolation: Taylor polynomials converge in a certain
  radius. Using the model values outside the original dataset may
  lead to inconsistent results.
  \item The data cannot be modeled with Taylor polynomials, or you need
  another power parameter (k) or R2 for the model.
 }
}
\details{
In general, extrapolation (point 1 and 2) can carefully be done to a
 certain degree outside the original sample, but it should in general
 be handled with caution. Please note that at extreme values, the models
 most likely become independent and it is thus recommended to restrict the
 norm score range to the relevant range of abilities, e.g. +/- 2.5 SD via
 the minNorm and maxNorm parameter.

 With \code{method = "analytic"} (default), monotonicity within each age is
 verified exactly: since the model is polynomial in the norm score L, the
 real roots of its derivative are computed via \code{polyroot} and the sign
 of the derivative is checked between consecutive roots. This detects even
 narrow violations that a coarse norm score grid can miss. Age remains
 discretized; violations that are entirely clipped by the raw score bounds
 are ignored. \code{method = "grid"} reproduces the classical numerical
 check and is used automatically as a fallback for models with non-Taylor
 predictors.
}
\examples{
\dontrun{
  model <- cnorm(raw = elfe$raw, group = elfe$group, plot = FALSE)
  modelViolations <- checkConsistency(model, minNorm = 25, maxNorm = 75)
  plotDerivative(model, minNorm = 25, maxNorm = 75)
}
}
\seealso{
Other model:
\code{\link[=bestModel]{bestModel()}},
\code{\link[=cnorm.cv]{cnorm.cv()}},
\code{\link[=derive]{derive()}},
\code{\link[=modelSummary]{modelSummary()}},
\code{\link[=print.cnorm]{print.cnorm()}},
\code{\link[=printSubset]{printSubset()}},
\code{\link[=rangeCheck]{rangeCheck()}},
\code{\link[=regressionFunction]{regressionFunction()}},
\code{\link[=summary.cnorm]{summary.cnorm()}},
\code{\link[=weightedAverageModel]{weightedAverageModel()}}
}
\concept{model}
