Compute Per-Region Surprise — compute_surprise • bayesiansurpriser

Computes the surprise (KL-divergence) for each observation/region, measuring how much each data point updates beliefs about the model space.

Usage

compute_surprise(
  model_space,
  observed,
  expected = NULL,
  return_signed = TRUE,
  return_posteriors = FALSE,
  return_contributions = FALSE,
  normalize_posterior = TRUE,
  ...
)

Arguments

model_space: A bs_model_space object
observed: Numeric vector of observed values (one per region)
expected: Numeric vector of expected values (optional, for signed surprise)
return_signed: Logical; compute signed surprise?
return_posteriors: Logical; return per-region posteriors?
return_contributions: Logical; return per-model contributions?
normalize_posterior: Logical; if TRUE (default), normalizes posteriors to sum to 1 before computing KL divergence. This is the standard Bayesian Surprise calculation. If FALSE, uses unnormalized posterior weights (P(D|M) * P(M)) for comparison with the original Correll & Heer JavaScript demo output.
...: Additional arguments passed to likelihood functions

Value

A bs_surprise object

Details

For each region i, computes:

The posterior P(M|D_i) given just that region's data
The KL-divergence from prior to posterior (surprise)
Optionally, the sign based on deviation direction

normalize_posterior = FALSE is a legacy replication mode for the original JavaScript demo's per-region map calculation. It is not a proper KL divergence between probability distributions and should not be used as the default method for new analyses.