psy-ugrid decoder for UGRID conventions

This module defines the decoder that we use to decode the UGRID conventions. It is supposed to overwrite the one defined in the psyplot.data module and has been originally developed in

https://codebase.helmholtz.cloud/psyplot/psyplot/-/merge_requests/31

Classes:

UGridDecoder(*args, **kwargs)

Decoder for UGrid data sets.
class psy_ugrid.decoder.UGridDecoder(*args, **kwargs)

Bases: CFDecoder

Decoder for UGrid data sets.

Methods:

can_decode(ds, var)

Check whether the given variable can be decoded.

clear_cache()

Clear the cache and remove the UGRID instances.

decode_coords(ds[, gridfile])

Reimplemented to set the mesh variables as coordinates

get_cell_node_coord(var[, coords, axis, nans])

Checks whether the bounds in the variable attribute are triangular

get_mesh(var[, coords])

Get the mesh variable for the given var

get_metadata_for_section(var, section, coords)

Get the metadata for a specific section

get_metadata_sections(var)

Get the metadata sections for a variable.

get_nodes(coord[, coords])

Get the variables containing the definition of the nodes

get_triangles(var[, coords, convert_radian, ...])

Get the of the given coordinate.

get_ugrid(var[, coords, loc])

Get the UGrid mesh object.

get_x(var[, coords])

Get the centers of the triangles in the x-dimension

get_xname(var[, coords])

Get the name of the spatial dimension

get_y(var[, coords])

Get the centers of the triangles in the y-dimension

get_yname(var[, coords])

Get the name of the spatial dimension

get_zname(var[, coords])

Get the name of the vertical dimension

infer_location(var[, coords, grid])

Infer the location for the variable.

is_unstructured(*args, **kwargs)

Reimpletemented to return always True.

Attributes:

supports_spatial_slicing

True if the data of the CFDecoder supports the extraction of a subset of the data based on the indices.
classmethod can_decode(ds, var)

Check whether the given variable can be decoded.

Returns True if a mesh coordinate could be found via the get_mesh() method

Parameters:

  • ds (xarray.Dataset) – The dataset that contains the given var

  • var (xarray.Variable or xarray.DataArray) – The array to decode

Returns:

True if the decoder can decode the given array var. Otherwise False

Return type:

bool

clear_cache()

Clear the cache and remove the UGRID instances.

static decode_coords(ds, gridfile=None)

Reimplemented to set the mesh variables as coordinates

Parameters:

  • ds (xarray.Dataset) – The dataset to decode

  • gridfile (str) – The path to a separate grid file or a xarray.Dataset instance which may store the coordinates used in ds

Returns:

ds with additional coordinates

Return type:

xarray.Dataset

get_cell_node_coord(var, coords=None, axis='x', nans=None)

Checks whether the bounds in the variable attribute are triangular

Parameters:

  • var (xarray.Variable or xarray.DataArray) – The variable to check

  • coords (dict) – Coordinates to use. If None, the coordinates of the dataset in the ds attribute are used.

  • axis ({'x', 'y'}) – The spatial axis to check

  • nans ({None, 'skip', 'only'}) – Determines whether values with nan shall be left (None), skipped ('skip') or shall be the only one returned ('only')

Returns:

the bounds corrdinate (if existent)

Return type:

xarray.DataArray or None

get_mesh(var, coords=None)

Get the mesh variable for the given var

Parameters:

  • var (xarray.Variable) – The data source whith the 'mesh' attribute

  • coords (dict) – The coordinates to use. If None, the coordinates of the dataset of this decoder is used

Returns:

The mesh coordinate

Return type:

xarray.Coordinate

get_metadata_for_section(var: DataArray, section: str, coords: Dict) → Dict[str, str]

Get the metadata for a specific section

Parameters:

  • var (xarray.DataArray) – The data array to get the metadata for

  • section (str) – The section name

  • coords (Dict) – Other coordinates in the dataset

Returns:

A mapping from metadata name to section.

Return type:

Dict[str, str]

get_metadata_sections(var: DataArray) → List[str]

Get the metadata sections for a variable.

Parameters:

var (xarray.DataArray) – The data array to get the metadata for

Returns:

The sections for the metadata information

Return type:

List[str]

get_nodes(coord, coords=None)

Get the variables containing the definition of the nodes

Parameters:

  • coord (xarray.Coordinate) – The mesh variable

  • coords (dict, optional) – The coordinates to use to get node coordinates

get_triangles(var, coords=None, convert_radian=True, copy=False, src_crs=None, target_crs=None, nans=None, stacklevel=1)

Get the of the given coordinate.

Parameters:

  • var (xarray.Variable or xarray.DataArray) – The variable to use

  • coords (dict) – Alternative coordinates to use. If None, the coordinates of the ds dataset are used

  • convert_radian (bool) – If True and the coordinate has units in ‘radian’, those are converted to degrees

  • copy (bool) – If True, vertice arrays are copied

  • src_crs (cartopy.crs.Crs) – The source projection of the data. If not None, a transformation to the given target_crs will be done

  • target_crs (cartopy.crs.Crs) – The target projection for which the triangles shall be transformed. Must only be provided if the src_crs is not None.

  • nans ({None, 'skip', 'only'}) – Determines whether values with nan shall be left (None), skipped ('skip') or shall be the only one returned ('only')

Returns:

The spatial triangles of the variable

Return type:

matplotlib.tri.Triangulation

Notes

If the 'location' attribute is set to 'node', a delaunay triangulation is performed using the matplotlib.tri.Triangulation class.

get_ugrid(var, coords=None, loc='infer')

Get the UGrid mesh object.

This method creates a gridded.pyugrid.ugrid.UGrid object for a given variable, depending on the corresponding 'mesh' attribute.

Parameters:

  • var (xarray.Variable) – The data source whith the 'mesh' attribute

  • coords (dict) – The coordinates to use. If None, the coordinates of the dataset of this decoder is used

  • dual ({"infer", "node", "edge", "face"}) – If “node” or “edge”, the dual grid will be computed.

Returns:

The UGrid object representing the mesh.

Return type:

gridded.pyugrid.ugrid.UGrid

get_x(var, coords=None)

Get the centers of the triangles in the x-dimension

Returns:

The y-coordinate or None if it could be found

Return type:

xarray.Coordinate or None

get_xname(var, coords=None)

Get the name of the spatial dimension

Returns:

The dimension name

Return type:

str

get_y(var, coords=None)

Get the centers of the triangles in the y-dimension

Returns:

The y-coordinate or None if it could be found

Return type:

xarray.Coordinate or None

get_yname(var, coords=None)

Get the name of the spatial dimension

Returns:

The dimension name

Return type:

str

get_zname(var, coords=None)

Get the name of the vertical dimension

Returns:

The dimension name

Return type:

str

infer_location(var, coords=None, grid=None)

Infer the location for the variable.

Parameters:

  • var (xarray.Variable) – The data source whith the 'mesh' attribute

  • coords (dict) – The coordinates to use. If None, the coordinates of the dataset of this decoder is used

  • grid (gridded.pyugrid.ugrid.UGrid) – The grid for this variable. If None, it will be created using the get_ugrid() method (if necessary)

Returns:

"node", "face" or "edge"

Return type:

str

is_unstructured(*args, **kwargs)

Reimpletemented to return always True. Any *args and **kwargs are ignored

supports_spatial_slicing: bool = False

True if the data of the CFDecoder supports the extraction of a subset of the data based on the indices.

For UGRID conventions, this is not easily possible because the extraction of a subset breaks the connectivity information of the mesh