% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/simplexreg_penalized_ic.R
\name{ic.penalized}
\alias{ic.penalized}
\title{Penalized Information Criteria for Simplex Regression Model Selection}
\usage{
ic.penalized(
  ...,
  kappa = 0.1,
  verbose = TRUE,
  digits = max(3, getOption("digits") - 3)
)
}
\arguments{
\item{...}{One or more objects of class \code{"simplexregression"} fitted with a
parametric mean link functions (\code{"plogit1"} or \code{"plogit2"}).}

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

\item{verbose}{Logical. If \code{TRUE} (default), prints the criteria values.
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 four columns:
\describe{
  \item{\code{df}}{Number of estimated parameters.}
  \item{\code{AICp}}{Penalized AIC value.}
  \item{\code{BICp}}{Penalized BIC value.}
  \item{\code{HQICp}}{Penalized HQIC value.}
}
When \code{verbose = TRUE}, the results are also printed to the console and
the data frame is returned invisibly. When \code{verbose = FALSE}, the data
frame is returned visibly without printing.
When \code{kappa = 0}, the columns are named \code{AIC}, \code{BIC}, and
\code{HQIC} instead of \code{AICp}, \code{BICp}, and \code{HQICp}.
}
\description{
Implements the Akaike, Schwarz, and Hannan–Quinn information
criteria with a penalty term for selecting among competing simplex regression
models with parametric mean link functions.
}
\details{
The penalized information criteria, as proposed by Justino and
Cribari-Neto (2026), extend the classical Akaike, Schwarz and
Hannan--Quinn criteria with an additional penalty term for the link
parameter \eqn{\lambda}:
\deqn{AIC^{(\lambda)} = -2 \ell + (2 + \kappa \, |\log(\lambda)|)r}
\deqn{BIC^{(\lambda)} = -2 \ell + (\log(n) + \kappa \, |\log(\lambda)|)r}
\deqn{HQIC^{(\lambda)}  = -2 \ell + (2 \log(\log(n)) + \kappa \, |\log(\lambda)|)r}
where:
\itemize{
  \item \eqn{\ell} denotes the maximized log-likelihood function;
  \item \eqn{\kappa \geq 0} controls the additional penalty associated with
  the link parameter;
  \item \eqn{\lambda} is the parameter of the parametric mean link function;
  \item \eqn{r} indicate the dimension of their parameter vector;
  \item \eqn{n} is the number of observations.
}

\strong{Important}: These penalized versions of the criteria should only be used
when the candidate models employ a parametric link function in the mean submodel
(use \code{kappa = 0.1}). When candidate models include 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 two models with parametric mean link functions
fit1 <- simplexreg(y ~ x1 + x2 | z1, data = data, link.mu = "plogit1")
fit2 <- simplexreg(y ~ x1 + x2 | z1, data = data, link.mu = "plogit2")

# Compute penalized criteria
ic.penalized(fit1, fit2)

}
\references{
Akaike, H. (1973). Information theory and an extension of the maximum
likelihood principle. \emph{Akadémiai Kiadó}, 267--281.

Hannan, E. J. and Quinn, B. G. (1979). The determination of the order of an
autoregression. \emph{Journal of the Royal Statistical Society Series B:
Statistical Methodology}, \bold{41}(2), 190--195.
\doi{10.1111/j.2517-6161.1979.tb01072.x}

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}

Schwarz, G. E. (1978). Estimating the dimension of a model. \emph{Annals of
Statistics}, \bold{6}(2), 461--464. \doi{10.1214/aos/1176344136}
}
\seealso{
\code{\link{ss.penalized}}
}
