Metadata-Version: 2.4
Name: avail-omics
Version: 1.0.2
Summary: AVAIL-omics: availability-aware multimodal integration for clinical cohorts with missing modalities.
Author: Busranur Delice
License: MIT
Keywords: multimodal,missing-modality,microbiome,neuroimaging,parkinson,machine-learning,benchmark,availability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: pandas>=1.3
Requires-Dist: scikit-learn>=1.0
Requires-Dist: scipy>=1.7
Requires-Dist: statsmodels>=0.13
Requires-Dist: matplotlib>=3.5
Requires-Dist: seaborn>=0.11
Requires-Dist: openpyxl>=3.0
Requires-Dist: networkx>=2.8
Requires-Dist: xgboost>=1.7
Provides-Extra: deep
Requires-Dist: torch>=1.13; extra == "deep"
Requires-Dist: pytorch-tabnet>=4.0; extra == "deep"
Requires-Dist: tabpfn; extra == "deep"
Requires-Dist: tabicl; extra == "deep"
Provides-Extra: imaging
Requires-Dist: nilearn>=0.10; extra == "imaging"
Requires-Dist: nibabel>=5.0; extra == "imaging"
Provides-Extra: timesfm
Requires-Dist: timesfm; extra == "timesfm"
Provides-Extra: radiomics
Requires-Dist: SimpleITK>=2.3; extra == "radiomics"
Requires-Dist: pyradiomics>=3.0; extra == "radiomics"
Provides-Extra: bio
Requires-Dist: shap>=0.41; extra == "bio"
Provides-Extra: full
Requires-Dist: torch>=1.13; extra == "full"
Requires-Dist: pytorch-tabnet>=4.0; extra == "full"
Requires-Dist: tabpfn; extra == "full"
Requires-Dist: tabicl; extra == "full"
Requires-Dist: shap>=0.41; extra == "full"
Requires-Dist: nilearn>=0.10; extra == "full"
Requires-Dist: nibabel>=5.0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: jupyter; extra == "dev"
Requires-Dist: nbformat; extra == "dev"
Dynamic: license-file

# AVAIL-omics

**Availability-aware multimodal integration for clinical cohorts with missing modalities.**

Real multimodal cohorts are incomplete: an fMRI is missing here, a shotgun
metagenome there. Complete-case analysis discards subjects; AVAIL-omics drops
*nobody*. Every modality trains its own base learner on all available
subjects, a fixed-length meta-feature vector (base probabilities +
availability flags) is assembled per subject, and a meta-learner makes the
joint decision.

## Install

```bash
pip install avail-omics           # core: CPU-only, no CUDA needed
pip install "avail-omics[deep]"   # + neural (MLP/MoE/GNN/Transformer) and
                                  #   deep-tabular (TabNet/TabPFN/TabICL) meta-learners
pip install "avail-omics[full]"   # + SHAP-based biomarker interpretation
```

## Quick start (any tabular multimodal dataset)

```python
from avail_omics.generic import run_generic_pipeline

res = run_generic_pipeline(
    data_root="mydata",      # metadata.tsv (SampleID, Group) + features/*.tsv
    out_dir="results",       # one .tsv per modality -> 11 meta-learners, LOO
)
```

Data layout (one file per modality, rows = samples):

```
mydata/
  metadata.tsv          # SampleID + Group (+ optional Age, Education, Sex)
  features/
    brain.tsv
    stool16S.tsv
    ...
```

Or use the CLI:

```bash
avail-omics run --data-root mydata --out results
avail-omics robustness --data-root mydata --out robustness \
    --permutations 25 --jobs 4          # full-pipeline label-permutation test
avail-omics sensitivity --data-root mydata --out sensitivity
```

## What is included

- **Leak-free protocol**: preprocessing, feature selection, imputation and
  hyperparameters are computed strictly inside each cross-validation fold.
- **16 missing-data strategies + hybrid**: complete-case, zero/mean/median/KNN/
  MICE/MissForest/SoftImpute imputation, availability-flag encoding, and the
  hybrid (fold-internal imputation + *true* availability flags).
- **11 meta-learners**: SimpleMean, WSimpleMean, ElasticNetLR, MLP, MoE, GNN,
  Transformer, XGBoost, TabNet, TabPFN, TabICL.
- **Robustness toolkit**: synthetic dropout, MCAR/MAR/MNAR simulation,
  label-permutation test, modality sensitivity/ablation, bootstrap CIs,
  conformal prediction sets, calibration (isotonic) with Brier reporting,
  integrity audit.

## Evidence summary (primary cohort, n=150 oral-gut-brain)

- HC vs PDD binary AUC **0.978** (MLP, leave-one-out)
- Severity continuum: Spearman ρ = 0.633 vs clinical stage; risk score tracks
  MMSE (ρ = -0.47) and CDRS (ρ = 0.63) — scores never used in training
- Label-permutation test of the full pipeline: permuted macro-AUC ≈ 0.50
  (p = 0.039), ruling out leakage as the source of the separation
- Sustains prediction where complete-case collapses (25-55% dropout)
- External validation on public cohorts: Wallen 2022 PD shotgun (AUC 0.642),
  HMP2 IBD multi-omics with genuine per-sample missingness (macro-AUC 0.771),
  preclinical AD (0.542), label-free reconstruction (Vascellari 2020)

## Web platform

A full pipeline web app (upload → auto-run → report) accompanies this
package; see the project repository.

## Citing

Manuscript in preparation. Until the paper is out, please cite the
repository and package: `avail-omics` v1.0.0.

## License

MIT
