% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/savvy_glm.fit2.R
\name{savvy_glm.fit2}
\alias{savvy_glm.fit2}
\title{Generalized Linear Models Fitting with Slab and Shrinkage Estimators}
\usage{
savvy_glm.fit2(x, y, weights = rep(1, nobs),
                        model_class = c("St", "DSh", "SR", "GSR", "LW", "QIS", "Sh"),
                        start = NULL, etastart = NULL, mustart = NULL,
                        offset = rep(0, nobs), family = gaussian(),
                        control = list(), intercept = TRUE,
                        use_parallel = FALSE, use_robust_start = FALSE)
}
\arguments{
\item{x}{A numeric matrix of predictors. As for \code{\link{glm.fit}}.}

\item{y}{A numeric vector of responses. As for \code{\link{glm.fit}}.}

\item{weights}{An optional vector of weights to be used in the fitting process. As for \code{\link{glm.fit}}.}

\item{model_class}{A character vector specifying the shrinkage model(s) to be used.
Allowed values are \code{"St"}, \code{"DSh"}, \code{"SR"}, \code{"GSR"}, \code{"LW"}, \code{"QIS"}, and \code{"Sh"}.
If a single value is provided, only that method is run. If multiple values are provided,
the function runs the specified methods in parallel (if \code{use_parallel = TRUE}) and returns the best one based on Akaike Information Criterion (AIC).
When the user does not explicitly supply a value for \code{model_class}, the default is \code{c("St", "DSh", "SR", "GSR", "LW", "QIS")} (i.e. \code{"Sh"} is not considered).}

\item{start}{Starting values for the parameters. As for \code{\link{glm.fit}}. If \code{NULL} and \code{use_robust_start = TRUE}, robust starting values may be calculated automatically (see Details).}

\item{etastart}{Starting values for the linear predictor. As for \code{\link{glm.fit}}.}

\item{mustart}{Starting values for the mean. As for \code{\link{glm.fit}}.}

\item{offset}{An optional offset to be included in the model. As for \code{\link{glm.fit}}.}

\item{family}{A description of the error distribution and link function to be used in the model. As for \code{\link{glm.fit}}.}

\item{control}{A list of parameters for controlling the fitting process. As for \code{\link{glm.fit}}.}

\item{intercept}{A logical value indicating whether an intercept should be included in the model, default is \code{TRUE}. As for \code{\link{glm.fit}}.}

\item{use_parallel}{Logical. If \code{TRUE}, enables parallel execution of the fitting process.
Defaults to \code{TRUE}. Set to \code{FALSE} for serial execution.}

\item{use_robust_start}{Logical. If \code{TRUE}, uses an optimization-based approach (via the \pkg{CVXR} package) to calculate robust starting values for fragile link functions (e.g., "log", "sqrt"). Defaults to \code{FALSE} to save computational time, as standard initialization works well for most typical datasets.}
}
\value{
The value returned by \code{savvy_glm.fit2} has the same structure as the value returned by \code{glm.fit}. It includes the following components:
\item{coefficients}{the estimated coefficients.}
\item{residuals}{the working residuals, that is the residuals in the final iteration of the IWLS fit.}
\item{fitted.values}{the fitted mean values, obtained by transforming the linear predictors by the inverse of the link function.}
\item{R}{the upper-triangular factor of the QR decomposition of the weighted model matrix.}
\item{rank}{the numeric rank of the fitted linear model.}
\item{qr}{the QR decomposition of the weighted model matrix.}
\item{family}{the family object used.}
\item{linear.predictors}{the final linear predictors.}
\item{deviance}{the deviance of the final model.}
\item{aic}{the AIC of the final model.}
\item{null.deviance}{the deviance for the null model.}
\item{iter}{the number of iterations used.}
\item{weights}{the final weights used in the fitting process.}
\item{prior.weights}{the weights initially supplied.}
\item{df.residual}{the residual degrees of freedom.}
\item{df.null}{the residual degrees of freedom for the null model.}
\item{y}{the response vector used.}
\item{converged}{a logical value indicating whether the IRLS iterations converged.}
\item{boundary}{a logical value indicating whether the algorithm stopped at a boundary value.}
\item{time}{the time taken for the fitting process.}
\item{chosen_fit}{the name of the chosen fitting method based on AIC.}
}
\description{
\code{savvy_glm.fit2} is a modified version of \code{glm.fit} that enhances the standard iteratively reweighted least squares (IRLS) algorithm by incorporating a set of shrinkage estimator functions.
These functions (namely \code{St_ost}, \code{DSh_ost}, \code{SR_ost}, \code{GSR_ost}, \code{LW_est}, \code{QIS_est}, and optionally \code{Sh_ost}) provide alternative coefficient updates based on shrinkage principles.
The function allows the user to select one or more of these methods via the \code{model_class} argument. Additionally, it optionally implements a robust optimization-based method to find starting values for fragile link functions.
}
\details{
\code{savvy_glm.fit2} extends the classical Generalized Linear Model (GLM) fitting procedure by evaluating a collection of shrinkage-based updates during each iteration of the IRLS algorithm.
When multiple shrinkage methods are specified in \code{model_class} (the default is \code{c("St", "DSh", "SR", "GSR", "LW", "QIS")}, thereby excluding \code{"Sh"} unless explicitly provided),
if the user explicitly includes \code{"Sh"} (for example, \code{model_class = c("St", "DSh", "SR", "GSR", "LW", "QIS", "Sh")} or \code{model_class = c("St", "Sh")}),
then the method \code{Sh_ost} is also evaluated.

The function can run these candidate methods in parallel (if \code{use_parallel = TRUE}). The final model is selected based on the lowest AIC.
In cases where any candidate model returns an \code{NA} or non-finite AIC (which may occur when using quasi-likelihood families),
the deviance is used uniformly as the model-selection criterion instead.

\strong{Robust Starting Values:}
In situations where the user does not provide \code{start}, \code{etastart}, or \code{mustart}, and the chosen \code{family} utilizes a fragile link function
(specifically \code{"log"}, \code{"sqrt"}, \code{"inverse"}, \code{"1/mu^2"}, or bounded links like \code{"logit"}), standard GLM initialization can lead to infinite deviance or immediate divergence.
If \code{use_robust_start = TRUE}, \code{savvy_glm.fit2} employs a novel, data-driven optimization approach using the \pkg{CVXR} package to calculate stable starting coefficients (\code{start}).
This process minimizes the squared difference between the linear predictor and a safely transformed target mean, enforcing positivity constraints strictly when required by the link function.

In essence, the function starts with initial estimates (either robustly generated or user-supplied)
and iteratively updates the coefficients using the chosen shrinkage method(s).
The incorporation of these shrinkage estimators aims to improve convergence properties and to yield more stable or parsimonious models under various data scenarios.

\strong{Shrinkage Estimators Used in the IRLS Algorithm:}
\describe{
  \item{\strong{Stein Estimator (St)}}{Computes a single multiplicative shrinkage factor applied uniformly to all coefficients. 
  The factor is chosen to minimize the overall mean squared error (MSE) of the OLS estimator. It is best suited when the 
  predictors are similarly scaled so that uniform shrinkage is appropriate.}

  \item{\strong{Diagonal Shrinkage (DSh)}}{Extends the Stein estimator by calculating an individual shrinkage factor for each coefficient. 
  Each factor is derived from the magnitude and variance of the corresponding coefficient, providing enhanced flexibility when 
  predictor scales or contributions differ.}

  \item{\strong{Simple Slab Regression (SR)}}{Penalizes the projection of the OLS estimator along a fixed, predefined direction. 
  It uses a closed-form solution under a slab (fixed-penalty) constraint, making it suitable when prior information suggests 
  shrinking the coefficients along a known direction.}

  \item{\strong{Generalized Slab Regression (GSR)}}{Generalizes SR by incorporating multiple, data-adaptive shrinkage directions. 
  It typically employs the leading eigenvectors of the design matrix as the directions, providing adaptive regularization that 
  effectively handles multicollinearity.}

  \item{\strong{Ledoit-Wolf Linear Shrinkage (LW)}}{Implements linear shrinkage towards a one-parameter matrix where all variances 
  are equal and all covariances are zero. This provides a well-conditioned estimator for large-dimensional covariance matrices, 
  based on the methodology of Ledoit and Wolf (2004b).}

  \item{\strong{Quadratic-Inverse Shrinkage (QIS)}}{A nonlinear shrinkage estimator derived under Frobenius loss, Inverse Stein's loss, 
  and Minimum Variance loss. It is highly effective for large covariance matrices and is based on the quadratic shrinkage approach 
  of Ledoit and Wolf (2022).}

  \item{\strong{Shrinkage Estimator (Sh)}}{Computes a non-diagonal shrinkage matrix by solving a \emph{Sylvester equation}. 
  It transforms the OLS estimator to achieve a lower mean squared error. This estimator is evaluated only when \code{"Sh"} is 
  explicitly included in the \code{model_class} argument.}
}
}
\examples{
# Example 1: Standard Poisson regression with log link
set.seed(123)
n <- 100
p <- 5
X <- cbind(1, matrix(rnorm(n * p), n, p))
true_beta <- c(0.5, -0.2, 0.1, 0, 0, 0)

mu <- exp(X \%*\% true_beta)
y <- rpois(n, lambda = mu)

# Fit using savvy_glm.fit2 with the Stein (St) estimator
fit1 <- savvy_glm.fit2(x = X, y = y,
                       family = poisson(link = "log"),
                       model_class = "St")

print(fit1$coefficients)

# Example 2: Demonstrating Robust Starting Values for a Quadratic Link
eta <- abs(X \%*\% true_beta) + 1
mu_quad <- eta^2

# Generate Poisson data using the quadratic mean
y_quad <- rpois(n, lambda = mu_quad)
fit2 <- savvy_glm.fit2(x = X, y = y_quad,
                       family = poisson(link = "sqrt"),
                       model_class = c("SR", "St", "LW"),
                       use_parallel = TRUE,
                       use_robust_start = TRUE)

print(fit2$chosen_fit)
print(fit2$coefficients)

}
\references{
Marschner, I. C. (2011). \emph{glm2: Fitting Generalized Linear Models with Convergence Problems}.
The R Journal, 3(2), 12–15. \doi{10.32614/RJ-2011-012}

Asimit, V., Avramescu, O., Chen, Z., Rivas, D., & Senatore, C. (2026). \emph{GLM Solutions via Shrinkage}.

Asimit, V., Cidota, M. A., Chen, Z., & Asimit, J. (2025). \emph{Slab and Shrinkage Linear Regression Estimation}.
Retrieved from \url{https://openaccess.city.ac.uk/id/eprint/35005/}.

Ledoit, O. and Wolf, M. (2004). \emph{A well-conditioned estimator for large-dimensional covariance matrices}.
Journal of Multivariate Analysis, 88(2):365–411. \doi{10.1016/S0047-259X(03)00096-4}

Ledoit, O. and Wolf, M. (2022). \emph{Quadratic shrinkage for large covariance matrices}.
Bernoulli, 28(3): 1519-1547. \doi{10.3150/20-BEJ1315}
}
\seealso{
\code{\link[stats]{glm.fit}}, \code{\link[stats]{glm}}, \code{\link[glm2]{glm.fit2}}
}
\author{
Ziwei Chen, Vali Asimit and Claudio Senatore\cr
Maintainer: Ziwei Chen <Ziwei.Chen.3@citystgeorges.ac.uk>
}
\keyword{models}
\keyword{regression}
