R/AllGeneric.R

In Biostatistics4SocialImpact/dlm: Distributed Lag Models for Built Environment Applications

## is.LagBasis <- function(object, ...)  inherits(object, "LagBasis")
## is.SmoothLag <- function(object, ...) inherits(object, "SmoothLag")
## is.dlMod <- function(object, ...)     inherits(object, "dlMod")

makeDlMod <- function(object, ...) UseMethod("makeDlMod", object)



#' @title Extract DLM parameter estimates
#'
#' @description Extract regression coefficients, variances, etc. from
#' fitted \code{\link{dlMod}} objects
#'
#' @param object
#'   a fitted \code{\link{dlMod}} object
#' @param scaled
#'   if \code{TRUE} (the default), any lag parameters are scaled for
#'   more natural interpretation (see Details)
#' @param ...
#'   additional arguments
#'
#' @usage
#' coef(object, ...)
#'
#' confint(object, ...)
#'
#' @details
#' Other typical methods like
#' \code{residuals}, and \code{sigma}, etc. are handled via inheritance
#' from \pkg{lme4} classes.
#' If the argument \code{scaled = TRUE}, parameter estimates are scaled
#' by the areas between radii and summed so that they can be interpreted
#' as the estimate up to a given radius (e.g. see the \pkg{dlmBE}
#' \link[=dlmBE-package]{package documentation}).
#'
#' \describe{
#'   \item{\code{coef.dlMod}}{follows the format of
#'     \code{lme4::\link[lme4]{coef.merMod}} to return the sums of fixed
#'     and random effects for each level and grouping factor}
#'   \item{\code{confint.dlMod}}{returns confidence intervals for regression
#'     coefficients following \code{stats::\link[stats]{confint}}}
#'   \item{\code{Sigma}}{returns the regression coefficient covariance matrix.
#'     Row and column indices are in the same order as \code{vcoef} (see below)}
#'   \item{\code{vcoef}}{returns vectorized coefficients from the fitted
#'     model. Fixed effects come before distributed lag coefficients, which
#'     come before other random effects coefficients. For example, if
#'     \eqn{\beta} is a vector of fixed effects; \eqn{\theta_1} and
#'     \eqn{\theta_2} are vectors of (separately penalized) DL coefficients;
#'     and \eqn{b_1}, \eqn{b_2}, \eqn{\ldots}{...} are additional random
#'     effects vectors for groups \eqn{1, 2, \ldots}{1, 2, ...}, then
#'     \code{vcoef} will return the (named) vector
#'     \eqn{(\beta^T, \theta_1^T, \theta_2^T, b_1^T, b_2^T, \ldots)^T}{(\beta', \theta_1', \theta_2', b_1', b_2', ...)'}.
#'     \code{vcoef0} returns the same coefficient vector
#'     but without names (and is slightly faster).}
#' }
#'
#' @return All of these functions return \code{numeric} data
#'
#' @name estimands
NULL


#' @rdname estimands
setGeneric("Sigma", function(object, ...) standardGeneric("Sigma"))

#' @rdname estimands
setGeneric("vcoef", function(object, ...) standardGeneric("vcoef"))

#' @rdname estimands
setGeneric("vcoef0", function(object, ...) standardGeneric("vcoef0"))



#' @rdname lagIndex
setGeneric("lagIndex", function(object, ...) standardGeneric("lagIndex"))

#' @rdname scaleMat
setGeneric("scaleMat",
           function(object, ...) standardGeneric("scaleMat")
           )

#' @rdname changePoint
setGeneric("changePoint", function(object, ...) standardGeneric("changePoint"))



## omega
## -------------------------------------------------------------------
#' @title Extract lag basis matrix
#' @inheritSection basis Decomposition
#'
#' @description
#' Extract lag basis matrix, \eqn{\Omega = [C_0, K_1]}. See
#' the definition below (which is borrowed from \code{\link{basis}})
#'
#' @param object
#'   An object storing details of the basis decomposition
#' @param ...
#'   additional arguments
#'
#' @return
#' A square numeric matrix
#'
#' @name omega
setGeneric("omega", function(object, ...) standardGeneric("omega"))




## cholfVar
## -------------------------------------------------------------------
#' @title Extract Cholesky factor of inverse Information matrix
#'
#' @description
#' Computes the Cholesky factor, \eqn{L}, of the inverse of the
#' Fisher Information matrix for all regression coefficients in
#' a fitted model. The coefficient covariance matrix can then be
#' computed as \eqn{L L^T}{L * L'}. While advanced users may find this
#' function useful for extending \pkg{dlmBE} functionality, typical
#' workflow should not need to call \code{cholfVar} methods directly.
#'
#' @param object
#'   a fitted model object
#' @param ...
#'   additional arguments
#'
#' @return A square numeric matrix represented as a
#' \code{Matrix::\link[Matrix]{sparseMatrix}} object
#'
#' @name cholfVar
setGeneric("cholfVar", function(object, ...) standardGeneric("cholfVar"))


#' @section Method for 'merMod' objects:
#' For a mixed-effects model of the form, for example,
#' \deqn{g(E(Y_i | b_i)) = X \beta + Z_i b_i}{g(E(Y_i | b_i)) = X * \beta + Z_i * b_i}
#' with link function \eqn{g(\cdot)}{g()}, and
#' \eqn{b_i \sim \mathrm{N}(0, \Sigma_b)}{b_i ~ N(0, \Sigma_b)}, the Cholesky
#' factor returned will be such that
#' \eqn{L L^T = I^{-1}(\hat{\theta})}{L * L' = I^-1(\hat{\theta})}, where
#' \eqn{\hat{\theta} = (\hat{\beta}^T, \hat{b}_1^T, \hat{b}_2^T, \ldots)^T}{\hat{\theta} = (\hat{\beta}', \hat{b}_1', \hat{b}_2', ...)'},
#' and \eqn{I(\hat{\theta})} is the estimated Fisher information at
#' \eqn{\hat{\theta}}.
#' @rdname cholfVar
setMethod("cholfVar", signature = "merMod",
  function(object, ...) {
    p <- lme4::getME(object, "p")
    q <- lme4::getME(object, "q")
    RZi <- t(solve(lme4::getME(object, "L"), Matrix::Diagonal(q), "L"))
    RXi <- solve(lme4::getME(object, "RX"))
    RZXi <- -RZi %*% lme4::getME(object, "RZX") %*% RXi
    Lambda <- lme4::getME(object, "Lambda")
    L <- Matrix::bdiag(RXi, Lambda %*% RZi)
    L[(p + 1):nrow(L), 1:p] <- Lambda %*% RZXi
    sigma(object) * L
  })