esa-2scm 0.3.1

ESA-2SCM Python Package for Causal Discovery

ESA-2SCM: Elastic Segment Allocation-based 2SLS Structural Causal Model for Causal Discovery

ESA-2SCM is a new method for detecting causality based on Elastic Segment Allocation-based synthetic instrumental variables with 2SLS application for estimating structural causal models.

For details of the model design, please refer to my Original Article:

• Lee, Sanghoon (2024). ESA-2SCM for Causal Discovery: Causal Modeling with Elastic Segmentation-based Synthetic Instrumental Variable, SnB Political and Economic Research Institute, 1, 21. <snbperi.org/article/234>

Model Overview

Suppose that you are interested in discovering the causal relationship between $x_1$ and $x_2$ (e.g., determining the true causal direction: $x_1$ -> $x_2$ vs. $x_2$ -> $x_1$, measuring the magnitude of causal impact):

Estimation of the above equation under standard OLS is structurally biased and inconsistent due to endogeneity:

where

thus,

The estimators are also asymptotically inconsistent, as:

ESA-2SCM provides a countermeasure to such problem, enabling the determination of true causal direction and estimation of the true causal coefficient through the following procedures.

1. Vector definition:

2. Sorting:

3. Set initial number of segments (M):

4. Segment size allocation:

5. Elastic adjustment algorithm for adjusting the number of segments:

6. Grouping based on the adjusted sizes and number of segments:

7. Segment value assignment:

8. Apply 2SLS using the generated Synthetic IV vectors (Z):
   

   • Get $z_1$ and $z_2$ via applying the process (1) to (7) for $x_1$ and $x_2$, then perform 2SLS to estimate for:

Compare fits to determine the true causal direction, and estimate the true causal coefficient from the correctly identified model.

Requirements

• Python3

• numpy

• pandas

• scipy

Installation

To install the ESA-2SCM package, use pip as follows:

pip install esa-2scm

Example Usage

import numpy as np
import pandas as pd
from esa_2scm import Esa2Scm

# For causal discovery and determination of the true causal direction, input x_1 and x_2 as follows to initialize the ESA-2SCM model:
model = Esa2Scm(x1, x2)

# Fit the model, using Synthetic IV generation method(syniv_method, default: 'ESA') to estimate causality
# Adjust the parameter M(default=2) to manually manage the degree of correlation between the Synthetic IVs (2SLS-converted) and the respective endogenous variables
# Adjust the regularization term tau (default=0) to control the strictness of the elastic adjustment algorithm for balanced segment size optimization
model.fit(syniv_method="esa", M=2, data_type='continuous', tau=0.01)

# To confirm the estimated causal direction:
print(model.causal_direction)

# To confirm the causal impact coefficient for the detected causal direction:
print(model.causal_coef)

# To confirm the true goodness of fit of the ESA-2SCM for determination of the causal direction:
print(model.esa2scm_score)

# With causal direction determined via ESA-2SCM, to confirm the posthoc goodness of fit of the Regression Model using original variables:
print(model.posthoc_score)

# To check the degree of correlation between the generated Synthetic IVs and the endogenous variables (x1 and x2, respectively):
print(model.corr_x1_to_slsiv)
print(model.corr_x2_to_slsiv)

# For model summary:
model.summary()

Documentation

Original Article of the ESA-2SCM:

• Lee, Sanghoon (2024). ESA-2SCM for Causal Discovery: Causal Modeling with Elastic Segmentation-based Synthetic Instrumental Variable, SnB Political and Economic Research Institute, 1, 21. <snbperi.org/article/234> [ARTICLE LINK]

Examples

Examples of running ESA-2SCM in Jupyter Notebook are included in esa_2scm/examples

License

Copyright 2024 Sanghoon Lee (DSsoli). All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Apache License 2.0

References

Should you use this package, please cite my original article as follows:

• Lee, Sanghoon (2024). ESA-2SCM for Causal Discovery: Causal Modeling with Elastic Segmentation-based Synthetic Instrumental Variable, SnB Political and Economic Research Institute, 1, 21. <snbperi.org/article/234> [ARTICLE LINK]