asycaus 1.0.0__py3-none-any.whl

asycaus/__init__.py

@@ -0,0 +1,64 @@
+"""
+asycaus
+=======
+
+Asymmetric Granger-causality suite for Python.  Python mirror of the Stata
+package `asycaus` by the same author.
+
+Quick start
+-----------
+
+>>> import numpy as np, asycaus
+>>> rng = np.random.default_rng(0)
+>>> x = np.cumsum(rng.standard_normal(300))
+>>> y = np.r_[0, 0.5*x[:-1] + rng.standard_normal(299)]
+>>> r = asycaus.static(y, x, shock="both", boot=200, plot=False)
+
+Available tests
+---------------
+
+asycaus.static        Hatemi-J (2012) static asymmetric (leverage bootstrap)
+asycaus.dynamic       Hatemi-J (2021) rolling / recursive
+asycaus.fourier       Nazlioglu et al. (2016) Fourier-augmented TY
+asycaus.spectral      Bahmani-Oskooee et al. (2016) BC frequency-domain
+asycaus.quantile      Fang et al. (2026) quantile asymmetric
+asycaus.efficient     Hatemi-J (2024) SUR (Pos / Neg / Joint / Pos=Neg)
+asycaus.all_tests     Run every test, return unified summary
+
+Author : Dr Merwan Roudane <merwanroudane920@gmail.com>
+GitHub : https://github.com/merwanroudane/asycaus
+License: MIT
+"""
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("asycaus")
+except PackageNotFoundError:
+    __version__ = "1.0.0"
+
+__author__  = "Dr Merwan Roudane"
+__email__   = "merwanroudane920@gmail.com"
+__license__ = "MIT"
+__url__     = "https://github.com/merwanroudane/asycaus"
+
+from . import engine
+from . import tables
+from . import plots
+from .static    import static,    StaticResult
+from .dynamic   import dynamic,   DynamicResult
+from .fourier   import fourier,   FourierResult
+from .spectral  import spectral,  SpectralResult
+from .quantile  import quantile,  QuantileResult
+from .efficient import efficient, EfficientResult
+from .all_tests import all_tests, AllResult
+from .engine    import pos_neg_components
+
+__all__ = [
+    "static", "dynamic", "fourier", "spectral", "quantile",
+    "efficient", "all_tests", "pos_neg_components",
+    "StaticResult", "DynamicResult", "FourierResult", "SpectralResult",
+    "QuantileResult", "EfficientResult", "AllResult",
+    "engine", "tables", "plots",
+    "__version__", "__author__", "__email__", "__license__", "__url__",
+]

asycaus/all_tests.py

