asymcaus: Asymmetric Causality Testing (GAUSS-Compatible)

A Python implementation fully compatible with the original GAUSS code by Abdulnasser Hatemi-J (2012).

Overview

This package provides asymmetric causality testing with exact compatibility with the original GAUSS implementation. All function names, parameters, and logic match the GAUSS code.

Reference

Hatemi-J, A. (2012). "Asymmetric causality tests with an application."
Empirical Economics, 43(1), 447-456.

Key Features

✅ Full GAUSS Compatibility

• Function names match GAUSS code exactly
• Same parameters and return values
• Identical mathematical implementation
• Compatible results with original code

✅ Complete Implementation

• asymmetric_causality_test() ← asymCause()
• cumulative_component() ← cumulativeComp()
• select_lag_order() ← lag_length2()
• compute_wald_statistic() ← W_test()
• bootstrap_critical_values() ← Bootstrap_Toda()
• varlags() ← varlags()
• rstrctvm() ← rstrctvm()
• estvar_params() ← estvar_params()

✅ All Information Criteria

• AIC (Akaike Information Criterion)
• AICC (Corrected AIC)
• SBC (Schwarz Bayesian Criterion / BIC)
• HQC (Hannan-Quinn Criterion)
• HJC (Hatemi-J Criterion)

✅ Interactive Visualizations

• Component decomposition plots
• Test results visualization
• Multi-test comparisons

Installation

git clone https://github.com/merwanroudane/asymcaus.git
cd asymcaus
pip install -e .

Quick Start

GAUSS-Compatible Syntax

import numpy as np
from asymcaus import asymmetric_causality_test, COMPONENT_POSITIVE, IC_SBC

# Generate data
y = np.random.randn(200, 1).cumsum(axis=0)
z = np.random.randn(200, 1).cumsum(axis=0)

# Test asymmetric causality (GAUSS-compatible)
Wstat, critical_values, lag_order, azd = asymmetric_causality_test(
    y=y,
    z=z,
    pos=COMPONENT_POSITIVE,  # 1 = positive, 0 = negative
    infocrit=IC_SBC,         # 3 = SBC/BIC
    intorder=0,              # Integration order
    ln_form=0,               # Log transformation (0=no, 1=yes)
    maxlags=8,               # Maximum lags
    bootmaxiter=1000,        # Bootstrap iterations
    fullprint=0              # Print details (0=no, 1=yes)
)

print(f"Wald Statistic: {Wstat:.4f}")
print(f"Critical Values (1%, 5%, 10%): {critical_values}")
print(f"Optimal Lag Order: {lag_order}")

GAUSS Function Mapping

Parameter Compatibility

Information Criteria (infocrit)

from asymcaus import IC_AIC, IC_AICC, IC_SBC, IC_HQC, IC_HJC, IC_MAXLAGS

# GAUSS: infocrit = 1
# Python:
infocrit = IC_AIC  # or simply: infocrit = 1

# GAUSS: infocrit = 3
# Python:
infocrit = IC_SBC  # or simply: infocrit = 3

Component Type (pos)

from asymcaus import COMPONENT_POSITIVE, COMPONENT_NEGATIVE

# GAUSS: pos = 1
# Python:
pos = COMPONENT_POSITIVE  # or simply: pos = 1

# GAUSS: pos = 0
# Python:
pos = COMPONENT_NEGATIVE  # or simply: pos = 0

Complete Examples

Example 1: Basic Test (GAUSS-style)

from asymcaus import asymmetric_causality_test

# GAUSS equivalent:
# { Wstat, WcriticalvalsS, ICOrder, Azdsys } = asymCause(y, z, 1, 3, 0, 0, 8, 1000, 0);

Wstat, WcriticalvalsS, ICOrder, Azdsys = asymmetric_causality_test(
    y, z, pos=1, infocrit=3, intorder=0, ln_form=0, 
    maxlags=8, bootmaxiter=1000, fullprint=0
)

Example 2: Component Decomposition

from asymcaus import cumulative_component

# GAUSS equivalent:
# { CUMDYZpc, CUMDYZnc } = cumulativeComp(data, 0, 0);

CUMDYZpc, CUMDYZnc = cumulative_component(data, ln_form=0, fullprint=0)

Example 3: All Four Combinations

from asymcaus import test_all_combinations

results = test_all_combinations(
    y, z,
    infocrit=3,
    bootmaxiter=1000
)

# Results contain:
# - pos_to_pos: Positive shocks → Positive shocks
# - pos_to_neg: Positive shocks → Negative shocks
# - neg_to_pos: Negative shocks → Positive shocks
# - neg_to_neg: Negative shocks → Negative shocks

Visualization

from asymcaus import plot_components, plot_causality_results, plot_multiple_tests

# Plot cumulative components
fig1 = plot_components(data, pos_comp, neg_comp, var_names=['y', 'z'])
fig1.show()

# Plot test results
fig2 = plot_causality_results(Wstat, critical_values)
fig2.show()

# Compare multiple tests
fig3 = plot_multiple_tests(results)
fig3.show()

Running Examples

cd examples
python gauss_compatible_example.py

This will:

1. Generate sample data
2. Decompose into components
3. Test all combinations
4. Create visualizations
5. Show GAUSS equivalence guide

Compatibility Verification

The package has been tested for compatibility with the original GAUSS code:

✅ Same shock decomposition results
✅ Identical lag selection
✅ Matching Wald statistics
✅ Equivalent bootstrap critical values
✅ Same restriction matrix logic

Documentation

• README.md - This file
• GAUSS_COMPATIBILITY.md - Detailed compatibility guide
• examples/ - Working examples with GAUSS equivalents

Dependencies

• Python >= 3.7
• numpy >= 1.20.0
• scipy >= 1.7.0
• plotly >= 5.0.0

Citation

@software{asymcaus2024,
  author = {Roudane, Merwan},
  title = {asymcaus: Asymmetric Causality Testing (GAUSS-Compatible)},
  year = {2024},
  url = {https://github.com/merwanroudane/asymcaus}
}

@article{hatemi2012asymmetric,
  title={Asymmetric causality tests with an application},
  author={Hatemi-J, Abdulnasser},
  journal={Empirical Economics},
  volume={43},
  number={1},
  pages={447--456},
  year={2012}
}

License

MIT License - see LICENSE file

Author

Dr. Merwan Roudane

• Email: merwanroudane920@gmail.com
• GitHub: https://github.com/merwanroudane

Acknowledgments

• Original GAUSS code by Abdulnasser Hatemi-J
• Scott Hacker for VAR estimation procedures
• Alan G. Isaac for varlags function

Version: 1.0.0
Status: Production/Stable
GAUSS Compatibility: ✅ Verified