forecast-realtime 0.5.3__tar.gz

forecast_realtime-0.5.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bank of England
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

forecast_realtime-0.5.3/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: forecast_realtime
+Version: 0.5.3
+Summary: A package for producing real-time forecasts
+Author-email: Paul Labonne <paul.labonne@bankofengland.co.uk>, Sumer Singh <sumer.singh@bankofengland.co.uk>, Harry Li <Harry.Li@bankofengland.co.uk>, Nades Raviraj <Nades.Raviraj@bankofengland.co.uk>
+Maintainer-email: Paul Labonne <paul.labonne@bankofengland.co.uk>, Sumer Singh <sumer.singh@bankofengland.co.uk>
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: statsmodels<0.15.0,>=0.14.0
+Requires-Dist: forecast_evaluation>=0.1.13
+Requires-Dist: pandas>=3.0.3
+Requires-Dist: scipy>=1.17.1
+Requires-Dist: tqdm>=4.67.3
+Requires-Dist: numpy>=2.4.5
+Requires-Dist: pyarrow>=24.0.0
+Provides-Extra: dev
+Requires-Dist: pre_commit>=4.6.0; extra == "dev"
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"
+Requires-Dist: pydoclint>=0.9.1; extra == "dev"
+Requires-Dist: syrupy>=5.2.0; extra == "dev"
+Requires-Dist: ruff>=0.15.13; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+Requires-Dist: zensical; extra == "docs"
+Provides-Extra: notebooks
+Requires-Dist: marimo==0.24.0; extra == "notebooks"
+Requires-Dist: news_decomp>=0.0.7; extra == "notebooks"
+Provides-Extra: models
+Requires-Dist: bvar>=0.3.1; extra == "models"
+Requires-Dist: nowcast-midas>=0.0.1; extra == "models"
+Requires-Dist: scikit-learn>=1.8.0; extra == "models"
+Requires-Dist: xgboost>=3.2.0; extra == "models"
+Provides-Extra: ridge
+Requires-Dist: scikit-learn>=1.8.0; extra == "ridge"
+Provides-Extra: lasso
+Requires-Dist: scikit-learn>=1.8.0; extra == "lasso"
+Provides-Extra: elasticnet
+Requires-Dist: scikit-learn>=1.8.0; extra == "elasticnet"
+Provides-Extra: random-forest
+Requires-Dist: scikit-learn>=1.8.0; extra == "random-forest"
+Provides-Extra: xgboost
+Requires-Dist: xgboost>=3.2.0; extra == "xgboost"
+Provides-Extra: bvar
+Requires-Dist: bvar>=0.3.1; extra == "bvar"
+Provides-Extra: nowcast-midas
+Requires-Dist: nowcast-midas>=0.0.1; extra == "nowcast-midas"
+Dynamic: license-file
+
+# Real-time Forecast Package
+
+A Python package for real-time orchestration of forecasting models.
+
+The main object, **RealTimeModel**, combines a **ForecastData** object (from the
+`forecast_evaluation` package) with one or more **ForecastModel** objects.
+`ForecastModel` is an abstract base class with
+`_fit()`, `_forecast()` and an optional `_forecast_decomp()` method. All
+built-in models inherit from it, and you can subclass it to wrap any Python (or
+R, MATLAB, or Julia) forecasting model.
+
+## Installation
+
+```bash
+pip install forecast_realtime[models]
+```
+
+## Quick demo
+
+```python
+import forecast_evaluation as fe
+import forecast_realtime as rt
+
+forecast_data = fe.ForecastData(load_fer=True)
+
+ridge = rt.models.ForecastRidge(label="Ridge", cv=5, scale=True)
+lasso = rt.models.ForecastLasso(label="LASSO", cv=5, scale=True)
+
+rt_model = rt.RealTimeModel(
+    data=forecast_data,
+    models=[ridge, lasso],
+)
+
+rt_model.forecast(
+    y_variables=["cpisa"],
+    X_variables=["gdpkp"],
+    data_transformation={"cpisa": "pop", "gdpkp": "pop"},
+    steps=12,
+    y_lags=4,
+    X_imputation="last",
+)
+
+# Optional interactive dashboard:
+# rt_model.data.run_dashboard()
+```
+
+### Marimo notebook
+
+Install the notebook and model dependencies from the repository root:
+
+```bash
+pip install -e ".[models,notebooks]"
+```
+
+Open the demo as an editable notebook with visible code cells and outputs:
+
+```bash
+marimo edit notebooks/demo_models.py
+```
+
+## Add your own model
+
+Subclass `ForecastModel` and implement `_fit()` and `_forecast()` (plus
+`_forecast_decomp()` if you want news decompositions). `y` and `X` arrive as
+pandas DataFrames, and the base class handles validation, lags, dummies and
+forecast dates.
+
+```python
+import numpy as np
+import pandas as pd
+
+from forecast_realtime import ForecastModel
+
+
+class MyOLS(ForecastModel):
+    """Small OLS model showing the custom-model authoring pattern."""
+
+    def _fit(self, y, X=None, **kwargs):
+        # y and X are passed as pandas DataFrames
+        if X is None:
+            raise ValueError("MyOLS requires X")
+        X = X.to_numpy(dtype=float)
+        y = y.to_numpy(dtype=float)
+
+        # OLS estimate: beta = (X'X)^-1 X'y
+        self.beta = np.linalg.inv(X.T @ X) @ X.T @ y
+
+        return self
+
+    def _forecast(self, steps, X=None, y=None, **kwargs):
+        if X is None:
+            raise ValueError("MyOLS requires future X")
+        # ForecastModel passes the historical and future design rows.
+        future_X = X.loc[X.index > self.last_y_fit_date].iloc[:steps]
+        return future_X.to_numpy(dtype=float) @ self.beta
+```
+
+Pass it straight to `RealTimeModel`:
+
+```python
+rt_model = rt.RealTimeModel(data=forecast_data, models=[MyOLS()])
+```
+
+## Documentation
+
+- [docs/index.md](docs/index.md) — how `ForecastModel` and `RealTimeModel` work.
+- [docs/models.md](docs/models.md) — built-in models and R/MATLAB/Julia wrappers.
+- [docs/usage.md](docs/usage.md) — lags, dummies, imputation, transformations,
+  news decomposition and parallel execution.
+- [adding_a_model.md](docs/adding_a_model.md) — the full `ForecastModel` interface.
+- [forecasting_strategy.md](docs/forecasting_strategy.md) — forecasting methodology.
+- [CONTRIBUTING.md](CONTRIBUTING.md) — development setup and workflow.
+
+## Data Classification
+Bank of England Data Classification: OFFICIAL BLUE

