API Reference

Date:

Jan 28, 2026

This page provides an auto-generated summary of TOAD’s API. All interaction with TOAD happens through the :class:`toad.TOAD` class, which serves as the main entry point for the entire framework.

Main Entry Point

The toad.TOAD class is the primary interface for all TOAD functionality. You initialize it with your data (xarray Dataset or path to netCDF file), then use its methods and properties to perform shift detection, clustering, visualization, and analysis.

toad.TOAD(data[, time_dim, log_level, engine])

Main object for interacting with TOAD.

The TOAD class provides:

• Computation methods: toad.TOAD.compute_shifts() and toad.TOAD.compute_clusters() for the main analysis pipeline

• Plotting interface: Access via toad.TOAD.plot property (returns a toad.plotting.Plotter instance)

• Statistics interface: Access via toad.TOAD.stats() method (returns a toad.postprocessing.Stats instance)

• Aggregation interface: Access via toad.TOAD.aggregate property (returns a toad.postprocessing.Aggregation instance)

• Preprocessing interface: Access via toad.TOAD.preprocess property

• Data access: The underlying xarray Dataset is available via toad.TOAD.data

Shift Detection Methods

Shift detection algorithms that can be passed to toad.TOAD.compute_shifts():

toad.shifts.ASDETECT([lmin, lmax, ...])

Detect abrupt shifts in a time series using gradient-based analysis related to [Boulton+Lenton2019].

Clustering Methods

Clustering algorithms from scikit-learn (or custom implementations) can be passed to toad.TOAD.compute_clusters(). TOAD is compatible with any clustering method that follows the scikit-learn ClusterMixin interface.

Common examples: - sklearn.cluster.HDBSCAN - sklearn.cluster.DBSCAN

Plotting and Visualization

The plotting functionality is accessed through the toad.TOAD.plot property, which returns a toad.plotting.Plotter instance. You can customize map styling using toad.plotting.MapStyle.

toad.plotting.Plotter(td)	Plotting utilities for TOAD objects.
toad.plotting.MapStyle([resolution, ...])	Configuration for map styling parameters.

Regridding

Regridding utilities for ensuring equal spacing in global datasets. These are typically used automatically when needed, but can be configured via the regridder parameter in toad.TOAD.compute_clusters().

toad.regridding.HealPixRegridder([nside])	Regrid data onto a equal-area HEALPix grid to avoid polar bias in clustering
toad.regridding.base.BaseRegridder()	Abstract base class for spatial regridders in TOAD.

Supporting Modules

These modules provide the underlying functionality used by the TOAD class:

toad.shifts	Shifts module for TOAD.
toad.clustering	Clustering module for TOAD (Temporal Offset Analysis and Detection).
toad.postprocessing
toad.utils	Utility functions and constants for TOAD.