chronobox 0.1.0__tar.gz

chronobox-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.hypothesis/
+.mutmut-cache
+mutants/
+
+# IDE
+.vscode/
+.idea/
+
+# Docs
+site/
+
+# Logs
+logs/
+
+# OS
+.DS_Store
+Thumbs.db

chronobox-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json
+      - id: check-toml
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+      - id: check-merge-conflict
+      - id: detect-private-key
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.0
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.9.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [numpy, pandas-stubs]
+        args: [--ignore-missing-imports]

chronobox-0.1.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-17
+
+### Added
+- ARIMA/SARIMA model with MLE via Kalman filter (kalmanbox)
+- Auto-ARIMA with stepwise algorithm and information criteria
+- VAR model with lag selection, Granger causality, IRF, FEVD
+- SVAR model with Cholesky, short-run, and long-run identification
+- VECM model with Johansen cointegration test
+- ARDL model with bounds testing and ECM
+- Unit root tests: ADF, Phillips-Perron, KPSS, ERS/DF-GLS
+- Cointegration tests: Johansen trace and max eigenvalue
+- Diagnostic tests: Ljung-Box, Breusch-Godfrey, ARCH-LM
+- Filters: Hodrick-Prescott, Baxter-King, Christiano-Fitzgerald, Hamilton
+- Time series decomposition (STL, classical)
+- Visualization module with diagnostic plots
+- Report generation (HTML, professional themes)
+- ChronoExperiment pattern for systematic model comparison
+- CLI with 5 commands: estimate, test, forecast, decompose, filter
+- ~30 built-in datasets (classic, macro, finance, simulated)
+- Download scripts for Brazilian macro data (BCB SGS, IBGE SIDRA)
+- Numba optimization for critical loops (@optional_jit)
+- MkDocs documentation with ~40 pages
+- CI/CD with GitHub Actions
+- 10 quality assurance phases
+
+### Dependencies
+- kalmanbox (Kalman filter and MLE)
+- NumPy >= 1.24
+- SciPy >= 1.10
+- pandas >= 2.0
+- matplotlib >= 3.7

chronobox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NodesEcon
+
+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.

chronobox-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.1
+Name: chronobox
+Version: 0.1.0
+Summary: Time series analysis library with ARIMA, state-space models, and automatic model selection
+Author: NodesEcon
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.11
+Requires-Dist: kalmanbox
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.10
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7; extra == 'dev'
+Requires-Dist: hypothesis>=6.0; extra == 'dev'
+Requires-Dist: interrogate>=1.5; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.0; extra == 'dev'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'dev'
+Requires-Dist: mutmut>=2.4; extra == 'dev'
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: radon>=6.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: safety>=2.3; extra == 'dev'
+Requires-Dist: structlog>=23.0; extra == 'dev'
+Provides-Extra: numba
+Requires-Dist: numba>=0.57; extra == 'numba'
+Description-Content-Type: text/markdown
+
+# chronobox
+
+Time series analysis library with ARIMA, state-space models, and automatic model selection.
+
+## Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from chronobox import ARIMA
+from chronobox.datasets import load_dataset
+
+airline = load_dataset('airline')
+model = ARIMA(order=(0,1,1), seasonal_order=(0,1,1,12))
+results = model.fit(airline['passengers'])
+print(results.summary())
+forecast = results.forecast(steps=12)
+```
+
+## Auto-ARIMA
+
+```python
+from chronobox import auto_arima
+
+best = auto_arima(airline['passengers'], seasonal=True, m=12)
+print(best.summary())
+```
+
+## License
+
+MIT

chronobox-0.1.0/README.md

@@ -0,0 +1,35 @@
+# chronobox
+
+Time series analysis library with ARIMA, state-space models, and automatic model selection.
+
+## Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from chronobox import ARIMA
+from chronobox.datasets import load_dataset
+
+airline = load_dataset('airline')
+model = ARIMA(order=(0,1,1), seasonal_order=(0,1,1,12))
+results = model.fit(airline['passengers'])
+print(results.summary())
+forecast = results.forecast(steps=12)
+```
+
+## Auto-ARIMA
+
+```python
+from chronobox import auto_arima
+
+best = auto_arima(airline['passengers'], seasonal=True, m=12)
+print(best.summary())
+```
+
+## License
+
+MIT

chronobox-0.1.0/chronobox/__init__.py