@@ -0,0 +1,160 @@
+"""asycaus.all_tests — run the full battery and print a unified summary."""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any
+import pandas as pd
+
+from .static import static, StaticResult
+from .dynamic import dynamic, DynamicResult
+from .fourier import fourier, FourierResult
+from .spectral import spectral, SpectralResult
+from .quantile import quantile, QuantileResult
+from .efficient import efficient, EfficientResult
+
+
+@dataclass
+class AllResult:
+    static_:    StaticResult     | None = None
+    fourier_:   FourierResult    | None = None
+    efficient_: EfficientResult  | None = None
+    spectral_:  SpectralResult   | None = None
+    quantile_:  QuantileResult   | None = None
+    dynamic_:   DynamicResult    | None = None
+    summary:    pd.DataFrame     = field(default_factory=pd.DataFrame)
+    depvar: str = "y"
+    causvar: str = "x"
+
+    def print(self):
+        from .tables import print_all_summary
+        print_all_summary(self)
+        return self
+
+    def plot(self, *, save=None):
+        from .plots import plot_dashboard
+        return plot_dashboard(self, save=save)
+
+
+def all_tests(
+    y, x,
+    max_lag: int = 4,
+    ic: str = "hjc",
+    intorder: int = 1,
+    boot: int = 500,
+    seed: int | None = 12345,
+    kmax: int = 5,
+    nfreq: int = 50,
+    quantiles=(0.1, 0.25, 0.5, 0.75, 0.9),
+    window: int | None = None,
+    lnform: bool = False,
+    skip_dynamic: bool = False,
+    skip_spectral: bool = False,
+    skip_quantile: bool = False,
+    show: bool = True,
+    plot: bool = False,
+) -> AllResult:
+    """Run every asymmetric-causality test on the same (y, x) pair and print a
+    unified summary table at the end.  Dashboard plot optional via `plot=True`.
+    """
+    print("\n" + "=" * 78)
+    print(f"{'ASYMMETRIC CAUSALITY BATTERY':^78}")
+    print(f"{'Author: Dr Merwan Roudane':^78}")
+    print("=" * 78)
+    print(f" Direction tested:  causvar -> depvar")
+
+    common = dict(max_lag=max_lag, ic=ic, intorder=intorder, lnform=lnform,
+                  show=False, plot=False)
+
+    print("\n[1/6] Static Asymmetric Causality (Hatemi-J 2012)...")
+    sr = static(y, x, shock="both", boot=boot, seed=seed, **common)
+
+    print("\n[2/6] Fourier Asymmetric TY (Nazlioglu et al. 2016)...")
+    fr = fourier(y, x, shock="both", kmax=kmax, form="single", **common)
+
+    print("\n[3/6] Efficient Asymmetric (Hatemi-J 2024)...")
+    er = efficient(y, x, max_lag=max_lag, ic=ic, intorder=intorder,
+                   lnform=lnform, show=False, plot=False)
+
+    sp = None
+    if not skip_spectral:
+        print("\n[4/6] Spectral Asymmetric (Bahmani-Oskooee et al. 2016)...")
+        sp = spectral(y, x, shock="both", nfreq=nfreq, max_lag=max_lag, ic=ic,
+                      lnform=lnform, show=False, plot=False)
+
+    qr = None
+    if not skip_quantile:
+        print("\n[5/6] Quantile Asymmetric (Fang et al. 2026)...")
+        qr = quantile(y, x, shock="both", quantiles=quantiles,
+                      max_lag=max_lag, ic=ic, intorder=intorder,
+                      lnform=lnform, show=False, plot=False)
+
+    dy = None
+    if not skip_dynamic:
+        print("\n[*]   Dynamic Asymmetric (Hatemi-J 2021, Pos shocks)...")
+        try:
+            dy = dynamic(y, x, shock="pos", mode="rolling",
+                         window=window, max_lag=max_lag, ic=ic,
+                         intorder=intorder, boot=min(boot, 200), seed=seed,
+                         lnform=lnform, show=False, plot=False, progress=False)
+        except Exception as ex:
+            print(f"   (dynamic skipped: {ex})")
+            dy = None
+
+    # Build unified summary -------------------------------------------------
+    rows = []
+    for s in ["Positive", "Negative"]:
+        if s in sr.table.index:
+            row = sr.table.loc[s]
+            rows.append({"Test": "Static (Hatemi-J 2012)",
+                         "Shock": s[:3], "Statistic": row["Wald"],
+                         "p-value": row["asy_p"],
+                         "Decision": row["decision_5pct"]})
+    for s in ["Positive", "Negative"]:
+        if s in fr.table.index:
+            row = fr.table.loc[s]
+            rows.append({"Test": "Fourier (Nazlioglu 2016)",
+                         "Shock": s[:3], "Statistic": row["Wald"],
+                         "p-value": row["asy_p"],
+                         "Decision": row["decision_5pct"]})
+    eff = er.raw
+    rows.extend([
+        {"Test": "Efficient Pos only (HJ 2024)", "Shock": "Pos",
+         "Statistic": eff["W_pos"], "p-value": eff["p_pos"],
+         "Decision": "Reject" if eff["p_pos"] < 0.05 else "Fail to reject"},
+        {"Test": "Efficient Neg only (HJ 2024)", "Shock": "Neg",
+         "Statistic": eff["W_neg"], "p-value": eff["p_neg"],
+         "Decision": "Reject" if eff["p_neg"] < 0.05 else "Fail to reject"},
+        {"Test": "Efficient Joint (HJ 2024)", "Shock": "both",
+         "Statistic": eff["W_joint"], "p-value": eff["p_joint"],
+         "Decision": "Reject" if eff["p_joint"] < 0.05 else "Fail to reject"},
+        {"Test": "Efficient Pos=Neg (HJ 2024)", "Shock": "diff",
+         "Statistic": eff["W_diff"], "p-value": eff["p_diff"],
+         "Decision": "Reject" if eff["p_diff"] < 0.05 else "Fail to reject"},
+    ])
+    if sp is not None:
+        for s in sp.summary.index:
+            pct = sp.summary.loc[s, "pct_reject_5pct"]
+            rows.append({"Test": "Spectral (BCRanjbar 2016)",
+                         "Shock": s[:3], "Statistic": f"{pct:.2%} freq.",
+                         "p-value": pct,
+                         "Decision": "Reject at some" if pct > 0 else "Fail to reject"})
+    if qr is not None:
+        for s in ["Positive", "Negative"]:
+            sub = qr.table[qr.table["shock"] == s]
+            if len(sub):
+                nrej = (sub["asy_p"] < 0.05).sum()
+                pct = nrej / len(sub)
+                rows.append({"Test": "Quantile (Fang et al. 2026)",
+                             "Shock": s[:3], "Statistic": f"{pct:.2%} quant.",
+                             "p-value": pct,
+                             "Decision": "Reject at some" if nrej > 0 else "Fail to reject"})
+
+    summary = pd.DataFrame(rows)
+    out = AllResult(static_=sr, fourier_=fr, efficient_=er, spectral_=sp,
+                    quantile_=qr, dynamic_=dy, summary=summary)
+    if show:
+        out.print()
+    if plot:
+        try: out.plot()
+        except Exception: pass
+    return out

