pyforesight

Time series forecasting in Python that picks its model by what would have worked.

foresight fits several models to a series, replays the past to see how each would have done, chooses by out-of-sample error and reports intervals taken from the errors actually observed, including intervals for the total of the next k periods.

The models, the backtest and the utilities are the Rust crate foresight, compiled into the package: the numbers are the crate's, the backtest runs on all cores, and nothing else is needed at run time. NumPy and pandas are accepted and, for pandas, produced on request, but neither is required.

Website: https://strategicprojects.github.io/pyforesight/ · Português

Install

pip install pyforesight

Python 3.9 or later. Wheels are ready for Linux (x86-64 and aarch64), macOS (Intel and Apple silicon) and Windows; elsewhere pip compiles the Rust code, which needs a Rust toolchain (https://rustup.rs). The package is imported as foresight.

Use

import foresight as fs

# monthly data whose first observation is in March
y = fs.monthly(values, first_month=3)

# replay the last 36 months, 12 months ahead, with the 11 default models
report = fs.backtest(y)

best = report.best
print(f"{best.name}: MAPE {best.score:.1f}%")
for p in best.forecast:
    lo, hi = p.interval(0.80)
    print(p.horizon, round(p.mean), round(lo), round(hi))

half_year = best.cumulative(6)      # the total of the next six months, with its own interval
report.to_pandas()                  # one row per candidate (needs pandas)
best.to_pandas()                    # the forecast with its intervals

One model on its own:

# seasonal ARIMA on the log scale
fit = fs.log(fs.Arima.airline()).fit(y)
next_year = fit.forecast(12)

# orders chosen from the data, inspected
auto = fs.AutoArima().fit(fs.monthly(log_values, first_month=3))
auto.details["order"], auto.details["seasonal_order"], auto.aicc

A trend that bends, with dated events:

model = fs.Prophet(
    events={"campaign": [10, 34, 58, 82, 106, 130]},  # future ones included
    steps={"new_law": 80},                              # a lasting change of level
)
fit = model.fit(y)
fit.details["changepoints"], fit.details["effects"]

Several models combined, and the wider set of candidates:

ensemble = fs.Ensemble(fs.defaults(), weighting="stacked")
report = fs.backtest(y, fs.thorough() + [ensemble.named("my_ensemble")])

Any sequence of numbers works where a series is expected: a list, a NumPy array, a pandas Series. Only the values are read (an index of dates is not), so say what the series is with fs.monthly, fs.quarterly or fs.Series, or pass the seasonal period: fs.Theta().fit(values, period=12). Missing values (None, NaN) are only accepted by the cleaning functions.

Good to know:

• Positions count from 0 at the first observation: Prophet's events and steps, Outlier.index, Report.first_origin and the changepoints of a fit. Months and quarters (first_month, first_season) count from 1.
• A candidate that cannot forecast at every origin and from the whole series is left out of the report, with a warning; report.dropped names them.
• fs.set_max_threads(n) limits the threads of backtests and ensembles; the results do not depend on it. The GIL is released while models are fitted.
• Models, fits and reports hold Rust objects and cannot be pickled or copied; a model is cheap to build again in another process.

What is in it

How it differs from the usual toolkits

Most forecasting libraries choose a model by an in-sample information criterion and derive intervals from distributional assumptions. Here the choice and the intervals both come from forecasts made without seeing the future they are judged against. The interval for a total (say, the rest of a fiscal year) is measured on totals, because adding up monthly limits overstates its uncertainty.

Checked

The package runs the Rust crate, so its numbers are the crate's; the tests check that nothing is lost on the way, against results recorded by the crate: ARIMA, regression with ARIMA errors, ETS, Prophet, TBATS, STL and MSTL, Croston, cleaning, ensembles, tests of stationarity and seasonality, and the backtests of 11 and 18 candidates on three public series. The crate itself is compared with the R packages forecast 9.0.2 and prophet 1.1.7, and reproduced independently by the Go edition foresight-go. The same methods are available in R: foresightr.

pip install maturin pytest
maturin develop --release
pytest                 # about 30 s; pytest -m "not slow" skips TBATS and the thorough backtest

Data

tests/data has two public series: the monthly ICMS and FPE revenue of the state of Piauí, Brazil (Siconfi/STN, with the IPCA price index from the Central Bank of Brazil), and the airline passengers of Box & Jenkins.

Citation

Zenodo: https://doi.org/10.5281/zenodo.23050402 (all versions); see also CITATION.cff.

Authors

André Leite, Marcos Wasiliew, Hugo Vasconcelos, Carlos Amorim and Diogo Bezerra.

License

MIT.