@@ -0,0 +1,42 @@
+"""chronobox - Time series analysis library with ARIMA and automatic model selection."""
+
+from chronobox.__version__ import __version__
+from chronobox.analysis.counterfactual import Counterfactual
+from chronobox.analysis.hd import HistoricalDecomposition
+from chronobox.decomposition import STL, ClassicalDecomposition
+from chronobox.models.arfima import ARFIMA
+from chronobox.models.arima import ARIMA
+from chronobox.models.bvar import BayesianVAR
+from chronobox.models.ets import ETS
+from chronobox.models.favar import FAVAR
+from chronobox.models.gvar import GVAR
+from chronobox.models.holtwinters import HoltWinters
+from chronobox.models.svar import SVAR
+from chronobox.models.theta import ThetaMethod
+from chronobox.models.tvpvar import TVPVAR
+from chronobox.models.var import VAR
+from chronobox.models.vecm import VECM
+from chronobox.selection.auto_arima import auto_arima
+from chronobox.selection.auto_ets import auto_ets
+
+__all__ = [
+    "ARFIMA",
+    "ARIMA",
+    "ETS",
+    "FAVAR",
+    "GVAR",
+    "STL",
+    "SVAR",
+    "TVPVAR",
+    "VAR",
+    "VECM",
+    "BayesianVAR",
+    "ClassicalDecomposition",
+    "Counterfactual",
+    "HistoricalDecomposition",
+    "HoltWinters",
+    "ThetaMethod",
+    "__version__",
+    "auto_arima",
+    "auto_ets",
+]

chronobox-0.1.0/chronobox/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

chronobox-0.1.0/chronobox/_logging.py

