% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/simplexreg_sscriteria.R
\name{penalized.ss}
\alias{penalized.ss}
\title{Scout Score Criterion for Simplex Regression Model Selection}
\usage{
penalized.ss(
  ...,
  kappa = 0.1,
  verbose = TRUE,
  digits = max(3, getOption("digits") - 3)
)
}
\arguments{
\item{...}{Two or more objects of class \code{"simplexregression"} to be compared.}

\item{kappa}{A numeric value controlling the additional penalty for the link mean
parameter, \eqn{\kappa \geq 0}. Default is \code{0.1}. Use \code{kappa = 0} for
standard Scout Score.}

\item{verbose}{Logical. If \code{TRUE} (default), prints the SS values for
all models and the selected model. If \code{FALSE}, returns results silently.}

\item{digits}{Integer specifying the number of decimal places for output.
Default is \code{max(3, getOption("digits") - 3)}.}
}
\value{
A data frame with rows named after the candidate models and two columns:
\describe{
  \item{\code{df}}{Number of estimated parameters in each model.}
  \item{\code{SS}}{Scout Score value. The model with the highest value is
  the selected one.}
}
When \code{verbose = TRUE}, the selected model is also printed to the console.
The data frame is returned invisibly in this case, and visibly when
\code{verbose = FALSE}.
}
\description{
Implements the Scout Score (SS) criterion for selecting among
competing simplex regression models with parametric and fixed mean link functions.
}
\details{
The Scout Score criterion, originally proposed by Costa et al. (2024) for
selecting link functions in the \eqn{\beta\text{ARMA}} (beta autoregressive
moving average) model, extends Vuong's test statistic to compare \eqn{M \geq 2}
competing non-nested models using their individual log-likelihood contributions.

For each candidate model \eqn{j \in {1, \ldots, M}}, the Scout Score is defined as:
\deqn{SS_j = 1 - M + \sum_{k=1, k \neq j}^M (1 + \dot{\Delta}_{jk})^2,}

where \eqn{\dot{\Delta}_{jk} = \max\{0, \Delta_{jk}\}} and \eqn{\Delta_{jk}}
is Vuong's (1989) test statistic comparing models \eqn{j} and \eqn{k}, penalized
by a term \eqn{\delta_{jk}} that combines the difference in parameter-vector
dimensions with, when applicable, a link-complexity penalty controlled by
\code{kappa}. The model with the highest Scout Score is selected as the most
adequate. For the full derivation of \eqn{\Delta_{jk}}, \eqn{\delta_{jk}}, and
the rationale behind the link-complexity penalty, see Justino and
Cribari-Neto (2026) and Costa et al. (2024).

When at least one of the candidate models does not use a parametric mean
link function, \eqn{\kappa} is internally set to \code{0} (see \strong{Important}
below), so that \eqn{\delta_{jk}} reduces to the classical dimension penalty
with no link-complexity term.

The model with the highest Scout Score is selected as the most adequate.

\strong{Important}: The penalty term \eqn{\delta_{jk}} is only applied when
\emph{all} candidate models employ a parametric mean link function, in which
case \code{kappa} (default \code{0.1}) controls the additional penalty. In
any other case --- whether all candidate models use fixed mean links, or the
set of candidate models mixes parametric and fixed mean links --- the penalty
is disabled and the standard, unpenalized Scout Score is computed for all
models (\code{kappa} is internally reset to \code{0}). If the user explicitly
requested \code{kappa > 0} in either of these situations, a warning is issued;
if \code{kappa} was left at its default value, no warning is issued, since
falling back to the standard Scout Score is the expected behavior.

\strong{Note}: all candidate models must be fitted to the same response
vector \code{y}; the function verifies this and stops with an error if the
response vectors differ.
}
\examples{
# Simulate data
set.seed(2026)
n <- 100
x1 <- runif(n, 0, 1)
x2 <- runif(n, 0, 1)
z1 <- runif(n, 0, 1)
mu <- parametric_mean_link_inv(0.6 - 2*x1 - 1.5*x2, 0.5, "plogit1")
sigma2 <- dispersion_link_inv(-2 - 2.5*z1, "log")
y <- rsimplex(n, mu, sigma2)
data <- data.frame(y = y, x1 = x1, x2 = x2, z1 = z1)

# Fit models
fit1 <- simplexreg(y ~ x1 + x2 | z1, data = data, link.mu = "plogit1")
fit2 <- simplexreg(y ~ x1 + x2 | z1, data = data, link.mu = "plogit2")
fit3 <- simplexreg(y ~ x1 + x2 | z1, data = data, link.mu = "logit")
fit4 <- simplexreg(y ~ x1 + x2 | z1, data = data, link.mu = "probit")

# Compare models with verbose output
result <- penalized.ss(fit1, fit2, kappa = 0.1)

# Compare models silently
result <- penalized.ss(fit1, fit2, kappa = 0.1, verbose = FALSE)

# Use standard Scout Score (no parametric link penalty)
result <- penalized.ss(fit1, fit2, fit3, fit4, kappa = 0)

}
\references{
Costa, E., Cribari-Neto, F. and Scher, V. T. (2024).
Test inferences and link function selection in dynamic beta modeling of seasonal
hydro-environmental time series with temporary abnormal regimes.
\emph{Journal of Hydrology}, \bold{638}, 131489.
\doi{10.1016/j.jhydrol.2024.131489}

Justino, M. E. C. and Cribari-Neto, F. (2026).
Simplex regression with a flexible logit link: Inference and application
to cross-country impunity data.
\emph{Applied Mathematical Modelling}, \bold{154}, 116713. \doi{10.1016/j.apm.2025.116713}

Vuong, Q. H. (1989). Likelihood ratio tests for model selection and non-nested
hypotheses. \emph{Econometrica}, \bold{57}(2), 307--333. \doi{10.2307/1912557}
}
\seealso{
\code{\link{penalized.ic}}
}
