nowcasting-dfm 0.1.3__tar.gz

nowcasting_dfm-0.1.3/.gitignore

@@ -0,0 +1,29 @@
+# Caches
+__pycache__/
+.pickles/
+*.pickle
+.pytest_cache/
+.tox/
+.venv/
+.venv2/
+
+# Build artifacts
+dist/
+dist2/
+build/
+*.egg-info/
+
+# Env
+.env
+.DS_Store
+dfm_sp/.DS_Store
+
+# Large datasets
+data/
+*.xlsx
+*.xls
+*.csv
+*.html 
+
+TransformedData.xlsx
+*.pickle

nowcasting_dfm-0.1.3/LICENSE

@@ -0,0 +1,31 @@
+BSD 3-Clause License
+
+Copyright (c) 2018, Federal Reserve Bank of New York (original MATLAB implementation by Eric Qian and Brandyn Bok)
+Copyright (c) 2019, Galib Khan (independent Python translation, not affiliated with FRBNY, https://github.com/MajesticKhan/Nowcasting-Python)
+Copyright (c) 2026, Sermet Pekin (extensions and modernisation)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

nowcasting_dfm-0.1.3/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: nowcasting-dfm
+Version: 0.1.3
+Summary: Macroeconomic nowcasting via Dynamic Factor Models (DFM), extending the FRBNY framework (Qian & Bok) with a modern Python API: real-time vintage management, Kalman-based news decomposition, optional Numba acceleration, caching, and interactive Plotly visualizations.
+Project-URL: Homepage, https://github.com/SermetPekin/nowcasting-dfm
+Project-URL: Issues, https://github.com/SermetPekin/nowcasting-dfm/issues
+Author-email: Sermet Pekin <sermet.pekin@gmail.com>
+License: BSD-3-Clause
+License-File: LICENSE
+Keywords: dynamic-factor-model,econometrics,em-algorithm,forecast,kalman-filter,macroeconomics,nowcasting
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Requires-Dist: matplotlib>=3.10.9
+Requires-Dist: numba>=0.66.0
+Requires-Dist: numpy<2.3
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: plotly>=5.18.0
+Requires-Dist: scipy>=1.11.0
+Requires-Dist: statsmodels>=0.14.0
+Requires-Dist: xlrd>=2.0.2
+Provides-Extra: all
+Requires-Dist: ipykernel>=7.3.0; extra == 'all'
+Requires-Dist: nbformat>=5.10.4; extra == 'all'
+Description-Content-Type: text/markdown
+
+# nowcasting-dfm
+
+A Python implementation of the Dynamic Factor Model (DFM) for macroeconomic nowcasting, extending the FRBNY framework (Qian & Bok) with a modern API: real-time vintage management, Kalman-based news decomposition, optional Numba acceleration, caching, and interactive Plotly visualizations.
+
+Based on "[Macroeconomic Nowcasting and Forecasting with Big Data](https://www.newyorkfed.org/research/staff_reports/sr830.html)" (Bok et al., *Staff Reports 830*, NY Fed).
+
+## Installation
+
+```bash
+pip install nowcasting-dfm
+```
+
+For Jupyter notebook support:
+
+```bash
+pip install nowcasting-dfm[all]
+```
+
+## Quick Start
+
+```python
+from dfm_sp import Options, run_with_options, run, download_sample_data
+
+# Download sample US vintage data (only needed once)
+download_sample_data()
+
+# Configure and run the model
+options = Options(
+    vintage="2016-12-16",
+    country="US",
+    spec_file_name="Spec_US_example.xls",
+    max_iter=5000,
+    use_cache=True,
+)
+
+Spec, X, Time, Z = run_with_options(options)
+result = run(X, Spec, options)
+```
+
+### Nowcast update — decompose the impact of new data releases
+
+```python
+from dfm_sp import Options, sp_update_nowcast
+
+options = Options(vintage="2016-12-16", country="US", spec_file_name="Spec_US_example.xls")
+
+result = sp_update_nowcast(
+    options,
+    new_date="2016-12-23",
+    series="GDPC1",
+    period="2016q4",
+)
+result["fig"].show()  # interactive Plotly waterfall chart
+```
+
+## Architecture & Optimizations
+
+*   **Modular Architecture (`sp_*` modules):** Transitioned the procedural scripts into a structured object-oriented library (`dfm_sp`). Introduced formal configuration dataclasses (`sp_classes.py`) and modular plotting logic (`sp_plots.py`) to streamline experimental workflows.
+*   **Centralized Transformations (`sp_transformations.py`):** Abstracted legacy nested-lambda blocks into a dedicated `MacroTransformations` registry. Implements 4 new stationary bounds (`dln`, `dl1`, `d2l`, `zsc`) allowing complex structural vector geometries without inline array indexing side-effects.
+*   **Execution Caching:** Integrated a `use_cache` parameter into the `Options` class. High-dimensional Expectation-Maximization (EM) operations are serialized, allowing rapid iteration on visualization and reporting without repeatedly waiting on matrix re-calculations.
+*   **Numba JIT Acceleration:** The core Expectation-Maximization algorithm and Kalman Filter transition loop have been rewritten for ahead-of-time C compilation via `@numba.jit`. This drastically cuts execution time for extensive parameter searches (`max_iter` 5000+).
+*   **Automated Econometric Validation:** Integrated Augmented Dickey-Fuller (ADF) testing via `statsmodels` to evaluate series stationarity post-transformation, directly guarding against feeding non-stationary data into the DFM.
+*   **Testing Suite:** A comprehensive `pytest` suite enforces the mathematical integrity of the Numba translation against the pure Python implementation, particularly concerning NaN propagation ("ragged edges") inherent in raw macroeconomic releases.
+*   **Dependency Management:** Migrated to Python 3.14+ utilizing `uv` and `pyproject.toml` for hermetic environment resolution.
+*   **HTML Reporting:** Automatically generates standalone Plotly HTML reports containing Factor Contributions, Likelihood optimizations, and Model loadings.
+*   **"News" Attribution Waterfalls:** Provides native bindings (`sp_news.py`) to dissect the mathematical drivers behind week-over-week DFM forecast changes. Generates Plotly Waterfall charts bridging `Actual vs Expected` impacts weighted by the Kalman gain.
+*   **Pseudo-Real-Time Synthesizer:** Includes `sp_vintage_generator.py` for automatically simulating historical "ragged-edge" data matrices from a single modern dataset. Maps execution algorithms (e.g. `1st Friday of the Month`, `15th of the Month`) to dynamically blind data that had not yet been published, allowing mathematically un-cheated backtesting independent of the FRED ALFRED API.
+
+## Repository Structure
+
+* `data/` : Example US macro series retrieved from [FRED](https://fred.stlouisfed.org/).
+* `dfm_sp/` : Core package module encompassing the execution engines and analytics.
+    * `Functions/` : Kalman Filtering, Spline imputation, and EM-Step mathematics.
+    * `tests/` : Component tests simulating missing economic data and ragged tails.
+* `main.py` : Execution script illustrating the estimation of a standard panel and generating visualization artifacts.
+* `example_Nowcast.py` : Demonstration of out-of-sample prediction mechanics (e.g., real GDP growth).
+* `Spec_US_example.xls` : Model specification configurations, dictating series transformations and blocking parameters for mixed-frequency analysis.
+
+## Attribution & Notice
+
+This package is not affiliated with the Federal Reserve Bank of New York.
+
+The lineage of this work is:
+
+1. **Eric Qian & Brandyn Bok (FRBNY)** — original MATLAB implementation of the DFM nowcasting framework ([FRBNY-TimeSeriesAnalysis/Nowcasting](https://github.com/FRBNY-TimeSeriesAnalysis/Nowcasting))
+2. **Galib Khan (MajesticKhan)** — independent Python translation ([MajesticKhan/Nowcasting-Python](https://github.com/MajesticKhan/Nowcasting-Python))
+3. **Sermet Pekin** — this package: modernised API, caching, plotting layer, news decomposition, vintage synthesizer, and testing suite
+
+Academic credit for the methodology: Bok, Caratelli, Giannone, Sbordone & Tambalotti, "[Macroeconomic Nowcasting and Forecasting with Big Data](https://www.newyorkfed.org/research/staff_reports/sr830.html)", *Staff Reports 830*, Federal Reserve Bank of New York.

nowcasting_dfm-0.1.3/README.md

@@ -0,0 +1,89 @@
+# nowcasting-dfm
+
+A Python implementation of the Dynamic Factor Model (DFM) for macroeconomic nowcasting, extending the FRBNY framework (Qian & Bok) with a modern API: real-time vintage management, Kalman-based news decomposition, optional Numba acceleration, caching, and interactive Plotly visualizations.
+
+Based on "[Macroeconomic Nowcasting and Forecasting with Big Data](https://www.newyorkfed.org/research/staff_reports/sr830.html)" (Bok et al., *Staff Reports 830*, NY Fed).
+
+## Installation
+
+```bash
+pip install nowcasting-dfm
+```
+
+For Jupyter notebook support:
+
+```bash
+pip install nowcasting-dfm[all]
+```
+
+## Quick Start
+
+```python
+from dfm_sp import Options, run_with_options, run, download_sample_data
+
+# Download sample US vintage data (only needed once)
+download_sample_data()
+
+# Configure and run the model
+options = Options(
+    vintage="2016-12-16",
+    country="US",
+    spec_file_name="Spec_US_example.xls",
+    max_iter=5000,
+    use_cache=True,
+)
+
+Spec, X, Time, Z = run_with_options(options)
+result = run(X, Spec, options)
+```
+
+### Nowcast update — decompose the impact of new data releases
+
+```python
+from dfm_sp import Options, sp_update_nowcast
+
+options = Options(vintage="2016-12-16", country="US", spec_file_name="Spec_US_example.xls")
+
+result = sp_update_nowcast(
+    options,
+    new_date="2016-12-23",
+    series="GDPC1",
+    period="2016q4",
+)
+result["fig"].show()  # interactive Plotly waterfall chart
+```
+
+## Architecture & Optimizations
+
+*   **Modular Architecture (`sp_*` modules):** Transitioned the procedural scripts into a structured object-oriented library (`dfm_sp`). Introduced formal configuration dataclasses (`sp_classes.py`) and modular plotting logic (`sp_plots.py`) to streamline experimental workflows.
+*   **Centralized Transformations (`sp_transformations.py`):** Abstracted legacy nested-lambda blocks into a dedicated `MacroTransformations` registry. Implements 4 new stationary bounds (`dln`, `dl1`, `d2l`, `zsc`) allowing complex structural vector geometries without inline array indexing side-effects.
+*   **Execution Caching:** Integrated a `use_cache` parameter into the `Options` class. High-dimensional Expectation-Maximization (EM) operations are serialized, allowing rapid iteration on visualization and reporting without repeatedly waiting on matrix re-calculations.
+*   **Numba JIT Acceleration:** The core Expectation-Maximization algorithm and Kalman Filter transition loop have been rewritten for ahead-of-time C compilation via `@numba.jit`. This drastically cuts execution time for extensive parameter searches (`max_iter` 5000+).
+*   **Automated Econometric Validation:** Integrated Augmented Dickey-Fuller (ADF) testing via `statsmodels` to evaluate series stationarity post-transformation, directly guarding against feeding non-stationary data into the DFM.
+*   **Testing Suite:** A comprehensive `pytest` suite enforces the mathematical integrity of the Numba translation against the pure Python implementation, particularly concerning NaN propagation ("ragged edges") inherent in raw macroeconomic releases.
+*   **Dependency Management:** Migrated to Python 3.14+ utilizing `uv` and `pyproject.toml` for hermetic environment resolution.
+*   **HTML Reporting:** Automatically generates standalone Plotly HTML reports containing Factor Contributions, Likelihood optimizations, and Model loadings.
+*   **"News" Attribution Waterfalls:** Provides native bindings (`sp_news.py`) to dissect the mathematical drivers behind week-over-week DFM forecast changes. Generates Plotly Waterfall charts bridging `Actual vs Expected` impacts weighted by the Kalman gain.
+*   **Pseudo-Real-Time Synthesizer:** Includes `sp_vintage_generator.py` for automatically simulating historical "ragged-edge" data matrices from a single modern dataset. Maps execution algorithms (e.g. `1st Friday of the Month`, `15th of the Month`) to dynamically blind data that had not yet been published, allowing mathematically un-cheated backtesting independent of the FRED ALFRED API.
+
+## Repository Structure
+
+* `data/` : Example US macro series retrieved from [FRED](https://fred.stlouisfed.org/).
+* `dfm_sp/` : Core package module encompassing the execution engines and analytics.
+    * `Functions/` : Kalman Filtering, Spline imputation, and EM-Step mathematics.
+    * `tests/` : Component tests simulating missing economic data and ragged tails.
+* `main.py` : Execution script illustrating the estimation of a standard panel and generating visualization artifacts.
+* `example_Nowcast.py` : Demonstration of out-of-sample prediction mechanics (e.g., real GDP growth).
+* `Spec_US_example.xls` : Model specification configurations, dictating series transformations and blocking parameters for mixed-frequency analysis.
+
+## Attribution & Notice
+
+This package is not affiliated with the Federal Reserve Bank of New York.
+
+The lineage of this work is:
+
+1. **Eric Qian & Brandyn Bok (FRBNY)** — original MATLAB implementation of the DFM nowcasting framework ([FRBNY-TimeSeriesAnalysis/Nowcasting](https://github.com/FRBNY-TimeSeriesAnalysis/Nowcasting))
+2. **Galib Khan (MajesticKhan)** — independent Python translation ([MajesticKhan/Nowcasting-Python](https://github.com/MajesticKhan/Nowcasting-Python))
+3. **Sermet Pekin** — this package: modernised API, caching, plotting layer, news decomposition, vintage synthesizer, and testing suite
+
+Academic credit for the methodology: Bok, Caratelli, Giannone, Sbordone & Tambalotti, "[Macroeconomic Nowcasting and Forecasting with Big Data](https://www.newyorkfed.org/research/staff_reports/sr830.html)", *Staff Reports 830*, Federal Reserve Bank of New York.

nowcasting_dfm-0.1.3/dfm_sp/__init__.py

@@ -0,0 +1,62 @@
+import warnings
+
+# Suppress annoying standard warnings during import
+warnings.filterwarnings("ignore", category=FutureWarning)
+
+from dfm_sp.core.dfm import dfm
+from dfm_sp.core.summarize import summarize
+from dfm_sp.sp_utils import get_latest, Timer
+from dfm_sp.sp_update_nowcast_ import sp_update_nowcast
+
+
+from pathlib import Path
+from dfm_sp.sp_daily import daily_report
+
+# Exposed Public API (Easier names)
+from dfm_sp.sp_classes import Options, ResultObject
+from dfm_sp.core.load_spec import SpecConfig, load_spec
+from dfm_sp.core.load_data import load_data
+from dfm_sp.core.dfm import dfm
+from dfm_sp.core.summarize import summarize
+from dfm_sp.sp_run import run_with_options, run
+from dfm_sp.sp_plots import (
+    plot_transformed_data,
+    plot_loglik,
+    plot_common,
+    plot_loglik_together,
+    plot_projection_x_over_y,
+)
+from dfm_sp.sp_plots_blocks import plot_block_contributions
+from dfm_sp.sp_news import plot_news_waterfall
+
+# Expose Vintage Synthesizer heavily simplified
+from dfm_sp.sp_vintage_generator import VintageMaker, FixedDayRule, WeekdayRule
+
+# Data download helper
+from dfm_sp.sp_download import download_sample_data
+
+__all__ = [
+    # Core DFM Loop
+    "Options",
+    "SpecConfig",
+    "ResultObject",
+    "run_with_options",
+    "run",
+    # Plotting/Visualizations
+    "plot_transformed_data",
+    "plot_loglik",
+    "plot_common",
+    "plot_loglik_together",
+    "plot_projection_x_over_y",
+    "plot_block_contributions",
+    "plot_news_waterfall",
+    # Pre-Processing
+    "VintageMaker",
+    "FixedDayRule",
+    "WeekdayRule",
+    # Classic Endpoints
+    "load_spec",
+    "load_data",
+    "dfm",
+    "summarize",
+]

nowcasting_dfm-0.1.3/dfm_sp/core/__init__.py

@@ -0,0 +1 @@
+