toad.utils

Utility functions and constants for TOAD.

This module provides helper functions and constants used throughout TOAD, including: - Dimension handling and coordinate detection - Attribute management and naming conventions - Deprecation utilities - Grid validation

Functions

convert_numeric_to_original_time(...)

Convert a numeric time result back to original format for user-facing results.

convert_time_to_seconds(time_array)

Convert time dimension values to numeric seconds since the first time point.

deprecated([message])

Mark functions as deprecated with @deprecated decorator

detect_latlon_names(data)

Detect latitude and longitude coordinate names in a dataset.

get_space_dims(xr_da, tdim)

Get spatial dimensions from an xarray DataArray or Dataset.

get_unique_variable_name(desired_name, ...)

Generate a unique variable name by appending sequential numbers if needed.

is_regular_grid(data)

Check if a dataset has a regular grid.
toad.utils.convert_numeric_to_original_time(numeric_result, numeric_times, original_time_values)

Convert a numeric time result back to original format for user-facing results.

Parameters:

  • numeric_result (float) – The numeric time value to convert

  • numeric_times (ndarray) – Array of numeric time values used for calculations

  • original_time_values (DataArray) – Array of original time values for conversion

Returns:

The interpolated original time value (can be between existing values)

Return type:

float | datetime

toad.utils.convert_time_to_seconds(time_array)

Convert time dimension values to numeric seconds since the first time point.

Parameters:

  • time_array (DataArray) – xarray DataArray containing the time dimension to convert

  • time_dim – Name of the time dimension in the DataArray

Returns:

Array of numeric time values in seconds relative to first time point

Return type:

numpy.ndarray

Raises:

ValueError – If time dimension values are not integers, floats, or datetime objects

Examples

>>> times = xr.DataArray(pd.date_range('2000-01-01', periods=5))
>>> convert_time_to_seconds(times, 'time')
array([0., 86400., 172800., 259200., 345600.])
toad.utils.create_global_dataset(lat_size=90, lon_size=180, time_size=80, background_trend=0.0, background_noise=0.005, n_shifts=3, random_seed=42)

Generate a global dataset with background trend and spatially coherent abrupt shifts.

Parameters:

  • lat_size (int) – Number of latitude points

  • lon_size (int) – Number of longitude points

  • time_size (int) – Number of time points

  • background_trend (float) – Linear trend coefficient

  • background_noise (float) – Amplitude of random noise

  • n_shifts (int) – Number of abrupt shift events to add

  • random_seed (int) – Seed for reproducible results

Returns:

Dataset containing the time series and coordinates labels (xr.DataArray): Binary indicator of shift locations shift_params (dict): Parameters of the generated shifts

Return type:

data (xr.Dataset)

Example

>>> data_ds, labels_xr, shift_params = create_global_dataset(
>>>    lat_size=30,
>>>    lon_size=60,
>>>    time_size=120,
>>>    n_shifts=3,
>>>    random_seed=1,
>>>    background_noise=0.01,
>>> )
toad.utils.deprecated(message=None)

Mark functions as deprecated with @deprecated decorator

toad.utils.detect_latlon_names(data)

Detect latitude and longitude coordinate names in a dataset.

Searches for common latitude/longitude names in coordinates first, then falls back to data variables.

Parameters:

data (Dataset) – xarray Dataset to search

Returns:

Tuple of (lat_name, lon_name). Either can be None if not found.

Return type:

Tuple[str | None, str | None]

toad.utils.get_space_dims(xr_da, tdim)

Get spatial dimensions from an xarray DataArray or Dataset.

Parameters:

  • xr_da (DataArray | Dataset) – Input DataArray or Dataset to get dimensions from

  • tdim (str) – Name of temporal dimension. All other dims are considered spatial.

Returns:

List of spatial dimension names as strings. If standard spatial dims (x/y, y/x) or (lon/lat, lat/lon) are found, returns only those.

Raises:

ValueError – If provided temporal dim is not in the dimensions

Return type:

list[str]

toad.utils.get_unique_variable_name(desired_name, existing_vars, logger=None)

Generate a unique variable name by appending sequential numbers if needed.

Parameters:

  • base_name – The desired variable name

  • existing_vars – Container with existing variable names (Dataset, dict, list, set, etc.)

  • logger – Optional logger for info messages

  • desired_name (str)

Returns:

Unique variable name (either base_name or base_name_N)

Return type:

str

Examples

>>> get_unique_variable_name("tas_cluster", ["tas_cluster"])
"tas_cluster_1"
>>> get_unique_variable_name("tas_cluster", ["tas_cluster", "tas_cluster_1"])
"tas_cluster_2"
>>> get_unique_variable_name("tas_cluster_5", ["tas_cluster_5", "tas_cluster_6"])
"tas_cluster_7"
toad.utils.is_regular_grid(data)

Check if a dataset has a regular grid.

Parameters:

data (Dataset) – xarray Dataset to check

Returns:

True if the grid is regular (1D lat/lon), False otherwise

Return type:

bool

Modules

cluster_consensus_utils

shift_selection_utils

Utility functions for shift selection.

synthetic_data