dataset

xarray extensions for tidal model data

Source code

General Attributes and Methods

class pyTMD.io.dataset.DataTree(dtree)

Accessor for extending an xarray.DataTree for tidal model data

assign_coords(x: ndarray, y: ndarray, crs: str | int | dict = 4326, **kwargs)

Assign new coordinates to the DataTree

Parameters:

x: np.ndarray

Updated x-coordinates

y: np.ndarray

Updated y-coordinates

crs: str, int, or dict, default 4326 (WGS84 Latitude/Longitude)

Coordinate reference system of coordinates

kwargs: dict

Keyword arguments for xarray.Dataset.assign_coords

Returns:

dtree: xarray.DataTree

DataTree with updated coordinates

coords_as(x: ndarray, y: ndarray, crs: str | int | dict = 4326, **kwargs)

Transform coordinates into DataArrays in the DataTree coordinate reference system

Parameters:

x: np.ndarray

Input x-coordinates

y: np.ndarray

Input y-coordinates

crs: str, int, or dict, default 4326 (WGS84 Latitude/Longitude)

Coordinate reference system of input coordinates

Returns:

X: xarray.DataArray

Transformed x-coordinates

Y: xarray.DataArray

Transformed y-coordinates

crop(*args, **kwargs)

Crop DataTree to input bounding box

inpaint(**kwargs)

Inpaint over missing data in DataTree

interp(x: ndarray, y: ndarray, **kwargs)

Interpolate DataTree to new coordinates

Parameters:

x: np.ndarray

Interpolation x-coordinates

y: np.ndarray

Interpolation y-coordinates

subset(c: str | list)

Reduce to a subset of constituents

Parameters:

c: str or list

List of constituents names

transform_as(x: ndarray, y: ndarray, crs: str | int | dict = 4326, **kwargs)

Transform coordinates to/from the DataTree coordinate reference system

Parameters:

x: np.ndarray

Input x-coordinates

y: np.ndarray

Input y-coordinates

crs: str, int, or dict, default 4326 (WGS84 Latitude/Longitude)

Coordinate reference system of input coordinates

direction: str, default ‘FORWARD’

Direction of transformation

• 'FORWARD': from input crs to model crs

• 'INVERSE': from model crs to input crs

Returns:

X: np.ndarray

Transformed x-coordinates

Y: np.ndarray

Transformed y-coordinates

to_ellipse(**kwargs)

Expresses tidal currents in terms of four ellipse parameters

Returns:

dtree: xr.DataTree

DataTree containing:

• major: amplitude of the semi-major axis

• minor: amplitude of the semi-minor axis

• incl: angle of inclination of the northern semi-major axis

• phase: phase lag of the current behind the tidal potential

from_ellipse(**kwargs)

Calculates tidal currents from the four ellipse parameters

• major: amplitude of the semi-major axis

• minor: amplitude of the semi-minor axis

• incl: angle of inclination of the northern semi-major axis

• phase: phase lag of the current behind the tidal potential

Returns:

dtree: xr.DataTree

DataTree containing transports or currents

property crs

Coordinate reference system of the DataTree

atlas

alias of ATLASDataTree

otis

alias of OTISDataTree

class pyTMD.io.dataset.Dataset(ds)

Accessor for extending an xarray.Dataset for tidal model data

to_dataarray(**kwargs)

Converts Dataset to a DataArray with constituents as a dimension

assign_coords(x: ndarray, y: ndarray, crs: str | int | dict = 4326, **kwargs)

Assign new coordinates to the Dataset

Parameters:

x: np.ndarray

Updated x-coordinates

y: np.ndarray

Updated y-coordinates

crs: str, int, or dict, default 4326 (WGS84 Latitude/Longitude)

Coordinate reference system of coordinates

kwargs: dict

Keyword arguments for xarray.Dataset.assign_coords

Returns:

ds: xarray.Dataset

Dataset with updated coordinates

barycentric_interp(x: ndarray, y: ndarray, **kwargs)

Interpolate unstructured Datasets using a barycentric method with first or second order triangular finite elements

Parameters:

x: np.ndarray

Interpolation x-coordinates

y: np.ndarray

Interpolation y-coordinates

order: int

Polynomial order of the triangular elements

• 1: linear

• 2: quadratic

cutoff: int or float, default np.inf

Maximum distance to check for elements

Returns:

other: xarray.Dataset

Interpolated Dataset

coords_as(x: ndarray, y: ndarray, crs: str | int | dict = 4326, **kwargs)

Transform coordinates into DataArrays in the Dataset coordinate reference system

Parameters:

