lenapy.utils.geo

The geo module provides functions related to spatial grid.

This module includes functions to:

Standardize the coordinates names in cf conventions.
Linearly interpolate a coordinate isosurface where a field equals a target.
Change longitude origin.
Estimate surface of grid cells.
Compute distance from grid cells to a list of points.

lenapy.utils.geo.rename_data(data, **kwargs)[source]

Standardization of coordinates names of a product. Looks for different possible names for latitude, longitude, and time, and turn them into a standardized name. Definitions are based on standard cf attributes and units : https://cfconventions.org Custom names changes can also be performed with kwargs parameter.

Parameters:

data (xr.DataArray | xr.Dataset) – xarray object that has coordinates to rename.
**kwargs ({old_name: new_name, ...}, optional) – Dictionary specifying old names to be changed into new names.

Returns:

renamed – New object containing modified names.

Return type:

xr.DataArray | xr.Dataset

Example

ds=xr.open_mfdataset('product.nc', preprocess=rename_data)

lenapy.utils.geo.isosurface(data, target, dim, coord=None, upper=False)[source]

Linearly interpolate a coordinate isosurface where a field equals a target. Compute the isosurface along the specified coordinate at the value defined by the target argument. Data is supposed to be monotonic along the chosen dimension. If not, the first fitting value encountered is retained, starting from the end (bottom) if upper=False, or from the beggining (top) if upper=True.

Parameters:

data (xr.DataArray) – The field in which to interpolate the target isosurface.
target (float) – Criterion value to be satisfied at the iso surface.
dim (str) – Dimension along which to compute the isosurface.
coord (str (optional)) – The field coordinate to interpolate. If absent, coordinate is supposed to be “dim”.
upper (bool) – Order to perform the research of the criterion value. If True, returns the highest point of the isosurface, else the lowest.

Returns:

isosurface – DataArray containing the isosurface along the dimension dim on which data=target.

Return type:

xr.DataArray

Examples

Calculate the depth of an isotherm with a value of 5.5:

temp = xr.DataArray(range(10, 0, -1), coords={"depth": range(10)})
isosurface(temp, 5.5, dim="depth")
# Output : <xarray.DataArray ()>
# array(4.5)

lenapy.utils.geo.split_duplicate_coords(data)[source]

lenapy.utils.geo.longitude_increase(data)[source]

lenapy.utils.geo.reset_longitude(data, orig=-180)[source]

Rolls the longitude to place the specified longitude at the beginning of the array.

Returns:: origin – First longitude in the array.
Return type:: float

Example

data = xr.open_dataset('/home/user/lenapy/data/gohc_2020.nc', engine="lenapyNetcdf")
surface = data.lngeo.surface_cell()

lenapy.utils.geo.surface_cell(data, ellipsoidal_earth=True, a_earth=None, f_earth=0.003352810681182319)[source]

Returns the Earth surface of each cell defined by a longitude/latitude in a xarray object. Cells limits are half the distance between each given coordinate. Given coordinates are not necessary the center of each cell. Border cells are supposed to have the same size on each side of the given coordinate. Ex : coords=[1,2,4,7,9] ==> cell sizes are [1,1.5,2.5,2.5,2]

The surface of the cell is given by default for an ellipsoidal earth of radius LNPY_A_EARTH_GRS80 and flattening LNPY_F_EARTH_GRS80. The parameter ellipsoidal_earth can be set to False for the surface on a spherical Earth. It can be set to ‘approx’ for the surface with an approximation of the ellipsoid on each cell by a spherical cell with the radius corresponding to the distance between the ellispoid point and the center.

If surface_cell() is applied to a complete grid, the sum of all cells is equal to 4πR² for the spherical Earth. For the ellipsoidal Earth, the sum is equal to 2πa² + πb²/e*log((1 + e)/(1 - e))

Mathematics are detailed in this PDF document.

Parameters:

data (xr.DataArray | xr.Dataset) – xarray object that must have latitude and longitude coordinates.
ellipsoidal_earth (bool | str, optional) – Boolean to choose if the surface of the Earth is an ellipsoid or a sphere. Default is True for ellipsoidal Earth If ellipsoidal_earth=’approx’, the given surface is the one of a spherical cell with the radius corresponding to the distance between the ellispoid point and the center of the ellipsoid.
a_earth (float, optional) – Earth semi-major axis [m]. If not provided, use data.attrs[‘radius’] and if it does not exist, use LNPY_A_EARTH_GRS80.
f_earth (float, optional) – Earth flattening. Default is LNPY_F_EARTH_GRS80.

Returns:

surface – DataArray with cell surface.

Return type:

xr.DataArray

Example

xr.open_dataset('/home/user/lenapy/data/gohc_2020.nc', engine="lenapyNetcdf")
surface = data.lngeo.surface_cell()

lenapy.utils.geo.ecarts(data, dim)[source]

Return the width of each cell along specified coordinate. Cell limits are half-distance between each given coordinate (that are not necessary the center of each cell). Border cells are supposed to have the same size on each side of the given coordinate. Ex : coords=[1,2,4,7,9] ==> cells size is [1,1.5,2.5,2.5,2]

Parameters:

data (xr.DataArray | xr.Dataset) – Must have latitude and longitude coordinates.
dim (str) – Coordinate along which to compute cell width.

Returns:

width – xr.DataArray with cell width for each coordinate.

Return type:

xr.DataArray

lenapy.utils.geo.distance(data, pt, ellipsoidal_earth=False, a_earth=None, f_earth=0.003352810681182319)[source]

Compute the great-circle/geodetic distance between coordinates on a sphere / ellipsoid. The computation of the distance for ellipsoidal_earth=True uses the pyproj librairy that implements the algorithm given in [Karney2013].

Parameters:

data (xr.DataArray | xr.Dataset) – Must have latitude and longitude coordinates.
pt (xr.DataArray | xr.Dataset) – Object with coordinates that are not latitude or longitude but that contain latitude and longitude. For example, a list of points with a coordinate “id”.
ellipsoidal_earth (bool | str, optional) – Boolean to choose if the surface of the Earth is an ellipsoid or a sphere. Default is False for spherical Earth.
a_earth (float, optional) – Earth semi-major axis [m]. If not provided, use data.attrs[‘radius’] and if it does not exist, use LNPY_A_EARTH_GRS80.
f_earth (float, optional) – Earth flattening. Default is LNPY_F_EARTH_GRS80.

Returns:

distance – DataArray with distance between the latitude and longitude of data and the latitude and longitude of pt. The final coordinates are latitude, longitude + coordinates of pt.

Return type:

xr.DataArray

References

[Karney2013]

C.F.F. Karney, “Algorithms for geodesics”, Journal of Geodesy, 87, 43-55, (2013). doi: 10.1007/s00190-012-0578-z

lenapy.utils.geo.assert_grid(ds)[source]

Verify if the given xr.Dataset have dimensions ‘longitude’ and ‘latitude’. Raise Assertion error if not.

Parameters:: ds (xr.DataArray) – Spatial grid to verify.
Returns:: True – Returns True if the dataset has dimensions ‘longitude’ and ‘latitude’.
Return type:: bool
Raises:: AssertionError – This function raises AssertionError is self._obj is not a xr.Dataset corresponding to spherical harmonics.

lenapy.utils.geo.surface_grid(da, type='nan', **kwargs)[source]