bust-pid: BUST-PID Framework for Partial Information Decomposition

A Python toolkit for computing bivariate Partial Information Decomposition (PID) on discrete data, with quadratic-extrapolation bias correction, permutation screening, and the BUST (Breadth--Uniformity--Synergy--Total) scoring framework.

BUST-PID provides a complete pipeline from raw discrete variables to publication-ready synergy maps. It is designed for cohort studies where sample sizes are moderate and finite-sample bias matters, but the methods are general and apply to any discrete multivariate dataset.

This repository accompanies the manuscript
"Interpreting Higher-Order Dependence in Multimorbidity using Cohort Data:
A Partial Information Decomposition Approach", currently under review at
*PLOS Computational Biology.

The code is shared at this stage so that reviewers and readers can inspect the analysis pipeline. The API may change before acceptance, and a tagged release (v1.0) will be cut once the paper is accepted.

The LASA cohort data on which the paper's analyses are run are not, and will not be, included in this repository — access is governed by the LASA Steering Group (request data). A synthetic-data demo (examples/demo_end_to_end.py) reproduces the full pipeline without LASA access.

---

Installation

From PyPI (when published):

pip install bust-pid

From source:

git clone https://github.com/cillianhourican/bust-pid.git
cd bust-pid
pip install -e .

For development dependencies (pytest, coverage):

pip install -e ".[dev]"

---

Quick Start

Run the self-contained demo (no data files needed):

git clone https://github.com/cillianhourican/bust-pid.git
cd bust-pid
pip install -e .
python examples/demo_end_to_end.py

This generates synthetic data and runs the full pipeline: discretise, screen, estimate PID, compute BUST scores, build networks, and produce plots in demo_output/.

For a step-by-step tutorial see docs/quickstart.md; for LASA paper reproduction see examples/lasa_reproduction/.

Note on dit and NumPy 2.0

If you encounter AttributeError: np.alltrue was removed, patch the installed dit package:

sed -i 's/np\.alltrue/np.all/g' \
  $(python -c "import dit, pathlib; print(pathlib.Path(dit.__file__).parent)")/{helpers,validate}.py

---

Module Overview

Module	Description
estimation	PID atom computation via dit, quadratic-extrapolation bias correction, bootstrap confidence intervals.
screening	Permutation-based significance screening with Benjamini--Hochberg FDR control.
bust	BUST score computation: Breadth, Uniformity, Synergy strength, and Total information.
network	Synergy network construction, hierarchical clustering, similarity matrices, and clique detection.
plotting	Visualization functions for BUST maps, PID recovery plots, forest/CI plots.
utils	Data discretisation, sparse-state merging, and I/O helpers.
synthetic	Synthetic data generators with analytic ground-truth PID atoms for pipeline validation.

---

Citation

If you use this software, please cite:

Hourican, C., Peeters, G., Melis, R. J. F., Kok, A., van Schoor, N. M., Wezeman, S., Lees, M., Olde Rikkert, M. G. M., Quax, R. Interpreting Higher-Order Dependence in Multimorbidity using Cohort Data: A Partial Information Decomposition Approach. (To appear.)

BibTeX:

@article{hourican2025bust,
  title   = {Interpreting Higher-Order Dependence in Multimorbidity
             using Cohort Data: A Partial Information Decomposition Approach},
  author  = {Hourican, Cillian and Peeters, Geeske and
             Melis, Ren{\'e} J.F. and Kok, Almar and
             van Schoor, Natasja M. and Wezeman, Sandra and
             Lees, Mike and Olde Rikkert, Marcel G.M. and
             Quax, Rick},
  note    = {To appear}
}

---

License

MIT. See LICENSE for details.