x: np.ndarray

Input x-coordinates

y: np.ndarray

Input y-coordinates

crs: str, int, or dict, default 4326 (WGS84 Latitude/Longitude)

Coordinate reference system of input coordinates

Returns:

X: xarray.DataArray

Transformed x-coordinates

Y: xarray.DataArray

Transformed y-coordinates

crop(bounds: list | tuple, buffer: int | float = 0)

Crop Dataset to input bounding box

Parameters:

bounds: list, tuple

Bounding box [min_x, max_x, min_y, max_y]

buffer: int or float, default 0

Buffer to add to bounds for cropping

extrap_like(other: Dataset, **kwargs)

Extrapolate missing values in Dataset using nearest-neighbors or inverse distance weighting

Parameters:

other: xarray.Dataset

Dataset with missing values to be extrapolated

kwargs: dict

Keyword arguments for pyTMD.interpolate._query_tree()

Returns:

other: xarray.Dataset

Dataset with extrapolated values

grid_interp(x: ndarray, y: ndarray, method='linear', **kwargs)

Interpolate a regular or rectilinear Dataset to new coordinates

Parameters:

x: np.ndarray

Interpolation x-coordinates

y: np.ndarray

Interpolation y-coordinates

method: str, default ‘linear’

Interpolation method

Returns:

other: xarray.Dataset

Interpolated Dataset

infer(t: float | ndarray, **kwargs)

Infer minor tides from Dataset at times

Parameters:

t: float or np.ndarray

Days relative to 1992-01-01T00:00:00 UTC

kwargs: dict

Keyword arguments for pyTMD.predict.infer_minor()

Returns:

darr: xarray.DataArray

Predicted tides

inpaint(**kwargs)

Inpaint over missing data in Dataset

Parameters:

kwargs: dict

Keyword arguments for pyTMD.interpolate.inpaint()

Returns:

ds: xarray.Dataset

Interpolated Dataset

interp(x: ndarray, y: ndarray, **kwargs)

Interpolate Dataset to new coordinates

Parameters:

x: np.ndarray

Interpolation x-coordinates

y: np.ndarray

Interpolation y-coordinates

extrapolate: bool, default False

Spatially extrapolate values beyond model domain

cutoff: int or float, default np.inf

Maximum distance for extrapolation

k: int, default 1

Number of nearest neighbors to use for extrapolation

• 1: nearest neighbor (NN)

• >1: inverse distance weighting (IDW)

power: int or float, default 2

Power parameter for inverse distance weighting extrapolation

workers: int, default 1

Number of workers to use for parallel extrapolation

kwargs: dict

Keyword arguments for interpolation functions

Returns:

other: xarray.Dataset

Interpolated Dataset

node_equilibrium()

Compute the equilibrium amplitude and phase of the 18.6 year node tide [11, 12]

pad(n: int = 1, chunks=None)

Pad Dataset by repeating edge values in the x-direction

Parameters:

n: int, default 1

Number of padding values to add on each side

Returns:

ds: xarray.Dataset

Padded Dataset

predict(t: float | ndarray, **kwargs)

Predict tides from Dataset at times

Parameters:

t: float or np.ndarray

Days relative to 1992-01-01T00:00:00 UTC

kwargs: dict

Keyword arguments for pyTMD.predict.time_series()

Returns:

darr: xarray.DataArray

Predicted tides

subset(c: str | list)

Reduce to a subset of constituents

Parameters:

c: str or list

List of constituents names

transform_as(x: ndarray, y: ndarray, crs: str | int | dict = 4326, **kwargs)

Transform coordinates to/from the Dataset coordinate reference system

Parameters:

x: np.ndarray

Input x-coordinates

y: np.ndarray

Input y-coordinates

crs: str, int, or dict, default 4326 (WGS84 Latitude/Longitude)

Coordinate reference system of input coordinates

direction: str, default ‘FORWARD’

Direction of transformation

• 'FORWARD': from input crs to model crs

• 'INVERSE': from model crs to input crs

Returns:

X: np.ndarray

Transformed x-coordinates

Y: np.ndarray

Transformed y-coordinates

to_units(units: str, value: float = 1.0)

Convert Dataset to specified tide units

Parameters:

units: str

Output units

value: float, default 1.0

Scaling factor to apply

to_base_units()

Convert Dataset to base units

to_default_units()

Convert Dataset to default tide units

property constituents

List of tidal constituent names in the Dataset

property crs

Coordinate reference system of the Dataset

property is_global: bool

Determine if Dataset covers a global domain

property area_of_use: str | None

Area of use from the Dataset CRS

