% 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. Default is 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}}
denotes Vuong's test statistic comparing models \eqn{j} and \eqn{k}:
\deqn{\Delta_{jk} = n^{-1/2} \hat{\omega}_{jk}^{-1} \left[\sum_{i=1}^n
\log\left(\frac{f_{ji}(\hat{\boldsymbol{\theta}}_j)}{f_{ki}(\hat{
\boldsymbol{\theta}}_k)}\right) - \delta_{jk}\right],}

with

\eqn{\hat{\omega}_{jk}^2 = \frac{1}{n} \sum_{i=1}^n \left( \log
\left( \frac{f_{ji}(\boldsymbol{\hat{\theta}}_j)}{f_{ki}
(\boldsymbol{\hat{\theta}}_k)} \right) \right)^2 - \left( \frac{1}{n}
\sum_{i=1}^n \log \left( \frac{f_{ji}(\boldsymbol{\hat{\theta}}_j)}
{f_{ki}(\boldsymbol{\hat{\theta}}_k)} \right) \right)^2.}

Here, \eqn{f_{ji}(\boldsymbol{\hat{\theta}}_j)} and
\eqn{f_{ki}(\boldsymbol{\hat{\theta}}_k)} denote the fitted densities under
models \eqn{j} and \eqn{k}, respectively.

The penalization term \eqn{\delta_{jk}} for simplex models with parametric and
fixed mean links, as proposed by Justino and Cribari-Neto (2026), is given by:

\deqn{\delta_{jk} = 0.5[(r_j - r_k) + \kappa(|\log(\hat{\lambda}_j)| -
|\log(\hat{\lambda}_k)|)]\log(n),}
where \eqn{r_j} and \eqn{r_k} indicate the dimensions of their parameter vectors,
and \eqn{\kappa \geq 0} controls the additional penalty associated with the link
parameter. The term \eqn{\kappa(|\log(\hat{\lambda}_j)| - |\log(\hat{\lambda}_k)|)}
measures link complexity on a logarithmic scale, ensuring symmetry around
\eqn{\lambda = 1}.

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

\strong{Important}: This penalized term \eqn{\delta_{jk}} should only be used
when all candidate models employ a parametric link function in the mean submodel
(use \code{kappa = 0.1}). When the set of candidate models includes specifications
with fixed link functions, the standard unpenalized versions of these criteria
should be applied instead (use \code{kappa = 0}).
}
\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{
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}

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}

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}}
}
