Metadata-Version: 2.4
Name: bnmetrics
Version: 0.2.2
Summary: Bayesian network metrics: SHD, F1, SID, and per-Markov-blanket comparisons over DAGs, CPDAGs, and PAGs.
Author: Pavel Averin
License: MIT License
License-File: LICENSE
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: numpy<3,>=1.24
Provides-Extra: dev
Requires-Dist: ipython>=8; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: networkx>=3; extra == 'dev'
Requires-Dist: pandas>=2; extra == 'dev'
Requires-Dist: pytest-xdist>=3; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2024.1; extra == 'docs'
Requires-Dist: linkify-it-py>=2; extra == 'docs'
Requires-Dist: myst-parser>=2; extra == 'docs'
Requires-Dist: sphinx-autoapi>=3; extra == 'docs'
Requires-Dist: sphinx>=7; extra == 'docs'
Provides-Extra: networkx
Requires-Dist: networkx<4,>=3.0; extra == 'networkx'
Provides-Extra: pandas
Requires-Dist: pandas<3,>=2.0; extra == 'pandas'
Provides-Extra: viz
Requires-Dist: graphviz>=0.20; extra == 'viz'
Requires-Dist: ipython>=8.0; extra == 'viz'
Requires-Dist: plotly<7,>=5.0; extra == 'viz'
Description-Content-Type: text/markdown

# `bnmetrics`: Bayesian Network Metrics

`bnmetrics` is a Python library for evaluating, comparing, and visualising
DAGs, CPDAGs, and PAGs — descriptive structural metrics, comparative
metrics including SHD, HD, F1, and SID, and Markov-blanket-scoped
analysis, with optional graphviz and plotly visualisations.

`bnmetrics` is part of the [constraint-based causal discovery
suite](https://github.com/averinpa/constraint-based-causal-discovery-suite)
alongside `cbcd` (algorithms), `citk` (CI tests), and `dagsampler`
(simulator). Any object satisfying the `bnmetrics.GraphLike` Protocol —
including `cbcd`'s `DAG`, `CPDAG`, and `PAG` instances — drives every
metric without imports between the packages.

[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation](https://img.shields.io/badge/docs-averinpa.github.io-blue.svg)](https://averinpa.github.io/constraint-based-causal-discovery-suite/bnmetrics/)

## Features

- **Descriptive metrics** — `count_edges`, `count_nodes`,
  `count_colliders`, `count_root_nodes`, `count_leaf_nodes`,
  `count_isolated_nodes`, `count_directed_arcs`,
  `count_undirected_arcs`, `count_bidirected_arcs`,
  `count_circle_edges`, `count_reversible_arcs`, `in_degree`,
  `out_degree`.
- **Comparative metrics** — `shd`, `hd`, `f1`, `precision`, `recall`,
  `true_positives`, `false_positives`, `false_negatives`,
  `count_additions`, `count_deletions`, `count_reversals`.
- **Structural Intervention Distance** — `sid()` after Peters &
  Bühlmann (2015), returning the SID together with bounds for CPDAG
  comparison.
- **Markov-blanket scoping** — `markov_blanket(g, var)` returns a
  sub-`GraphLike` that can be passed back to any metric.
- **Multi-metric comparison** — `compare(true, estimate)` produces a
  `Comparison` exposing every descriptive and comparative metric in
  a single call, with optional pandas export.
- **Visualisation** (optional `viz` extra) — side-by-side graphviz
  comparison with true-positive highlighting and a plotly heatmap
  for SID's incorrect-edge matrix.

## Installation

```bash
pip install bnmetrics                # core (numpy only)
pip install bnmetrics[viz]           # + graphviz, plotly, ipython
pip install bnmetrics[networkx]      # + networkx (DiGraph adapter input)
pip install bnmetrics[pandas]        # + pandas (compare().to_dataframe())
```

## Documentation

- Full [documentation](https://averinpa.github.io/constraint-based-causal-discovery-suite/bnmetrics/) is hosted on GitHub Pages.
- [Examples](examples/) — runnable Jupyter notebooks.
- [CHANGELOG](CHANGELOG.md).

## Acknowledgements

`bnmetrics` is the Python successor to
[DAGMetrics](https://github.com/averinpa/DAGMetrics), an R package by
the same author for analysing Bayesian networks in microbial
abundance data ([Averin et al.,
2025](https://doi.org/10.3390/agronomy15040987)). The metric
definitions — Hamming distance, structural Hamming distance, F1,
additions / deletions / reversals, reversible-arc counts, the
Markov-blanket subgraph construction — are derivative of the R
original.

The Structural Intervention Distance follows [Peters & Bühlmann
(2015)](https://doi.org/10.1162/NECO_a_00708); the implementation
operates directly on the int8 endpoint-mark matrix used throughout
the suite.

`bnmetrics` v0.2.x is a full Python rewrite around a canonical `(n, n)`
int8 endpoint-mark matrix matching `cbcd`'s representation.
Cross-package interop with `cbcd` and `dagsampler` is via the
structural `bnmetrics.GraphLike` Protocol — no imports between the
packages.

## License

[MIT](LICENSE)