property axis_units: str

Units of the coordinate axes from the Dataset CRS

property grid_type: str

Spatial structure of the Dataset

atlas

alias of ATLASDataset

compact

alias of CompactDataset

fes

alias of FESDataset

got

alias of GOTDataset

otis

alias of OTISDataset

class pyTMD.io.dataset.DataArray(da)

Accessor for extending an xarray.DataArray for tidal model data

property amplitude

Calculate the amplitude of a tide model constituent

Returns:

amp: xarray.DataArray

Tide model constituent amplitude

property phase

Calculate the phase of a tide model constituent

Returns:

ph: xarray.DataArray

Tide model constituent phase (degrees)

find_peaks(**kwargs)

Find peaks in the DataArray

Parameters:

kwargs: dict

Keyword arguments for xarray.DataArray.differentiate

Returns:

high_peaks: xarray.DataArray

Boolean array indicating locations of high tide peaks

low_peaks: xarray.DataArray

Boolean array indicating locations of low tide peaks

to_units(units: str, value: float = 1.0)

Convert DataArray to specified tide units

Parameters:

units: str

Output units

value: float, default 1.0

Scaling factor to apply

to_base_units(value=1.0)

Convert DataArray to base units

Parameters:

value: float, default 1.0

Scaling factor to apply

to_default_units(value=1.0)

Convert DataArray to default tide units

Parameters:

value: float, default 1.0

Scaling factor to apply

property units

Units of the DataArray

property quantity

Pint Quantity of the DataArray

property group

Variable group of the DataArray

pyTMD.io.dataset.combine_attrs(attrs_list: list[dict], context: str | None, **kwargs) → dict

Combine attributes from multiple datasets into a single dictionary merging conflicting values into a list

Parameters:

attrs_list: list of dict

List of attribute dictionaries from multiple datasets

context: str

Context for the attributes being combined

skip_keys: list of str, default [“units”]

List of attribute keys to skip from comparison

Returns:

result: dict

Combined attributes dictionary

pyTMD.io.dataset.equivalent_attrs(a: Any, b: Any) → bool

Check if two attribute values are equivalent (ignoring case for strings)

Adapted from xarray.structure.merge.equivalent_attrs

Parameters:

a: Any

First attribute value

b: Any

Second attribute value

pyTMD.io.dataset.register_datatree_subaccessor(name)

Register a custom subaccessor on DataTree objects

Parameters:

name: str

Name of the subaccessor

pyTMD.io.dataset.register_dataset_subaccessor(name)

Register a custom subaccessor on Dataset objects

Parameters:

name: str

Name of the subaccessor

pyTMD.io.dataset.register_dataarray_subaccessor(name)

Register a custom subaccessor on DataArray objects

Parameters:

name: str

Name of the subaccessor

pyTMD.io.dataset._transform(i1: ndarray, i2: ndarray, source_crs: str | int | dict = 4326, target_crs: str | int | dict = None, **kwargs)

Transform coordinates to/from the dataset coordinate reference system

Parameters:

i1: np.ndarray

Input x-coordinates

i2: np.ndarray

Input y-coordinates

source_crs: str, int, or dict, default 4326 (WGS84 Latitude/Longitude)

Coordinate reference system of input coordinates

target_crs: str, int, or dict, default None

Coordinate reference system of output coordinates

direction: str, default ‘FORWARD’

Direction of transformation

• 'FORWARD': from input crs to model crs

• 'INVERSE': from model crs to input crs

Returns:

o1: np.ndarray

Transformed x-coordinates

o2: np.ndarray

Transformed y-coordinates

pyTMD.io.dataset._coords(x: ndarray, y: ndarray, source_crs: str | int | dict = 4326, target_crs: str | int | dict = None, **kwargs)

Transform coordinates into DataArrays in a new coordinate reference system

Parameters:

x: np.ndarray

Input x-coordinates

y: np.ndarray

Input y-coordinates

source_crs: str, int, or dict, default 4326 (WGS84 Latitude/Longitude)

Coordinate reference system of input coordinates

target_crs: str, int, or dict, default None

Coordinate reference system of output coordinates

type: str or None, default None

Coordinate data type

If not provided: must specify time parameter to auto-detect

• None: determined from input variable dimensions

• 'drift': drift buoys or satellite/airborne altimetry

• 'grid': spatial grids or images

• 'time series': time series at a single point

time: np.ndarray or None, default None

Time variable for determining coordinate data type

Returns:

X: xarray.DataArray

Transformed x-coordinates

Y: xarray.DataArray

Transformed y-coordinates