kalmanbox 0.1.0__tar.gz

kalmanbox-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

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

@@ -0,0 +1,33 @@
+# Pre-commit hooks for kalmanbox
+# Install: pre-commit install
+# Run all: pre-commit run --all-files
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.8
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/RobertCraiworthy/pyright-python
+    rev: v1.1.367
+    hooks:
+      - id: pyright
+        additional_dependencies:
+          - numpy
+          - scipy
+          - pandas
+          - pandas-stubs

kalmanbox-0.1.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# 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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-17
+
+### Added
+
+- **Core**: StateSpaceRepresentation with system matrices (T, Z, R, H, Q)
+- **Kalman Filter**: Numerically stable implementation with Joseph-form updates
+- **RTS Smoother**: Rauch-Tung-Striebel backward smoother
+- **Models**:
+  - LocalLevel (random walk + noise)
+  - LocalLinearTrend (trend + level)
+  - BSM (Basic Structural Model with seasonality)
+  - UCM (Unobserved Components Model)
+  - DynamicFactor (dynamic factor model)
+  - TVPRegression (time-varying parameter regression)
+  - ARIMASSM (ARIMA in state-space form)
+- **Estimation**: Maximum Likelihood via scipy.optimize
+- **Forecasting**: Point forecasts with confidence intervals
+- **Diagnostics**: Ljung-Box test, Jarque-Bera test, residual analysis
+- **Missing data**: Automatic handling of NaN observations
+- **Reports**: HTML and LaTeX report generation
+- **Datasets**: 19 built-in datasets (classic, macro, Brazilian)
+- **CLI**: Command-line interface (estimate, info, forecast)
+- **Experiment**: KalmanExperiment for model comparison and validation
+- **Numba**: Optional JIT acceleration for core loops (5x+ speedup)
+- **Documentation**: Full MkDocs site with tutorials, API reference, theory
+
+### Dependencies
+
+- Python >= 3.11
+- NumPy >= 1.24
+- SciPy >= 1.10
+- pandas >= 2.0

kalmanbox-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.

kalmanbox-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.1
+Name: kalmanbox
+Version: 0.1.0
+Summary: State-space models and Kalman filtering for time series analysis
+Author: NodesEcon
+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: 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: 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: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: radon>=6.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: structlog>=23.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: numba
+Requires-Dist: numba>=0.58; extra == 'numba'
+Description-Content-Type: text/markdown
+
+# kalmanbox
+
+State-space models and Kalman filtering for time series analysis.
+
+## Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from kalmanbox import LocalLevel
+from kalmanbox.datasets import load_dataset
+
+nile = load_dataset('nile')
+model = LocalLevel(nile['volume'])
+results = model.fit()
+print(results.summary())
+```
+
+## License
+
+MIT

kalmanbox-0.1.0/README.md

@@ -0,0 +1,25 @@
+# kalmanbox
+
+State-space models and Kalman filtering for time series analysis.
+
+## Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from kalmanbox import LocalLevel
+from kalmanbox.datasets import load_dataset
+
+nile = load_dataset('nile')
+model = LocalLevel(nile['volume'])
+results = model.fit()
+print(results.summary())
+```
+
+## License
+
+MIT

kalmanbox-0.1.0/kalmanbox/__init__.py

@@ -0,0 +1,33 @@
+"""kalmanbox - State-space models and Kalman filtering for time series analysis."""
+
+from kalmanbox.__version__ import __version__
+from kalmanbox.core.model import StateSpaceModel
+from kalmanbox.core.representation import StateSpaceRepresentation
+from kalmanbox.core.results import StateSpaceResults
+from kalmanbox.models.arima_ssm import ARIMA_SSM
+from kalmanbox.models.bsm import BasicStructuralModel
+from kalmanbox.models.custom import CustomStateSpace
+from kalmanbox.models.cycle import CycleModel
+from kalmanbox.models.dynamic_factor import DynamicFactorModel
+from kalmanbox.models.local_level import LocalLevel
+from kalmanbox.models.local_linear_trend import LocalLinearTrend
+from kalmanbox.models.regression_ssm import RegressionSSM
+from kalmanbox.models.tvp import TimeVaryingParameters
+from kalmanbox.models.ucm import UnobservedComponents
+
+__all__ = [
+    "__version__",
+    "ARIMA_SSM",
+    "BasicStructuralModel",
+    "CustomStateSpace",
+    "CycleModel",
+    "DynamicFactorModel",
+    "LocalLevel",
+    "LocalLinearTrend",
+    "RegressionSSM",
+    "StateSpaceModel",
+    "StateSpaceRepresentation",
+    "StateSpaceResults",
+    "TimeVaryingParameters",
+    "UnobservedComponents",
+]