forecast_realtime-0.5.3/README.md

@@ -0,0 +1,115 @@
+# Real-time Forecast Package
+
+A Python package for real-time orchestration of forecasting models.
+
+The main object, **RealTimeModel**, combines a **ForecastData** object (from the
+`forecast_evaluation` package) with one or more **ForecastModel** objects.
+`ForecastModel` is an abstract base class with
+`_fit()`, `_forecast()` and an optional `_forecast_decomp()` method. All
+built-in models inherit from it, and you can subclass it to wrap any Python (or
+R, MATLAB, or Julia) forecasting model.
+
+## Installation
+
+```bash
+pip install forecast_realtime[models]
+```
+
+## Quick demo
+
+```python
+import forecast_evaluation as fe
+import forecast_realtime as rt
+
+forecast_data = fe.ForecastData(load_fer=True)
+
+ridge = rt.models.ForecastRidge(label="Ridge", cv=5, scale=True)
+lasso = rt.models.ForecastLasso(label="LASSO", cv=5, scale=True)
+
+rt_model = rt.RealTimeModel(
+    data=forecast_data,
+    models=[ridge, lasso],
+)
+
+rt_model.forecast(
+    y_variables=["cpisa"],
+    X_variables=["gdpkp"],
+    data_transformation={"cpisa": "pop", "gdpkp": "pop"},
+    steps=12,
+    y_lags=4,
+    X_imputation="last",
+)
+
+# Optional interactive dashboard:
+# rt_model.data.run_dashboard()
+```
+
+### Marimo notebook
+
+Install the notebook and model dependencies from the repository root:
+
+```bash
+pip install -e ".[models,notebooks]"
+```
+
+Open the demo as an editable notebook with visible code cells and outputs:
+
+```bash
+marimo edit notebooks/demo_models.py
+```
+
+## Add your own model
+
+Subclass `ForecastModel` and implement `_fit()` and `_forecast()` (plus
+`_forecast_decomp()` if you want news decompositions). `y` and `X` arrive as
+pandas DataFrames, and the base class handles validation, lags, dummies and
+forecast dates.
+
+```python
+import numpy as np
+import pandas as pd
+
+from forecast_realtime import ForecastModel
+
+
+class MyOLS(ForecastModel):
+    """Small OLS model showing the custom-model authoring pattern."""
+
+    def _fit(self, y, X=None, **kwargs):
+        # y and X are passed as pandas DataFrames
+        if X is None:
+            raise ValueError("MyOLS requires X")
+        X = X.to_numpy(dtype=float)
+        y = y.to_numpy(dtype=float)
+
+        # OLS estimate: beta = (X'X)^-1 X'y
+        self.beta = np.linalg.inv(X.T @ X) @ X.T @ y
+
+        return self
+
+    def _forecast(self, steps, X=None, y=None, **kwargs):
+        if X is None:
+            raise ValueError("MyOLS requires future X")
+        # ForecastModel passes the historical and future design rows.
+        future_X = X.loc[X.index > self.last_y_fit_date].iloc[:steps]
+        return future_X.to_numpy(dtype=float) @ self.beta
+```
+
+Pass it straight to `RealTimeModel`:
+
+```python
+rt_model = rt.RealTimeModel(data=forecast_data, models=[MyOLS()])
+```
+
+## Documentation
+
+- [docs/index.md](docs/index.md) — how `ForecastModel` and `RealTimeModel` work.
+- [docs/models.md](docs/models.md) — built-in models and R/MATLAB/Julia wrappers.
+- [docs/usage.md](docs/usage.md) — lags, dummies, imputation, transformations,
+  news decomposition and parallel execution.
+- [adding_a_model.md](docs/adding_a_model.md) — the full `ForecastModel` interface.
+- [forecasting_strategy.md](docs/forecasting_strategy.md) — forecasting methodology.
+- [CONTRIBUTING.md](CONTRIBUTING.md) — development setup and workflow.
+
+## Data Classification
+Bank of England Data Classification: OFFICIAL BLUE

