R/estimation-helpers.R

Defines functions .gpvam_information .gpvam_update_residual .gpvam_residual_diagonal .gpvam_estep

Documented in .gpvam_estep .gpvam_information .gpvam_residual_diagonal .gpvam_update_residual

#' Conditional or prediction-error moments for an LMM E-step
#'
#' @param X,Y,Z Fixed-effects design, response, and random-effects design.
#' @param R_inv,G Residual precision and random-effects covariance matrices.
#' @param ybetas Current fixed-effects coefficients (ML).
#' @param REML Use prediction-error moments and generalized least squares.
#' @param profile Recompute generalized least squares even for ML.
#' @return Random-effect covariance with mean, likelihood, and covariance blocks
#'   attached as attributes.
#' @keywords internal
.gpvam_estep <- function(X, Y, Z, R_inv, ybetas, G, REML = FALSE, profile = REML) {
    G.chol <- chol(G)
    G.inv <- chol2inv(G.chol)
    H <- forceSymmetric(crossprod(Z, R_inv) %*% Z + G.inv)
    H.chol <- chol(H)
    H.inv <- chol2inv(H.chol)
    B <- crossprod(X, R_inv) %*% Z
    BH <- B %*% H.inv
    S <- forceSymmetric(symmpart(crossprod(X, R_inv) %*% X - BH %*% t(B)))
    S.chol <- chol(S)
    betacov <- chol2inv(S.chol)
    C12 <- -betacov %*% BH
    if (profile) {
        ybetas <- as.vector(betacov %*% (crossprod(X, R_inv) %*% Y -
                                       BH %*% crossprod(Z, R_inv) %*% Y))
    }
    if (REML) {
        covariance <- H.inv + t(BH) %*% betacov %*% BH
    } else {
        covariance <- H.inv
    }
    eta <- H.inv %*% crossprod(Z, R_inv) %*% (Y - X %*% ybetas)
    residual <- Y - X %*% ybetas - Z %*% eta
    likelihood <- -0.5 * (length(Y) - if (REML) ncol(X) else 0) * log(2 * pi) +
        sum(log(diag(chol(R_inv)))) - sum(log(diag(G.chol))) -
        sum(log(diag(H.chol))) -
        0.5 * as.numeric(crossprod(residual, R_inv) %*% residual +
                         crossprod(eta, G.inv) %*% eta)
    if (REML) likelihood <- likelihood - sum(log(diag(S.chol)))
    res <- as.matrix(covariance)
    attr(res, "eta") <- as.matrix(eta)
    attr(res, "ybetas") <- ybetas
    attr(res, "likelihood") <- likelihood
    attr(res, "betacov") <- as.matrix(betacov)
    attr(res, "C12") <- as.matrix(C12)
    attr(res, "h.inv") <- H.inv
    res
}

#' Diagonal residual second moments for a diagonal residual covariance
#'
#' @param X,Z,Y Design matrices and response.
#' @param ybetas,eta Fixed-effect estimates and random-effect predictions.
#' @param covariance Random-effect conditional or prediction-error covariance.
#' @param betacov,C12 Fixed-effect and fixed/random prediction-error blocks.
#' @param REML Include fixed-effect and cross-covariance terms.
#' @return A numeric vector of residual second moments.
#' @keywords internal
.gpvam_residual_diagonal <- function(X, Z, Y, ybetas, eta, covariance,
                                     betacov, C12, REML) {
    residual <- as.vector(Y - X %*% ybetas - Z %*% eta)
    result <- residual^2 + rowSums((Z %*% covariance) * Z)
    if (REML) result <- result + rowSums((X %*% betacov) * X) +
        2 * rowSums((X %*% C12) * Z)
    as.vector(result)
}