kalmanbox-0.1.0/kalmanbox/__version__.py

@@ -0,0 +1,3 @@
+"""Version information for kalmanbox."""
+
+__version__ = "0.1.0"

kalmanbox-0.1.0/kalmanbox/_logging.py

@@ -0,0 +1,73 @@
+"""Logging configuration for kalmanbox.
+
+Uses structlog if available, falls back to stdlib logging.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+_LOG_FORMAT = "%(asctime)s [%(name)s] %(levelname)s: %(message)s"
+
+_has_structlog = False
+try:
+    import structlog
+
+    _has_structlog = True
+except ImportError:
+    pass
+
+if TYPE_CHECKING:
+    import structlog
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Get a logger with the kalmanbox namespace.
+
+    Parameters
+    ----------
+    name : str
+        Logger name (will be prefixed with 'kalmanbox.').
+
+    Returns
+    -------
+    logging.Logger
+        Configured logger instance.
+    """
+    logger = logging.getLogger(f"kalmanbox.{name}")
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter(_LOG_FORMAT))
+        logger.addHandler(handler)
+        logger.setLevel(logging.WARNING)
+    return logger
+
+
+def configure_logging(level: str = "WARNING", use_structlog: bool = True) -> None:
+    """Configure kalmanbox logging.
+
+    Parameters
+    ----------
+    level : str
+        Log level: DEBUG, INFO, WARNING, ERROR.
+    use_structlog : bool
+        Use structlog if available (default True).
+    """
+    numeric_level = getattr(logging, level.upper(), logging.WARNING)
+    root = logging.getLogger("kalmanbox")
+    root.setLevel(numeric_level)
+
+    if use_structlog and _has_structlog:
+        structlog.configure(
+            processors=[
+                structlog.stdlib.filter_by_level,
+                structlog.stdlib.add_log_level,
+                structlog.stdlib.add_logger_name,
+                structlog.dev.ConsoleRenderer(),
+            ],
+            wrapper_class=structlog.stdlib.BoundLogger,
+            context_class=dict,
+            logger_factory=structlog.stdlib.LoggerFactory(),
+            cache_logger_on_first_use=True,
+        )

kalmanbox-0.1.0/kalmanbox/cli/__init__.py

@@ -0,0 +1,5 @@
+"""KalmanBox command-line interface."""
+
+from kalmanbox.cli.main import main
+
+__all__ = ["main"]

kalmanbox-0.1.0/kalmanbox/cli/main.py

