% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/shash.R
\name{gradient_shash}
\alias{gradient_shash}
\title{Analytic gradient of the negative log-likelihood for a shash regression model}
\usage{
gradient_shash(
  params,
  X_mu,
  X_sigma,
  X_epsilon,
  X_delta = NULL,
  y,
  weights = NULL,
  fixed_delta = NULL
)
}
\arguments{
\item{params}{A numeric vector containing all model parameters}

\item{X_mu}{Design matrix for location parameter}

\item{X_sigma}{Design matrix for scale parameter}

\item{X_epsilon}{Design matrix for skewness parameter}

\item{X_delta}{Design matrix for tail weight parameter (or NULL for fixed delta)}

\item{y}{Response vector}

\item{weights}{Observation weights}

\item{fixed_delta}{If not NULL, the delta parameter is fixed to this value}
}
\value{
Numeric vector: gradient of the negative log-likelihood with
  respect to \code{params}.
}
\description{
Computes the exact gradient of \code{\link{log_likelihood_shash}} with
respect to all regression coefficients. Supplying this gradient to
\code{\link[stats]{optim}} (method \code{"L-BFGS-B"}) avoids costly and
noisy finite-difference approximations, typically yielding a speedup
and more reliable convergence.
}
\details{
With \eqn{z = (y - \mu)/\sigma} and \eqn{A = \delta \, \mathrm{asinh}(z) + \epsilon},
the per-observation log-density is
\deqn{\ell = \log\delta - \log\sigma - \tfrac{1}{2}\log(2\pi)
  - \tfrac{1}{2}\log(1+z^2) - \tfrac{1}{2}\sinh^2(A) + \log\cosh(A).}
The gradient uses the chain rule through the linear predictors:
\deqn{\partial\ell/\partial A = \tanh(A) - \sinh(A)\cosh(A)}
\deqn{\partial\ell/\partial z = -z/(1+z^2) + (\partial\ell/\partial A)\,\delta/\sqrt{1+z^2}}
\deqn{\partial\ell/\partial\mu = -(\partial\ell/\partial z)/\sigma}
\deqn{\partial\ell/\partial\log\sigma = -1 - z\,(\partial\ell/\partial z)}
\deqn{\partial\ell/\partial\epsilon = \partial\ell/\partial A}
\deqn{\partial\ell/\partial\log\delta = 1 + (\partial\ell/\partial A)\,\delta\,\mathrm{asinh}(z)}
Coefficient gradients follow as \eqn{-X^\top (w \cdot \partial\ell/\partial\eta)}
for the negative log-likelihood. Contributions of observations whose linear
predictor is clamped (see \code{log_likelihood_shash}) are zeroed, which is
the exact subgradient of the clamped objective. In extreme regions where
\eqn{\sinh(A)\cosh(A)} would overflow, the gradient magnitude is capped at
a large finite value; these regions coincide with the penalty branch of the
objective, so the capped direction remains correct.
}
\keyword{internal}
