Skip to contents

Temporally-Varying Coefficients (TVC)

Source: R/temporal.R
temporal_tvc.Rd

Specify temporally-varying coefficients for ratio models. TVCs allow regression coefficients to change smoothly over time using a Gaussian process or random walk prior. This captures how effects evolve temporally.

Usage

temporal_tvc(
  time_var,
  terms = 1,
  structure = c("rw1", "rw2", "ar1", "iid", "gp"),
  group_var = NULL,
  shared = TRUE
)

Arguments

time_var

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

terms

Which coefficients should vary over time. Options:

  • Integer vector: Column indices of design matrix (1 = intercept)

  • Character vector: Coefficient names (e.g., "(Intercept)", "depth")

  • Formula: ~ 1 + depth for intercept and depth

structure

Temporal structure for the varying coefficients:

  • "rw1": First-order random walk (default)

  • "rw2": Second-order random walk (smoother)

  • "ar1": First-order autoregressive

  • "iid": Independent draws at each time point (no temporal smoothing)

  • "gp": Gaussian process (for irregular time spacing). Not yet implemented; temporal_tvc() errors if selected.

group_var

Optional name of grouping variable for panel data.

shared

Logical; if TRUE (default), TVC effects enter both numerator and denominator. Set to FALSE for process-specific TVCs (triggers warning about potential confounding).

Value

A ratiod_tvc object

Details

The TVC model extends the linear predictor:

$$\eta(t) = X\beta + \tilde{X}(t)w(t)$$

where:

  • \(\beta\) are global (non-time-varying) coefficients

  • \(\tilde{X}(t)\) is the subset of covariates with TVCs

  • \(w(t)\) are time-varying adjustments

Each TVC follows a temporal process: $$w_j(t) \sim RW1(\sigma_j^2) \text{ or other temporal structure}$$

Interpretation: A positive TVC for depth at time t means the depth effect is stronger at t than the global average. The temporal variance \(\sigma^2_j\) quantifies how much the effect varies over time.

Identifiability: TVCs are centered (sum-to-zero constraint) to separate the time-varying component from the global effect.

See also

spatial_svc() for spatially-varying coefficients, temporal_rw1() for temporal random effects, tvc() for extracting TVC posteriors

Examples

# Create TVC specification
tvc <- temporal_tvc("year", terms = 1)
print(tvc)
#> tulpaRatio temporally-varying coefficients
#> ======================================
#> 
#> Time variable: year 
#> Structure: RW1 (first-order random walk) 
#> Shared: Yes (enters both processes) 
#> 
#> Terms: columns  1 

if (FALSE) { # \dontrun{
# Generate synthetic data with time-varying effect (not run - TVC experimental)
set.seed(150)
df <- data.frame(
  year = rep(2010:2025, each = 5),
  x = rnorm(80),
  count = rpois(80, lambda = 20),
  effort = rgamma(80, shape = 4, rate = 1)
)

# Time-varying intercept (random temporal field)
fit <- tratio(
  count | effort ~ x,
  data = df,
  family = ratiod_poisson_gamma(),
  tvc = temporal_tvc("year", terms = 1),
  mode = "hmc",
  control = list(iter = 200, warmup = 100, chains = 1)
)
summary(fit)

# Time-varying effect of x
fit2 <- tratio(
  count | effort ~ x,
  data = df,
  family = ratiod_poisson_gamma(),
  tvc = temporal_tvc("year", terms = c("(Intercept)", "x"), structure = "rw2"),
  mode = "hmc",
  control = list(iter = 200, warmup = 100, chains = 1)
)

# Extract and plot the time-varying coefficients
tvc_effects <- tvc(fit2)
plot(tvc_effects, "x")
} # }