ForecastEnsembles.jl

Experimental. The API is still moving and the underlying forecast data types are under active redesign. Pin a specific commit if you depend on it.

Overview

A Julia package for combining probabilistic forecasts from several component models.

ForecastEnsembles.jl computes weighted or unweighted ensembles of forecasts expressed as quantiles, samples, CDFs, or summary statistics. Weights can be supplied by the user, fixed (equal weighting), or estimated from past forecast performance via quantile regression averaging or CRPS-stacking. Trained and untrained methods are interchangeable through one EnsembleWeights type.

The work builds on three R packages: hubEnsembles (simple/weighted mean and median, linear opinion pool), qrensemble (quantile regression averaging), and lopensemble (CRPS-stacked linear opinion pool). The Julia version pulls all three under one in-memory representation, two verbs (fit, combine), and two ensemble types (MixtureEnsemble, QuantileEnsemble). Multiple dispatch picks the right algorithm for each (output_type, method) pair.

The optimiser backends are pluggable: QRA's LP runs through JuMP, so HiGHS, GLPK, Gurobi or anything else with a JuMP wrapper is one line away, and CRPS-stacking goes through Optim.jl.

Getting started

using ForecastEnsembles, DataFrames

df = DataFrame(
    location       = "A",
    horizon        = 1,
    model_id       = repeat(["m1", "m2", "m3"], inner = 2),
    output_type    = "quantile",
    output_type_id = repeat([0.25, 0.75], 3),
    value          = [1.0, 3.0, 2.0, 4.0, 0.5, 2.5],
)

ft = ForecastTable(df; task_id_cols = [:location, :horizon])
combine(ft, QuantileEnsemble(:mean))

ForecastTable(
  models       = ["hub-ensemble"]
  output_type  = quantile
  task_id_cols = [:location, :horizon]
  rows         = 2
)

For an end-to-end walkthrough on real flu hospitalisation forecasts, see docs/src/example.md.

Documentation

Full documentation — method reference, worked examples, and the API — is at epiforecasts.io/ForecastEnsembles.jl. The Methods page explains the two axes (combination operation and weighting scheme) that organise the methods.

<!– standard-sections:start –> <!– MANAGED by EpiAwarePackageTools.scaffold — do not edit between the markers. These standard sections are re-rendered on every scaffold_update; edit the package-owned sections outside them, or CITATION.cff. –>

Contributing

We welcome contributions and new contributors! Please open an issue or pull request on GitHub. This package follows ColPrac and the SciML style.

How to cite

If you use ForecastEnsembles in your work, please cite it. Citation metadata lives in CITATION.cff, which GitHub renders as a "Cite this repository" button on the repository page.

Code of conduct

Please note that the ForecastEnsembles project is released with a Contributor Code of Conduct. By contributing, you agree to abide by its terms. <!– standard-sections:end –>