🧬 OncoShift (oncoshift)

Enterprise Safety & Robustness Auditing Engine for Multi-Modal Health AI Foundation Models

OncoShift is a Python library for quantifying representation collapse, calibration degradation, and clinical decision utility failure in multi-modal health foundation models under real-world distribution shift.

⚡ Installation

Install the package via pip:

pip install oncoshift

Or install from source in editable mode:

git clone https://github.com/Sharon-codes/Onco-Shift.git
cd Onco-Shift
pip install -e oncoshift_sdk/

🚀 Quickstart

Audit any PyTorch model backbone or Hugging Face model repository in 3 lines of code:

import torch
import torch.nn as nn
from oncoshift import OncoAuditor

# 1. Instantiate auditor for your target medical backbone
auditor = OncoAuditor(model=my_foundation_model, modality="pathology")

# 2. Input baseline clean tensors
x_clean = torch.randn(32, 3, 224, 224)

# 3. Run automated robustness audit
results = auditor.audit(baseline_tensor=x_clean, epsilon=0.5)

# Inspect empirical metric scores
print(f"Wasserstein Distance W₁  : {results['w1_distance']:.4f}")
print(f"Gromov-Wasserstein GW₂   : {results['gromov_wasserstein']:.4f}")
print(f"Feature Leakage Ratio η  : {results['leakage_ratio']:.4f}")
print(f"SVCCA Alignment          : {results['svcca_alignment']:.4f}")
print(f"Brier Reliability Error  : {results['brier_reliability']:.4f}")
print(f"Net Benefit (at pt=0.30) : {results['net_benefit_at_30']:.4f}")

📐 Mathematical Auditing Modules

1. Optimal Transport Geometry (oncoshift.math_engine)

• 1st Wasserstein Distance ($W_1$): Linear programming exact solver (ot.emd2) over ground metric $M_{ij} = |z_P^{(i)} - z_Q^{(j)}|_2$.
• Gromov-Wasserstein Alignment ($GW_2$): Topological distance divergence solver (ot.gromov.gromov_wasserstein2).
• SVD Feature Leakage Ratio ($\eta_{\text{leakage}}$): Quantifies off-manifold feature drift via orthogonal singular vector projection.
• Singular Vector CCA ($\text{SVCCA}$): Subspace canonical correlation between baseline and shifted feature representations.

from oncoshift import (
    compute_wasserstein_nd,
    compute_gromov_wasserstein,
    compute_feature_leakage_ratio,
    compute_svcca
)

w1 = compute_wasserstein_nd(z_baseline, z_shifted)
gw2 = compute_gromov_wasserstein(z_baseline, z_shifted)
leakage = compute_feature_leakage_ratio(z_baseline, z_shifted)
svcca = compute_svcca(z_baseline, z_shifted)

2. Clinical Decision Analysis (oncoshift.auditor)

• Murphy (1973) Brier Score Decomposition: Exact decomposition into Reliability ($\text{Rel}$), Resolution ($\text{Res}$), and Uncertainty ($\text{Unc}$).
• Decision Curve Analysis (DCA Net Benefit): Measures net clinical utility at decision threshold $p_t = 0.30$.

from oncoshift import decompose_brier_score, compute_decision_curve

brier_metrics = decompose_brier_score(y_true, p_pred, n_bins=10)
print(f"Reliability Penalty: {brier_metrics['reliability']:.4f}")

dca_results = compute_decision_curve(y_true, p_pred, thresholds=[0.30])
print(f"Net Benefit at 0.30: {dca_results['net_benefit_model'][0]:.4f}")

3. Multi-Modal Distribution Shift Perturbations (oncoshift.shifts)

Generate realistic clinical perturbations across 3 primary health modalities:

• Pathology: Stain variation, defocus blur ($\sigma_{\text{blur}}$), and geometric tissue folds.
• Radiology: Acquisition motion blur and additive Gaussian sensor noise.
• EHR: Hawkes self-exciting process missingness cascades and irregular observation sampling.

from oncoshift import apply_pathology_shift, apply_radiology_shift, apply_ehr_shift

x_path_shifted = apply_pathology_shift(x_tiles, epsilon=0.5)
x_rad_shifted = apply_radiology_shift(x_cxr, epsilon=0.5)
x_ehr_shifted = apply_ehr_shift(x_seq, epsilon=0.5)

📜 Author & License

Developed by Sharon Melhi (@Sharon-codes).
Distributed under the MIT License.