forecast_realtime-0.5.3/pyproject.toml

@@ -0,0 +1,131 @@
+[project]
+name = "forecast_realtime"
+version = "0.5.3"
+
+description = "A package for producing real-time forecasts"
+
+authors = [
+    {name="Paul Labonne", email="paul.labonne@bankofengland.co.uk"},
+    {name="Sumer Singh", email = "sumer.singh@bankofengland.co.uk"},
+    {name="Harry Li", email = "Harry.Li@bankofengland.co.uk"},
+    {name="Nades Raviraj", email = "Nades.Raviraj@bankofengland.co.uk"},
+]
+
+maintainers = [
+    {name="Paul Labonne", email="paul.labonne@bankofengland.co.uk"},
+    {name="Sumer Singh", email = "sumer.singh@bankofengland.co.uk"},
+]
+
+license = "MIT"
+
+readme = "README.md"
+
+requires-python = ">=3.11"
+
+dependencies = [
+    # forecast-evaluation depends on a compatible statsmodels version.
+    # Remove this constraint when forecast-evaluation resolves the compatibility issue.
+    "statsmodels>=0.14.0,<0.15.0",
+    "forecast_evaluation>=0.1.13",
+    "pandas >= 3.0.3",
+    "scipy >= 1.17.1",
+    "tqdm >= 4.67.3",
+    "numpy >= 2.4.5",
+    "pyarrow >= 24.0.0", # Required by external model wrappers.
+]
+
+[project.optional-dependencies]
+dev = [
+    "pre_commit >= 4.6.0",
+    "pytest >= 9.0.3",
+    "pytest-xdist", # Enables parallel test runs with pytest -n auto.
+    "pydoclint >= 0.9.1",
+    "syrupy >= 5.2.0",
+    "ruff >= 0.15.13",
+]
+
+docs = [
+    "mkdocstrings[python]",
+    "zensical",
+]
+
+notebooks = [
+    "marimo==0.24.0",
+    "news_decomp>=0.0.7",
+]
+
+models = [
+    "bvar >= 0.3.1",
+    "nowcast-midas >= 0.0.1",
+    "scikit-learn >= 1.8.0",
+    "xgboost >= 3.2.0",
+]
+
+ridge = ["scikit-learn >= 1.8.0"]
+lasso = ["scikit-learn >= 1.8.0"]
+elasticnet = ["scikit-learn >= 1.8.0"]
+random_forest = ["scikit-learn >= 1.8.0"]
+xgboost = ["xgboost >= 3.2.0"]
+bvar = ["bvar >= 0.3.1"]
+nowcast_midas = ["nowcast-midas>=0.0.1"]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.package-data]
+forecast_realtime = [
+    "runners/*.r",
+    "runners/*.m",
+    "runners/*.jl",
+    "models/r_scripts/*.r",
+]
+
+[tool.ruff]
+line-length = 90
+target-version = "py311"
+
+[tool.ruff.lint]
+# Enable specific rules
+select = [
+    "E",  # pycodestyle
+    "F",  # pyflakes
+    "I",  # isort
+    "UP", # pyupgrade
+]
+
+# Ignore specific rules
+ignore = [
+    "D100", # Missing docstring in public module
+    "D104", # Missing docstring in public package,
+    "D213",
+    "D211"
+]
+
+# Exclude files and directories
+exclude = [
+    ".git",
+    ".ruff_cache",
+    "__pycache__",
+    "build",
+    "dist",
+    "*.png",
+    "examples/**",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]  # Ignore unused imports in __init__.py files
+
+[tool.pydoclint]
+style = "numpy"
+arg-type-hints-in-signature = true
+arg-type-hints-in-docstring = true
+skip-checking-short-docstrings = true
+skip-checking-private-functions = true
+skip-checking-raises = true
+allow-init-docstring = true
+check-class-attributes = false
+should-document-star-arguments = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

