Metadata-Version: 2.4
Name: causaliq-analysis
Version: 0.4.0
Summary: Tools for analysing and visualising causal graphs
Author-email: CausalIQ <info@causaliq.com>
Maintainer-email: CausalIQ <info@causaliq.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/causaliq/causaliq-analysis
Project-URL: Documentation, https://github.com/causaliq/causaliq-analysis#readme
Project-URL: Repository, https://github.com/causaliq/causaliq-analysis
Project-URL: Bug Tracker, https://github.com/causaliq/causaliq-analysis/issues
Keywords: causaliq
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: causaliq-workflow>=0.5.0
Requires-Dist: click>=8.0.0
Requires-Dist: causaliq-core>=0.7.0
Requires-Dist: causaliq-data
Requires-Dist: causaliq-knowledge>=0.6.0
Requires-Dist: compress-pickle
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pandas-stubs>=2.0.0; extra == "dev"
Requires-Dist: types-requests>=2.32.0; extra == "dev"
Requires-Dist: pre-commit>=2.20.0; extra == "dev"
Requires-Dist: build>=0.8.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.10.0; extra == "test"
Provides-Extra: workflow
Requires-Dist: causaliq-workflow>=0.5.0; extra == "workflow"
Provides-Extra: docs
Requires-Dist: mkdocs<2.0.0,>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
Requires-Dist: mkdocstrings==0.30.1; extra == "docs"
Requires-Dist: mkdocstrings-python==1.18.2; extra == "docs"
Dynamic: license-file

# causaliq-analysis

![Python Versions](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)

This repo provides tools for analysing and visualising learned causal graphs,
including structural metrics, stability assessment, significance tests, and
publication-ready tables and charts. It is part of the
[CausalIQ ecosystem](https://causaliq.org/) for intelligent causal discovery.

## Status

**Current Version**: v0.4.0

This repository is part of the [CausalIQ ecosystem](https://causaliq.org/) and
is in active development. Recent work has focused on graph evaluation,
optimal DAG extraction, and metric summarisation.


## Features

✅ **Implemented Releases**

- **Release v0.4.0 - Evaluation & Summarisation**: Structural evaluation
  metrics (F1, precision, recall, SHD) vs ground truth, optimal DAG
  extraction from PDGs, metric summarisation, noisy-OR and max merge
  strategies.
- **Release v0.3.0 - Graph Merging**: Merge multiple DAGs/PDAGs/PDGs into
  probabilistic dependency graphs (PDGs) with weighted edge probabilities.
  Trace migration to convert legacy traces to modern GraphML format.
- **Release v0.2.0 - Legacy Trace**: Support for reading and writing
  structure learning traces in legacy pickle format.
- **Release v0.1.0 - Foundation Metrics**: CausalIQ and Bayesys structural
  graph metrics and KL metric.

🛣️ **Upcoming Releases**

- **Release v0.5.0 - Publication Assets**: publication-ready charts and tables


## Upcoming Key Innovations

### 🧠 LLM-assisted Graph Averaging
- **Uncertain or conflicting edges** - resolved using LLM queries

### 📊 Publication-ready chart generation
- **Seaborn charts** - flexible, but standardised publication-ready chart generation

### ▦ Publication-ready table generation
- **LaTeX tables** - converts tabular analysis data into publication-ready LaTeX tables
 
## Integration with CausalIQ Ecosystem

- 🔍 **CausalIQ Discovery** generates causal graphs which this package evaluates and visualises.
- 🤖 **CausalIQ Workflow** can access all features of this package (through the Action interface) so that analysis and visualisation are incorporated into CausalIQ workflows.
- 🧪 **CausalIQ Papers** uses the analysis, table and chart features of this package to generate published paper assets.

## LLM Support

The following provides project-specific context for this repo which should be provided after the [personal and ecosystem context](https://github.com/causaliq/causaliq/blob/main/LLM_DEVELOPMENT_GUIDE.md):

```text
I wish to migrate the code in legacy/core/metrics.py following all CausalIQ development guidelines
so that the legacy repo can use the migrated code instead. 
```

## Quick Start

```python
# to be completed
```

## Getting started

### Prerequisites

- Git 
- Latest stable versions of Python 3.9, 3.10. 3.11, 3.12 or 3.13


### Clone the new repo locally and check that it works

Clone the causaliq-analysis repo locally as normal

```bash
git clone https://github.com/causaliq/causaliq-analysis.git
```

Set up the Python virtual environments and activate the default Python virtual environment. You may see
messages from VSCode (if you are using it as your IDE) that new Python environments are being created
as the scripts/setup-env runs - these messages can be safely ignored at this stage.

```text
scripts/setup-env -Install
scripts/activate
```

Check that the causaliq-analysis CLI is working, check that all CI tests pass, and start up the local mkdocs webserver. There should be no errors  reported in any of these.

```text
causaliq-analysis --help
scripts/check_ci
mkdocs serve
```

Enter **http://127.0.0.1:8000/** in a browser and check that the 
causaliq-data documentation is visible.

If all of the above works, this confirms that the code is working successfully on your system.


## Documentation

Full API documentation is available at: **http://127.0.0.1:8000/** (when running `mkdocs serve`)

## Contributing

This repository is part of the CausalIQ ecosystem. For development setup:

1. Clone the repository
2. Run `scripts/setup-env -Install` to set up environments  
3. Run `scripts/check_ci` to verify all tests pass
4. Start documentation server with `mkdocs serve`

---

**Supported Python Versions**: 3.9, 3.10, 3.11, 3.12, 3.13  
**Default Python Version**: 3.11  
**License**: MIT