asycaus/dynamic.py

@@ -0,0 +1,131 @@
+"""asycaus.dynamic — Hatemi-J (2021) rolling / recursive asymmetric causality."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+import numpy as np
+import pandas as pd
+
+from .engine import (pos_neg_components, select_lag, wald_test,
+                     bootstrap_critical_values, ic_label)
+
+
+@dataclass
+class DynamicResult:
+    table: pd.DataFrame
+    depvar: str = "y"
+    causvar: str = "x"
+    shock: str = "pos"
+    mode: str = "Rolling window"
+    window: int = 0
+    smin: int = 0
+    nsub: int = 0
+    ic: str = "HJC"
+    boot: int = 200
+    intorder: int = 1
+
+    def print(self):
+        from .tables import print_dynamic_table
+        print_dynamic_table(self)
+        return self
+
+    def plot(self, *, ax=None, save=None):
+        from .plots import plot_dynamic
+        return plot_dynamic(self, ax=ax, save=save)
+
+
+def dynamic(
+    y, x,
+    shock: str = "pos",
+    mode: str = "rolling",
+    window: int | None = None,
+    max_lag: int = 4,
+    ic: str = "hjc",
+    intorder: int = 1,
+    boot: int = 200,
+    seed: int | None = 12345,
+    lnform: bool = False,
+    show: bool = True,
+    plot: bool = True,
+    progress: bool = True,
+) -> DynamicResult:
+    """Hatemi-J (2021) dynamic asymmetric Granger-causality.
+
+    Parameters
+    ----------
+    mode : {'rolling','recursive'}, default 'rolling'.
+    window : int or None
+        Window length S.  Defaults to Phillips-Shi-Yu (2015) lower bound
+        S = ceil(T*(0.01 + 1.8/sqrt(T))).
+    progress : bool
+        Print "subsample k/N" every 10 windows.
+    """
+    y = np.asarray(y, dtype=float).ravel()
+    x = np.asarray(x, dtype=float).ravel()
+    if lnform:
+        y = np.log(y); x = np.log(x)
+    Y = np.column_stack([y, x])
+
+    if shock.lower() in {"pos", "positive"}:
+        Zfull = pos_neg_components(Y, positive=True); s_lbl = "Positive components"
+        s_short = "pos"
+    elif shock.lower() in {"neg", "negative"}:
+        Zfull = pos_neg_components(Y, positive=False); s_lbl = "Negative components"
+        s_short = "neg"
+    else:
+        raise ValueError("shock must be 'pos' or 'neg'")
+
+    Tcomp = Zfull.shape[0]
+    if Tcomp < 10:
+        raise ValueError("Too few observations after differencing.")
+
+    smin = math.ceil(Tcomp * (0.01 + 1.8 / math.sqrt(Tcomp)))
+    if window is None:
+        window = smin
+    min_window = max_lag + intorder + 3
+    if window < min_window:
+        raise ValueError(f"window must be at least {min_window}.")
+
+    nsub = Tcomp - window + 1
+    if nsub < 1:
+        raise ValueError("window too large for the sample.")
+
+    mode = mode.lower()
+    if mode not in {"rolling", "recursive"}:
+        raise ValueError("mode must be 'rolling' or 'recursive'.")
+    mode_lbl = "Rolling window" if mode == "rolling" else "Recursive"
+
+    rows = []
+    for k in range(1, nsub + 1):
+        if progress and (k % 10 == 0 or k == nsub):
+            print(f"  subsample {k}/{nsub}")
+        if mode == "rolling":
+            s_idx, e_idx = k - 1, k - 1 + window
+        else:
+            s_idx, e_idx = 0, window + k - 1
+        Zsub = Zfull[s_idx:e_idx, :]
+        p = select_lag(Zsub, 1, max_lag, ic)
+        W, _ = wald_test(Zsub, p, intorder, dep_idx=0, cause_idx=1)
+        cv = bootstrap_critical_values(Zsub, p, intorder, 0, 1, B=boot,
+                                       seed=(seed or 0) + k)
+        rows.append({
+            "sub_start": s_idx + 1, "sub_end": e_idx, "lag": p,
+            "Wald": W, "cv10": cv["cv10"], "cv5": cv["cv5"], "cv1": cv["cv1"],
+            "ratio_5pct": W / cv["cv5"] if cv["cv5"] else np.nan,
+        })
+
+    table = pd.DataFrame(rows)
+    res = DynamicResult(
+        table=table, depvar="y", causvar="x", shock=s_short,
+        mode=mode_lbl, window=window, smin=smin, nsub=nsub,
+        ic=ic_label(ic), boot=boot, intorder=intorder,
+    )
+    if show:
+        res.print()
+    if plot:
+        try:
+            res.plot()
+        except Exception:
+            pass
+    return res

asycaus/efficient.py

@@ -0,0 +1,86 @@
+"""asycaus.efficient — Hatemi-J (2024) efficient SUR asymmetric causality."""
+
+from __future__ import annotations
+from dataclasses import dataclass
+import numpy as np
+import pandas as pd
+
+from .engine import pos_neg_components, select_lag, efficient_sur, ic_label
+
+
+@dataclass
+class EfficientResult:
+    table: pd.DataFrame
+    raw: dict
+    depvar: str = "y"
+    causvar: str = "x"
+    ic: str = "HJC"
+    intorder: int = 1
+    lag: int = 1
+
+    def print(self):
+        from .tables import print_efficient_table
+        print_efficient_table(self)
+        return self
+
+    def plot(self, *, ax=None, save=None):
+        from .plots import plot_efficient
+        return plot_efficient(self, ax=ax, save=save)
+
+
+def efficient(
+    y, x,
+    max_lag: int = 8,
+    ic: str = "hjc",
+    intorder: int = 1,
+    lnform: bool = False,
+    show: bool = True,
+    plot: bool = True,
+) -> EfficientResult:
+    """Hatemi-J (2024) efficient asymmetric causality test (SUR).
+
+    Tests four hypotheses jointly within one SUR system:
+      H1: no causality via positive shocks
+      H2: no causality via negative shocks
+      H3: joint no causality (H1 AND H2)
+      H4: Pos = Neg causal coefficients  --  the formal asymmetry test.
+    """
+    y = np.asarray(y, dtype=float).ravel()
+    x = np.asarray(x, dtype=float).ravel()
+    if lnform:
+        y = np.log(y); x = np.log(x)
+    Y = np.column_stack([y, x])
+
+    Zpos = pos_neg_components(Y, positive=True)
+    Zneg = pos_neg_components(Y, positive=False)
+    p_pos = select_lag(Zpos, 1, max_lag, ic)
+    p_neg = select_lag(Zneg, 1, max_lag, ic)
+    p = max(p_pos, p_neg)
+
+    out = efficient_sur(Zpos, Zneg, p, intorder, 0, 1)
+
+    rows = [
+        {"hypothesis": "No causality via POS shocks", "Wald": out["W_pos"],
+         "df": p,     "asy_p": out["p_pos"],
+         "decision_5pct": "Reject" if out["p_pos"]   < 0.05 else "Fail to reject"},
+        {"hypothesis": "No causality via NEG shocks", "Wald": out["W_neg"],
+         "df": p,     "asy_p": out["p_neg"],
+         "decision_5pct": "Reject" if out["p_neg"]   < 0.05 else "Fail to reject"},
+        {"hypothesis": "Joint no causality",          "Wald": out["W_joint"],
+         "df": 2 * p, "asy_p": out["p_joint"],
+         "decision_5pct": "Reject" if out["p_joint"] < 0.05 else "Fail to reject"},
+        {"hypothesis": "POS = NEG causal effects",    "Wald": out["W_diff"],
+         "df": p,     "asy_p": out["p_diff"],
+         "decision_5pct": "Reject" if out["p_diff"]  < 0.05 else "Fail to reject"},
+    ]
+    table = pd.DataFrame(rows).set_index("hypothesis")
+    res = EfficientResult(table=table, raw=out, ic=ic_label(ic),
+                          intorder=intorder, lag=p)
+    if show:
+        res.print()
+    if plot:
+        try:
+            res.plot()
+        except Exception:
+            pass
+    return res