BayesianPosterior contract

Preparation, equations, outputs and refusal rules

prepare_bayesian_subjects(panel, as_of, forecast_source=..., settings=...) constructs the input for BayesianPosterior. Pass the same settings and source names to both. Symbols follow Notation.

Reading and history

  • Cutoff: Observations must have known_at < as_of; all timestamps are UTC-aware.
  • Subjects: Preparation returns subjects with at least one observation known at the cutoff. It has no explicit requested-universe argument.
  • Actual revisions: The latest actual known at the cutoff is used. To work with first releases, select the first actual per subject before preparation.
  • Growth base: \(y_{t-1}\) is the actual for the latest available period whose period_end precedes the subject’s period end. It need not be the immediately preceding calendar quarter.
  • Shared period ends: Periods of one entity and target that share a period_end are ordered by their actual’s known_at, then by period label. Another entity’s rows never change that order.
  • Historical estimates: Each error uses the source reading strictly before the selected actual’s known_at. With revised actuals, that can be later than the original release; a first-release policy must therefore select actuals first.
  • History window: Prior and error statistics contain periods strictly earlier than the subject, using data available at the outer cutoff.
  • Historical evaluation: Prepare again at each target’s historical cutoff. A frame prepared today is not a backtest of earlier publication decisions.
  • Freshness: Ages are attached but not capped. The caller owns freshness checks.
  • Training guard: A non-null fitted_through must precede the as_of date. A null date provides no calibration training-window protection.

Many reading moments

prepare_bayesian_subjects_each(panel, readings, forecast_source=..., settings=...) prepares one row per reading. A readings frame holds the subject columns, period_end and a UTC as_of, as validate_readings checks. It serves an evaluation that replays every report at several horizons.

  • Row parity: Each row equals the row prepare_bayesian_subjects returns for that subject at that row’s as_of, on every column that call returns.
  • Source columns: The frame carries every source in the panel. A source not yet knowable at a row’s moment is missing there. The one-moment call would have no column for that source at all.
  • Nothing knowable yet: A reading whose subject has no observation before its as_of gets a row with every prepared field missing. The posterior refuses that row as missing input.
  • Shared history: History depends on the moment only through which actuals were knowable. Readings of one entity and target that share those actuals therefore share one computation.
  • Applying: BayesianPosterior accepts the frame directly. Subject keys are unique per as_of rather than overall.
  • Training guard: A non-null fitted_through must precede every as_of date.
  • Reserved names: A source named like a generated column is refused. That covers as_of and the history columns, such as previous_actual or consensus_bias.

Independent blend

The prior mean \(\mu_0\) and sample variance \(\sigma_0^2\) come from sequential realised growth \(g_i=y_i/y_{i-1}-1\). Model and consensus growth are \(x_M=m/y_{t-1}-1\) and \(x_C=c^*/y_{t-1}-1\).

For source \(j\), the error variance is mean squared growth error, not variance around the mean error. Precisions use a numerical floor \(\varepsilon\):

\[ \sigma_j^2=\frac{1}{n_j}\sum_i(x_{j,i}-g_i)^2,\qquad \tau_j=\frac{1}{\max(\sigma_j^2,\varepsilon)}. \]

With \(T=\tau_0+\tau_M+\tau_C\), the posterior is

\[ \hat\theta=\frac{\mu_0\tau_0+x_M\tau_M+x_C\tau_C}{T},\qquad w_j=\frac{\tau_j}{T},\qquad \sigma_\theta=T^{-1/2},\qquad \hat y=y_{t-1}(1+\hat\theta). \]

  • Minimum history: minimum_observations applies to growth and source errors; BayesianSettings requires at least two. Growth observations count changes, so three growth observations normally require four actual levels.
  • Missing model precision: The model term is omitted from \(T\) and the numerator. Model precision and weight stay missing; the posterior and interval remain available.
  • Model excluded: include_model=False omits the model entirely. Its precision and weight are also missing, not zero.
  • Missing prior or consensus precision: No posterior is produced.
  • Assumptions: Readings are treated as independent. Lower computed variance does not guarantee improved predictive accuracy when errors are correlated.

Optional adjustments

  • Bias correction: A local-level Kalman filter tracks the historical relative consensus error \(\beta\). The current consensus becomes \(c^*=c/(1+\lambda\beta)\), where \(\lambda\) is consensus_bias_lambda. A missing bias or nonpositive adjustment denominator leaves consensus unchanged. The source error variances in this API are still computed from the original historical estimates.
  • Dispersion: With dispersion_weighted=True, positive analyst dispersion \(d\) supplies \(\tau_C=1/\max(\kappa(d/|y_{t-1}|)^2,\varepsilon)\). Unusable dispersion falls back to historical consensus error precision.
  • Count: With consensus_count_exponent \(\alpha\), divide dispersion variance by the positive contributor count raised to \(\alpha\). An unusable count uses historical error precision instead. Required metadata columns must exist.
  • Winsorisation: winsorize_fraction clips both tails of realised growth and the upper tail of error magnitudes within each expanding history window.

Interval

Let \(q_L\) and \(q_U\) be quantiles of the configured Student-t distribution at \((1-p)/2\) and \((1+p)/2\), where \(p\) is interval_width. Growth bounds are \(\hat\theta+\sigma_\theta q_L\) and \(\hat\theta+\sigma_\theta q_U\). Convert both to levels and sort them, so a negative base does not reverse bounds.

  • Shape: interval_df, interval_loc and interval_scale define the distribution. See interval calibration for validation rules.
  • Interpretation: This is a configured predictive band, not the ordinary credible interval of the conjugate Gaussian posterior. Nominal coverage does not establish measured coverage on the caller’s data.
  • Availability: An eligible BayesianPosterior result has finite level and interval outputs. Empirical intervals are not supported by this class.

Outputs

The result retains prepared input columns. These derived columns describe the calculation; growth is a fraction and level outputs use the input units.

Column Meaning
posterior_level Published level
posterior_growth Combined growth
posterior_growth_stdev Inverse square root of total precision
posterior_lower Lower level bound
posterior_upper Upper level bound
adjusted_consensus Consensus after bias correction
precision_prior Prior precision
precision_model Model precision
precision_consensus Consensus precision
weight_prior Prior share of total precision
weight_model Model share of total precision
weight_consensus Consensus share of total precision
eligible Publication verdict
eligibility_reason Verdict reason
settings_version Settings identity
preset Originating preset, if any

Refusals

A refused subject keeps its row with eligible false and an eligibility_reason; posterior outputs are missing. The checks, their order, what degrades instead of refusing, and what raises are on Bayesian eligibility.

Fit and audit

  • fit: Validates prepared inputs; it does not learn across subjects.
  • apply: Computes per-row arithmetic from prepared history, without fitting a new model or modifying settings.
  • to_dict: Records source identifiers, complete settings, version, preset and fitted-through date. The caller separately retains input data and cutoff.