Gaussian Process temporal structure

Specify a Gaussian Process (GP) temporal random effect for irregularly-spaced or continuous time points. Unlike RW1/RW2/AR1 which assume equally-spaced observations, GP temporal effects model correlation as a function of time distance.

This is particularly useful for:

• Irregularly-spaced time series

• Continuous time (e.g., exact timestamps)

• Smooth temporal trends with uncertainty

Usage

temporal_gp(
  time_var,
  cov = c("exponential", "matern", "gaussian", "periodic"),
  nu = 1.5,
  period = NULL,
  group_var = NULL,
  shared = TRUE,
  scale_coords = TRUE,
  parameterization = c("noncentered", "centered")
)

Arguments

time_var

Name of the time variable in data. Can be a formula (e.g., ~ year) or a character string (e.g., "year"). Should be numeric (continuous time) or convertible to numeric.

cov

Covariance function: "exponential" (default, rough), "matern" (tunable smoothness), "gaussian" (very smooth), or "periodic" (for seasonal patterns).

nu

Smoothness parameter for Matern covariance. Common values:

• 0.5: Equivalent to exponential (rough)

• 1.5: Once differentiable (moderate smoothness)

• 2.5: Twice differentiable (smooth) Ignored for non-Matern covariance functions.

period

Period for periodic covariance (e.g., 12 for monthly, 365 for daily data with annual cycle). Only used when cov = "periodic".

group_var

Optional name of grouping variable for panel data. If provided, separate GPs are estimated for each group.

shared

Logical; if TRUE (default), temporal effect enters both numerator and denominator.

scale_coords

Logical; if TRUE (default), time values are scaled to unit variance before computing distances.

parameterization

Parameterization for GP effects: "noncentered" (default) stores z ~ N(0,1) and scales by covariance (better for weakly-informed effects); "centered" stores effects directly (better for strongly-informed effects).

Value

A ratiod_temporal_gp object

Details

The GP temporal model adds a time-correlated random effect:

$$\eta(t) = X\beta + f(t)$$

where \(f(t)\) follows a Gaussian process: $$f(t) \sim GP(0, \sigma^2 C(|t - t'|; \phi))$$

The correlation function \(C(d; \phi)\) depends on time distance \(d\):

• Exponential: \(C(d) = \exp(-d/\phi)\) - continuous but not differentiable

• Matern: Smooth with tunable roughness via \(\nu\)

• Gaussian: \(C(d) = \exp(-(d/\phi)^2)\) - infinitely differentiable

• Periodic: \(C(d) = \exp(-2\sin^2(\pi d/p)/\phi^2)\) - for seasonal data

Implementation: Uses a state-space representation for O(n) computational complexity when possible (exponential, Matern with half-integer nu).

See also

temporal_rw1(), temporal_ar1() for equally-spaced temporal effects, spatial_gp() for spatial GP effects

Examples

# Create GP temporal specification
temporal_gp("timestamp")
#> tulpaRatio Gaussian Process temporal specification
#> ==============================================
#> 
#> Time variable: timestamp 
#> Covariance: exponential 
#> Shared: Yes (enters both processes) 
temporal_gp("day", cov = "matern", nu = 1.5)
#> tulpaRatio Gaussian Process temporal specification
#> ==============================================
#> 
#> Time variable: day 
#> Covariance: matern (nu = 1.5) 
#> Shared: Yes (enters both processes) 
temporal_gp("month", cov = "periodic", period = 12)
#> tulpaRatio Gaussian Process temporal specification
#> ==============================================
#> 
#> Time variable: month 
#> Covariance: periodic (period = 12.0) 
#> Shared: Yes (enters both processes) 

if (FALSE) { # \dontrun{
# Irregularly-spaced time series (not run - GP temporal experimental)
set.seed(140)
times <- sort(runif(30, 0, 100))
df <- data.frame(
  time = times,
  x = rnorm(30),
  count = rpois(30, lambda = 20),
  effort = rgamma(30, shape = 4, rate = 1)
)

fit <- tratio(
  count | effort ~ x,
  data = df,
  family = ratiod_poisson_gamma(),
  temporal = temporal_gp("time"),
  control = list(iter = 200, warmup = 100, chains = 1)
)
} # }