marEx

The problem

Detecting and tracking marine heatwaves, or any extreme ocean event, across decades of daily global model output is an engineering problem before it is a scientific one. The data does not fit in memory, the events split and merge as they evolve, and a naive three-dimensional connected-component pass fuses everything that touches in space and time into a single spurious mega-event. marEx does it properly and at scale (100+ yr daily global in minutes), on one codebase that runs unchanged from a laptop to a large HPC allocation (laptop to 1024+ cores).

PACKAGE

CI passing · Zenodo DOI · Documentation

How it works

marEx is a three-stage pipeline: detect the extremes, track them through time, then visualise and analyse. Detection offers a family of anomaly methods and a generalised Hobday day-of-year extreme definition with spatial pooling, backed by histogram-based approximate percentiles so that thresholds can be computed on data far larger than memory. The tracking stage is where the care shows. Overlap-thresholded merge and split handling, with nearest-neighbour partitioning, keeps a genealogical record of every event as it divides and recombines, so a heatwave that splits in two and later rejoins is followed as one lineage rather than collapsed into a single blob or shattered into many.

The distinctive engineering reach is grid-agnosticism. The same operators run on regular latitude-longitude grids and on the unstructured meshes of modern ocean models (FESOM, ICON-O, MPAS-Ocean), where cells have no rows and columns to index and neighbour relationships have to be carried explicitly. Supporting both from one API, rather than maintaining a separate unstructured fork, is what lets the framework follow the science onto exascale model output.

In production

The proof that the tracking is right is what it refuses to do. Naive connected-component methods manufacture spurious mega-events by fusing anything that overlaps in space-time; marEx’s overlap-thresholded genealogy does not, and the difference is stark when the two are run on the same field. That correctness, together with the scaling, is why the package has been adopted well beyond its origin: 230k+as of 2026-07 from PyPI, and operational use at UK Met Office, ECMWF & NOAA.

> ENGINE_ROOM — Distributed tracking, merge and split genealogy, and the JAX fast path

marEx is Dask-first: every stage is lazy and chunked, so a dataset far larger than memory is processed in streaming passes rather than loaded whole, and the same work distributes across cores or cluster nodes with no change of code. An optional JAX path accelerates the numerical core where it is available (10–50× JAX speedup), with a graceful NumPy and Numba fallback when it is not, and SLURM integration for HPC scheduling.

The tracking correctness rests on the merge and split handling. Rather than treat a space-time volume as one connected component, marEx resolves the overlaps between consecutive time slices, partitions a merged object back to its parents by nearest neighbour, and records the genealogy, so the identity of an event survives the divisions and recombinations that a naive labelling destroys. The comparison below runs both on the same data: the naive method fuses distinct events, marEx keeps each one separate and traceable.

The package ships with a full test suite and continuous integration, ReadTheDocs documentation with runnable gridded, regional, and unstructured tutorials, and a Zenodo DOI for citation, so a result produced with marEx is reproducible by anyone who installs it.

What this demonstrates