Panel workflow compatibility

bayesian_kpi_predictions and its differences from BayesianPosterior

This reference preserves the separate panel workflow. Main tutorials use BayesianPosterior; the two APIs are not interchangeable.

Behavior	BayesianPosterior	bayesian_kpi_predictions
Input	Prepared subject frame	Long panel
Settings	BayesianSettings	BayesianPredictionSettings
Main output	posterior_level	prediction
Actual selection in preparation	Latest known at cutoff	First known at cutoff
Separate historical model source	Caller prepares it	backtest_source
Historical replay	Caller supplies each cutoff	Built-in backtest series
Correlation adjustment	Unavailable	Available
Empirical interval	Unavailable	Available
Directional confidence	Unavailable	Available
Publication-relative horizons	Caller supplies cutoff	Built-in
Missing model precision	Estimate and interval can remain	Depends on historical or forward series
Excluded model weight	Missing	Zero

• Historical missing precision: An enabled model without precision prevents a workflow backtest posterior.
• Forward missing precision: The workflow can publish a prior-consensus prediction while precision, weight and interval diagnostics remain missing.
• Correlation adjustment: Supports prediction only, with no interval.
• Bias history: The workflow adjusts consensus before its error-history fit; posterior preparation measures source errors on original historical estimates.
• Preset scope: posterior_preset and bayesian_preset share supported profile settings. Empirical intervals and confidence caps are workflow-only additions.
• Training provenance: Research presets currently have no confirmed fitted-through date. See training provenance.

Example calls

Use bayesian_kpi_predictions for the complete Bayesian workflow. The panel needs reported actuals and historical estimates as well as live predictions.

import pandas as pd
import tutorial_support as examples
import postforecast as pf

examples.set_style()
history = examples.quarterly_history()
as_of = pd.Timestamp("2026-05-10", tz="UTC")
settings = pf.bayesian_preset(
    "plain-2026-09",
    series="predictions",
    values=("prediction", "posterior-growth", "prediction-lower", "prediction-upper"),
)
predictions = pf.bayesian_kpi_predictions(
    history,
    as_of,
    forecast_source="model",
    settings=settings,
)
predictions[["entity", "period", *settings.values, "eligible"]]

	entity	period	prediction	posterior-growth	prediction-lower	prediction-upper	eligible
0	ZS	2026-06	800.649	0.0494807	795.166	807.144	True

• Historical output: Set series="backtests" for historical estimates fitted on strictly earlier observations. Set series="combined" for the stitched series.
• Separate model histories: Pass backtest_source= when historical model estimates have a different source identifier from live predictions.
• Training start: Set start_date in the settings to restrict the training sample. Filter display dates after calculation to retain the intended history.
• Dispersion weighting: Set stdev_weighted_consensus=True and supply consensus dispersion. Count weighting additionally uses estimate_count and consensus_count_exponent. See the precision rules.
• Publication horizons: For the independent method, set relative_to="publish" and a nonpositive relative_days, or "latest". Pass a publications frame with subject keys and UTC publication_date. See the publication-relative contract.

To use correlation adjustment, construct compatible settings:

correlated_settings = pf.BayesianPredictionSettings(
    version="correlation-example",
    method="correlation adjusted",
    series="predictions",
    values=("prediction",),
)
correlated = pf.bayesian_kpi_predictions(
    history,
    as_of,
    forecast_source="model",
    settings=correlated_settings,
)
correlated[["entity", "period", "prediction", "eligible", "eligibility_reason"]]

	entity	period	prediction	eligible	eligibility_reason
0	ZS	2026-06	812.084	True	eligible

• Required model: Correlation adjustment requires model observations.
• Supported output: Only prediction is available for this method.
• Unsupported options: Dispersion weighting and publication-relative horizons are rejected. See the complete restrictions.

Mathematical definitions

• Independent: Equations, outputs and history semantics.
• Correlation adjusted: Joint conditioning and restrictions.

Result handling

• Eligibility: Check eligible and retain eligibility_reason; diagnostic values can remain populated when the prediction is unavailable.
• Identity: Keep subject keys, as_of, method, settings_version, preset, fitted_through and relative_days when combining runs.
• Units: Growth is fractional; consensus-bias-pct is in percentage points.
• Training window: start_date restricts training. Filter display dates after calculation.
• Availability: Observations use an exclusive cutoff. Publication availability uses an inclusive previous-publication comparison, as detailed in the independent reference.
• Universe: Forward predictions target unrealised subjects. Excluding the model does not convert historical consensus-only subjects into forward predictions.
• Audit: Retain the complete settings payload and input snapshot outside the library.

Implementation origins

bayesian_kpi_predictions reproduces the numerical workflow of Exabel’s production signal. BAYESIAN_DEFAULTS (formerly DSL_DEFAULTS) carries that signal’s default arguments, and the method names independent and correlation adjusted are the signal’s own.

• Independent: IndependentBayesianRegularizedPredictionSignal.
• Correlation adjusted: CorrelatedBayesianRegularizedPredictionSignal.
• Output names: The hyphenated output names and the stdev_weighted_consensus argument are kept from the signal.

Audited source

• Snapshot: Exabel checkout 9e1e92ca26, with no local edits. The signal file matches the remote master blob 6c5e7de34ae036e1b4ebe3080ac0684091243163 at the time of the audit.
• Signal: bayesian_kpi_prediction_signal.py.
• Bias filter: kalman_filter.py.
• Horizon inference: latest_prediction_relative_days.py.

The consensus bias alignment departs from that snapshot: forecast rows include the latest reported consensus error. The golden cases were regenerated for it; historical rows are unchanged.

The first port covered only the tutorial’s independent forecast update. The complete workflow was added afterwards and audited against the source above.

Calculation coverage

Signal behavior	Implementation
Actual growth	series_math.actual_growth
Previous-actual estimate growth	series_math.estimate_growth
Growth-to-level conversion	prediction_math
Dispersion-to-growth conversion	prediction_math
Shifted expanding prior	series_math.prior_moments
Fixed forecast prior	series_math.prior_moments
Shifted expanding error precision	series_math.error_precision
Fixed forecast error precision	series_math.error_precision
Absolute and relative growth errors	series_math.growth_errors
Dispersion, count exponent and variance multiplier	prediction_math
Shifted consensus bias and Kalman filter	series_math.adjust_consensus_for_bias
Independent posterior	prediction_math
Correlation-adjusted posterior	series_math.correlation_adjusted_expectation
Joint-history alignment and sample covariance	prediction_math
Student-t growth and ordered level bounds	prediction_math
Reference output names	prediction_settings.BAYESIAN_VALUES
Per-output historical/forward stitching	prediction_math.calculate_prediction_series
Publication availability gate	preparation
Fixed and latest publication-relative horizons	preparation
Training-window start	preparation

Parity evidence

• Numerical parity: 36 golden scenarios generated by executing the signal’s numerical methods in isolation, without the Exabel runtime. Cases cover both methods, all output selections, bias, error modes, missing histories, dispersion fallback and forecast stitching. Expected missingness is checked alongside values.
• Deliberate differences: Panel reads use this package’s exclusive known_at boundary rather than Exabel’s date-version loaders. Calendar lookup, currency conversion, the two-year query prefetch and signal evaluation stay with the caller.