TOAD is a Python package designed for detecting and clustering spatio-temporal patterns in gridded Earth-system datasets, such as model outputs. The input data should be structured as a 3D array in the format space × space × time, where time can represent actual time or some other forcing variable or bifurcation parameter. TOAD provides a streamlined pipeline for identifying and analyzing spatio-temporal regions or clusters that exhibit similar dynamical responses to external forcing.

Currently, TOAD focuses on identifying regions that experience similar abrupt transitions, such as the sudden loss of ice volume in a specific area. The goal, however, is to expand the package's functionality to support broader use cases, enabling the detection and clustering of diverse types of dynamical shifts across a wide range of systems.

The TOAD pipeline consists of three main components:

1. Shift Detection: Performs time series analysis at each individual grid cell to identify abrupt transitions or dynamical shifts using configurable detection methods (e.g., ASDETECT) with adjustable sensitivity parameters.
2. Clustering: Groups the detected shifts spatially and temporally (or along a bifurcation parameter) to reveal cohesive patterns using clustering methods (e.g., HDBSCAN) with configurable space/time scaling.
3. Aggregation & Synthesis: Aggregates results across multiple cluster maps from different datasets, models, variables, realisations, or methods to produce consensus clusters and statistics, and generates plots and summaries of the identified clusters for insights and interpretation.

TOAD's core functionality is exposed through the TOAD class, which analyzes netCDF files or xarray datasets. The primary methods - compute_shifts, compute_clusters, and compute_consensus() - handle the three main pipeline steps. The pipeline supports aggregation of results across multiple runs, enabling consensus-based analysis. Additional helper functions and visualization tools make it easy to explore and understand the results.

Installation

$ pip install tipmip-toad

or

$ git clone https://github.com/tipmip-methods/toad.git
$ cd toad
$ pip install .

Simple use case

from toad import TOAD
from toad.shifts import ASDETECT
from sklearn.cluster import HDBSCAN


# init TOAD object with ice-thickness field and a custom time dimension.
td = TOAD("ice_thickness.nc", time_dim="GMST")

# Compute shifts for variable 'thk' using the method ASDETECT (Boulton & Lenton, 2019)
td.compute_shifts("thk", method=ASDETECT(timescale=(0.5, 3.5)))

# Compute clusters using HDBSCAN from scikit-learn (McInnes, 2017)
td.compute_clusters(
    var="thk",
    method=HDBSCAN(min_cluster_size=25),
    time_weight=2.0,
)

# Plot largest clusters in ccrs.SouthPolarStereo() projection
td.plot.overview("thk", map_style={"projection": "south_pole"}, mode="aggregated");

For more details, check out the tutorials.

Tutorials

• Basics: Learn the core concepts and workflow
• Visualization: Explore the plotting capabilities
• Aggregation: Explore how to identify regions of abrupt shifts that are consistent across models/members/variables/methods.
• Custom clustering: Implement new clustering methods
• Custom event detection: Implement new event detection algorithms

Documentation

Read the documentation, which includes a short video introduction!

About

TOAD is developed at the Potsdam Institute for Climate Impact Research (PIK) and the Max Planck Institute of Geoanthropology. The project originated from early prototype work by Sina Loriani in 2022. Since 2024, Jakob Harteg has led the full development of the package as part of his PhD project. Over time, numerous contributors have played important roles at various stages, including Lukas Röhrich and Fritz Kühlein. The project has also benefited greatly from scientific advice and guidance from Sina Loriani, Jonathan Donges, Ricarda Winkelmann, and many others. Community contributions, such as feature suggestions, bug reporting, or even extensions like new detection algorithms, are very welcome.

Citation

If you use TOAD in your research, please cite:

TOAD package: Harteg, J., Roehrich, L., De Maeyer, K., Garbe, J., Sakschewski, B., Klose, A. K., Donges, J., Winkelmann, R., and Loriani, S.: TOAD: Tipping and Other Abrupt events Detector, Zenodo, https://doi.org/10.5281/zenodo.18316437, 2026.

TOAD methodology paper (preprint): Harteg, J., Röhrich, L., De Maeyer, K., Garbe, J., Sakschewski, B., Klose, A. K., Donges, J. F., Winkelmann, R., and Loriani, S.: TOAD v1.0: A Python Framework for Detecting Abrupt Shifts and Coherent Spatial Domains in Earth-System Data, EGUsphere [preprint], https://doi.org/10.5194/egusphere-2026-356, 2026.

License

TOAD is licensed under the BSD 2-Clause License. See LICENSE.txt for details.

References

• Boulton, C. A., & Lenton, T. M. (2019). A new method for detecting abrupt shifts in time series. F1000Research, 8, 746. https://doi.org/10.12688/F1000RESEARCH.19310.1
• McInnes, L., Healy, J., & Astels, S. (2017). hdbscan: Hierarchical density based clustering. J. Open Source Softw., 2(11), 205. https://doi.org/10.21105/joss.00205
• The scikit-learn developers. (2025). scikit-learn. Zenodo. https://doi.org/10.5281/zenodo.591564