geoxplain 1.0.0

Interactive viewer for geospatial XAI attributions

GeoXplain

GeoXplain	GeoXplain Aurora Adapter	Documentation	Live demo	Paper
Current repository	Aurora backend	User guide and API	Hosted viewer	Manuscript

GeoXplain is an interactive Python-based visualization toolkit for exploring geospatial attribution maps across climate variables, atmospheric pressure layers, and forecast time. It turns computed attribution arrays, saved result bundles, targets, timestamps, vertical levels, and weather overlays into an interactive Jupyter widget or a standalone browser viewer.

The core package does not compute explanations and does not need to import your model. It is the visualization and interchange layer. Compute can happen anywhere: in your own pipeline, in a batch job, in another library, or through a backend such as the separate Aurora adapter.

Cite us

Will be published shortly.

Why GeoXplain

• Inspect geospatial attributions across variables, levels, methods, and time.
• Import raw NumPy arrays, .xia.npz attribution bundles, or compatible Python result objects.
• Add weather-field overlays from .overlay.npz bundles or compatible overlay objects.
• Work inside notebooks with GeoXplainWidget or export a self-contained static browser view with GeoXplain.
• Keep model-specific compute code out of the viewer package.

Import computed data

The most portable GeoXplain workflow is to compute explanations somewhere else and import the result. A saved .xia.npz bundle is self-describing, so the viewer can recover method names, timestamps, targets, layer labels, and attribution grids without the original model package.

Quickstart: a runnable walkthrough of the snippets below, including bundle import, manual .npy import, and building grids from in-memory NumPy arrays, lives in examples/quickstart.ipynb.

from geoxplain import GeoXplainWidget
from geoxplain.xia_result import load_xia_result

result = load_xia_result("zurich.xia.npz")  # can be found in examples

widget = GeoXplainWidget(title="Ticino attribution", height=720)  # both optional
widget.add_attribution(result)
widget

You can also add arrays directly when you already have a computed grid:

import numpy as np
from geoxplain import GeoXplainWidget

saliency = np.load("saliency_700hPa.npy")

widget = GeoXplainWidget(title="Model attribution")
widget.add_attribution(
    saliency,
    pressure_level=700,
    method="Saliency",
    timestamp="2024-03-20T00:00:00Z",
    target=(46.25, 8.75),
)
widget

Weather overlays use the same idea:

from geoxplain.overlay_result import load_overlay_result

overlay = load_overlay_result("zurich.overlay.npz")
widget.add_overlay(overlay)

Compute on-the-fly with a backend

When you want GeoXplain to sit next to live explanation computation, use a backend that produces GeoXplain-compatible results. The first packaged backend is the separate geoxplain-aurora-adapter, which computes attributions and weather overlays for Microsoft Aurora.

Quickstart: find a runnable walkthrough for on-the-fly computations in examples/quickstart_on_the_fly.ipynb.

import geoxplain_aurora_adapter as ax
from geoxplain import GeoXplainWidget

target = ax.Target.point(
    var="q",
    level=850,
    lat=46.25,
    lon=8.75,
    timestamp="2024-03-20T00:00:00Z",
)

result = ax.run_saliency(
    target=target,
    input=["t", "q"],
    remote="http://localhost:8765",
)

GeoXplainWidget(result=result, height=720)

Without remote=, the adapter runs in the current Python process. With a listener URL, the same call can dispatch work to a GPU workstation, server, or SLURM-backed service while GeoXplain remains the viewer.

Installation

pip install geoxplain

This package is only the visualization tool; for on-the-fly computations for Microsoft Aurora, see GeoXplain Aurora Adapter.

Screenshot capture is optional:

pip install "geoxplain[screenshots]"

For local documentation and development:

uv sync --group dev
uv run mkdocs serve

Documentation

The documentation source lives in docs/ and is built with MkDocs Material. The deployed documentation is available at clemenskoprolin.github.io/geoxplain. Useful starting points:

• Quickstart
• Visualize results
• Data model and file formats
• Aurora backend overview
• Python API reference

Quick reference links for LLMs and tooling:

• LLM documentation map
• Consolidated generated reference
• Structured API inventory

Build docs locally

uv run python docs/_tooling/generate_llm_reference.py
uv run mkdocs build --strict

License

GeoXplain is distributed under the MIT License. See LICENSE and THIRD_PARTY_NOTICES.md.