{"id":48268965,"url":"https://github.com/utkukose/gemex","last_synced_at":"2026-04-04T22:01:49.527Z","repository":{"id":349181301,"uuid":"1200561146","full_name":"utkukose/gemex","owner":"utkukose","description":"GEMEX is a novel, model-agnostic Explainable AI (XAI) library   grounded in Riemannian information geometry and differential   geometry. It treats a trained model as defining a statistical   manifold equipped with the Fisher Information Metric and derives   all explanations from the intrinsic geometry of that manifold.","archived":false,"fork":false,"pushed_at":"2026-04-04T15:41:04.000Z","size":8588,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T18:31:00.267Z","etag":null,"topics":["differential-geometry","explainable-ai","explainable-artificial-intelligence","explainable-machine-learning","explainable-ml","fisher-information-metric","gemex","manifold","model-agnostic","model-agnostic-explanations","riemannian-geometry","riemannian-information-geometry","xai"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/utkukose.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-03T15:00:53.000Z","updated_at":"2026-04-04T15:49:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/utkukose/gemex","commit_stats":null,"previous_names":["utkukose/gemex"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/utkukose/gemex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utkukose%2Fgemex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utkukose%2Fgemex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utkukose%2Fgemex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utkukose%2Fgemex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/utkukose","download_url":"https://codeload.github.com/utkukose/gemex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utkukose%2Fgemex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31416332,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T20:09:54.854Z","status":"ssl_error","status_checked_at":"2026-04-04T20:09:44.350Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["differential-geometry","explainable-ai","explainable-artificial-intelligence","explainable-machine-learning","explainable-ml","fisher-information-metric","gemex","manifold","model-agnostic","model-agnostic-explanations","riemannian-geometry","riemannian-information-geometry","xai"],"created_at":"2026-04-04T22:01:30.608Z","updated_at":"2026-04-04T22:01:49.506Z","avatar_url":"https://github.com/utkukose.png","language":"Python","readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://raw.githubusercontent.com/utkukose/gemex/main/docs/images/GEMEX_logo.png\" alt=\"GEMEX — Geodesic Entropic Manifold Explainability\" width=\"360\"/\u003e\n\n# GEMEX\n### Geodesic Entropic Manifold Explainability\n\n*The first XAI library grounded in Riemannian information geometry*\n\n[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://python.org)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-1.2.1-orange.svg)](pyproject.toml)\n[![ORCID](https://img.shields.io/badge/ORCID-0000--0002--9652--6415-a6ce39.svg)](https://orcid.org/0000-0002-9652-6415)\n[![Submitted to: IEEE HORA 2026](https://img.shields.io/badge/IEEE-HORA%202026-blue.svg)](#publication)\n\n**Prof. Dr. Utku Kose**\n\nSuleyman Demirel University, Turkey \u0026nbsp;·\u0026nbsp; University of North Dakota, USA\n\u0026nbsp;·\u0026nbsp; VelTech University, India \u0026nbsp;·\u0026nbsp; Universidad Panamericana, Mexico\n\n[utkukose@gmail.com](mailto:utkukose@gmail.com) \u0026nbsp;·\u0026nbsp; [www.utkukose.com](http://www.utkukose.com)\n\n\u003c/div\u003e\n\n---\n\n**GEMEX** explains *any* machine learning model — tabular data, time series, or\nimages — by measuring the **true curved geometry** of its prediction surface,\nrather than approximating it as flat.\n\n```bash\npip install gemex\n```\n\n---\n\n## Quick start\n\n```python\nfrom gemex import Explainer, GemexConfig\n\ncfg = GemexConfig(n_geodesic_steps=20, n_reference_samples=60,\n                  interaction_order=2)\nexp = Explainer(model, data_type='tabular',\n                feature_names=feature_names,\n                class_names=['No','Yes'], config=cfg)\n\nresult = exp.explain(x_instance, X_reference=X_train)\n\nprint(result.summary())\nprint(result.top_features(5))\nprint(result.top_interactions(3))\nprint(f\"Ricci: {result.manifold_curvature:.4f}  FIM: {result.fim_quality}\")\n\n# All 13 visualisation types — dark and light themes\nresult.plot(\"gsf_bar\",             theme=\"dark\")\nresult.plot(\"force\",               theme=\"dark\")\nresult.plot(\"waterfall\",           theme=\"dark\")\nresult.plot(\"heatmap\",             theme=\"dark\")\nresult.plot(\"beeswarm\",            theme=\"dark\", batch_results=batch)\nresult.plot(\"network\",             theme=\"dark\")\nresult.plot(\"curvature\",           theme=\"dark\")\nresult.plot(\"attention_heatmap\",   theme=\"dark\")\nresult.plot(\"attention_dwell\",     theme=\"dark\")\nresult.plot(\"attention_vs_effect\", theme=\"dark\")\nresult.plot(\"bias\",                theme=\"dark\")\nresult.plot(\"image_trio\",          theme=\"dark\")  # image data only\nresult.plot(\"triplet_hypergraph\",  theme=\"dark\")  # interaction_order=3\n```\n\n---\n\n## All 13 visualisations — what they show and how to read them\n\n### 1 · GSF Attribution Bar Chart (`gsf_bar`)\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/utkukose/gemex/main/docs/images/pima_gsf_bar_dark.png\" width=\"88%\" alt=\"GEMEX GSF attribution bar chart\"/\u003e\n\u003c/div\u003e\n\n**What it shows:** Each bar is a signed **Geodesic Sensitivity Field (GSF)** score\n— how strongly each feature pushes the model's prediction toward or against the\npredicted class, measured by integrating directional sensitivity along the curved\ngeodesic path on the statistical manifold.\n\n**How to read it:**\n- 🟢 **Green bar** → feature *supports* the predicted class. Longer = stronger.\n- 🔴 **Red/orange bar** → feature *opposes* the predicted class.\n- **Error bars** → curvature-weighted geometric uncertainty. Width reflects how\n  much the manifold curves in that feature's direction. Wide bars mean the model's\n  surface is geometrically complex near this feature — a confidence indicator\n  *exclusive to GEMEX* (unavailable in SHAP or LIME).\n- Features are **sorted by absolute importance** (most important at bottom).\n- Unlike SHAP values, GSF scores are **reparametrisation-invariant**: rescaling a\n  feature (e.g. cm → metres) does not change its attribution.\n\n---\n\n### 2 · Force Plot (`force`)\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/utkukose/gemex/main/docs/images/pima_force_dark.png\" width=\"88%\" alt=\"GEMEX force plot\"/\u003e\n\u003c/div\u003e\n\n**What it shows:** A waterfall-style push/pull visualisation showing how the\nprediction probability is built up from a baseline value through the contributions\nof each feature.\n\n**How to read it:**\n- The plot reads left-to-right from baseline probability to final prediction.\n- 🟢 **Green segments** push the probability upward (toward the predicted class).\n- 🔴 **Red segments** pull it downward.\n- Feature order follows actual attribution magnitude — the largest movers appear first.\n- The final bar position shows the predicted probability.\n- Useful for explaining a single prediction to a non-technical stakeholder: \"your\n  prediction starts at the average of 0.5 and these factors moved it to 0.73.\"\n\n---\n\n### 3 · Waterfall Chart (`waterfall`)\n\n**What it shows:** Cumulative attribution from baseline to prediction, shown as\na stacked bar where each feature's contribution is added sequentially.\n\n**How to read it:**\n- Start at the left (baseline f(x₀)) and read right to the final prediction f(x).\n- Each step shows the marginal contribution of one feature along the geodesic.\n- Unlike the force plot, waterfall shows the exact numerical accumulation at each step.\n- Useful for verifying completeness: the cumulative sum should approach f(x) − f(x₀).\n\n---\n\n### 4 · Feature × Instance Heatmap (`heatmap`)\n\n**What it shows:** A 2D heatmap where each row is one instance and each column\nis one feature. Cell colour encodes the signed GSF attribution.\n\n**How to read it:**\n- **Bright warm colours** → strong positive attribution (feature supports prediction).\n- **Cool/dark colours** → negative or near-zero attribution.\n- **Consistent bright columns** → features the model reliably uses across instances.\n- **Variable columns** → feature influence is instance-specific.\n- Most useful with 10+ instances to reveal global patterns and outliers.\n\n---\n\n### 5 · Beeswarm Distribution (`beeswarm`)\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/utkukose/gemex/main/docs/images/pima_beeswarm_dark.png\" width=\"88%\" alt=\"GEMEX beeswarm plot\"/\u003e\n\u003c/div\u003e\n\n**What it shows:** A global view of attribution distributions across a batch of\ninstances — the GEMEX equivalent of SHAP's beeswarm summary plot.\n\n**How to read it:**\n- Each dot is one instance. Dots are spread vertically to avoid overlap.\n- **Horizontal position** → GSF attribution value (positive right, negative left).\n- **Dot colour** → feature value (warm = high, cool = low) using the original scale.\n- Wide horizontal spread = feature has variable importance across instances.\n- Narrow cluster near zero = feature rarely matters regardless of its value.\n- Requires `batch_results=batch` argument. Run `exp.explain_batch(X_test[:50])` first.\n\n---\n\n### 6 · Feature Interaction Network (`network`)\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/utkukose/gemex/main/docs/images/heart_network_dark.png\" width=\"78%\" alt=\"GEMEX interaction network\"/\u003e\n\u003c/div\u003e\n\n**What it shows:** A graph of pairwise feature interactions measured via\n**Parallel Transport Interaction (PTI)** — the holonomy angle accumulated when\nparallel-transporting a feature's attribution vector around a closed loop on the\nstatistical manifold.\n\n**How to read it:**\n- **Node size** → absolute GSF importance. Larger = more important.\n- 🟢 **Green node** → feature supports the prediction.\n- 🔴 **Red node** → feature opposes the prediction.\n- **Edge thickness** → strength of the nonlinear interaction. Thick = strong\n  co-dependency that no additive method (SHAP, LIME) can capture.\n- 🟡 **Yellow edge** → amplifying interaction (features reinforce each other).\n- 🟣 **Purple edge** → suppressing interaction (features partially cancel).\n- **Dashed ring** → Bias Trap risk (geodesic over-attends this feature).\n- **\"HUB\" label** → high geometric interaction with many other features.\n\n---\n\n### 7 · Geodesic Arc-Length Profile (`curvature`)\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/utkukose/gemex/main/docs/images/heart_geodesic_profile_dark.png\" width=\"90%\" alt=\"Geodesic arc-length and Ricci scalar\"/\u003e\n\u003c/div\u003e\n\n**What it shows:** Two panels: (left) how the geodesic path length evolves from\nbaseline to instance for multiple instances; (right) the distribution of Ricci\nscalars across a batch.\n\n**How to read it:**\n- The **dashed diagonal** = perfectly flat manifold (what SHAP and Integrated\n  Gradients assume). Deviations reveal genuine curvature.\n- **Deviation above diagonal** → model surface curves upward; high sensitivity region.\n- **Sharp steps** → decision boundary crossings (visible in GBM/Random Forest).\n  GEMEX follows the actual path over these; SHAP walks straight through them.\n- **Right panel (Ricci histogram)** → higher = more curved decision boundary.\n  High Ricci = prediction in a geometrically complex region requiring careful interpretation.\n  *This metric does not exist in SHAP, LIME, or GradCAM.*\n\n---\n\n### 8 · Feature Attention Heatmap (`attention_heatmap`)\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/utkukose/gemex/main/docs/images/heart_attention_heatmap_dark.png\" width=\"80%\" alt=\"GEMEX FAS attention heatmap\"/\u003e\n\u003c/div\u003e\n\n**What it shows:** The **Feature Attention Sequence (FAS)** — how long the\ngeodesic path \"dwells\" near each feature's axis during the journey from baseline\nto the explained instance. A form of geometric attention map.\n\n**How to read it:**\n- **Bright yellow cell** → geodesic spends a long time moving in this feature's\n  direction — the model is geometrically \"attentive\" to it along the path.\n- **Dark cell** → resolved quickly; feature's influence is concentrated and local.\n- **Rows** = instances; **columns** = features.\n- Stable bright columns (same across rows) = features the model consistently uses.\n- Variable columns = instance-specific dependencies.\n- Unusually bright cells that do not correspond to high GSF scores may indicate\n  Bias Trap risk (see plot 11).\n\n---\n\n### 9 · Attention Dwell Bar Chart (`attention_dwell`)\n\n**What it shows:** Per-feature geodesic dwell time as a simple bar chart for one\ninstance — a more readable version of one row from the heatmap.\n\n**How to read it:**\n- Taller bar = geodesic spends more time near this feature axis.\n- Compare to the GSF bar chart: features with high dwell but low GSF are potential\n  Bias Trap candidates — the model \"thinks about\" them a lot but doesn't assign them\n  much final importance.\n- Useful for understanding the model's internal geometric reasoning process.\n\n---\n\n### 10 · Attention vs Effect Scatter (`attention_vs_effect`)\n\n**What it shows:** A scatter plot of geodesic dwell time (x-axis) vs absolute\nGSF attribution (y-axis) for all features in one instance.\n\n**How to read it:**\n- **Top-right quadrant** → high dwell, high effect: features the model both\n  attends to and acts on. These are the most geometrically important features.\n- **Top-left quadrant** → high effect, low dwell: the model resolves these features\n  quickly but strongly. Sharp, local decision boundaries.\n- **Bottom-right quadrant** → high dwell, low effect: **potential Bias Trap**.\n  The model spends geometric attention here but produces little final output.\n- **Bottom-left quadrant** → low dwell, low effect: unimportant features.\n\n---\n\n### 11 · Bias Trap Detection (`bias`)\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/utkukose/gemex/main/docs/images/heart_bias_dark.png\" width=\"75%\" alt=\"GEMEX bias trap detection\"/\u003e\n\u003c/div\u003e\n\n**What it shows:** Features where the model has developed **geometric bias** —\nthe geodesic path spends disproportionately long near a feature's axis relative\nto its actual effect on the prediction. A novel GEMEX-exclusive diagnostic.\n\n**How to read it:**\n- **High risk bar** → dwell time is disproportionate to effect. The model may be\n  over-relying on this feature in a geometrically unstable way.\n  *Flag for review — especially if the feature is a sensitive attribute (age, sex, ethnicity).*\n- **Low risk** → dwell and effect are proportionate. Attribution is geometrically stable.\n- This plot has no equivalent in any other XAI library. The concept draws from the\n  Riemannian geometry of the model's statistical manifold and cannot be computed\n  from SHAP values, LIME coefficients, or gradient maps.\n\n---\n\n### 12 · GeodesicCAM / ManifoldSeg / PerturbFlow (`image_trio`)\n\n**What it shows:** Three-panel image explanation for `data_type='image'`:\n- **Panel 1 (Original)** — the input image.\n- **Panel 2 (GeodesicCAM)** — GSF attribution upsampled to pixel space. Bright\n  regions = model most sensitive here along the geodesic path. *Model-agnostic\n  equivalent of GradCAM — no CNN access required.*\n- **Panel 3 (ManifoldSeg)** — iso-information regions: areas where the model's\n  prediction sensitivity is approximately equal. Similar to a level-set of the\n  probability function on the manifold.\n- **Panel 4 (PerturbFlow)** — geodesic gradient field: arrows show how pixel\n  changes would propagate on the manifold surface.\n\n**How to read it:** Bright GeodesicCAM regions are the most discriminative for\nthe prediction. ManifoldSeg boundaries separate regions of qualitatively different\nmodel sensitivity. PerturbFlow arrows show the local direction of maximum\nprediction change.\n\n---\n\n### 13 · Triplet Hypergraph (`triplet_hypergraph`)\n\n**What it shows:** Three-way feature interactions computed via the\n**Riemannian Curvature Triplet (RCT)** — a visualisation of the Riemann curvature\ntensor projected onto feature triplets. Requires `interaction_order=3`.\n\n**How to read it:**\n- Each triangle represents a feature triplet (i, j → k).\n- **Gold triangle** → synergistic triplet (positive curvature): the three features\n  together produce more than their pairwise sum.\n- **Purple triangle** → antagonistic triplet (negative curvature): features partially\n  cancel each other's three-way contribution.\n- Triangle opacity encodes magnitude.\n- Node size encodes absolute GSF importance.\n- *GEMEX is the only XAI library that computes three-way feature interactions.*\n\n---\n\n## Validated comparative results\n\n\u003e **These results are to appear in a peer-reviewed study**. Currently submitted to IEEE HORA 2026.\n\u003e Three datasets × three model families (GBM, MLP, DeepMLP) × 5 random seeds.\n\n### Key finding 1 — Stability: GEMEX is 6–8× more consistent than SHAP\n\nAcross all three datasets and all model families, GEMEX produces the most\nconsistent explanations for similar inputs (Lipschitz stability metric, lower is\nbetter):\n\n| Dataset | GEMEX | SHAP | Ratio |\n|---|---|---|---|\n| Pima Diabetes (GBM) | **0.145** | 0.891 | 6.1× |\n| Heart Disease (GBM) | **0.139** | 1.064 | 7.7× |\n| Breast Cancer (GBM) | **0.304** | 2.397 | 7.9× |\n\nIn clinical settings this matters directly — a clinician comparing two similar\npatients should not receive contradictory attribution outputs from the same method.\n\n### Key finding 2 — Monotonicity improves with model smoothness\n\nGEMEX monotonicity (directional accuracy of attributions) improves substantially\non smooth neural network models, reaching 0.538 (MLP) and 0.587 (DeepMLP) on\nHeart Disease vs 0.125 on GBM. This reflects the geodesic integrator's superior\nperformance on smooth probability surfaces where the path does not cross\npiecewise-constant boundaries.\n\n### Key finding 3 — Ricci scalar tracks model geometry\n\nThe Ricci scalar decreases as model depth increases on Heart Disease:\nGBM 0.563 → MLP 0.355 → DeepMLP 0.310. This reflects the well-known\ntendency of deeper networks toward flatter probability landscapes, and GEMEX\nis the only XAI tool that captures this as a quantitative geometric signal.\n\n\n### Understanding the evaluation metrics\n\n| Metric | ↑/↓ | What it measures | Reference |\n|---|---|---|---|\n| **Faithfulness** | ↑ higher | Spearman correlation between attribution rank and prediction drop when features removed in that order | Alvarez-Melis \u0026 Jaakkola (2018, NeurIPS)¹ |\n| **Monotonicity** | ↑ higher | Fraction of features where attribution sign matches the direction of prediction change when that feature is perturbed | Luss et al. (2019, KDD)² |\n| **Completeness error** | ↓ lower | |Σ attributions − (f(x) − f(baseline))| — how far attributions deviate from the actual prediction change | Sundararajan et al. (2017, ICML)³ |\n| **Stability** | ↓ lower | Lipschitz ratio: attribution distance / input distance, averaged over random pairs — lower = more consistent explanations for similar inputs | Alvarez-Melis \u0026 Jaakkola (2018, NeurIPS)¹ |\n| **Ricci scalar** | — | Intrinsic curvature of the model's statistical manifold. Higher = more curved decision boundary. **GEMEX-exclusive — no equivalent in other methods.** | Amari \u0026 Nagaoka (2000)⁴ |\n\n*¹ Alvarez-Melis, D. \u0026 Jaakkola, T.S. (2018). Towards Robust Interpretability with Self-Explaining Neural Networks. NeurIPS 31.*\n*² Luss, R., Chen, P.Y., Dhurandhar, A., et al. (2019). Generating Contrastive Explanations with Monotonic Attribute Functions. arXiv:1905.12698. Published KDD 2021.*\n*³ Sundararajan, M., Taly, A. \u0026 Yan, Q. (2017). Axiomatic Attribution for Deep Networks. ICML 2017, PMLR 70:3319–3328.*\n*⁴ Amari, S. \u0026 Nagaoka, H. (2000). Methods of Information Geometry. AMS.*\n\n### Stability showcase\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/utkukose/gemex/main/docs/images/A_stability_showcase.png\" width=\"97%\" alt=\"Stability comparison\"/\u003e\n\u003c/div\u003e\n\n### Ricci scalar — exclusive to GEMEX\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/utkukose/gemex/main/docs/images/C_ricci_exclusive.png\" width=\"90%\" alt=\"Ricci scalar\"/\u003e\n\u003c/div\u003e\n\n### Complete metric comparison\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/utkukose/gemex/main/docs/images/D_complete_comparison.png\" width=\"97%\" alt=\"All metrics\"/\u003e\n\u003c/div\u003e\n\n---\n\n## Model-agnostic image XAI\n\nGEMEX treats CNN image classifiers as genuine black boxes. It requires only\na probability output function — no layer hooks, no gradient access, no\narchitectural knowledge. The examples below cover greyscale X-ray,\ngreyscale CT organs, and **3-channel RGB** blood cell microscopy.\n\n### Chest X-ray — PneumoniaMNIST\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/utkukose/gemex/main/docs/images/pneumonia_comparison_dark.png\" width=\"97%\" alt=\"GEMEX vs GradCAM — chest X-ray\"/\u003e\n\u003c/div\u003e\n\nGEMEX (GeodesicCAM) identifies bilateral lower lobe infiltrates in this pneumonia\ncase using only `predict_proba()`. GradCAM requires full internal CNN access.\nDeletion AUC: GEMEX=0.835, GradCAM=0.939, GradCAM++=0.708.\n\n### Blood cell microscopy — BloodMNIST (RGB, 8 classes)\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/utkukose/gemex/main/docs/images/bloodmnist_class0_dark.png\" width=\"97%\" alt=\"GEMEX vs GradCAM — blood cell Basophil\"/\u003e\n\u003c/div\u003e\n\nBloodMNIST is a **3-channel RGB dataset** (blood cell microscopy, 8 cell types).\nFor the Basophil class, GEMEX highlights the cell body as the dominant region\n(Ricci=0.545, FIM=good) — matching GradCAM and GradCAM++ — using only\noutput probabilities, with no CNN layer access.\n\n### Abdominal CT organs — OrganAMNIST (11 classes)\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/utkukose/gemex/main/docs/images/organamnist_class8_dark.png\" width=\"97%\" alt=\"GEMEX vs GradCAM — abdominal organ\"/\u003e\n\u003c/div\u003e\n\nGEMEX achieves mean Deletion AUC of 0.335 across 11 organ classes, outperforming\nGradCAM (0.291) and Saliency (0.234). Mean Ricci scalar: 0.637±0.100 (all FIM\nquality ratings: good).\n\n\u003e **Important distinction:** GradCAM treats CNNs as white boxes — it hooks into\n\u003e convolutional layer activations and backpropagates gradients. It cannot explain\n\u003e proprietary APIs, non-CNN models, or any model where internal layers are\n\u003e inaccessible. GEMEX explains the same CNN as a genuine black box.\n\n\n## What no other XAI method provides\n\n| Capability | GEMEX | SHAP | LIME | GradCAM |\n|---|:---:|:---:|:---:|:---:|\n| Reparametrisation-invariant attribution | ✓ | ✗ | ✗ | ✗ |\n| Holonomy pairwise interactions (PTI) | ✓ | ✗ | ✗ | ✗ |\n| Three-way Riemann curvature (RCT) | ✓ | ✗ | ✗ | ✗ |\n| Geometric uncertainty per feature | ✓ | ✗ | ✗ | ✗ |\n| Manifold curvature (Ricci scalar) | ✓ | ✗ | ✗ | ✗ |\n| Bias Trap Detection (BTD) | ✓ | ✗ | ✗ | ✗ |\n| Feature Attention Sequence (FAS) | ✓ | ✗ | ✗ | ✗ |\n| Black-box image XAI (greyscale + RGB) | ✓ | ✗ | partial | ✗ |\n| Tabular + time series + image | ✓ | partial | partial | ✗ |\n\n---\n\n## Supported data types\n\n```python\n# Tabular (medical, financial, scientific)\nexp = Explainer(model, data_type='tabular', ...)\n\n# Time series (ECG, HAR, sensor signals)\nexp = Explainer(model, data_type='timeseries', ...)\n\n# Image — patch-based, genuine black box (no architecture access)\ncfg = GemexConfig(image_patch_size=4)   # 28×28 → 7×7=49 patches, ~6× faster\nexp = Explainer(model, data_type='image', ..., config=cfg)\n```\n\n---\n\n## Installation\n\n```bash\npip install gemex                  # core\npip install gemex[torch]           # + PyTorch CNN support\npip install medmnist               # MedMNIST medical imaging\npip install gemex[full]            # all backends\n```\n\n---\n\n## Examples\n\n| # | Script | Data type | Datasets |\n|---|---|---|---|\n| 01 | `01_tabular_heart_diabetes.py` | Tabular | Cleveland Heart Disease, Pima Diabetes (data sets in csv files, also downloadable)|\n| 02 | `02_comparative_study.py` | Tabular | Heart + Diabetes + Breast Cancer vs SHAP/LIME/ELI5 (GBM, MLP, DeepMLP) |\n| 03 | `03_timeseries_ecg.py` | Time series | ECG5000 (real data included in ECG5000/ folder) |\n| 04 | `04_ablation_study.py` | Tabular | Per-component ablation with Wilcoxon tests |\n| 05 | `05_statistical_comparison.py` | Tabular | Multi-seed study with bootstrap CI |\n| 06 | `06_pneumoniamnist.py` | Image | PneumoniaMNIST — GEMEX vs GradCAM vs GradCAM++ |\n| 07 | `07_pathmnist.py` | Image | PathMNIST — Colorectal cancer tissue (9 classes) |\n| 08 | `08_dermamnist.py` | Image | DermaMNIST — Skin lesions HAM10000 (7 classes) |\n| 09 | `09_organamnist.py` | Image | OrganAMNIST — Abdominal CT organs (11 classes) |\n| 10 | `10_bloodmnist.py` | Image | BloodMNIST — Blood cell microscopy (8 classes) |\n\n---\n\n## Configuration reference\n\n| Parameter | Default | Description |\n|---|---|---|\n| `n_geodesic_steps` | 40 | 4th-order Runge-Kutta (RK4) integration steps along geodesic |\n| `n_reference_samples` | 80 | Background distribution sample size |\n| `fim_epsilon_auto` | True | Auto-expand step size for tree/GBM models |\n| `fim_local_n` | 16 | Neighbourhood perturbation count |\n| `interaction_order` | 2 | 1=attribution only · 2=+PTI holonomy · 3=+RCT triplets |\n| `image_patch_size` | 1 | 1=pixel · 4=7×7 patches (~6× faster, stronger Ricci) |\n| `model_type` | 'auto' | 'auto' · 'tree' · 'smooth' |\n| `gsf_normalise` | False | Force sum(GSF) = f(x) − f(baseline) |\n\n---\n\n## Current limitations and design trade-offs\n\nLike any XAI framework, GEMEX involves trade-offs between geometric richness,\ncomputational cost, and axiomatic coverage. The points below are known limitations\nin v1.2.1 that are being actively addressed in future versions.\n\n- **Speed vs geometric richness:** Tracing a geodesic requires more model calls\n  per instance than straight-line perturbation methods such as SHAP or LIME.\n  This is a fundamental trade-off of the manifold approach, not a fixable bug.\n  See [speed tips](#speed-tips) for settings that bring the cost down significantly.\n  GPU parallelisation of the RK4 integrator is planned for v1.3.0.\n- **Tree model FIM quality:** GBM, XGBoost and Random Forest produce flat\n  probability regions between split boundaries, making FIM gradient estimation\n  harder. GEMEX handles this automatically with adaptive step-size expansion,\n  though results are less reliable than on smooth models. Always check\n  `result.fim_quality` — a `'poor'` rating signals that Ricci scalar values\n  for that instance should be treated with caution. Improved tree-specific FIM\n  estimation is on the roadmap.\n- **Completeness is a diagnostic, not a constraint:** GEMEX attributions are\n  not forced to sum to f(x) − f(baseline). Ablation testing confirmed that\n  adding this constraint destabilises the geodesic. Completeness error is best\n  treated as a descriptive metric rather than a quality gate. Future versions\n  may explore optional soft-completeness modes.\n- **High-dimensional Ricci estimation:** Beyond roughly 100 input features,\n  FIM neighbourhood sampling can become sparse and Ricci may return zero for\n  some instances. Increasing `fim_local_n` and `fim_local_sigma` mitigates\n  this in most cases. A more scalable high-dimensional FIM estimator is\n  planned for v1.3.0.\n\n---\n\n\u003ca name=\"speed-tips\"\u003e\u003c/a\u003e\n## Speed tips\n\nGEMEX trades computation for geometric richness. Here are the main levers:\n\n| Goal | Setting | Effect |\n|---|---|---|\n| **Quick exploration** | `n_geodesic_steps=8, n_reference_samples=20` | ~5× faster, slightly less accurate geodesic |\n| **Attribution only** | `interaction_order=1` | Skip PTI/RCT computation, saves ~30% |\n| **Image data** | `image_patch_size=4` | 784 pixels → 49 patches, ~6× faster |\n| **Tree models** | `model_type='tree'` | Starts at larger epsilon, avoids wasted zero-gradient calls |\n| **Production** | `n_geodesic_steps=12, n_reference_samples=30, interaction_order=1` | ~0.25 s/instance |\n\n```python\n# Fast settings for exploration\ncfg_fast = GemexConfig(\n    n_geodesic_steps    = 8,\n    n_reference_samples = 20,\n    interaction_order   = 1,   # attribution only — no interactions\n    verbose             = False\n)\n\n# Recommended settings for publication-quality results\ncfg_full = GemexConfig(\n    n_geodesic_steps    = 20,\n    n_reference_samples = 60,\n    interaction_order   = 2,   # + PTI pairwise interactions\n    fim_local_n         = 16,\n    fim_local_sigma     = 0.10,\n)\n```\n\n**FIM quality check:** Always inspect `result.fim_quality` after explaining.\nIf it returns `'poor'`, increase `fim_local_n` or `fim_local_sigma`, or switch\nto `model_type='tree'` for tree-based models.\n\n```python\nresult = exp.explain(x, X_reference=X_train)\nif result.fim_quality == 'poor':\n    print(\"Warning: FIM poorly estimated. Try increasing fim_local_n.\")\n    print(f\"  Ricci scalar may be unreliable: {result.manifold_curvature:.4f}\")\n```\n\n**Batch explanation:** Use `explain_batch` rather than looping for efficiency:\n\n```python\n# Preferred — single reference computation\nbatch = exp.explain_batch(X_test[:50], X_reference=X_train)\nfig = batch[0].plot('beeswarm', batch_results=batch, theme='dark')\n```\n\n---\n\n\u003ca name=\"publication\"\u003e\u003c/a\u003e\n## Publication\nSubmitted:\n\u003e **Kose, U. (2026). GEMEX: Model-Agnostic XAI via Geodesic Entropic Manifold Analysis.**\n\u003e *8th International Congress on Human-Computer Interaction, Optimization and Robotic\n\u003e Applications (HORA 2026), May 21–23, 2026. IEEE indexed.*\n\nThe peer-reviewed paper presents full experimental validation: 5-seed comparative\nstudy (GBM, MLP, DeepMLP) across three medical datasets, ablation analysis,\nECG5000 time series evaluation, and image XAI comparison with GradCAM and\nGradCAM++ on PneumoniaMNIST, OrganAMNIST and BloodMNIST (RGB).\n\n```bibtex\n@inproceedings{kose_gemex_2026,\n  author    = {Kose, Utku},\n  title     = {GEMEX: Model-Agnostic XAI via Geodesic Entropic Manifold Analysis},\n  booktitle = {8th International Congress on Human-Computer Interaction,\n               Optimization and Robotic Applications (HORA 2026)},\n  year      = {2026},\n  month     = {May},\n  note      = {Submitted. IEEE indexed. ORCID: 0000-0002-9652-6415}\n}\n```\n\n---\n\n## References\n\n1. Amari, S. \u0026 Nagaoka, H. (2000). *Methods of Information Geometry.* American Mathematical Society.\n2. Rao, C.R. (1945). Information and accuracy in statistical estimation. *Bulletin of the Calcutta Mathematical Society*, 37, 81–91.\n3. Kobayashi, S. \u0026 Nomizu, K. (1963). *Foundations of Differential Geometry.* Interscience.\n4. **Alvarez-Melis, D. \u0026 Jaakkola, T.S. (2018).** Towards Robust Interpretability with Self-Explaining Neural Networks. *Advances in Neural Information Processing Systems 31 (NeurIPS 2018),* 7786–7795.\n5. **Luss, R., Chen, P.Y., Dhurandhar, A., Sattigeri, P., Zhang, Y., Shanmugam, K. \u0026 Tu, C.C. (2019).** Generating Contrastive Explanations with Monotonic Attribute Functions. arXiv:1905.12698. Published *KDD 2021,* 1139–1149.\n6. **Sundararajan, M., Taly, A. \u0026 Yan, Q. (2017).** Axiomatic Attribution for Deep Networks. *Proceedings of the 34th ICML,* PMLR 70:3319–3328.\n7. Lundberg, S.M. \u0026 Lee, S.I. (2017). A unified approach to interpreting model predictions. *NeurIPS 2017,* 4765–4774.\n8. Ribeiro, M.T., Singh, S. \u0026 Guestrin, C. (2016). \"Why should I trust you?\". *KDD 2016,* 1135–1144.\n9. Yang, J. et al. (2023). MedMNIST v2. *Scientific Data,* 10(1), 41. https://doi.org/10.1038/s41597-022-01721-8\n10. Chattopadhay, A. et al. (2018). Grad-CAM++. *WACV 2018,* 839–847. https://doi.org/10.1109/WACV.2018.00097 \n\n---\n\n## License \u0026 development note\n\nMIT License · Copyright © 2026 Prof. Dr. Utku Kose\n\nGEMEX was developed through a human-AI collaboration. The theoretical framework,\nmathematical foundations, algorithmic design decisions, and research directions\nare the original intellectual contribution of Prof. Dr. Utku Kose.\nAI-assisted tools were used in implementation and documentation phases.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Futkukose%2Fgemex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Futkukose%2Fgemex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Futkukose%2Fgemex/lists"}