|
Download README.md from BioinstLab/bnet-ot-fusion: direct link, hf CLI and curl.
- Browser
- Download file 7.5 kB
-
https://huggingface.co/BioinstLab/bnet-ot-fusion/resolve/main/README.md
- Command line
-
hf download hf://BioinstLab/bnet-ot-fusion/README.md
-
curl -L -o README.md https://huggingface.co/BioinstLab/bnet-ot-fusion/resolve/main/README.md
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). | |