pycointbreak 0.1.0__py3-none-any.whl

pycointbreak/__init__.py

@@ -0,0 +1,237 @@
+"""
+pycointbreak — A Python library for testing breaks in fractional
+cointegration relationships
+================================================================
+
+Implements:
+
+* The **Hassler & Breitung (2006)** residual-based LM-type test
+  against fractional cointegration (eqs. 12–14 and 17–18).
+* The **Rodrigues, Sibbertsen & Voges (2019)** supremum tests for
+  *breaks* in the cointegrating relationship — split sample,
+  forward / backward incremental, and rolling (eqs. 5–15).
+* The RSV (2019) **break-point estimator** (eq. 19), with both
+  forward and reverse residual scans (Theorem 3 / Remark 3.3).
+
+Author
+------
+Dr. Merwan Roudane
+Email: merwanroudane920@gmail.com
+GitHub: https://github.com/merwanroudane/pycointbreak
+
+References
+----------
+Hassler, U. and Breitung, J. (2006). A Residual-Based LM Type Test
+Against Fractional Cointegration. *Econometric Theory*, 22(6),
+1091-1111.
+
+Rodrigues, P. M. M., Sibbertsen, P. and Voges, M. (2019).
+Testing for breaks in the cointegrating relationship: On the
+stability of government bond markets' equilibrium. Discussion
+Paper 656.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Dr. Merwan Roudane"
+__email__ = "merwanroudane920@gmail.com"
+__url__ = "https://github.com/merwanroudane/pycointbreak"
+
+from .breakpoint import BreakPointResult, estimate_break_point
+from .critical_values import (
+    HB_CRITICAL_VALUES,
+    RSV_TABLE1,
+    bootstrap_rsv_cv,
+    hb_critical_value,
+    hb_pvalue,
+    rsv_critical_value,
+    simulate_sup_chi2_cv,
+)
+from .fracdiff import (
+    drift_regressor,
+    fdiff,
+    frac_coefs,
+    harmonic_running_sum,
+)
+from .gph import GPHResult, gph
+from .hassler_breitung import HBResult, hassler_breitung_test
+from .reporting import (
+    battery_to_dataframe,
+    combine_results,
+    render_table,
+)
+from .rsv_tests import RSVResult, rsv_battery, rsv_sup_test
+from .simulate import (
+    frac_integrate,
+    simulate_hb_dgp,
+    simulate_rsv_dgp,
+    simulate_segmented_cointegration,
+)
+
+# Plotting is a soft dependency — only re-exported if matplotlib is
+# importable.
+try:  # pragma: no cover
+    from .plots import (
+        plot_breakpoint_objective,
+        plot_residual_diagnostics,
+        plot_rsv_battery,
+        plot_rsv_profile,
+        plot_series_with_breaks,
+        plot_split_heatmap,
+        set_style,
+    )
+except ImportError:  # pragma: no cover
+    pass
+
+
+__all__ = [
+    # version / metadata
+    "__version__",
+    "__author__",
+    "__email__",
+    "__url__",
+    # main tests
+    "hassler_breitung_test",
+    "rsv_sup_test",
+    "rsv_battery",
+    "estimate_break_point",
+    # result classes
+    "HBResult",
+    "RSVResult",
+    "BreakPointResult",
+    "GPHResult",
+    # building blocks
+    "fdiff",
+    "frac_coefs",
+    "harmonic_running_sum",
+    "drift_regressor",
+    "frac_integrate",
+    "gph",
+    # critical values
+    "hb_critical_value",
+    "hb_pvalue",
+    "rsv_critical_value",
+    "simulate_sup_chi2_cv",
+    "bootstrap_rsv_cv",
+    "HB_CRITICAL_VALUES",
+    "RSV_TABLE1",
+    # simulation
+    "simulate_rsv_dgp",
+    "simulate_segmented_cointegration",
+    "simulate_hb_dgp",
+    # reporting
+    "battery_to_dataframe",
+    "combine_results",
+    "render_table",
+    # plotting (re-exported only if matplotlib is installed)
+    "plot_series_with_breaks",
+    "plot_rsv_profile",
+    "plot_rsv_battery",
+    "plot_breakpoint_objective",
+    "plot_residual_diagnostics",
+    "plot_split_heatmap",
+    "set_style",
+]
+
+
+def cite() -> str:
+    """Return a BibTeX-formatted citation for the library and the two
+    underlying papers."""
+    return r"""
+@software{Roudane_pycointbreak_2024,
+  author  = {Roudane, Merwan},
+  title   = {pycointbreak: Python tools for fractional cointegration
+             tests with breaks},
+  year    = {2024},
+  url     = {https://github.com/merwanroudane/pycointbreak},
+  version = {""" + __version__ + r"""}
+}
+
+@article{HasslerBreitung2006,
+  author  = {Hassler, Uwe and Breitung, J{\"o}rg},
+  title   = {A Residual-Based {LM} Type Test Against Fractional
+             Cointegration},
+  journal = {Econometric Theory},
+  volume  = {22},
+  number  = {6},
+  pages   = {1091--1111},
+  year    = {2006}
+}
+
+@techreport{RodriguesSibbertsenVoges2019,
+  author      = {Rodrigues, Paulo M. M. and Sibbertsen, Philipp and
+                 Voges, Michelle},
+  title       = {Testing for breaks in the cointegrating relationship:
+                 On the stability of government bond markets'
+                 equilibrium},
+  institution = {Hannover Economic Papers (HEP)},
+  number      = {656},
+  year        = {2019}
+}
+""".strip() + "\n"
+
+
+def help_text() -> str:
+    """Return a one-screen orientation guide."""
+    return r"""
+================================================================
+  pycointbreak — Quickstart
+================================================================
+  Author : Dr. Merwan Roudane <merwanroudane920@gmail.com>
+  GitHub : https://github.com/merwanroudane/pycointbreak
+  Version: """ + __version__ + r"""
+
+  Implements:
+    - Hassler & Breitung (2006) LM test for no fractional
+      cointegration.
+    - Rodrigues, Sibbertsen & Voges (2019) supremum tests for
+      breaks in the cointegrating relationship.
+    - Break-point estimator (RSV2019 eq. 19).
+
+  Typical workflow
+  ----------------
+  >>> import numpy as np
+  >>> from pycointbreak import (
+  ...     simulate_segmented_cointegration,
+  ...     hassler_breitung_test,
+  ...     rsv_battery,
+  ...     estimate_break_point,
+  ...     plot_rsv_battery,
+  ...     plot_series_with_breaks,
+  ...     plot_breakpoint_objective,
+  ...     render_table, battery_to_dataframe,
+  ... )
+
+  >>> # 1. Get / simulate two I(d) series.
+  >>> y, x = simulate_segmented_cointegration(
+  ...     T=500, d=1.0, b=0.4, break_frac=0.5,
+  ...     regime="coint_then_spurious", seed=1)
+
+  >>> # 2. Full-sample HB test.
+  >>> hb = hassler_breitung_test(y, x, d=1.0, p=1)
+  >>> print(hb.summary())
+
+  >>> # 3. RSV battery of sup-tests for breaks.
+  >>> bat = rsv_battery(y, x, d=1.0)
+  >>> for k, r in bat.items():
+  ...     print(r.summary())
+
+  >>> # 4. Pretty Table 7-style summary.
+  >>> df = battery_to_dataframe(bat, hb=hb, label="y on x")
+  >>> print(render_table(df, fmt="text",
+  ...                    title="Tests for segmented cointegration"))
+
+  >>> # 5. Estimate the break date.
+  >>> bp = estimate_break_point(y, x, d=1.0, direction="auto")
+  >>> print(bp.summary())
+
+  >>> # 6. Plots.
+  >>> plot_series_with_breaks({"y": y, "x": x}, {"break": bp.obs})
+  >>> plot_rsv_battery(bat)
+  >>> plot_breakpoint_objective(bp)
+================================================================
+""".strip()
+
+
+def about() -> None:  # pragma: no cover
+    """Print library metadata and author info."""
+    print(help_text())

pycointbreak/breakpoint.py

@@ -0,0 +1,238 @@
+"""
+Break-point estimator
+=====================
+
+Implements eq. (19) of Rodrigues, Sibbertsen & Voges (2019):
+
+.. math::
+
+    \\hat\\tau \\;=\\; \\arg\\inf_{\\tau \\in \\Delta}
+    [\\tau T]^{-2\\hat d}\\sum_{t=1}^{[\\tau T]}\\hat e_t^{\\,2}(\\tau),
+    \\qquad \\Delta = (\\delta, 1 - \\delta),
+
+with :math:`0 < \\delta < 0.5`. By Theorem 3, when the break is from
+cointegration to no cointegration, :math:`\\hat\\tau \\to \\tau_0`.
+
+By Remark 3.3 the same estimator applied to the reversed residual
+series can be used when the break is from no cointegration to
+cointegration.
+
+Author
+------
+Dr. Merwan Roudane  <merwanroudane920@gmail.com>
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Optional, Union
+
+import numpy as np
+import pandas as pd
+
+ArrayLike = Union[np.ndarray, pd.Series, pd.DataFrame]
+
+
+@dataclass
+class BreakPointResult:
+    """Result of the RSV2019 break-point estimator.
+
+    Attributes
+    ----------
+    tau_hat : float
+        Break fraction in [0, 1].
+    obs : int
+        Observation index of the estimated break (``int(tau_hat * T)``).
+    date : pandas.Timestamp or None
+        Calendar date of the break if the input series carried a
+        DatetimeIndex.
+    delta : float
+        Trimming parameter used.
+    direction : str
+        Either 'forward' (cointegrated -> spurious) or 'backward'
+        (spurious -> cointegrated).
+    objective : numpy.ndarray
+        The objective ``[tauT]^{-2d} * SSR(tau)`` evaluated along the
+        full grid (useful for plotting).
+    tau_grid : numpy.ndarray
+        Grid of break fractions on which the objective was evaluated.
+    T : int
+    d : float
+    """
+
+    tau_hat: float
+    obs: int
+    date: Optional[pd.Timestamp]
+    delta: float
+    direction: str
+    objective: np.ndarray
+    tau_grid: np.ndarray
+    T: int
+    d: float
+
+    def summary(self) -> str:
+        lines = []
+        lines.append("=" * 70)
+        lines.append("  RSV (2019) break-point estimator")
+        lines.append("=" * 70)
+        lines.append(f"  Direction               : {self.direction}")
+        lines.append(f"  Trimming delta          : {self.delta:.3f}")
+        lines.append(f"  Fractional order d      : {self.d:.3f}")
+        lines.append(f"  Sample size T           : {self.T}")
+        lines.append("-" * 70)
+        lines.append(f"  tau_hat                 : {self.tau_hat:.4f}")
+        lines.append(f"  Observation             : {self.obs}")
+        if self.date is not None:
+            lines.append(f"  Estimated break date    : {self.date.date()}")
+        lines.append("=" * 70)
+        return "\n".join(lines)
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            f"BreakPointResult(tau_hat={self.tau_hat:.3f}, obs={self.obs}, "
+            f"direction={self.direction})"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Internal: OLS residuals
+# ---------------------------------------------------------------------------
+def _ols_residuals_for_breakpoint(
+    y1: np.ndarray,
+    y2: np.ndarray,
+    include_const: bool,
+) -> np.ndarray:
+    T = y1.size
+    if include_const:
+        X = np.column_stack([np.ones(T), y2])
+    else:
+        X = y2
+    beta, *_ = np.linalg.lstsq(X, y1, rcond=None)
+    return y1 - X @ beta
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+def estimate_break_point(
+    y1: ArrayLike,
+    y2: ArrayLike,
+    d: float = 1.0,
+    delta: float = 0.05,
+    direction: Literal["forward", "backward", "auto"] = "auto",
+    include_const: bool = True,
+    residuals: Optional[np.ndarray] = None,
+    index: Optional[pd.DatetimeIndex] = None,
+) -> BreakPointResult:
+    """Estimate the break fraction :math:`\\tau_0` per eq. (19) of
+    RSV2019.
+
+    Parameters
+    ----------
+    y1 : array_like, shape (T,)
+        Scalar :math:`I(d)` series.
+    y2 : array_like, shape (T,) or (T, m)
+        :math:`I(d)` regressor(s).
+    d : float, default 1.0
+        Fractional integration order. By Theorem 3, ``d`` need only be
+        consistently estimated.
+    delta : float, default 0.05
+        Trimming parameter :math:`0 < \\delta < 0.5`. RSV2019 (last
+        paragraph of Sec. 4) recommend a small :math:`\\delta`.
+    direction : {'forward', 'backward', 'auto'}, default 'auto'
+        ``'forward'`` corresponds to a break from cointegration to no
+        cointegration (Theorem 3). ``'backward'`` (Remark 3.3) applies
+        the estimator to the reversed residual series, suitable for a
+        break from no cointegration to cointegration. ``'auto'``
+        evaluates both and returns the lower objective value.
+    include_const : bool, default True
+        Whether to include a constant in the cointegrating regression.
+    residuals : array_like, optional
+        Pre-computed OLS residuals (overrides ``y1``, ``y2``).
+    index : pandas.DatetimeIndex, optional
+        If given, used to map the estimated observation index to a
+        calendar date.
+
+    Returns
+    -------
+    BreakPointResult
+    """
+    if residuals is None:
+        y1_arr = np.asarray(y1, dtype=float).ravel()
+        y2_arr = np.atleast_2d(np.asarray(y2, dtype=float))
+        if y2_arr.shape[0] != y1_arr.size:
+            y2_arr = y2_arr.T
+        if isinstance(y1, pd.Series) and index is None:
+            if isinstance(y1.index, pd.DatetimeIndex):
+                index = y1.index
+        e = _ols_residuals_for_breakpoint(y1_arr, y2_arr, include_const)
+    else:
+        e = np.asarray(residuals, dtype=float).ravel()
+
+    T = e.size
+    if not 0.0 < delta < 0.5:
+        raise ValueError("delta must be in (0, 0.5).")
+
+    t_lo = int(np.ceil(delta * T))
+    t_hi = int(np.floor((1.0 - delta) * T))
+    if t_hi <= t_lo + 1:
+        raise ValueError(
+            "Sample too small for the requested delta — reduce delta."
+        )
+
+    def _forward_obj(e_local: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+        tau_grid = np.arange(t_lo, t_hi + 1) / T
+        obj = np.empty(tau_grid.size, dtype=float)
+        # Cumulative sum of squared residuals — O(T) total.
+        csum_sq = np.cumsum(e_local**2)
+        for k, tt in enumerate(np.arange(t_lo, t_hi + 1)):
+            ssr = csum_sq[tt - 1]
+            scale = float(tt) ** (-2.0 * d)
+            obj[k] = scale * ssr
+        return tau_grid, obj
+
+    def _do(direction_label: str, e_local: np.ndarray):
+        tau_grid, obj = _forward_obj(e_local)
+        k_star = int(np.argmin(obj))
+        tau_hat = float(tau_grid[k_star])
+        obs = int(tau_hat * T)
+        date = None
+        if index is not None:
+            # For backward, the optimum was found on the reversed
+            # series, so the calendar position is T - obs (clipped).
+            obs_for_date = obs if direction_label == "forward" else max(
+                0, T - obs - 1
+            )
+            try:
+                date = index[obs_for_date]
+            except IndexError:
+                date = None
+        return tau_hat, obs, date, tau_grid, obj
+
+    if direction == "forward":
+        tau_hat, obs, date, grid, obj = _do("forward", e)
+    elif direction == "backward":
+        tau_hat, obs, date, grid, obj = _do("backward", e[::-1])
+    elif direction == "auto":
+        fwd = _do("forward", e)
+        bwd = _do("backward", e[::-1])
+        # Pick the one with lower objective at its argmin.
+        if fwd[4].min() <= bwd[4].min():
+            tau_hat, obs, date, grid, obj = fwd
+            direction = "forward"
+        else:
+            tau_hat, obs, date, grid, obj = bwd
+            direction = "backward"
+    else:
+        raise ValueError(f"Unknown direction '{direction}'.")
+
+    return BreakPointResult(
+        tau_hat=tau_hat,
+        obs=obs,
+        date=date,
+        delta=float(delta),
+        direction=direction,
+        objective=obj,
+        tau_grid=grid,
+        T=int(T),
+        d=float(d),
+    )