Metadata-Version: 2.1
Name: gcastle
Version: 1.0.2
Summary: gCastle is the fundamental package for causal structure learning with Python.
Home-page: https://github.com/huawei-noah/trustworthyAI/tree/master/gcastle
Author: Huawei Noah's Ark Lab
Author-email: zhangkeli1@huawei.com
License: Apache License 2.0
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: tqdm (>=4.48.2)
Requires-Dist: numpy (>=1.19.1)
Requires-Dist: pandas (>=0.22.0)
Requires-Dist: scipy (>=1.4.1)
Requires-Dist: scikit-learn (>=0.21.1)
Requires-Dist: matplotlib (>=2.1.2)
Requires-Dist: python-igraph (>=0.8.2)
Requires-Dist: loguru (>=0.5.3)
Requires-Dist: networkx (>=2.5)
Requires-Dist: torch (>=1.4.0)
Requires-Dist: tensorflow (>=1.15.0)

# gCastle

## Introduction

`gCastle` is a causal structure learning toolchain developed by [Huawei Noah's Ark Lab](https://www.noahlab.com.hk/#/home). The package contains various functionality related to causal learning and evaluation, including:

* Data generation and processing: data simulation, data reading operators, and data pre-processing operators (such as prior injection and variable selection).
* Causal structure learning: causal structure learning methods, including both classic and recently developed methods, especially gradient-based ones that can handle large problems.
* Evaluation metrics: various commonly used metrics for causal structure learning, including F1, SHD, FDR, TPR, FDR, NNZ, etc.

## Algorithm List

| Algorithm | Category (based on data) | Description |
| :--: | :-- | :-- |
| [PC](https://arxiv.org/abs/math/0510436) | IID | A classic causal discovery algorithm based on conditional independence tests |
| [DirectLiNGAM](https://arxiv.org/abs/1101.2489) | IID | A direct learning algorithm for linear non-Gaussian acyclic model (LiNGAM) |
| [ICALiNGAM](https://dl.acm.org/doi/10.5555/1248547.1248619) | IID | An ICA-based learning algorithm for linear non-Gaussian acyclic model (LiNGAM) |
| [NOTEARS](https://arxiv.org/abs/1803.01422) | IID | A gradient-based algorithm for linear data models (typically with least-squares loss) |
| [NOTEARS-MLP](https://arxiv.org/abs/1909.13189) | IID | A gradient-based algorithm using neural network modeling for non-linear causal relationships |
| [NOTEARS-SOB](https://arxiv.org/abs/1909.13189) | IID | A gradient-based algorithm using Sobolev space modeling for non-linear causal relationships |
| [NOTEARS-lOW-RANK](https://arxiv.org/abs/2006.05691) | IID | Adapting NOTEARS for large problems with low-rank causal graphs |
| [GOLEM](https://arxiv.org/abs/2006.10201) | IID | A more efficient version of NOTEARS that can reduce number of optimization iterations |
| [GraN_DAG](https://arxiv.org/abs/1906.02226) | IID | A gradient-based algorithm using neural network modeling for non-linear additive noise data  |
| [MCSL](https://arxiv.org/abs/1910.08527) | IID | A gradient-based algorithm for non-linear additive noise data by learning the binary adjacency matrix|
| [GAE](https://arxiv.org/abs/1911.07420) | IID | A gradient-based algorithm using graph autoencoder to model non-linear causal relationships|
| [RL](https://arxiv.org/abs/1906.04477) | IID | A RL-based algorithm that can work with flexible score functions (including non-smooth ones) |
| CORL1 | IID | A RL- and order-based algorithm that improves the efficiency and scalability of previous RL-based approach |
| CORL2 | IID | A RL- and order-based algorithm that improves the efficiency and scalability of previous RL-based approach |
| TTPM | EVENT SEQUENCE | A causal structure learning algorithm based on Topological Hawkes process for spatio-temporal event sequences |

## Installation

### Dependencies

gCastle requires:

* python (>= 3.6)
* tqdm (>= 4.48.2)
* numpy (>= 1.19.1)
* pandas (>= 0.22.0)
* scipy (>= 1.4.1)
* scikit-learn (>= 0.21.1)
* matplotlib (>=2.1.2)
* python-igraph (>= 0.8.2)
* loguru (>= 0.5.3)
* networkx (>= 2.5)
* torch (>= 1.4.0)
* tensorflow (>= 1.15.0)

### PIP installation

```bash
pip install gcastle
```

## Usage Example (PC algorithm)

```python
from castle.common import GraphDAG
from castle.metrics import MetricsDAG
from castle.datasets import IIDSimulation, DAG
from castle.algorithms import PC

# data simulation, simulate true causal dag and train_data.
weighted_random_dag = DAG.erdos_renyi(n_nodes=10, n_edges=10,
                                      weight_range=(0.5, 2.0), seed=1)
dataset = IIDSimulation(W=weighted_random_dag, n=2000, method='linear',
                        sem_type='gauss')
true_causal_matrix, X = dataset.B, dataset.X

# structure learning
pc = PC()
pc.learn(X)

# plot predict_dag and true_dag
GraphDAG(pc.causal_matrix, true_causal_matrix)

# calculate metrics
mt = MetricsDAG(pc.causal_matrix, true_causal_matrix)
print(mt.metrics)
```

You can visit [examples](https://github.com/huawei-noah/trustworthyAI/tree/master/gcastle) to find more examples.

## Next Up & Contributing

You can find more news about [gCastle](https://github.com/huawei-noah/trustworthyAI/tree/master/gcastle) on the github website.


