bnet-ot-fusion / README.md
BioinstLab's picture
Initial commit: BNet-OT multimodal late fusion implementation
3c8ce9d
|
Raw History Blame Contribute Delete
7.5 kB
# Sinkhorn-Based Optimal Transport Late Fusion for Breast Cancer Diagnosis
> **This is a cleaned reimplementation of the method in Asiedu Asare et al. (2026).**
> The original notebooks, trained models, and intermediate outputs from the 2025 experiments were not retained, so results may not reproduce exactly.
Paper:
> Asiedu Asare M, Acquah I, Appiah Yeboah B, Owusu E. **Resilient Sinkhorn-Based Optimal Transport Late Fusion Framework for Breast Cancer Diagnosis.** *Cancer Informatics.* 2026;25:1–15. doi:[10.1177/11769351261420789](https://doi.org/10.1177/11769351261420789)
The framework combines two independently trained models, a histopathology image classifier (BreakHis) and a clinical risk-factor model (BCSC), at the level of their output probabilities. The fusion layer aligns the two predictions with entropy-regularized optimal transport and is designed to keep working when one modality is missing.
This repository implements the fusion layer and its evaluation as described in the paper. It does not include the two upstream models; it takes their predicted probabilities as input.
## What is implemented
| Paper | Code |
|---|---|
| Eq. 13: predictions as vectors in the probability simplex | `otfusion.fusion.to_distribution` |
| Eq. 14: modality mask m = [m_p, m_q] | `otfusion.fusion.modality_mask` (NaN = missing), or masks passed explicitly |
| Eq. 15: uniform substitution for a missing modality | `otfusion.fusion.substitute_missing` |
| Eq. 16: confidence-weighted fusion factor α | `otfusion.fusion.dynamic_alpha` |
| Eq. 17: cost matrix (divergence + clinical semantic penalty) | `otfusion.fusion.cost_matrix`, `semantic_cost` |
| Eq. 18: entropic OT, Sinkhorn-Knopp in the log domain | `otfusion.sinkhorn.sinkhorn_log` |
| Eq. 19: fused prediction from the row marginal of T*, outer-product fallback | `otfusion.fusion.sinkhorn_fusion` |
| Simulated modality dropout (Table 5) | `otfusion.dropout.simulate_dropout` |
| Calibrated fused output (Figs. 3–4) | `otfusion.calibration` (isotonic regression) |
| PR-AUC, recall, F1, Brier, 95% bootstrap CIs (1000 resamples), paired tests | `otfusion.metrics` |
| Decision curve analysis (Fig. 3) | `otfusion.metrics.net_benefit`, `otfusion.plots.plot_decision_curve` |
| Calibration curve, PR curve, average transport plan (Figs. 4–5) | `otfusion.plots` |
| Runtime per sample | recorded by `otfusion.pipeline.run_evaluation` |
## Default parameters
Defaults in `FusionConfig` are the values reported in the paper:
| Parameter | Value | Meaning |
|---|---|---|
| `fp_weight` (w_p) | 1.8 | Semantic cost, entry (0, 1) of C_semantic |
| `fn_weight` (w_n) | 1.2 | Semantic cost, entry (1, 0) of C_semantic |
| `alpha` | 0.1 | Blend between divergence and semantic cost; `"dynamic"` uses Eq. 16 |
| `reg` | 0.15 | Entropic regularization of the OT problem |
| `max_iter` | 5000 | Maximum Sinkhorn iterations |
| `stop_thr` | 1e-9 | Sinkhorn convergence threshold |
| `eps` | 1e-8 | Numerical stability constant in Eq. 16 |
## Installation
```bash
git clone <this repository>
cd bnet-ot-fusion
pip install -e . # or: pip install -r requirements.txt
```
Python 3.10 or later. Dependencies: NumPy, SciPy, scikit-learn, matplotlib.
## Usage
### As a library
```python
import numpy as np
from otfusion import FusionConfig, sinkhorn_fusion
p_hist = np.array([0.92, 0.15, np.nan]) # histopathology P(malignant); NaN = missing
p_risk = np.array([0.40, 0.70, 0.65]) # clinical risk P(high risk)
result = sinkhorn_fusion(p_hist, p_risk, FusionConfig())
result.fused # (N, 2) fused probability vectors
result.plans # (N, 2, 2) transport plans
result.fallback # samples where the outer-product fallback was used
```
### Full evaluation
Save each model's predictions as `.npy` files (positive-class probabilities of shape `(N,)` or two-class vectors of shape `(N, 2)`), then:
```bash
python scripts/evaluate.py \
--hist p_hist_test.npy --risk p_risk_test.npy --labels y_test.npy \
--calib-hist p_hist_val.npy --calib-risk p_risk_val.npy --calib-labels y_val.npy \
--out results/
```
This writes `results.json` (metrics with CIs for the fused model and baselines, paired comparisons, dropout results, runtime) and four figures to `results/`. Run `python scripts/evaluate.py --help` for all options.
### Demo on synthetic data
```bash
python examples/synthetic_demo.py
```
Runs the whole pipeline on random synthetic predictions to show the inputs and outputs. The numbers it prints are unrelated to the paper.
## Implementation notes
The paper's description leaves a few choices open. This implementation resolves them as follows:
- **α (Eqs. 16–17).** Eq. 16 defines a per-sample, confidence-weighted α, while the training section reports a fixed blending factor α = 0.1. The default is the fixed value; set `alpha="dynamic"` for Eq. 16.
- **Regularization naming.** The paper uses ε both for the entropic regularization in Eq. 18 and for a 1e-8 stability constant. Here they are separate: `reg` (0.15) for Eq. 18 and `eps` (1e-8) for Eq. 16.
- **Sinkhorn solver.** A batched log-domain Sinkhorn-Knopp solver is implemented directly in NumPy/SciPy. The fallback plan p ⊗ q is used when the final marginal violation exceeds `fallback_tol` (1e-6).
- **Row marginal.** Because Eq. 18 constrains T 1 = p̃, the row marginal read out in Eq. 19 equals the (mask-substituted) histopathology vector p̃ whenever Sinkhorn converges. This is covered by `tests/test_fusion.py::test_eq19_row_marginal_equals_p_under_marginal_constraint`.
- **Calibration.** The paper reports calibrated fused probabilities. Here an isotonic calibrator is fitted on a separate calibration split when provided, and otherwise cross-fitted (5 folds), so that no sample is calibrated with its own label.
- **Dropout.** By default each affected sample loses one modality chosen at random ("randomly omitting 1 input source"). Modes `hist`, `risk` and `both` are also available.
- **Paired tests.** `paired_comparison` scores both models on the same bootstrap resamples and reports the difference with a 95% CI, a bootstrap p-value, and a paired t-test on the replicates (as reported in the paper). The t-test p-value depends on the number of resamples, so the CI is the more interpretable summary.
## Tests
```bash
pip install pytest
pytest
```
The tests check the Sinkhorn solution against a brute-force optimum, the marginal constraints, masking and uniform substitution, Eq. 16 limits, the cost matrix, the fallback, dropout masks, metrics against scikit-learn, decision-curve formulas, and an end-to-end pipeline run.
## Data
The datasets are publicly available from their owners and are not redistributed here:
- BreakHis: http://www.inf.ufpr.br/vri/databases/BreaKHis_v1.tar.gz
- BCSC Risk Factors: https://www.bcsc-research.org/index.php/datasets/rf/risk-factor-dataset-download
## Citation
```bibtex
@article{asieduasare2026sinkhorn,
title = {Resilient Sinkhorn-Based Optimal Transport Late Fusion Framework for Breast Cancer Diagnosis},
author = {Asiedu Asare, Michael and Acquah, Isaac and Appiah Yeboah, Benjamin and Owusu, Emmanuel},
journal = {Cancer Informatics},
volume = {25},
pages = {1--15},
year = {2026},
doi = {10.1177/11769351261420789}
}
```
## Contact
Michael Asiedu Asare, Biomedical Technologies Lab, Kwame Nkrumah University of Science and Technology.
Corresponding author: Isaac Acquah (iacquah.coe@knust.edu.gh).