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_latlon_info(data, space_dims)	Detect lat/lon names and grid type from dataset and space dimensions.
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 | datetime64

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

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)
array([0., 86400., 172800., 259200., 345600.])

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_latlon_info(data, space_dims)

Detect lat/lon names and grid type from dataset and space dimensions.

Returns:

(lat_name, lon_name, has_latlon, is_latlon_dims) - has_latlon: True if both lat and lon coordinates were found - is_latlon_dims: True if space_dims are exactly [lat_name, lon_name]

Parameters:

• data (Dataset)

• space_dims (list[str])

Return type:

Tuple[str | None, str | None, bool, bool]

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:

• desired_name (str) – The desired variable name

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

• logger – Optional logger for info messages

Returns:

Unique variable name (either desired_name or desired_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
repr_html	Helpers for HTML representation of the TOAD object.
shift_selection_utils	Utility functions for shift selection.