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)

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, separate random walks are estimated for each group.
shared: Logical; if TRUE (default), temporal effect enters both numerator and denominator linear predictors identically.
rho_prior: Prior for the autocorrelation parameter. Default is NULL which uses a Uniform(-1, 1) prior. Can specify a Beta prior on (rho+1)/2 for more informative priors.

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.

Examples

# Create temporal AR1 specification
temporal_ar1("year")
#> tulpaRatio temporal specification
#> ============================
#> 
#> Type: AR1 (First-order Autoregressive) 
#> Time variable: year 
#> Shared: Yes (enters both processes) 
temporal_ar1("year", group = "site")
#> tulpaRatio temporal specification
#> ============================
#> 
#> Type: AR1 (First-order Autoregressive) 
#> Time variable: year 
#> Group variable: site 
#> 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 = 200, warmup = 100, chains = 1)
)
#> Inference: Exact (Tier 1)
#>   Backend: hmc
#> Fitting ratio model...
#>   Family: poisson_gamma
#>   Observations: 60
#>   Iterations: 200 (warmup: 100)
#>   Temporal: ar1 (20 time points)
#> Running NUTS sampler...
#>   Parameters: 27
#>   Iterations: 200 (warmup: 100)
#>   Chains: 1 (cores: 1)
#>   Temporal: ar1 (20 time points)

# 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 = 200, warmup = 100, chains = 1)
)
#> Inference: Exact (Tier 1)
#>   Backend: hmc
#> Fitting ratio model...
#>   Family: poisson_gamma
#>   Observations: 48
#>   Iterations: 200 (warmup: 100)
#>   Temporal: ar1 (16 time points)
#> Running NUTS sampler...
#>   Parameters: 55
#>   Iterations: 200 (warmup: 100)
#>   Chains: 1 (cores: 1)
#>   Temporal: ar1 (16 time points)
# }