% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/modelling.R
\name{bestModel}
\alias{bestModel}
\title{Determine Regression Model}
\usage{
bestModel(
  data,
  raw = NULL,
  R2 = NULL,
  k = NULL,
  t = NULL,
  predictors = NULL,
  terms = 0,
  weights = NULL,
  force.in = NULL,
  plot = TRUE,
  extensive = TRUE,
  averaging = FALSE,
  minDip = 0.01
)
}
\arguments{
\item{data}{Preprocessed dataset with 'raw' scores, powers, interactions, and
usually an explanatory variable (like age).}

\item{raw}{Name of the raw score variable (default: 'raw').}

\item{R2}{Adjusted R^2 stopping criterion for model building.}

\item{k}{Power constant influencing model complexity (default: taken from the
data preparation, max: 6).}

\item{t}{Age power parameter. If unset, taken from the data preparation
(default 3).}

\item{predictors}{List of predictors or regression formula for model
selection. Overrides 'k' and can include additional variables.}

\item{terms}{Desired number of terms in the model.}

\item{weights}{Optional case weights. If set to FALSE, default weights
(if any) are ignored.}

\item{force.in}{Variables forcibly included in the regression.}

\item{plot}{If TRUE (default), displays a percentile plot of the model and
information about the regression object. FALSE turns off plotting and report.}

\item{extensive}{If TRUE (default), screen models for consistency and - if
possible - exclude inconsistent ones.}

\item{averaging}{If TRUE (default FALSE), apply BIC-weighted model averaging
across the consistency-screened candidate models instead of selecting a
single model. Requires \code{extensive = TRUE} and age-based norming.}

\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{
The model. Further exploration can be done using
  \code{plotSubset(model)} and \code{plotPercentiles(data, model)}.
}
\description{
Computes Taylor polynomial regression models by evaluating a series of models
with increasing number of predictors. It aims to find a consistent model that
effectively captures the variance in the data. It draws on the regsubsets
function from the leaps package, builds up to 10 models per number of
predictors, screens them for model consistency (monotonicity of the mapping
between norm score and raw score over the complete age range) and selects the
consistent model with the highest R^2. This automatic model selection should
usually be accompanied by visual inspection of the percentile plots and
assessment of fit statistics. Set R^2 or the number of terms manually to
retrieve a more parsimonious model, if desired.
}
\details{
The functions \code{rankBySlidingWindow}, \code{rankByGroup}, \code{bestModel},
\code{computePowers} and \code{prepareData} are usually not called directly,
but accessed through other functions like \code{cnorm}.

Additional functions like \code{plotSubset(model)} and \code{cnorm.cv} can
aid in model evaluation.

If \code{averaging = TRUE}, the final coefficients are not taken from a
single selected model, but computed as a BIC-weighted average across all
consistency-screened candidate models (weights \eqn{w_j \propto
exp(-\Delta BIC_j / 2)}). Since a convex combination of functions that are
all monotone in the same direction is itself monotone, the averaged model is
guaranteed to remain consistent, while reducing model selection variance.
This replaces the deprecated \code{subsampling} approach.
}
\examples{
\dontrun{
# It is not recommended to directly use this function. Rather use 'cnorm' instead.
normData <- prepareData(elfe)
model <- bestModel(normData)
plotSubset(model)
plotPercentiles(buildCnormObject(normData, model))

# Specifying variables explicitly
preselectedModel <- bestModel(normData, predictors = c("L1", "L3", "L1A3", "A2", "A3"))
print(regressionFunction(preselectedModel))
}
}
\seealso{
plotSubset, plotPercentiles, plotPercentileSeries, checkConsistency

Other model:
\code{\link[=checkConsistency]{checkConsistency()}},
\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}
