AR1 Temporal Structure (First-Order Autoregressive)

Specify a first-order autoregressive temporal random effect. AR1 models temporal correlation where each time point depends on the previous one: phi[t] = rho * phi[t-1] + epsilon[t].

Unlike RW1/RW2, AR1 is a proper (stationary) model with an estimated autocorrelation parameter rho.

Usage

temporal_ar1(
  time_var,
  group_var = NULL,
  shared = TRUE,
  rho_prior = NULL,
  parameterization = c("centered", "noncentered")
)

Arguments

time_var: Name of the time variable in data. Can be a formula (e.g., ~ year) or a character string (e.g., "year").
group_var: Optional name of grouping variable for panel data. If provided, a separate AR1 process is estimated for each group.
shared: Logical; if TRUE (default), temporal effect enters both numerator and denominator linear predictors identically.
rho_prior: Prior on the autocorrelation, as a prior_beta() on (rho + 1) / 2. NULL takes the model-wide ratiod_priors(rho_temporal = ), which defaults to Beta(2, 2).
parameterization: Coordinate the field is sampled in. "centered" (default) samples the effects themselves; "noncentered" samples the N(0, I) innovations the AR1 recursion builds the effects from, so both the precision and rho reach the linear predictor through the transform. AR1 is proper and stationary, so this is a different construction from the intrinsic walks' sigma * A^-1 z.

Value

A ratiod_temporal object

Details

The AR1 process has marginal variance sigma^2 / (1 - rho^2) and correlation between time points t and s of rho^|t-s|.

The precision matrix is tridiagonal and full rank, so no constraints are needed.

rho is estimated on (-1, 1), the range every AR1 correlation in the package is sampled on, so an alternating series is reachable. The sampled coordinate is logit((rho + 1) / 2), which is what rho_prior places its Beta on.

Examples

# Create temporal AR1 specification
temporal_ar1("year")
#> tulpaRatio temporal specification
#> ============================
#> 
#> Type: AR1 (First-order Autoregressive) 
#> Time variable: year 
#> Parameterization: centered 
#> Shared: Yes (enters both processes) 
temporal_ar1("year", group = "site")
#> tulpaRatio temporal specification
#> ============================
#> 
#> Type: AR1 (First-order Autoregressive) 
#> Time variable: year 
#> Group variable: site 
#> Parameterization: centered 
#> Shared: Yes (enters both processes) 

# \donttest{
# AR1 temporal correlation
set.seed(127)
df <- data.frame(
  year = rep(2005:2024, each = 3),
  x = rnorm(60),
  count = rpois(60, lambda = 18),
  effort = rgamma(60, shape = 3.5, rate = 1)
)

fit <- tratio(
  count | effort ~ x,
  data = df,
  family = ratiod_poisson_gamma(),
  temporal = temporal_ar1("year"),
  mode = "hmc",
  control = list(iter = 400, chains = 1, seed = 1)
)

# Panel data with group-specific AR1
set.seed(128)
df_panel <- data.frame(
  year = rep(2012:2027, each = 3),
  site = rep(paste0("site", 1:3), times = 16),
  x = rnorm(48),
  count = rpois(48, lambda = 12),
  effort = rgamma(48, shape = 2.5, rate = 1)
)

fit2 <- tratio(
  count | effort ~ x,
  data = df_panel,
  family = ratiod_poisson_gamma(),
  temporal = temporal_ar1("year", group_var = "site"),
  mode = "hmc",
  control = list(iter = 400, chains = 1, seed = 1)
)
# }