Multi-Scale temporal structure

Specify a multi-scale temporal random effect that decomposes temporal variation into trend, seasonal, and short-term components. Each component has its own variance parameter and structure.

This is particularly useful for long time series where patterns exist at multiple temporal scales (e.g., annual cycles, decadal trends).

Usage

temporal_multiscale(
  time_var,
  trend = c("rw2", "rw1", "none"),
  seasonal = NULL,
  short_term = c("ar1", "iid", "none"),
  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").

trend

Type of trend component: "rw2" (default, smooth), "rw1" (less smooth), or "none".

seasonal

Period for seasonal component (integer). Set to NULL or 0 for no seasonal component. Common values: 12 (monthly), 52 (weekly).

short_term

Type of short-term residual component: "ar1" (default, correlated), "iid" (independent), or "none".

group_var

Optional name of grouping variable for panel data.

shared

Logical; if TRUE (default), temporal effects enter both numerator and denominator.

Value

A ratiod_temporal_multiscale object

Details

The multi-scale temporal model decomposes variation additively:

$$\eta(t) = trend(t) + seasonal(t) + short(t)$$

where:

• trend(t): Long-term smooth change via RW1 or RW2

• seasonal(t): Repeating pattern with period P via cyclic RW1

• short(t): Residual temporal correlation via AR(1) or IID

Each component has a separate variance parameter with PC priors to favor simpler models (fewer active components).

Sum-to-zero constraints are applied to trend and seasonal components for identifiability with the intercept.

See also

temporal_rw1(), temporal_rw2(), temporal_ar1() for single-component temporal effects, spatial_multiscale() for multi-scale spatial effects

Examples

# Create multi-scale temporal specification
temporal_multiscale("month_id", trend = "rw2", seasonal = 12, short_term = "ar1")
#> tulpaRatio Multi-Scale temporal specification
#> =========================================
#> 
#> Time variable: month_id 
#> 
#> Components:
#>   Trend: RW2 (second-order random walk, smooth) 
#>   Seasonal: Period = 12 (cyclic RW1)
#>   Short-term: AR(1) (autocorrelated residuals) 
#> 
#> Shared: Yes (enters both processes) 
temporal_multiscale("year", trend = "rw2", seasonal = NULL, short_term = "none")
#> tulpaRatio Multi-Scale temporal specification
#> =========================================
#> 
#> Time variable: year 
#> 
#> Components:
#>   Trend: RW2 (second-order random walk, smooth) 
#> 
#> Shared: Yes (enters both processes) 

if (FALSE) { # \dontrun{
# Decompose into trend + seasonal + short-term (not run - experimental)
set.seed(129)
df <- data.frame(
  month_id = 1:48,
  x = rnorm(48),
  count = rpois(48, lambda = 20),
  effort = rgamma(48, shape = 4, rate = 1)
)

fit <- tratio(
  count | effort ~ x,
  data = df,
  family = ratiod_poisson_gamma(),
  temporal = temporal_multiscale(
    time_var = "month_id",
    trend = "rw2",
    seasonal = 12,
    short_term = "ar1"
  ),
  control = list(iter = 200, warmup = 100, chains = 1)
)

# Extract and plot components
temporal_effects <- temporal(fit)
plot(temporal_effects, component = "trend")
} # }