Utility functions for psy-transect

Functions:

estimate_resolution(*coords)

Estimate the minimum resolution in a grid.

get_distance_from_start(points)

Get the cumulative distance for a list of points.

get_haversine_distance_from_start(points[, ...])

Get the cumulative distance for a list of points.

interpolate_points(points, arrays, coords, ...)

Interpolate data arrays along a path.

mesh_to_cf_bounds(coord, old_dim, new_dim[, ...])

Transform a mesh boundary variable to CF-conform bounds

nearest_points(points, arrays, coords, ...)

Select the closest grid cells along a path.

remove_coordinates(encoding, coord_names[, ...])

select_level(level, ds, coord, dim)

select_transect(points, ds, *coords[, ...])

unique_everseen(iterable[, key])

List unique elements, preserving order.
psy_transect.utils.estimate_resolution(*coords)

Estimate the minimum resolution in a grid.

psy_transect.utils.get_distance_from_start(points: ndarray) → ndarray

Get the cumulative distance for a list of points.

This function calculates the distance between consecutive points and generates the cumulative sum.

Parameters:

points (np.ndarray of shape [N, M]) – An array of point coordinates

Returns:

The distance from the start of the path for each point in points.

Return type:

np.ndarray of shape N

psy_transect.utils.get_haversine_distance_from_start(points: ndarray, to_radian: bool = False) → ndarray

Get the cumulative distance for a list of points.

This function calculates the distance between consecutive points and generates the cumulative sum.

Parameters:

  • points (np.ndarray of shape [N, M]) – An array of point coordinates

  • to_radian (bool) – If True, assume that the points are given in degrees and convert them to radian.

Returns:

The distance from the start of the path for each point in points in units of km

Return type:

np.ndarray of shape N

psy_transect.utils.interpolate_points(points: ndarray, arrays: List[DataArray], coords: List[IndexVariable], coord_dims: List[str], cell_dim: str, method: str = 'inverse_distance_weighting', **kws: Any) → List[DataArray]

Interpolate data arrays along a path.

This method interpolates data arrays to a path indicated by an array of points.

Parameters:

  • points (np.ndarray of shape [N, M]) – The path consisting of N points with M dimensions

  • arrays (List[xr.DataArray]) – The data arrays to extract

  • coords (List[xr.IndexVariable]) – The list of the M coordinates that belong to the given arrays

  • coord_dims (List[str]) – The names of each of the M dimensions. This list must have the same number of dimensions as the size of the second dimension in points.

  • cell_dim (str) – The name of the dimension to generate for the new arrays.

  • exact (bool, optional) – If True, the resulting dimension indicated by cell_dim will have the size N, otherwise we will only keep the unique cells within the given coords.

Returns:

The given arrays at the location indicated by the given points

Return type:

List of xr.DataArray

psy_transect.utils.mesh_to_cf_bounds(coord: DataArray | IndexVariable, old_dim: str, new_dim: str, ds: Dataset | None = None, coordinate: bool = True, bounds_dim: str = 'bnds', coord_name: str | None = None, add_coordinate: bool = True) → Dataset

Transform a mesh boundary variable to CF-conform bounds

This function takes a coordinate with shape (l, m, n+1) and transforms it into a variable of shape (l, m, n, 2). n can be at any position of the variable. The exact position is defined by the dim_map parameter.

Parameters:

  • coord (xarray.DataArray or xarray.IndexVariable) – The original coordinate to transform

  • old_dim (str) – The name of the dimension within the dims attribute of coord with size n+1

  • new_dim (str) – The new name of the dimension that will have size n.

  • ds (xarray.Dataset, optional) – The dataset where to store the new data into. By default, a new empty dataset will be created

  • coordinate (bool, optional) – If True, generate the coordinate variable. If False, only the CF-conform bounds variable is created. By default True.

  • bounds_dim (str, optional) – The name of the newly created dimension with shape 2, by default “bnds”

  • coord_name (str, optional) – The name of the coordinate. This parameter will be ignored if coordinate is False. If None, the coordinate will get the same name as coord. By default None.

  • add_coordinate (bool, optional) – If True and coordinate is True, the generated coordinate will be added to the 'coordinates' attribute of all variables in the provided dataset ds that have the all the dimensions of coord. By default True

Returns:

The updated ds or a fresh dataset

Return type:

xarray.Dataset

psy_transect.utils.nearest_points(points: ndarray, arrays: List[DataArray], coords: List[IndexVariable], coord_dims: List[str], cell_dim: str, exact: bool = False, compute_haversine: bool | None = None) → List[DataArray]

Select the closest grid cells along a path.

This method takes the closest grid cells along a transect using scikit-learns BallTree.

Parameters:

  • points (np.ndarray of shape [N, M]) – The path consisting of N points with M dimensions

  • arrays (List[xr.DataArray]) – The data arrays to extract

  • coords (List[xr.IndexVariable]) – The list of the M coordinates that belong to the given arrays

  • coord_dims (List[str]) – The names of each of the M dimensions. This list must have the same number of dimensions as the size of the second dimension in points.

  • cell_dim (str) – The name of the dimension to generate for the new arrays.

  • exact (bool, optional) – If True, the resulting dimension indicated by cell_dim will have the size N, otherwise we will only keep the unique cells within the given coords.

  • compute_haversine (bool, optional) – If True, assume that the coordinate data is given in radian and compute the haversine distance. If None, we will check if the coordinate units are in "degrees_east" and "degrees_north", or "radian" and compute the distance.

Returns:

The given arrays at the location indicated by the given points

Return type:

List of xr.DataArray

psy_transect.utils.remove_coordinates(encoding, coord_names, new_coords=[])
psy_transect.utils.select_level(level, ds, coord, dim)
psy_transect.utils.select_transect(points, ds, *coords, exact=False, cell_dim=None, method='nearest', **kws)
psy_transect.utils.unique_everseen(iterable, key=None)

List unique elements, preserving order. Remember all elements ever seen.

Function taken from https://docs.python.org/2/library/itertools.html