Skip to contents

Full unstructured spatial trait covariance: spatial_dep(0 + trait | coords)

Source: R/brms-sugar.R
spatial_dep.Rd

Canonical name for the full unstructured cross-trait spatial covariance \(\boldsymbol\Sigma_{\text{spa}} \otimes \mathbf{Q}^{-1}\), with \(T(T+1)/2\) free parameters (\(\boldsymbol\Sigma_{\text{spa}}\) parameterised via Cholesky). Mathematically identical to spatial_latent(0 + trait | coords, d = T) standalone; the keyword choice is documentary.

Usage

spatial_dep(formula, coords = NULL, mesh = NULL, rho = 1)

Arguments

formula

0 + trait | coords style formula (LHS is the trait factor 0 + trait; RHS is the coords placeholder symbol that points at the make_mesh() coordinate columns).

coords

Character; the column-name pair of spatial coordinates in data (e.g. c("lon", "lat")). Resolved by the parser when supplied as keyword argument; NULL when the orientation expresses the coordinates via the formula RHS.

mesh

An fmesher mesh object built via make_mesh(). It may be supplied here or through the top-level mesh = argument to gllvmTMB(). The engine does not construct a mesh automatically from coords.

rho

Source-strength attenuation between 0 and 1, or NULL to estimate it in a complete replicated multivariate Gaussian model without competing covariance. Omitted or explicit 1 preserves the existing model. Range remains a separate estimated parameter. Attenuation preserves the projected marginal variance at each modeled location and applies to the whole trait covariance, including Psi. The grouping column must identify locations consistently across replicates. Estimated latent models require rank one and at least four traits. The frozen spatial study found no passing recovery cell (14 partial and 2 blocked); rho intervals remain unvalidated. new-location prediction is not supported for attenuated models.

Value

A formula marker; never evaluated.

Details

Use spatial_dep() when you want an explicit full-unstructured cross-trait spatial covariance fit. Use spatial_latent() for the rank-reduced K-factor model. Use spatial_indep() for the marginal-only per-trait spatial fit.

Formula orientation

Same convention as the rest of the spatial_* keywords: the canonical orientation is 0 + trait | coords (LHS = trait factor, RHS = the coords placeholder). spatial_dep is born with this orientation; the legacy coords | trait form is not accepted.

Mutual exclusion with spatial_latent() / spatial_indep()

Combining spatial_dep(0 + trait | coords) with spatial_latent is over-parameterised; combining with spatial_indep is redundant. The parser raises cli::cli_abort() in any of these cases.

See also

spatial_latent(), spatial_indep(), dep(), phylo_dep(), extract_Sigma().

Examples

if (FALSE) { # \dontrun{
  sim <- simulate_site_trait(
    n_sites = 30, n_species = 6, mean_species_per_site = 5,
    spatial_range = 0.4, sigma2_spa = rep(0.3, 6), seed = 1
  )
  mesh <- make_mesh(sim$data, c("lon", "lat"), cutoff = 0.1)
  fit <- gllvmTMB(
    value ~ 0 + trait +
            spatial_dep(0 + trait | site, mesh = mesh),
    data  = sim$data,
    trait = "trait",
    unit  = "site"
  )
} # }