Compute Temporal Surprise — surprise_temporal • bayesiansurpriser

Computes surprise over time, allowing beliefs to update as new data arrives. This is useful for detecting changes in patterns over time and for streaming data applications.

Usage

surprise_temporal(
  data,
  time_col,
  observed,
  expected = NULL,
  region_col = NULL,
  models = c("uniform", "baserate", "funnel"),
  update_prior = TRUE,
  window_size = NULL,
  signed = TRUE,
  ...
)

Arguments

data: Data frame with time-indexed observations
time_col: Column name for time variable (unquoted or string)
observed: Column name for observed values
expected: Column name for expected values (optional)
region_col: Column name for region/spatial identifier (optional). If provided, computes per-region surprise at each time point.
models: Model specification (see surprise())
update_prior: Logical; should prior be updated after each time step?
window_size: For rolling window analysis: number of time periods to include. If NULL, uses all prior data.
signed: Compute signed surprise?
...: Additional arguments passed to compute_surprise()

Value

A bs_surprise_temporal object containing:

surprise_by_time: List of surprise results for each time period
time_values: Vector of time values
cumulative_surprise: Matrix of cumulative surprise
model_space: The model space used

Examples

# Create temporal data
df <- data.frame(
  year = rep(2010:2020, each = 5),
  region = rep(letters[1:5], 11),
  events = rpois(55, lambda = 50),
  population = rep(c(10000, 50000, 100000, 25000, 15000), 11)
)

# Compute temporal surprise
result <- surprise_temporal(df,
  time_col = year,
  observed = events,
  expected = population,
  region_col = region
)

# View results
print(result)
#> <bs_surprise_temporal>
#>   Time periods: 11 
#>   Time range: 2010 to 2020 
#>   Models: 3