pattern-causality 0.0.2

Pattern Causality Algorithm in Python

pattern_causality_py

pattern_causality is a powerful Python library implementing the Pattern Causality algorithm for analyzing causal relationships in time series data. This package provides efficient tools for detecting and quantifying causality patterns between multiple time series, with particular emphasis on nonlinear complex systems.

Key Features

• Lightweight Analysis: Fast causality detection between pairs of time series
• Parameter Optimization: Automated search for optimal embedding parameters
• Cross-validation Support: Robust validation of causality results
• Matrix Analysis: Efficient computation of causality matrices for multiple time series
• Effect Analysis: Advanced tools for analyzing causal effects in complex systems

Installation

Using pip (Recommended)

The easiest way to install the package is via pip:

pip install pattern-causality

From Source

For the latest development version, you can install directly from GitHub:

pip install git+https://github.com/skstavroglou/pattern_causality_py.git

Quick Start Guide

Loading Sample Data

The package comes with a built-in climate indices dataset for testing and demonstration:

from pattern_causality import load_data

# Load the included climate indices dataset
data = load_data()
print("Available climate indices:", data.columns.tolist())

Basic Causality Analysis

Perform a basic causality analysis between two time series using the lightweight implementation:

from pattern_causality import pc_lightweight

# Load data
data = load_data()

# Example using two climate indices
X = data['NAO'].values  # North Atlantic Oscillation
Y = data['AAO'].values  # Arctic Oscillation

# Run lightweight pattern causality analysis
# Parameters:
# - E: embedding dimension
# - tau: time delay
# - h: prediction horizon
# - metric: distance metric, default is "euclidean"
# - weighted: whether to use weighted causality, default is True
result = pc_lightweight(X=X, Y=Y, E=3, tau=1, h=1)
print("Causality strength:\n", result)

Parameter Optimization

Find the optimal parameters for your specific dataset:

from pattern_causality import optimal_parameters_search

data = load_data()
# Search for best parameters up to Emax and tau_max
result = optimal_parameters_search(
    Emax=5, 
    tau_max=5, 
    metric="euclidean", 
    dataset=data.drop(columns=['Date'])
)
print("Optimal parameters:\n", result)

Cross-Validation Analysis

Validate your causality results using different sample sizes:

from pattern_causality import pc_cross_validation

data = load_data()
X = data['NAO'].values
Y = data['AAO'].values

# Perform cross-validation with different sample sizes
cv_results = pc_cross_validation(
    X=X,
    Y=Y,
    E=3,
    tau=1,
    metric="euclidean",
    h=1,
    weighted=True,
    numberset=[100, 200, 300, 400, 500]  # Different sample sizes
)
print("Cross-validation results:\n", cv_results)

Multi-Series Analysis

Analyze causality patterns between multiple time series simultaneously:

from pattern_causality import pc_matrix

data = load_data()
results = pc_matrix(
    dataset=data.drop(columns=['Date']),
    E=3,
    tau=1,
    metric="euclidean",
    h=1,
    weighted=True
)

print("Pattern Causality Matrix Results:")
print("Positive causality matrix:", results['positive'])
print("\nNegative causality matrix:", results['negative'])
print("\nDark causality matrix:", results['dark'])
print("\nVariable names:", results['items'])

Effect Analysis

Calculate and analyze the causal effects between different time series:

from pattern_causality import pc_matrix, pc_effect

# Load data and calculate pc_matrix
data = load_data()
pc_matrix_results = pc_matrix(
    dataset=data.drop(columns=['Date']),
    E=3,
    tau=1,
    metric="euclidean",
    h=1,
    weighted=True
)

# Calculate effects
effects = pc_effect(pc_matrix_results)
print("Pattern Causality Effects:")
print("\nPositive effects:", effects['positive'])
print("\nNegative effects:", effects['negative'])
print("\nDark effects:", effects['dark'])

Testing

This package includes a comprehensive test suite. To run the tests:

## Install test dependencies
pip install pytest pytest-cov
## Run tests
python -m pytest tests/
## Run tests with coverage report
python -m pytest tests/ --cov=pattern_causality

Test Coverage

The test suite covers:

• Basic functionality tests
• Advanced functionality tests
• Utility function tests

Current test coverage: 79%

Contributing

We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development

1. Clone the repository
2. Install development dependencies:

   pip install -e ".[dev]"
   

3. Run tests:

   pytest
   

References

• Stavroglou, S. K., Pantelous, A. A., Stanley, H. E., & Zuev, K. M. (2019). Hidden interactions in financial markets. Proceedings of the National Academy of Sciences, 116(22), 10646-10651.

• Stavroglou, S. K., Pantelous, A. A., Stanley, H. E., & Zuev, K. M. (2020). Unveiling causal interactions in complex systems. Proceedings of the National Academy of Sciences, 117(14), 7599-7605.

• Stavroglou, S. K., Ayyub, B. M., Kallinterakis, V., Pantelous, A. A., & Stanley, H. E. (2021). A novel causal risk‐based decision‐making methodology: The case of coronavirus. Risk Analysis, 41(5), 814-830.

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.