marEx: Marine Extremes Detection and Tracking

marEx is a Python package for efficient identification and tracking of marine extremes (e.g., Marine Heatwaves) in oceanographic data. It provides a complete pipeline from raw data preprocessing to tracked event visualisation, supporting both structured and unstructured grids.

Key Features

Comprehensive Marine Extreme Detection: Advanced algorithms for identifying marine heatwaves, cold spells, and other extreme events
Flexible Grid Support: Works with both structured (regular lat/lon) and unstructured (irregular mesh) grids
Parallel Processing: Built on Dask for efficient memory management and parallel computation
Advanced Tracking: Sophisticated event tracking through time with merge/split handling
Rich Visualisation: Comprehensive plotting system with automatic grid detection
HPC Ready: Optimised for supercomputing environments with SLURM integration

Quick Start

Installation

Install marEx using pip:

pip install marEx

For the full installation with optional dependencies (JAX acceleration, HPC support):

pip install marEx[full]

For development:

pip install marEx[dev]

Basic Usage

Here’s a simple example of detecting and tracking marine heatwaves:

import xarray as xr
import marEx

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

# Preprocess data to identify extreme events
extreme_events_ds = marEx.preprocess_data(
    sst,
    threshold_percentile=95
)

# Track events through time
events_ds = marEx.tracker(
    extreme_events_ds.extreme_events,
    extreme_events_ds.mask,
    R_fill=8,
    area_filter_quartile=0.5
).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]))

Core Architecture

marEx follows a modular architecture with three main components:

Data Preprocessing (marEx.detect): Raw data preprocessing, detrending, anomaly detection, and extreme event identification
Event Tracking (marEx.track): Coherent binary object identification, labelling, and tracking through time with merge/split handling
Visualisation (marEx.plotX): Polymorphic plotting system supporting both gridded and unstructured data

Data Flow Pipeline

Raw Data → detect.py (preprocessing) → track.py (tracking) → plotX (visualisation)

The package processes chunked xarray DataArrays through:

Detrending and anomaly computation
Percentile-based extreme event identification
Binary object labeling and temporal tracking
Statistical analysis and visualisation

Documentation Contents

Getting Started

Advanced Usage

Troubleshooting

API Reference