#' Update the within-student residual covariance
#'
#' Complete observations have a closed-form update. Incomplete patterns use
#' Cholesky coordinates so the covariance remains positive definite throughout
#' optimization of the expected residual log likelihood.
#' @param R_i Current residual covariance.
#' @param pattern.sum Pattern-specific summed residual second moments.
#' @param pattern.key Binary matrix of observed years by pattern.
#' @param pattern.countoverlength Numbers of students for each pattern.
#' @param patterns Indices of the observed patterns.
#' @return An updated positive-definite covariance matrix.
#' @keywords internal
.gpvam_update_residual <- function(R_i, pattern.sum, pattern.key,
                                    pattern.countoverlength, patterns) {
    n <- nrow(R_i)
    if (length(patterns) == 1L && all(pattern.key[patterns, ] == 1)) {
        return(forceSymmetric(Matrix(pattern.sum[[patterns]] /
                                     pattern.countoverlength[[patterns]])))
    }
    # Work on a correlation scale to keep response units out of optimization.
    scale <- sqrt(diag(R_i))
    S <- as.matrix(R_i) / outer(scale, scale)
    observed <- lapply(patterns, function(p) which(pattern.key[p, ] == 1))
    moments <- lapply(seq_along(patterns), function(k) {
        i <- observed[[k]]
        as.matrix(pattern.sum[[patterns[k]]]) / outer(scale[i], scale[i])
    })
    counts <- vapply(patterns, function(p) pattern.countoverlength[[p]], numeric(1))
    lower <- lower.tri(S, diag = TRUE)
    diagonal <- which(row(S)[lower] == col(S)[lower])
    encode <- function(S) {
        L <- t(chol(S))
        par <- L[lower]
        par[diagonal] <- log(par[diagonal])
        par
    }
    decode <- function(par) {
        par[diagonal] <- exp(par[diagonal])
        L <- matrix(0, n, n)
        L[lower] <- par
        L
    }
    objective <- function(par, gradient = FALSE) {
        L <- decode(par)
        covariance <- tcrossprod(L)
        value <- 0
        grad <- matrix(0, n, n)
        for (k in seq_along(patterns)) {
            i <- observed[[k]]
            ch <- tryCatch(chol(covariance[i, i, drop = FALSE]),
                           error = function(e) NULL)
            if (is.null(ch)) return(if (gradient) rep(0, length(par)) else Inf)
            precision <- chol2inv(ch)
            value <- value + counts[k] * sum(log(diag(ch))) +
                0.5 * sum(precision * moments[[k]])
            if (gradient) grad[i, i] <- grad[i, i, drop = FALSE] +
                0.5 * (counts[k] * precision - precision %*% moments[[k]] %*% precision)
        }
        if (!gradient) return(value)
        result <- (2 * grad %*% L)[lower]
        result[diagonal] <- result[diagonal] * diag(L)
        result
    }
    initial <- encode(S)
    fit <- stats::optim(initial, objective, function(par) objective(par, TRUE),
                        method = "BFGS", control = list(reltol = 1e-10, maxit = 200))
    if (!is.finite(fit$value) || fit$value > objective(initial) + 1e-8)
        stop("Residual covariance optimization failed to improve the EM objective")
    forceSymmetric(Matrix(tcrossprod(decode(fit$par)) * outer(scale, scale)))
}

#' Numerically differentiate the profile score in scale-free coordinates
#'
#' @param func Function returning the negative profile likelihood gradient.
#' @param x Covariance and optional persistence parameters.
#' @param scale Positive response-variance scale for covariance parameters.
#' @param unscaled Number of trailing, dimensionless persistence parameters.
#' @param method Numerical differentiation method.
#' @param ... Arguments passed to the score function.
#' @return Observed profile information in the original parameter units.
#' @keywords internal
.gpvam_information <- function(func, x, scale, unscaled = 0,
                               method = "Richardson", ...) {
    scales <- rep(scale, length(x))
    if (unscaled > 0) scales[seq.int(length(x) - unscaled + 1, length(x))] <- 1
    arguments <- list(...)
    score <- function(z) do.call(func, c(list(z * scales), arguments)) * scales
    for (attempt in 0:6) {
        step <- 1e-4 / 10^attempt
        ans <- tryCatch(suppressWarnings(numDeriv::jacobian(score, x / scales,
            method = method, method.args = list(eps = step, d = step))),
            error = function(e) NULL)
        if (!is.null(ans) && all(is.finite(ans)))
            return((ans + t(ans)) / (2 * outer(scales, scales)))
    }
    warning("Variance-component Hessian could not be evaluated at positive-definite perturbations.",
            call. = FALSE)
    matrix(NA_real_, length(x), length(x))
}

Try the GPvam package in your browser

Any scripts or data that you put into this service are public.

GPvam documentation built on Oct. 23, 2026, 1:06 a.m.