EcoFair is a privacy-preserving Vertical Federated Learning framework for skin‑lesion diagnosis.
Each patient case is first processed by a lite model on the edge image client; the heavy model (also resident on the image client) is activated selectively only when the routing gate triggers. Raw images and raw tabular records are never transmitted — only compact embeddings are sent to the server for multimodal fusion.

The framework jointly optimises:

• Clinical accuracy — malignant-class detection across dangerous skin lesion categories,
• Energy efficiency — across the full edge-to-cloud inference path,
• Demographic fairness — across age and sex subgroups, and
• Neurosymbolic risk-awareness — integrating expert-derived risk scores from age and anatomical site metadata.

Offline feature extraction (once per dataset):
The notebooks in feature_extraction/ run lite and heavy CNN backbones over each dataset and record image embeddings alongside an energy_stats.json file per model. The lite model's energy figures reflect the physical power constraints of low-power edge hardware (e.g. Raspberry Pi class devices). The heavy model's energy is measured on GPU using pynvml. Both are consumed by the pipeline notebooks to produce hardware-grounded energy metrics.

Online inference:
The lite backbone runs entirely on the edge image client; raw images remain local and are never transmitted. The lite model produces an image embedding and an initial diagnosis probability vector. The tabular client (also on the edge node) encodes patient metadata — age, sex, anatomical site, neurosymbolic risk score — into a second embedding. Both embeddings are forwarded to the central server for multimodal fusion via the shared server head.

Neurosymbolic routing:
Before server submission, a three-tier gate on the edge decides whether the lite result alone is sufficient or whether the heavy model (also on the image client) should be activated:

• Uncertainty — softmax entropy of the lite output exceeds a normalised threshold,
• Ambiguity — the probability gap between safe and dangerous class mass is too small,
• Safety — a neurosymbolic risk score (age × anatomical-site malignancy rate) exceeds a clinical threshold.

If any gate fires, the heavy backbone is invoked on the image client, its embedding is transmitted alongside the lite embedding, and the server head produces an ensembled prediction. Otherwise only the lite path is used, saving energy.

.
├── ecofair-ham.ipynb          # Pipeline notebook — HAM10000
├── ecofair-bcn.ipynb          # Pipeline notebook — BCN20000
├── ecofair-pad.ipynb          # Pipeline notebook — PAD‑UFES‑20
├── feature_extraction/
│   ├── image-feature-extractor-lite.ipynb   # Lite CNN extraction + edge energy profiling
│   ├── image-feature-extractor-heavy.ipynb  # Heavy CNN extraction + GPU energy profiling
│   └── README.md
└── src/                       # Backend modules — loaded by the pipeline notebooks
    ├── config.py              # Hyper-parameters and MODEL_PAIRS
    ├── data_loader.py         # Feature / metadata alignment and CV splits
    ├── features.py            # Neurosymbolic risk scoring and tabular feature engineering
    ├── models.py              # VFL model topology (adapters, tabular client, server head)
    ├── training.py            # 5-fold CV driver (multi-pair)
    ├── routing.py             # Threshold and budget routing, SafetyFirst optimiser
    ├── fairness.py            # Subgroup fairness metrics (EO TPR, DP rate)
    ├── visualization.py       # All figures (confusion matrices, Pareto, fairness, etc.)
    └── utils.py               # Seeds, energy loading, CSV I/O

The src/ modules are dataset-agnostic and serve as the backend for all three pipeline notebooks. All dataset-specific configuration — paths, class lists, safe/dangerous splits — is defined at the top of each notebook.

For all three datasets, dangerous/malignant classes are mel, bcc, scc (and akiec on HAM10000); safe classes are the remaining non-malignant categories.

Lite and heavy branches share the same VFL topology — only the backbone CNN differs. Both lite and heavy backbones run on the edge image client; only embeddings are sent to the server.

Model pairs evaluated (configured in src/config.py):

Each pipeline notebook runs the full EcoFair pipeline for three lite→heavy model pairs under 5-fold stratified group cross-validation. Outputs are written to output/<DATASET>/ (e.g. ham_cv_results.csv, bcn_energy_metrics.csv, pad_fairness_summary.csv).

Per-pair fairness bar charts comparing Lite, EcoFair, and Heavy across the three datasets:

Additional outputs per notebook: subgroup accuracy, Equal Opportunity, Demographic Parity tables; confusion matrices; clinical safety plots; Pareto frontier (energy vs worst-group TPR).

All notebooks are designed to run on a Jupyter-compatible platform (Kaggle, JupyterLab, VS Code, Google Colab).

Step 1 — Extract features:
Open and run image-feature-extractor-lite.ipynb and image-feature-extractor-heavy.ipynb for each dataset. Each notebook writes features.npy, ids.npy, and energy_stats.json under output/<DATASET>/<MODEL>/. See feature_extraction/README.md for details.

Step 2 — Run the pipeline:
Open the relevant pipeline notebook and execute all cells:

Update the path constants at the top of each notebook to point to your local dataset locations and the feature extraction outputs from Step 1.