@@ -0,0 +1,16 @@
+"""Logging configuration for chronobox."""
+
+import logging
+
+_LOG_FORMAT = "%(asctime)s [%(name)s] %(levelname)s: %(message)s"
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Get a logger with the chronobox namespace."""
+    logger = logging.getLogger(f"chronobox.{name}")
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter(_LOG_FORMAT))
+        logger.addHandler(handler)
+        logger.setLevel(logging.WARNING)
+    return logger

chronobox-0.1.0/chronobox/analysis/__init__.py

@@ -0,0 +1,25 @@
+"""Time series analysis tools: IRF, FEVD, Granger causality, HD, Counterfactual, Spillover."""
+
+from chronobox.analysis.counterfactual import Counterfactual, CounterfactualResult
+from chronobox.analysis.fevd import FEVD
+from chronobox.analysis.granger import granger_causality
+from chronobox.analysis.hd import HistoricalDecomposition, HistoricalDecompositionResult
+from chronobox.analysis.irf import IRF
+from chronobox.analysis.spillover import (
+    RollingSpilloverResult,
+    SpilloverIndex,
+    SpilloverResult,
+)
+
+__all__ = [
+    "FEVD",
+    "IRF",
+    "Counterfactual",
+    "CounterfactualResult",
+    "HistoricalDecomposition",
+    "HistoricalDecompositionResult",
+    "RollingSpilloverResult",
+    "SpilloverIndex",
+    "SpilloverResult",
+    "granger_causality",
+]

chronobox-0.1.0/chronobox/analysis/counterfactual.py

@@ -0,0 +1,260 @@
+"""
+Counterfactual analysis based on historical decomposition.
+
+Answers: "What would have happened if shock k had not occurred?"
+
+References
+----------
+- Kilian, L. & Lutkepohl, H. (2017). Structural Vector Autoregressive
+  Analysis. Cambridge University Press. Chapter 4.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+@dataclass
+class CounterfactualResult:
+    """Results from counterfactual analysis.
+
+    Attributes
+    ----------
+    counterfactual : ndarray of shape (T, K_vars)
+        Counterfactual time series.
+    observed : ndarray of shape (T, K_vars)
+        Observed time series.
+    removed_contribution : ndarray of shape (T, K_vars)
+        The contribution that was removed.
+    shock_index : int | list[int]
+        Index(es) of the shock(s) removed.
+    scale : float
+        Scale factor applied (0 = full removal, 0.5 = half removal).
+    """
+
+    counterfactual: NDArray[np.floating[Any]]
+    observed: NDArray[np.floating[Any]]
+    removed_contribution: NDArray[np.floating[Any]]
+    shock_index: int | list[int]
+    scale: float
+
+
+class Counterfactual:
+    """Counterfactual analysis based on historical decomposition.
+
+    Parameters
+    ----------
+    hd : HistoricalDecomposition or HistoricalDecompositionResult
+        Historical decomposition results.
+    """
+
+    def __init__(self, hd: Any) -> None:
+        # Accept either HistoricalDecomposition or HistoricalDecompositionResult
+        if hasattr(hd, "result"):
+            self._hd_result = hd.result
+        elif hasattr(hd, "decomposition") and hasattr(hd, "base"):
+            self._hd_result = hd
+        else:
+            msg = "hd must be a HistoricalDecomposition or HistoricalDecompositionResult"
+            raise TypeError(msg)
+
+    @property
+    def decomposition(self) -> NDArray[np.floating[Any]]:
+        """Decomposition array (T, K_shocks, K_vars)."""
+        return self._hd_result.decomposition
+
+    @property
+    def base(self) -> NDArray[np.floating[Any]]:
+        """Base forecast (T, K_vars)."""
+        return self._hd_result.base
+
+    @property
+    def observed(self) -> NDArray[np.floating[Any]]:
+        """Observed values (T, K_vars)."""
+        return self._hd_result.observed
+
+    def without_shock(
+        self, shock_index: int | list[int]
+    ) -> NDArray[np.floating[Any]]:
+        """Compute counterfactual without specified shock(s).
+
+        Y_cf = Y - HD_k  (for single shock)
+        Y_cf = Y - sum(HD_k for k in shock_indices)  (for multiple shocks)
+
+        Parameters
+        ----------
+        shock_index : int or list[int]
+            Index(es) of the structural shock(s) to remove.
+
+        Returns
+        -------
+        ndarray of shape (T, K_vars)
+        """
+        if isinstance(shock_index, int):
+            shock_index = [shock_index]
+
+        removed = np.zeros_like(self.observed)
+        for k in shock_index:
+            removed += self.decomposition[:, k, :]
+
+        return self.observed - removed
+
+    def with_modified_shock(
+        self, shock_index: int, scale: float = 0.5
+    ) -> NDArray[np.floating[Any]]:
+        """Compute counterfactual with modified (scaled) shock.
+
+        Y_cf = Y - HD_k * (1 - scale)
+
+        Parameters
+        ----------
+        shock_index : int
+            Index of the structural shock to modify.
+        scale : float
+            Scale factor. 0 = remove entirely, 1 = keep as-is, 0.5 = halve.
+
+        Returns
+        -------
+        ndarray of shape (T, K_vars)
+        """
+        contribution = self.decomposition[:, shock_index, :]
+        return self.observed - contribution * (1.0 - scale)
+
+    def without_all_shocks(self) -> NDArray[np.floating[Any]]:
+        """Remove all shocks, leaving only the base forecast.
+
+        Returns
+        -------
+        ndarray of shape (T, K_vars)
+            Should equal self.base.
+        """
+        n_shocks = self.decomposition.shape[1]
+        return self.without_shock(list(range(n_shocks)))
+
+    def compute(
+        self,
+        shock_index: int | list[int],
+        scale: float = 0.0,
+    ) -> CounterfactualResult:
+        """Compute counterfactual with full result object.
+
+        Parameters
+        ----------
+        shock_index : int or list[int]
+            Shock(s) to modify.
+        scale : float
+            Scale factor (0 = remove, 1 = keep).
+
+        Returns
+        -------
+        CounterfactualResult
+        """
+        if isinstance(shock_index, int):
+            cf = self.with_modified_shock(shock_index, scale)
+            removed = self.decomposition[:, shock_index, :] * (1.0 - scale)
+        else:
+            removed = np.zeros_like(self.observed)
+            for k in shock_index:
+                removed += self.decomposition[:, k, :] * (1.0 - scale)
+            cf = self.observed - removed
+
+        return CounterfactualResult(
+            counterfactual=cf,
+            observed=self.observed,
+            removed_contribution=removed,
+            shock_index=shock_index,
+            scale=scale,
+        )
+
+    def plot(
+        self,
+        variable: int,
+        shock_index: int | list[int],
+        scale: float = 0.0,
+        figsize: tuple[int, int] = (12, 6),
+        title: str | None = None,
+        variable_name: str | None = None,
+        shock_name: str | None = None,
+    ) -> Any:
+        """Plot counterfactual vs observed.
+
+        Parameters
+        ----------
+        variable : int
+            Variable index to plot.
+        shock_index : int or list[int]
+            Shock(s) to remove.
+        scale : float
+            Scale factor (0 = remove, 1 = keep).
+        figsize : tuple
+            Figure size.
+        title : str or None
+            Plot title.
+        variable_name : str or None
+            Name of the variable for the plot label.
+        shock_name : str or None
+            Name of the shock for the plot label.
+
+        Returns
+        -------
+        matplotlib Figure
+        """
+        import matplotlib.pyplot as plt
+
+        result = self.compute(shock_index, scale)
+
+        fig, ax = plt.subplots(figsize=figsize)
+
+        n_t = result.observed.shape[0]
+        t_axis = np.arange(n_t)
+
+        ax.plot(
+            t_axis,
+            result.observed[:, variable],
+            "b-",
+            linewidth=1.5,
+            label="Observed",
+        )
+        ax.plot(
+            t_axis,
+            result.counterfactual[:, variable],
+            "r--",
+            linewidth=1.5,
+            label="Counterfactual",
+        )
+
+        # Shade the difference
+        ax.fill_between(
+            t_axis,
+            result.observed[:, variable],
+            result.counterfactual[:, variable],
+            alpha=0.2,
+            color="gray",
+            label="Shock contribution",
+        )
+
+        if variable_name is None:
+            variable_name = f"Variable {variable}"
+        if shock_name is None:
+            shock_name = f"Shock {shock_index}"
+
+        if title is None:
+            if scale == 0:
+                title = (
+                    f"Counterfactual: {variable_name} without {shock_name}"
+                )
+            else:
+                title = f"Counterfactual: {variable_name} with {shock_name} scaled by {scale:.1f}"
+
+        ax.set_title(title)
+        ax.set_xlabel("Time")
+        ax.set_ylabel("Value")
+        ax.legend()
+        ax.grid(True, alpha=0.3)
+
+        plt.tight_layout()
+        return fig