# Covariance Structure

This vignette details the different covariance structures available in clustTMB.

## 0.1 Random Effect Covariance Matrices

Covariance | Notation | No..of.Parameters | Data.requirements
--- | --- | --- | ---
Spatial GMRF | gmrf | 2 | spatial coordinates
AR(1) | ar1 | 2 | unit spaced levels
Rank Reduction | rr(random = H) | JH - (H(H-1))/2 |
Spatial Rank Reduction | rr(spatial = H) | 1 + JH - (H(H-1))/2 | spatial coordinates

### 0.1.1 Spatial GMRF

clustTMB fits spatial random effects using a Gaussian Markov Random Field (GMRF). The precision matrix, \(Q\), of the GMRF is the inverse of a Matern covariance function and takes two parameters: 1) \(\kappa\), which is the spatial decay parameter and a scaled function of the spatial range, \(\phi = \sqrt{8}/\kappa\), the distance at which two locations are considered independent; and 2) \(\tau\), which is a function of \(\kappa\) and the marginal spatial variance \(\sigma^{2}\):

\[\tau = \frac{1}{2\sqrt{\pi}\kappa\sigma}.\] The precision matrix is approximated following the SPDE-FEM approach [@Lindgren2011], where a constrained Delaunay triangulation network is used to discretize the spatial extent in order to determine a GMRF for a set of irregularly spaced locations, i$.

\[\omega_{i} \sim GMRF(Q[\kappa, \tau])\]

#### 0.1.1.1 Spatial Example

Prior to fitting a spatial cluster model with clustTMB, users need to set up the constrained Delaunay Triangulation network using the R package, fmesher. This package provides a CRAN distributed collection of mesh functions developed for the package, R-INLA. For guidance on setting up an appropriate mesh, see Triangulation details and examples and Tools for mesh assessment from

In this example, the following mesh specifications were used:

    loc <- meuse[, 1:2]
    Bnd <- fmesher::fm_nonconvex_hull(as.matrix(loc), convex = 200)
    meuse.mesh <- fmesher::fm_mesh_2d(as.matrix(loc),
      max.edge = c(300, 1000),
      boundary = Bnd
    )

    ## Loading required namespace: INLA

Coordinates are converted to a spatial point dataframe and read into the clustTMB model, along with the mesh, using the spatial.list argument. The gating formula is specified using the gmrf() command:

    Loc <- sf::st_as_sf(loc, coords = c("x", "y"))
    mod <- clustTMB(
      response = meuse[, 3:6],
      family = lognormal(link = "identity"),
      gatingformula = ~ gmrf(0 + 1 | loc),
      G = 4, covariance.structure = "VVV",
      spatial.list = list(loc = Loc, mesh = meuse.mesh)
    )

    ## intercept removed from gatingformula
    ##             when random effects specified

    ## spatial projection is turned off. Need to provide locations in projection.list$grid.df for spatial predictions

Models are optimized with nlminb(), model results can be viewed with nlminb commands:

    # Estimated fixed parameters
    mod$opt$par

    ##      betag      betag      betag      betad      betad      betad      betad
    ##  0.1810561  0.5594793  0.1898442  2.0157745  4.3160880  5.4259819  6.7095831
    ##      betad      betad      betad      betad      betad      betad      betad
    ##  1.0164082  3.6119034  5.2215817  6.2274867  0.1353846  3.1482198  4.2137115
    ##      betad      betad      betad      betad      betad      theta      theta
    ##  5.2614025 -1.4361504  3.1132966  4.2118588  5.1996568 -1.2100810 -2.9055386
    ##      theta      theta      theta      theta      theta      theta      theta
    ## -1.2794746 -1.2502187 -2.5718215 -3.1310896 -2.2406099 -2.3780380 -1.8212760
    ##      theta      theta      theta      theta      theta      theta      theta
    ## -4.0603269 -2.6424666 -3.0432260 -2.4648411 -3.3381004 -2.7804404 -2.6686130
    ##  ln_kappag
    ## -5.9346215

    # Minimum negative log likelihood
    mod$opt$objective

    ## [1] 2318.922

## 0.2 Gating Network Examples

When random effects, \(\mathbb{u}\), are specified in the gating network, the probability of cluster membership \(\pi_{i,g}\) for observation \(i\) is fit using multinomial regression:

\[ \begin{align} \mathbb{\eta}_{,g} &= X\mathbb{\beta}_{,g} + \mathbb{u}_{,g} \\ \mathbb{\pi}_{,g} &= \frac{ exp(\mathbb{\eta}_{,g})}{\sum^{G}_{g=1}exp(\mathbb{\eta}_{,g})} \end{align} \]