Election forecasts that show the full range of outcomes.

from kronikas import ElectionForecast

forecast = ElectionForecast(
    polls_csv="polls.csv",
    election_date="2024-11-05",
)
result = forecast.run()

# Point estimates with honest intervals
for est in result.today_estimates:
    print(f"{est.name}: {est.mean:.1f}% "
          f"({est.ci_lower:.1f}–{est.ci_upper:.1f})")

# P(this candidate polls highest on election day)
result.win_probabilities        # {'Alice': 0.91, ...}

# P(clears a 5% electoral threshold)
result.threshold_probabilities(5.0)

# Head-to-head, and every posterior draw as a DataFrame
result.lead_probability("Alice", "Bob")
result.party_forecast_dataframe(day="election_day")
result.house_effects_dataframe()

# Sampling takes minutes — keep the run
result.save("forecast-2024-03-20.nc")

Already have a DataFrame? ElectionForecast.from_dataframe(...) skips the CSV round-trip and never mutates the frame you pass it.

# Human-readable summary
kronikas forecast polls.csv --election-date 2024-11-05

# Machine-readable, quiet enough for cron
kronikas forecast polls.csv \
    --election-date 2024-11-05 \
    --threshold 5 --threshold 10 \
    --json forecast.json \
    --save-trace forecast.nc \
    --quiet

# How fragile is the call to an industry-wide error?
kronikas forecast polls.csv \
    --election-date 2024-11-05 \
    --shared-bias 2 --shared-bias 4

# Non-ISO dates, European decimals, renamed columns
kronikas forecast polls.csv \
    --election-date 2024-11-05 \
    --date-format "%d/%m/%Y" --decimal ,

kronikas forecast exits non-zero when the sampler reports a convergence problem — a scheduled run fails loudly instead of publishing bad numbers.

from datetime import date
from kronikas import backtest

# Replay the campaign: at each as-of date, throw away
# every later poll, refit, and score what it would have said.
report = backtest(
    "polls.csv",
    election_date=date(2024, 11, 5),
    as_of_dates=[date(2024, 8, 1), date(2024, 10, 1)],
    actual={"Alice": 48.2, "Bob": 47.1, "Carol": 4.7},
)

print(report.summary())
report.to_dataframe()   # one row per (as-of, candidate)
report.metrics()        # MAE, RMSE, CRPS, hit rate, bias

Bias is reported per candidate, never pooled: shares sum to 100, so signed errors cancel exactly across candidates and a pooled mean would be identically zero.

from kronikas import ModelConfig, PollsterPrior

config = ModelConfig(
    # --- Sampler ---
    num_tune=2000, num_draws=2000, num_chains=4,
    target_accept=0.99,
    init_method="adapt_full",

    # --- Time grid ---
    time_step_days=3,          # finer trend resolution

    # --- Priors, on the logit scale ---
    sigma_walk_prior=0.03,      # smoother trend
    sigma_house_prior=0.2,      # tighter house effects
    correlated_walk=True,      # LKJ-correlated innovations

    # --- What you already know about specific firms ---
    pollster_priors={
        "PollCo": PollsterPrior(mu_house={"Alice": 3}),
        "SurveyInc": PollsterPrior(kappa_log_sigma=1.0),
    },

    # --- Escape hatch to any pymc.sample() kwarg ---
    sampler_kwargs={"nuts_sampler": "nutpie"},
)

Prior means are given in percentage points and converted relative to each candidate's own support level — you state beliefs in the units you actually think in.