% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/simplexreg_fit.R
\name{simplexreg.fit}
\alias{simplexreg.fit}
\alias{simplexreg}
\title{Simplex Regression with Parametric or Fixed Mean Link}
\usage{
simplexreg(
  formula,
  data,
  subset,
  na.action,
  weights,
  offset,
  link.mu = c("logit", "probit", "loglog", "cloglog", "cauchit", "plogit1", "plogit2"),
  link.sigma2 = NULL,
  contrasts = NULL,
  control = simplexreg.control(...),
  model = TRUE,
  y = TRUE,
  x = FALSE,
  ...
)

simplexreg.fit(
  y,
  x,
  z,
  weights = NULL,
  offset = NULL,
  link.mu = c("logit", "probit", "loglog", "cloglog", "cauchit", "plogit1", "plogit2"),
  link.sigma2 = c("log", "sqrt", "identity"),
  x_names = NULL,
  z_names = NULL,
  control = simplexreg.control(...),
  ...
)
}
\arguments{
\item{formula}{A two-part formula: \code{y ~ x} or \code{y ~ x | 1}
(mean submodel, constant dispersion), or \code{y ~ x | z} (submodels for both
mean and dispersion).}

\item{data}{A data frame containing the variables in formula.}

\item{subset}{A specification of the rows/observations to be used: defaults to all.}

\item{na.action}{An optional (name of a) function for treating missing values (NAs).}

\item{weights}{An optional numeric vector of case weights.}

\item{offset}{Optional numeric vector specifying a known component to be
included in the linear predictor of the mean submodel during fitting.
One or more \code{\link{offset}} terms can be included in the formula instead
or as well, and if more than one is specified their sum is used. See
\code{\link{model.offset}}.}

\item{link.mu}{Character specification of the link function in the mean submodel
(parametric functions: \code{"plogit1"}, \code{"plogit2"}; or fixed functions:
\code{"logit"}, \code{"probit"}, \code{"loglog"}, \code{"cloglog"}, \code{"cauchit"}).}

\item{link.sigma2}{Character specification of the link function in the dispersion
submodel (\code{"log"}, \code{"sqrt"}, \code{"identity"}).}

\item{contrasts}{An optional list. See the \code{contrasts.arg} argument of
\code{\link[stats]{model.matrix.default}}.}

\item{control}{A list of control arguments specified via \code{\link{simplexreg.control}}.}

\item{model, y, x}{Logicals. If \code{TRUE} the corresponding components of the fit
(model frame, response, model matrix) are returned. For \code{\link{simplexreg.fit}},
\code{x} should be a numeric regressor matrix and \code{y} should be the numeric response
vector (with values in (0, 1)).}

\item{...}{Additional arguments passed to \code{\link{simplexreg.control}}.}

\item{z}{Design matrix for dispersion model (without intercept).}

\item{x_names}{Column names for mean design matrix (includes intercept).}

\item{z_names}{Column names for dispersion design matrix (includes intercept).}
}
\value{
An object of class \code{"simplexregression"}, i.e.,
a list with components as follows:
\itemize{
  \item \code{coefficients}: A list with elements \code{mean} and \code{dispersion},
  containing the estimated regression coefficients \eqn{\hat{\boldsymbol{\beta}}} and
  \eqn{\hat{\boldsymbol{\gamma}}} of the mean and dispersion submodels, respectively.
  For parametric mean link functions, the list also includes an additional element,
  \code{lambda}, containing the estimated link parameter \eqn{\hat{\lambda}}.
  \item \code{fitted.values}: a vector of fitted mean values,
  \item \code{optim}: a list containing \code{start} (initial values),
  \code{convergence} (convergence code), \code{counts} (number of iterations) and
  \code{method} (optimization method) from the optimization procedure,
  \item \code{scoring}: number of iterations from the optimization procedure via
  Fisher scoring,
  \item \code{mu.fv}: a vector of fitted mean values,
  \item \code{mu.lp}: a vector of fitted mean linear predictor,
  \item \code{mu.x}: design matrix for the mean model (with intercept),
  \item \code{mu.link}: character string specifying the mean link function,
  \item \code{mu.df}: degrees of freedom for the mean model,
  \item \code{sigma2.fv}: a vector of fitted dispersion values,
  \item \code{sigma2.lp}: a vector of fitted dispersion linear predictor,
  \item \code{sigma2.x}: design matrix for the dispersion model (with intercept),
  \item \code{sigma2.link}: character string specifying the dispersion link function,
  \item \code{sigma2.df}: degrees of freedom for the dispersion model,
  \item \code{lambda.fv}: estimated value of the parametric link function parameter
  (\code{NA} for mean fixed links),
  \item \code{df.residual}: residual degrees of freedom,
  \item \code{nobs}: number of observations,
  \item \code{loglik}: maximized log-likelihood value,
  \item \code{vcov}: variance-covariance matrix of the parameter estimates,
  \item \code{residuals}: a vector of quantile residuals,
  \item \code{AIC}, \code{BIC}, \code{HQIC}: Akaike, Schwarz, and Hannan-Quinn
  information criteria,
  \item \code{R2_N}, \code{R2_FC}: Nagelkerke, and Ferrari and Cribari-Neto
  pseudo R-squared measures,
  \item \code{zstat}: \eqn{z}-statistics for the coefficient tests,
  \item \code{pvalues}: \eqn{p}-values for the coefficient tests,
  \item \code{y}: the response vector,
  \item \code{x_names}: column names of the mean design matrix,
  \item \code{z_names}: column names of the dispersion design matrix,
  \item \code{control}: the control arguments passed to the \code{optim} call,
  \item \code{converged}: logical indicating successful convergence of \code{optim},
  \item \code{call}: the original function call,
  \item \code{formula}: the original two-part formula,
  \item \code{formula_mean}: formula for the mean submodel,
  \item \code{formula_disp}: formula for the dispersion submodel,
  \item \code{terms}: a list with \code{mean} and \code{dispersion} terms
  objects,
  \item \code{weights}: the weights used in fitting (if any),
  \item \code{offset}: the offset used in fitting (if any),
  \item \code{na.action}: the na.action attribute from the model frame,
  \item \code{subset}: the subset used in fitting (if any),
  \item \code{model}: the full model frame.

}
}
\description{
Fit simplex regression models for rates and proportions via
maximum likelihood estimation, modeling both the mean (via parametric
or fixed link function) and the dispersion parameter.
}
\details{
Simplex regression, introduced by Song and Tan (2000) and extended by
Song, Qiu and Tan (2004), is useful for modeling continuous response variables
restricted to the unit interval (0, 1), such as rates and proportions. The model
assumes that the dependent variable follows the simplex distribution, originally
proposed by Barndorff-Nielsen and Jørgensen (1991), which is indexed by the mean
\eqn{\mu} and the dispersion parameter \eqn{\sigma^2}.

Similar to generalized linear models (GLMs), simplex regression relates
the mean of the response variable and the dispersion parameter to their respective
linear predictors through link functions. This package implements five fixed link
functions (\code{"logit"}, \code{"probit"}, \code{"loglog"}, \code{"cloglog"},
\code{"cauchit"}) and two parametric link functions (\code{"plogit1"},
\code{"plogit2"}) for the mean submodel. For the dispersion submodel, the
links \code{"log"}, \code{"sqrt"} and \code{"identity"} are supported.

The model is specified through a two-part formula separated by \code{|}. The
left side contains the predictors for the mean submodel and the right side contains
the predictors for the dispersion submodel:
\itemize{
  \item Mean submodel: \eqn{g(\mu_i, \lambda) = \boldsymbol{x}_i'\boldsymbol{\beta}}
  (parametric link) or \eqn{g(\mu_i) = \boldsymbol{x}_i'\boldsymbol{\beta}} (fixed link),
  where \eqn{g(\cdot)} is the mean link function, \eqn{\lambda} is the
  extra shape parameter of the parametric link,
  \eqn{\boldsymbol{x}_i} is the vector of covariates for the \eqn{i}-th observation in
  the mean submodel, and \eqn{\boldsymbol{\beta}} is the corresponding
  vector of regression coefficients.
  \item Dispersion submodel: \eqn{h(\sigma^2_i) = \boldsymbol{z}_i'\boldsymbol{\gamma}},
  where \eqn{h(\cdot)} is the dispersion link function, \eqn{\boldsymbol{z}_i} is the
  vector of covariates for the \eqn{i}-th observation in the dispersion
  submodel, and \eqn{\boldsymbol{\gamma}} is the corresponding vector of
  regression coefficients.
}

Formula examples: \code{y ~ x1 + x2 | z1 + z2} (variable dispersion) or
\code{y ~ x1 + x2} (constant dispersion). The link functions for both
submodels are specified using \code{link.mu} and \code{link.sigma2}.

The parametric mean link functions include a parameter \eqn{\lambda} that
is estimated along with other model parameters. Parameter estimation is performed
via maximum likelihood using the \code{optim} function with analytical gradient
and initial values obtained from an auxiliary linear regression of the transformed
response. Subsequently, the \code{optim} result may be enhanced by an additional Fisher
scoring iteration using analytical gradients and expected information. The Fisher
scoring is just a refinement to move the gradients even closer to zero and can be
disabled by setting \code{fsmaxit = 0} in the control arguments.

Methods for extracting and analyzing results are implemented for objects
of class \code{"simplexregression"}, allowing the use of generic functions such as
\code{\link{summary}}, \code{\link{print}}, \code{\link{fitted}}, \code{\link{coef}},
\code{\link{formula}}, \code{\link{logLik}}, \code{\link{vcov}}, \code{\link{predict}},
\code{\link{terms}}, \code{\link{model.frame}}, \code{\link{model.matrix}},
\code{\link{plot}}, \code{\link{residuals}}, \code{\link{cooks.distance}},
\code{\link{gleverage}}, \code{\link{hatvalues}}, \code{\link{update}},
\code{\link{simulate}}, \code{\link{AIC}}, \code{\link[lmtest]{coeftest}} (from the
lmtest package), \code{\link[sandwich]{bread}} and \code{\link[sandwich]{estfun}} (from the sandwich package).
}
\examples{
data(ReadingSkills, package = "SimplexRegression")
fit <- simplexreg(accuracy ~ dyslexia * iq | dyslexia + iq + I(iq^2),
                 data = ReadingSkills)
summary(fit)

}
\references{
Barndorff-Nielsen, O. E. and Jørgensen, B. (1991).
Some parametric models on the simplex.
\emph{Journal of Multivariate Analysis}, \bold{39}(1), 106--116.
\doi{10.1016/0047-259X(91)90008-P}

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}

Jørgensen, B. (1997). \emph{The Theory of Dispersion Models}.
Chapman and Hall, London.

Song, P. X.-K. and Tan, M. (2000).
Marginal models for longitudinal continuous proportional data.
\emph{Biometrics}, \bold{56}(2), 496--502.
\doi{10.1111/j.0006-341X.2000.00496.x}

Song, P. X.-K.; Qiu, Z. and Tan, M. (2004).
Modelling heterogeneous dispersion in marginal models for longitudinal
proportional data.
\emph{Biometrical Journal}, \bold{46}(5), 540--553.
\doi{10.1002/bimj.200110052}

Song, P. X.-K. (2009).
Dispersion models in regression analysis.
\emph{Pakistan Journal of Statistics}, \bold{25}(4), 529--551.

Zhang, P. and Qiu, Z. G. (2014).
Regression analysis of proportional data using simplex distribution.
\emph{SCIENTIA SINICA Mathematica}, \bold{44}(1), 89--104.
\doi{10.1360/012013-200}
}
\seealso{
\code{\link{summary.simplexregression}},
\code{\link{predict.simplexregression}}, \code{\link{residuals.simplexregression}},
\code{\link{ic.penalized}}, \code{\link{ss.penalized}},
\code{\link{scoretest}}
}
