marEx 4.0.3

Marine Extremes Detection and Tracking

Marine Extremes Detection and Tracking

Efficient & scalable marine extremes detection, identification, & tracking for exascale climate data.

marEx is a high-performance Python framework for identifying and tracking extreme oceanographic events (such as Marine Heatwaves or Acidity Extremes) in massive climate datasets. Built on advanced statistical methods and distributed computing, it processes decades of daily-resolution global ocean data with unprecedented efficiency and scalability.

---

Key Features

• ⚡ Extreme Performance: Process 100+ years of high-resolution daily global data in minutes
• 🌐 Universal Grid Support: Native support for both regular (lat/lon) grids and unstructured ocean models
• 📈 Advanced Event Tracking: Handles coherent object splitting, merging, and evolution
• 📊 Multiple Detection Methods: Scientifically rigorous algorithms for robust extreme event identification
• ☁️ Cloud-Native Scaling: Identical codebase scales from laptop to supercomputer using up to 1024+ cores
• 🧠 Memory Efficient: Intelligent chunking and lazy evaluation for datasets larger than memory

---

https://github.com/user-attachments/assets/501537ff-5adb-4e13-ba08-6a333bac2a02

---

Quick Start

import xarray as xr
import marEx

# Load sea surface temperature data
sst = xr.open_dataset('sst_data.nc', chunks={'time': 30}).sst

# Identify extreme events
extreme_events_ds = marEx.preprocess_data(
    sst,
    threshold_percentile=95,
    method_anomaly='shifting_baseline',
    method_extreme='hobday_extreme'
)

# Track events through time
events_ds = marEx.tracker(
    extreme_events_ds.extreme_events,
    extreme_events_ds.mask,
    R_fill=8,
    area_filter_absolute=100,
    allow_merging=True
).run()

# Visualise results
fig, ax, im = (events_ds.ID_field > 0).mean("time").plotX.single_plot(
    marEx.PlotConfig(var_units="MHW Frequency", cmap="hot_r", cperc=[0, 96])
)

---

Installation

pip install marEx[full,hpc]

For detailed installation instructions, including HPC environments and optional dependencies, see the Installation Guide.

---

Core Workflow

marEx follows a three-stage pipeline:

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  1. Detect      │  →   │  2. Track       │  →   │  3. Visualise   │
│    Extremes     │      │    Events       │      │     & Analyse   │
└─────────────────┘      └─────────────────┘      └─────────────────┘
        ↓                        ↓                        ↓
preprocess_data()           tracker()                  plotX()
        ↓                        ↓                        ↓
Binary extreme map        Tracked objects          Maps, animations,
                            with unique IDs           & statistics

Learn more: Core Concepts | User Guide

---

Documentation

For detailed guides, tutorials, and API reference, visit the full documentation:

📚 marEx Documentation on ReadTheDocs

Quick Links:

• Quickstart Guide - Get started in 5 minutes
• Why marEx? - Learn about the unique capabilities
• Core Concepts - Understanding marEx's design and workflow
• User Guide - Comprehensive usage guide with method selection, parameter tuning, and performance optimisation
• API Reference - Complete function documentation
• Examples - Jupyter notebooks for gridded, regional, and unstructured data
• Troubleshooting - Common issues and solutions

---

Examples

Explore complete workflows in the example notebooks:

• Gridded Data: Standard analysis for regular lat/lon grids (satellite data, CMIP6 models)
• Regional Data: Regional analysis with boundary handling (EURO-CORDEX)
• Unstructured Data: Analysis for irregular meshes (FESOM, ICON-O, MPAS-Ocean)

Each example demonstrates the full pipeline from preprocessing to visualisation.

---

Key Capabilities

Detection Methods

marEx provides multiple scientifically rigorous methods for anomaly calculation and extreme identification:

Anomaly Detection:

• Shifting Baseline: Rolling climatology (most accurate, research standard)
• Detrend Fixed Baseline: Polynomial detrending + fixed climatology (preserves full time series)
• Fixed Baseline: Simple daily climatology (trend-inclusive)
• Harmonic Detrending: Fast polynomial + harmonic model (efficient screening)

Extreme Identification:

• Hobday Method: Day-of-year specific thresholds with spatial window extension (literature standard, Hobday et al. 2016)
• Global Method: Single threshold across time (fast, exploratory analysis)

→ Learn more about method selection

Advanced Tracking

• Morphological Operations: Fill spatial gaps and smooth event boundaries
• Temporal Gap Filling: Maintain event continuity across short interruptions
• Merge/Split Handling: Track event genealogy with improved nearest-neighbor partitioning
• Area Filtering: Remove spurious small events with percentile or absolute thresholds

→ Explore tracking algorithms

Performance & Scalability

• Dask-First Architecture: Parallel computation with automatic memory management
• JAX Acceleration: Optional GPU/TPU support for 10-50× speedup
• HPC Integration: SLURM cluster support for supercomputing environments
• Memory Optimisation: Process datasets 100-1000× larger than available RAM

→ Performance tuning guide

---

Getting Help

Support Channels

• Documentation - Detailed guides and API reference
• GitHub Issues - Bug reports and feature requests
• GitHub Discussions - Questions, ideas, and community support
• Example Notebooks - Complete workflow demonstrations

Reporting Issues

When reporting issues, please include:

• marEx version (marEx.__version__)
• Python version and operating system
• Dependency status (marEx.print_dependency_status())
• Minimal reproducible example
• Full error traceback

---

Citation

When using marEx in publications, please cite:

• marEx package: DOI 10.5281/zenodo.16922881
• Hobday et al. (2016): "A hierarchical approach to defining marine heatwaves." Progress in Oceanography 141, 227-238. DOI 10.1016/j.pocean.2015.12.014

---

Funding

This project has received funding through:

• The EERIE (European Eddy-Rich ESMs) Project
• The European Union's Horizon Europe research and innovation programme under Grant Agreement No. 101081383
• The Swiss State Secretariat for Education, Research and Innovation (SERI) under contract #22.00366

---

Contact

For questions, comments, or collaboration opportunities, please contact Aaron Wienkers.