% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/HelperFunctions.R
\name{reml_grad_from_dV}
\alias{reml_grad_from_dV}
\title{Evaluate the REML gradient with respect to a single correlation parameter}
\usage{
reml_grad_from_dV(dV, model_fit, glm_weight_function, ...)
}
\arguments{
\item{dV}{\eqn{N \times N} numeric matrix giving
\eqn{\partial\mathbf{V}/\partial\rho} for one scalar parameter
\eqn{\rho}, with the chain rule through any reparameterization already
applied.}

\item{model_fit}{A fitted \code{lgspline} object; see
\code{\link{lgspline}}.}

\item{glm_weight_function}{The GLM weight function used during model
fitting; see the \code{glm_weight_function} argument of
\code{\link{lgspline}}.}

\item{...}{Additional arguments forwarded to \code{glm_weight_function}.}
}
\value{
A scalar: the gradient of the negative REML objective with respect
  to \eqn{\rho}, divided by \eqn{N}.
}
\description{
Computes the derivative of the negative REML objective with respect to a
scalar correlation parameter, given the matrix derivative
\eqn{\partial \mathbf{V}/\partial \rho}.
}
\details{
\subsection{Notation}{
\eqn{\mathbf{D} = \mathrm{diag}(d_1,\ldots,d_N)} is the diagonal matrix of
observation weights (\code{observation_weights}), and
\eqn{\mathbf{W} = \mathrm{diag}(w_1,\ldots,w_N)} is the diagonal matrix of
GLM working weights evaluated at the current fitted values via
\code{glm_weight_function}, with the observation-weight contribution
carried separately by \eqn{\mathbf{D}}.  For canonical GLM families,
\eqn{w_i} is the usual IRWLS/Fisher-scoring weight on the mean--variance
scale; for example, logistic regression gives
\eqn{w_i = \mu_i(1-\mu_i)}.  The combined weighting entering the
information matrix is \eqn{\mathbf{W}\mathbf{D}}.  In Gaussian identity
models both reduce to scalar multiples of the identity.

\eqn{\mathbf{V}} is the \eqn{N \times N} correlation matrix implied by
\code{VhalfInv}, with
\eqn{\mathbf{V}^{-1} = (\mathbf{V}^{-1/2})^\top \mathbf{V}^{-1/2}}.

The penalized observed information at the current iterate is
\deqn{\mathbf{M} = (\mathbf{X}^*)^\top
  \mathbf{V}^{-1}\mathbf{W}\mathbf{D}\,\mathbf{X}^*
  + \mathbf{U}^\top\boldsymbol{\Lambda}\mathbf{U},}
where \eqn{\mathbf{X}^* = \mathbf{X}\mathbf{U}} is the constrained design
(\eqn{N \times P}) and the first term is the quadratic approximation to the
penalized log-likelihood Hessian at the current \eqn{\boldsymbol{\mu}}.
For non-Gaussian families this is a local approximation (the IRWLS/Fisher
scoring Hessian), not an exact GLS information matrix.

The constraint projection is
\eqn{\mathbf{U} = \mathbf{I} -
  \mathbf{G}\mathbf{A}(\mathbf{A}^\top\mathbf{G}\mathbf{A})^{-1}
  \mathbf{A}^\top}
with \eqn{\mathbf{G} = \mathbf{M}^{-1}}.
\eqn{\mathbf{U}} is idempotent (\eqn{\mathbf{U}^2 = \mathbf{U}}) but
\emph{not} symmetric, so
\eqn{\mathbf{U}^\top\boldsymbol{\Lambda}\mathbf{U} \neq
  \mathbf{U}\boldsymbol{\Lambda}\mathbf{U}^\top}.

The \code{U} stored in \code{model_fit$U} is on the expansion- and
response-standardised scale.  The rescaled version used here is
\deqn{\tilde{\mathbf{U}} =
  \mathbf{U} \cdot \mathrm{diag}(1, s_1, \ldots, s_{p-1},
    1, s_1, \ldots) / \hat{\sigma}_y,}
where \eqn{s_j} are the expansion scales and \eqn{\hat{\sigma}_y}
standardises the response.  All quantities below use
\eqn{\tilde{\mathbf{U}}} in place of \eqn{\mathbf{U}}.
}

\subsection{REML objective and its gradient}{
The REML objective is constructed by integrating out the fixed effects from
the penalized log-likelihood, using a Laplace approximation to the
marginal likelihood for non-Gaussian families.  This approximation is exact
for Gaussian identity models and is the standard extension used in
restricted maximum likelihood estimation for GLMMs.

The REML correction term is
\eqn{-\tfrac{1}{2}\log|\mathbf{M}|}, where \eqn{\mathbf{M}} is the
penalized observed information defined above.  Differentiating with respect
to \eqn{\rho} (noting only \eqn{\mathbf{V}} depends on \eqn{\rho})
gives the REML correction gradient
\deqn{-\frac{1}{2}\mathrm{tr}\!\Bigl(
  \mathbf{M}^{-1}
  (\mathbf{X}^*)^\top\mathbf{V}^{-1}
  \frac{\partial\mathbf{V}}{\partial\rho}
  \mathbf{V}^{-1}\mathbf{W}\mathbf{D}\,\mathbf{X}^*
  \Bigr).}
}

\subsection{Full gradient}{
\deqn{\frac{\partial(-\ell_R)}{\partial\rho}
  = \frac{1}{N}\Biggl[
    \underbrace{
      \frac{1}{2}\mathrm{tr}\!\Bigl(
        \mathbf{V}^{-1}\frac{\partial\mathbf{V}}{\partial\rho}
      \Bigr)
    }_{\text{(i) log-det of }\mathbf{V}}
    \underbrace{
      -\frac{1}{2\tilde{\sigma}^2}
      \mathbf{r}^\top\frac{\partial\mathbf{V}}{\partial\rho}\mathbf{r}
    }_{\text{(ii) residual quadratic form}}
    \underbrace{
      -\frac{1}{2}\mathrm{tr}\!\Bigl(
        \mathbf{M}^{-1}(\mathbf{X}^*)^\top\mathbf{V}^{-1}
        \frac{\partial\mathbf{V}}{\partial\rho}
        \mathbf{V}^{-1}\mathbf{W}\mathbf{D}\,\mathbf{X}^*
      \Bigr)
    }_{\text{(iii) REML correction}}
  \Biggr],}
where the whitened residual is
\deqn{\mathbf{r} =
  \mathrm{diag}\!\left(\sqrt{d_i}/\sqrt{w_i}\right)
  \mathbf{V}^{-1/2}(\mathbf{y} - \boldsymbol{\mu}),}
and \eqn{r_i =
  [\mathbf{V}^{-1/2}(\mathbf{y}-\boldsymbol{\mu})]_i
  \sqrt{d_i}/\sqrt{w_i}}.

Term (i) does not involve \eqn{\mathbf{D}} or \eqn{\mathbf{W}}; the
log-determinant of \eqn{\mathbf{V}} depends only on the correlation
structure.  For non-Gaussian families terms (ii) and (iii) are evaluated
at the current IRWLS iterate and constitute a local approximation.
}
}
\seealso{
\code{\link{lgspline}}, \code{\link{lgspline.fit}}
}