@@ -0,0 +1,294 @@
+"""KalmanBox CLI entry point."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from kalmanbox.__version__ import __version__
+
+# ---------------------------------------------------------------------------
+# Model registry: maps CLI names to (module_path, class_name)
+# ---------------------------------------------------------------------------
+_MODEL_REGISTRY: dict[str, tuple[str, str]] = {
+    "local_level": ("kalmanbox.models.local_level", "LocalLevel"),
+    "local_linear_trend": ("kalmanbox.models.local_linear_trend", "LocalLinearTrend"),
+    "bsm": ("kalmanbox.models.bsm", "BasicStructuralModel"),
+    "ucm": ("kalmanbox.models.ucm", "UnobservedComponents"),
+    "arima": ("kalmanbox.models.arima_ssm", "ARIMA_SSM"),
+    "tvp": ("kalmanbox.models.tvp", "TimeVaryingParameters"),
+}
+
+
+def _get_model_class(name: str) -> type:  # type: ignore[type-arg]
+    """Dynamically import and return a model class by CLI name."""
+    if name not in _MODEL_REGISTRY:
+        available = ", ".join(sorted(_MODEL_REGISTRY.keys()))
+        print(f"Error: unknown model '{name}'. Available: {available}", file=sys.stderr)
+        sys.exit(1)
+
+    module_path, class_name = _MODEL_REGISTRY[name]
+    import importlib
+
+    module = importlib.import_module(module_path)
+    return getattr(module, class_name)  # type: ignore[no-any-return]
+
+
+def _load_data(path: str) -> pd.DataFrame:
+    """Load CSV data file."""
+    data_path = Path(path)
+    if not data_path.exists():
+        print(f"Error: data file not found: {path}", file=sys.stderr)
+        sys.exit(1)
+    return pd.read_csv(data_path)  # type: ignore[no-any-return]
+
+
+def _build_model_kwargs(args: argparse.Namespace) -> dict[str, Any]:
+    """Build keyword arguments for model constructor from CLI args."""
+    kwargs: dict[str, Any] = {}
+    if hasattr(args, "seasonal_period") and args.seasonal_period is not None:
+        kwargs["seasonal_period"] = args.seasonal_period
+    if hasattr(args, "order") and args.order is not None:
+        parts = [int(x) for x in args.order.split(",")]
+        if len(parts) == 3:
+            kwargs["order"] = tuple(parts)
+        else:
+            print("Error: --order must be p,d,q (e.g. 1,1,1)", file=sys.stderr)
+            sys.exit(1)
+    if hasattr(args, "exog") and args.exog is not None:
+        exog_path = Path(args.exog)
+        if not exog_path.exists():
+            print(f"Error: exog file not found: {args.exog}", file=sys.stderr)
+            sys.exit(1)
+        exog_df = pd.read_csv(exog_path)
+        kwargs["exog"] = exog_df.to_numpy(dtype=np.float64)
+    return kwargs
+
+
+class _NumpyEncoder(json.JSONEncoder):
+    """JSON encoder that handles numpy types."""
+
+    def default(self, o: Any) -> Any:
+        """Encode numpy types to JSON-serializable Python types."""
+        if isinstance(o, np.ndarray):
+            return o.tolist()
+        if isinstance(o, np.integer):
+            return int(o)
+        if isinstance(o, np.floating):
+            return float(o)
+        return super().default(o)
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+def estimate_command(args: argparse.Namespace) -> None:
+    """Execute the 'estimate' command."""
+    data = _load_data(args.data)
+
+    # Determine the target column (first numeric column)
+    numeric_cols = data.select_dtypes(include=[np.number]).columns
+    if len(numeric_cols) == 0:
+        print("Error: no numeric columns found in data", file=sys.stderr)
+        sys.exit(1)
+
+    y = data[numeric_cols[0]].to_numpy(dtype=np.float64)
+    model_class = _get_model_class(args.model)
+    kwargs = _build_model_kwargs(args)
+
+    model = model_class(y, **kwargs)
+    results = model.fit()
+
+    # Build output dict
+    output: dict[str, Any] = {
+        "model": args.model,
+        "data": args.data,
+        "n_obs": len(y),
+        "loglike": float(results.loglike),
+        "aic": float(results.aic),
+        "bic": float(results.bic),
+        "params": {
+            name: float(val) for name, val in zip(results.param_names, results.params, strict=True)
+        },
+    }
+
+    output_path = Path(args.output)
+    with open(output_path, "w") as f:
+        json.dump(output, f, indent=2, cls=_NumpyEncoder)
+
+    print(f"Results saved to {output_path}")
+    print(f"  Model: {args.model}")
+    print(f"  LogLike: {output['loglike']:.4f}")
+    print(f"  AIC: {output['aic']:.4f}")
+    print(f"  BIC: {output['bic']:.4f}")
+
+
+def info_command(args: argparse.Namespace) -> None:
+    """Execute the 'info' command."""
+    model_class = _get_model_class(args.model)
+
+    # Create a dummy model with minimal data to inspect structure
+    dummy_y = np.ones(10, dtype=np.float64)
+    kwargs = _build_model_kwargs(args)
+
+    try:
+        model = model_class(dummy_y, **kwargs)
+    except Exception as e:
+        print(f"Error creating model: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Build representation from start params to inspect structure
+    rep = model._build_ssm(model.start_params)  # noqa: SLF001
+    print(f"Model: {args.model}")
+    print(f"  k_states: {rep.k_states}")
+    print(f"  k_obs: {rep.k_endog}")
+    print(f"  State dimensions: T={rep.T.shape}, Z={rep.Z.shape}")
+    print(f"  Parameters: {model.param_names}")
+    print(f"  n_params: {len(model.param_names)}")
+
+
+def forecast_command(args: argparse.Namespace) -> None:
+    """Execute the 'forecast' command."""
+    data = _load_data(args.data)
+
+    numeric_cols = data.select_dtypes(include=[np.number]).columns
+    if len(numeric_cols) == 0:
+        print("Error: no numeric columns found in data", file=sys.stderr)
+        sys.exit(1)
+
+    y = data[numeric_cols[0]].to_numpy(dtype=np.float64)
+    model_class = _get_model_class(args.model)
+    kwargs = _build_model_kwargs(args)
+
+    model = model_class(y, **kwargs)
+    results = model.fit()
+
+    fc = results.forecast(steps=args.steps)
+
+    # The forecast dict uses 'lower'/'upper' keys; arrays may be 2D (steps, k_endog)
+    lower_key = "lower_95" if "lower_95" in fc else "lower"
+    upper_key = "upper_95" if "upper_95" in fc else "upper"
+
+    mean_arr = np.asarray(fc["mean"]).flatten()
+    lower_arr = np.asarray(fc[lower_key]).flatten()
+    upper_arr = np.asarray(fc[upper_key]).flatten()
+
+    # Build forecast DataFrame
+    fc_df = pd.DataFrame(
+        {
+            "step": list(range(1, args.steps + 1)),
+            "mean": mean_arr,
+            "lower_95": lower_arr,
+            "upper_95": upper_arr,
+        }
+    )
+
+    output_path = Path(args.output)
+    fc_df.to_csv(output_path, index=False)
+
+    print(f"Forecast saved to {output_path}")
+    print(f"  Model: {args.model}")
+    print(f"  Steps: {args.steps}")
+    print(f"  Forecast mean (first 5): {mean_arr[:5].tolist()}")
+
+
+# ---------------------------------------------------------------------------
+# Shared argument helpers
+# ---------------------------------------------------------------------------
+def _add_model_args(parser: argparse.ArgumentParser) -> None:
+    """Add common model arguments to a subparser."""
+    parser.add_argument(
+        "--model",
+        required=True,
+        choices=list(_MODEL_REGISTRY.keys()),
+        help="Model type to use",
+    )
+    parser.add_argument(
+        "--seasonal-period",
+        type=int,
+        default=None,
+        help="Seasonal period (required for bsm, ucm with seasonal)",
+    )
+    parser.add_argument(
+        "--order",
+        type=str,
+        default=None,
+        help="ARIMA order as p,d,q (e.g. 1,1,1)",
+    )
+    parser.add_argument(
+        "--exog",
+        type=str,
+        default=None,
+        help="Path to CSV with exogenous variables (for tvp)",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Main parser
+# ---------------------------------------------------------------------------
+def build_parser() -> argparse.ArgumentParser:
+    """Build the CLI argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="kalmanbox",
+        description="KalmanBox: State-space models and Kalman filtering for time series",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"kalmanbox {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # --- estimate ---
+    est = subparsers.add_parser(
+        "estimate",
+        help="Estimate a state-space model from data",
+    )
+    _add_model_args(est)
+    est.add_argument("--data", required=True, help="Path to CSV data file")
+    est.add_argument("--output", default="results.json", help="Output JSON file path")
+    est.set_defaults(func=estimate_command)
+
+    # --- info ---
+    info = subparsers.add_parser(
+        "info",
+        help="Show model information (dimensions, parameters)",
+    )
+    _add_model_args(info)
+    info.set_defaults(func=info_command)
+
+    # --- forecast ---
+    fc = subparsers.add_parser(
+        "forecast",
+        help="Fit model and produce forecasts",
+    )
+    _add_model_args(fc)
+    fc.add_argument("--data", required=True, help="Path to CSV data file")
+    fc.add_argument("--steps", type=int, required=True, help="Number of forecast steps")
+    fc.add_argument("--output", default="forecast.csv", help="Output CSV file path")
+    fc.set_defaults(func=forecast_command)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    """CLI entry point."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(0)
+
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

kalmanbox-0.1.0/kalmanbox/core/__init__.py

@@ -0,0 +1,7 @@
+"""Core state-space model components."""
+
+from kalmanbox.core.model import StateSpaceModel
+from kalmanbox.core.representation import StateSpaceRepresentation
+from kalmanbox.core.results import StateSpaceResults
+
+__all__ = ["StateSpaceModel", "StateSpaceRepresentation", "StateSpaceResults"]

kalmanbox-0.1.0/kalmanbox/core/config.py

@@ -0,0 +1,19 @@
+"""Global configuration for kalmanbox."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class KalmanBoxConfig:
+    """Global configuration."""
+
+    default_optimizer: str = "L-BFGS-B"
+    max_iterations: int = 500
+    tolerance: float = 1e-8
+    diffuse_initial_variance: float = 1e7
+    symmetry_enforcement: bool = True
+    cholesky_fallback_eps: float = 1e-8
+
+
+# Singleton global config
+config = KalmanBoxConfig()