forecast_realtime-0.5.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

forecast_realtime-0.5.3/src/forecast_realtime/__init__.py

@@ -0,0 +1,40 @@
+from .data_transformation import (
+    InputMetricMapping,
+    ModelInputRequirements,
+    PreparedModelInputs,
+    RawInputBundle,
+    ResolvedTransformationPlan,
+)
+from .external_model import ExternalModel, JuliaModel, MATLABModel, RModel
+from .forecast_model import ForecastContext, ForecastModel, ForecastResult
+from .forecast_tree import ForecastTree, TreeNode
+from .formula import Formula
+from .real_time_model import RealTimeModel
+from .sample_realtime_data import generate_synthetic_data
+
+# Optional import - only load models if available
+try:
+    from . import models
+except ImportError:
+    models = None
+
+__all__ = [
+    "RealTimeModel",
+    "ForecastModel",
+    "ForecastContext",
+    "ForecastResult",
+    "ForecastTree",
+    "TreeNode",
+    "ExternalModel",
+    "Formula",
+    "RModel",
+    "MATLABModel",
+    "JuliaModel",
+    "generate_synthetic_data",
+    "ModelInputRequirements",
+    "InputMetricMapping",
+    "ResolvedTransformationPlan",
+    "RawInputBundle",
+    "PreparedModelInputs",
+    "models",
+]

forecast_realtime-0.5.3/src/forecast_realtime/_realtime_forecasting.py

@@ -0,0 +1,30 @@
+"""Private containers for realtime forecast execution."""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class ForecastTask:
+    """Pickleable work item submitted to a realtime forecast worker."""
+
+    model: object
+    data_transformation: object
+    vintages: np.ndarray
+    common: dict
+    input_metrics: dict[str, str] = None
+    y_input_metrics: dict[str, str] = None
+    X_input_metrics: dict[str, str] = None
+    y_conditioning_input_metrics: dict[str, str] = None
+    X_conditioning_input_metrics: dict[str, str] = None
+
+
+@dataclass(frozen=True)
+class ForecastRunResult:
+    """Completed worker outputs before aggregation and storage."""
+
+    forecasts: object
+    decompositions: object
+    all_vintages_skipped: bool
+    native_forecasts: object = None