spatiotemporal: Spatiotemporal interaction specifications for tulpa

In tulpa: Templated Unified Library for Posterior Approximation in Bayesian Hierarchical Models

Spatiotemporal interaction specifications for tulpa

Description

Functions to specify spatiotemporal interaction effects for tulpa models. These capture dependencies that arise when spatial patterns vary over time, or when temporal trends differ across space.

Specify a spatiotemporal interaction effect for tulpa models. The interaction captures structured or unstructured deviation from the additive spatial + temporal model.

No tulpa backend fits an interaction term, so this constructor errors. The additive space-time model is fitted by tulpa(spatial = , temporal = ) and by fit_st_nested().

Usage

spatiotemporal(
  spatial,
  temporal,
  type = c("I", "II", "III", "IV", "iid", "separable"),
  shared = NULL
)

Arguments

spatial	A spatial specification from spatial_car(), spatial_bym2(), or spatial_gp().
temporal	A temporal specification from temporal_rw1(), temporal_rw2(), temporal_ar1(), or temporal_gp().
type	Interaction type: "I" or "iid": Unstructured interaction (IID) "II": Structured time at each location "III": Structured space at each time point "IV": Fully structured (Kronecker product of spatial and temporal) "separable": Separable covariance (Kronecker product)
shared	Logical; if TRUE (default), spatiotemporal effect enters both all processes. Set to FALSE for process-specific effects (triggers warning about potential confounding).

Details

Spatiotemporal interactions extend the basic additive model:

\eta_{st} = X\beta + f_s(space) + f_t(time)

to include interactions:

\eta_{st} = X\beta + f_s(space) + f_t(time) + \delta_{st}

where \delta_{st} captures space-time interactions.

Interaction Types (following Knorr-Held, 2000):

• Type I: Unstructured interaction - IID \delta_{st} \sim N(0, \sigma^2)

• Type II: Structured time, unstructured space - temporal structure at each location

• Type III: Structured space, unstructured time - spatial structure at each time

• Type IV: Structured space AND time - full Kronecker interaction

Separable Models:

• Separable: Covariance is Kronecker product C_{st} = C_s \otimes C_t

• Non-separable: GP with joint space-time metric

Type I (IID)

Independent random effect for each space-time combination:

\delta_{st} \stackrel{iid}{\sim} N(0, \sigma^2_\delta)

This is the simplest form, requiring S*T parameters but capturing no structured interaction.

Type II (Temporal structure per location)

Each location has its own temporal random effect:

\delta_{\cdot t}^{(s)} \sim RW(\sigma^2)

This captures location-specific temporal trends but assumes independence across locations.

Type III (Spatial structure per time point)

Each time point has its own spatial random effect:

\delta_{s \cdot}^{(t)} \sim ICAR(\tau)

This captures time-specific spatial patterns but assumes independence across time points.

Type IV (Full structure)

Kronecker product of spatial and temporal precision matrices:

Q_\delta = Q_s \otimes Q_t

This is the most constrained model, assuming the interaction has the same structure as the marginal effects.

Separable

For GP-based effects, assumes separable covariance:

C(\mathbf{s}_1, t_1; \mathbf{s}_2, t_2) = C_s(\mathbf{s}_1, \mathbf{s}_2) \cdot C_t(t_1, t_2)

Value

Nothing: the call always signals an error.

References

Knorr-Held, L. (2000). Bayesian modelling of inseparable space-time variation in disease risk. Statistics in Medicine, 19(17-18), 2555-2567.

See Also

spatial_car(), spatial_gp(), temporal_rw1(), temporal_ar1()

Examples

adj <- matrix(0, 4, 4)
for (i in 1:3) adj[i, i + 1] <- adj[i + 1, i] <- 1
# No backend fits an interaction term, so the constructor refuses; the
# additive model is tulpa(spatial = , temporal = ).
try(spatiotemporal(spatial_car(adj, group_var = "region"),
                   temporal_rw1("year"), type = "IV"))

tulpa documentation built on Oct. 19, 2026, 5:09 p.m.