ugants.io package#

Support for loading and saving data to+from netcdf-ugrid files.

Submodules#

ugants.io.applications module#

IO themed UG-ANTS applications.

class ugants.io.applications.ExtractSingleMesh(mesh: Mesh)[source]#

Bases: Application

Extract a single named mesh from a UGrid netCDF file.

This application should only be run from the command line, not instantiated directly in code. The mesh provided to the __init__ is expected to have already been extracted from file in the from_command_line() method.

This application has no run method, since there is no processing required. The application just calls ugants.io.save.mesh() on the loaded mesh.

Example

>>> extract_mesh_app = ExtractSingleMesh.from_command_line()
>>> extract_mesh_app.save()

mesh: Mesh#: The single mesh extracted from file.

classmethod from_command_line(args: Sequence[str] | None = None)[source]#

Create an application instance from the command line.

The following arguments are parsed:

--mesh: The path to the mesh file from which to extract a mesh.
--mesh-name: The var_name of the mesh to be extracted.
output: The output file location to which to save the extracted mesh.

An instance of the ExtractSingleMesh class is created, instantiated with the mesh extracted from the provided file.

Parameters:: args (Sequence[str] | None) – Command line arguments to parse, by default None. If None, then the arguments are parsed from the command line.
Returns:: An instance of the class.
Return type:: ExtractSingleMesh

save()[source]#

Save the extracted mesh to UGrid netCDF.

Calls ugants.io.save.mesh() on the extracted mesh.

ugants.io.load module#

Load functions for UG-ANTS.

ugants.io.load.ugrid(uris, constraints=None) → CubeList[source]#

Load a UGrid file. Will not load if the file contains regular data.

Parameters:

uris (Any) – Location of file to load. Must be a NetCDF file.
constraints (Any | None) – One or more iris constraints. Each constraint can be either a string, or an instance of iris.Constraint. If the constraint is a string it will be used to match against cube.name().

Returns:

An iris iris.cube.CubeList containing the loaded data.

Return type:

iris.cube.CubeList

Raises:

iris.exceptions.InvalidCubeError – If the specified file does not contain UGrid data.
iris.exceptions.InvalidCubeError – If no data can be found which matches the provided constraint(s).
iris.exceptions.InvalidCubeError – If a mesh has been removed from a cube during constrained load. This may be caused by constraining on an unstructured dimension.

ugants.io.load.cf(uris, **kwargs)[source]#

Load one or more regular data input files.

Fails if files are identified as being UGRID.

Parameters:: uris (str or pathlib.Path) – A string or Path object to a file containing regular data. Can also be a list of files.
Returns:: cubes – An iris iris.cube.CubeList.
Return type:: iris.cube.CubeList
Raises:: ValueError – Raised if any input uris are not netCDF files.

ugants.io.load.mesh(uri: str | Path, mesh_name: str | None = None) → Mesh[source]#

Load a single mesh from a uri.

If no mesh_name is given, the mesh_name is inferred from the file itself, provided there is only one mesh in the file.

Parameters:

uri (str | pathlib.Path) – A string or Path to a netCDF file containing the mesh.
mesh_name (str | None) – The name of the mesh to load.

Returns:

An iris Mesh as provided by :func:iris.experimental.ugrid.load_mesh

Return type:

iris.experimental.ugrid.mesh.Mesh

Raises:

ValueError – If multiple meshes are present. If no meshes are present.

ugants.io.load.meshes(uris: str | Iterable[str], mesh_name: str | None = None) → list[Mesh][source]#

Load multiple meshes from netCDF file(s).

Parameters:

uris – Filepath(s) from which to load meshes.
mesh_name – The var_name of the meshes to load. If None (the default), all meshes are loaded.

Returns:

A list of meshes loaded from the uris with mesh_name, if provided.

Return type:

list[Mesh]

Raises:

ValueError – If no meshes are present at the given uris matching the mesh_name (if provided).

ugants.io.load.is_netcdf(uris)[source]#

Check uris point to netCDF files.

Parameters:: uris (str or pathlib.Path) – A string or Path object to a file containing regular data. Can also be a list of files.
Raises:: ValueError – Raised if any input uris are not netCDF files.

ugants.io.load.error_if_mesh(cube, filename)[source]#

Perform basic sanity checks to prevent accidently loading UGRID data.

A callback function for use with iris.load.

Parameters:

cube (iris.cube.Cube) – The iris cube to perform checking on.
filename (Any) – Original file used to generate the cube.

Raises:

ValueError – If cf_role is defined and is ‘mesh_topology’

ugants.io.save module#

Package for saving data to netcdf-ugrid files.

The routines also perform some standard checks on the source data to ensure that is has expected properties, such as all cubes being unstructured.

ugants.io.save.ugrid(cubes, filepath, **save_kwargs)[source]#

Save one or more unstructured Iris cubes to a netCDF4 UGRID-type file.

The resultant file will also be provided with two additional attributes.

ugants_status - Indicating whether the version of UG-ANTS is stable.
suite_provenance - Information on the suite (if applicable) taken from the SUITE_PROVENANCE environment variable.

Parameters:

cubes (iris.cube.Cube or iris.cube.CubeList) – One or more cubes to be saved. All cubes must be unstructured, with the same mesh.
filepath (str or pathlib.Path) – Creation path of a single netCDF file. Must have the extension “.nc”.
**save_kwargs (dict) – Any additional control keywords, passed to iris.fileformats.netcdf.save().

ugants.io.save.mesh(mesh: Mesh, filepath: str | Path, **save_kwargs)[source]#

Save one unstructured mesh to a netCDF4 UGRID-type file.

If a history attribute already exists on the provided mesh, then a new history entry will be prepended. If the provided mesh has no history, then one will be added.

The resultant file will also be provided with two additional attributes.

ugants_status - Indicating whether the version of UG-ANTS is stable.
suite_provenance - Information on the suite (if applicable) taken from the SUITE_PROVENANCE environment variable.

Note

The attributes will be added as local attributes to the mesh topology variable of the mesh. Iris 3.9 does not support adding global variables to meshes. See Iris issue #6085.

Warning

This function modifies the mesh in place by adding/modifying attributes. Iris currently does not have support for copying meshes, see Iris issue #5982.

Parameters:

mesh (Mesh) – A mesh to be saved.
filepath (str or pathlib.Path) – Creation path of a single netCDF file. Must have the extension “.nc”.
**save_kwargs (dict) – Any additional control keywords, passed to iris.experimental.ugrid.save_mesh().

ugants.io.xios_command_line module#

Implementation for the convert to XIOS application.

This application converts a UGrid netCDF file to a UGrid netCDF file with additional metadata and data layout suitable for loading in to XIOS. This is intended to be run at the end of a workflow for generating ancillary files.

class ugants.io.xios_command_line.ConvertToXIOS(sources: CubeList, cast_to_single: bool)[source]#

Bases: Application

Translate a UGrid cube to an XIOS compatible cube.

The pipeline is:

+------+    +-----+    +------+
| init | -> | run | -> | save |
+------+    +-----+    +------+

Where:

__init__() sets up the class with the source UGrid cubes to be translated to XIOS.
run() copies the sources to results and sets some metadata for XIOS, specifically:
1. If there is no online_operation attribute, use a default value of once.
2. If there is no long_name for a variable, copy the standard_name to the long_name.
3. Arrange data in CF order, such that the last dimensions are ‘time’, ‘vertical levels’, ‘mesh’ in that order, and all other dimensions (including pseudo level) precede those dimensions.
save() writes the XIOS results to disk with all metadata and data changes needed for XIOS. Additional changes beyond the run() metadata changes are:
1. Setting the _FillValue to a specific value that XIOS requires (XIOS does not honour the _FillValue attribute).
2. Ensuring the online_operation is a local attribute.
3. Cast all float type data to single precision, if cast_to_single is True.

__init__(sources: CubeList, cast_to_single: bool)[source]#

Instantiate class with UGrid sources that need to be translated to XIOS.

Parameters:

sources (iris.cube.CubeList) – Cube(s) representing the original UGrid data. Will be stored in sources.
cast_to_single (bool) – Cast all double precision (64 bit) float data to single precision (32 bit).

sources: CubeList#: Cube(s) representing the original UGrid data.

cast_to_single: bool#: Cast all double precision (64 bit) float data to single precision (32 bit).

results: CubeList = None#: Cube(s) with the additional metadata needed for XIOS. Generated by the run() method.

output: str = None#: Path for writing the results with XIOS compatible metadata and data.

run()[source]#

Apply most of the workarounds needed for XIOS.

Does not set the _FillValue attribute since this needs to be handled at the save stage.

Sets the results to be a copy of the cubes from sources with the workarounds needed for XIOS.

apply_long_name_workaround()[source]#

Set a long name on the cube when the cube has a standard name.

XIOS only cares that there is a long name, not what the long name is. If the cube has a standard name, copy that to the long name. If the cube doesn’t have a standard name, it will have a long name already.

See MetOffice/tcd-XIOS2-extras#32.

apply_online_operation_workaround()[source]#

Set online operation if it’s not already set.

The value of online operation is important. There are other valid values, so if the user has manually set one on the cube before saving, it should be preserved. Otherwise, set the online operation to once as a default option.

See MetOffice/tcd-XIOS2-extras#33.

apply_dimension_order_workaround()[source]#

Transpose cube to conform to XIOS expected order.

This means we want the last dimension to be the mesh, the penultimate dimension to be vertical levels (if present), the next last dimension to be time (if present). All other dimensions (including pseudo levels) need to be before time, vertical levels and the mesh. The original order for the other dimensions is preserved.

static get_fill_values(cubes)[source]#

Return the fill values to be used when saving each cube to netCDF.

The fill value will be determined according to each cube’s data type:

dtype	fill value
double (float64)	-1.7976931348623157e+308
single (float32)	-(32768.0 * 32768.0)
other	None

Warning

For data types other than double (64 bit) or single (32 bit) precision float, the returned fill value will be None. In practice, this means that the netCDF default fill value will be used for that data type.

Parameters:: cubes (iris.cube.CubeList) – Cubes to determine the fill values for.
Returns:: The fill value to be used when saving each cube to netCDF.
Return type:: list

save()[source]#

Save results to XIOS compatible UGrid netcdf.

Overrides parent class to use XIOS specific save arguments:

online_operation is defined as a local rather than global attribute. See MetOffice/tcd-XIOS2-extras#33.
Fill value is set per-field to a value required by XIOS (see get_fill_values()). See MetOffice/tcd-XIOS2-extras#31.
If cast_to_single is True, then all double (64 bit) float data will be cast to single (32 bit) float before saving.

ugants.io.xios_command_line.reorder_cube_dimensions(cube: Cube) → Cube[source]#

Reorder cube dimensions to be consistent with CF and XIOS.

The desired order is: other dimension(s), time, vertical, horizontal (mesh). The original order of the other dimensions is preserved.

“Other dimensions” includes pseudo levels.

Note that this function modifies the cube in-place, in addition to returning the modified cube.

Parameters:: cube (iris.cube.Cube) – Cube with dimensions to be reordered
Returns:: Cube with reordered dimensions
Return type:: iris.cube.Cube
Raises:: ValueError – If the provided cube has more than one time dimension, or more than one vertical dimension.

ugants.io.xios_command_line.cast_to_single_precision(cubes: CubeList)[source]#

Cast all double (float64) data to single precision (float32).

Integer data will not be cast.

Parameters:: cubes (iris.cube.CubeList) – Cubes to be cast
Returns:: A copy of the provided cubes with all float64 data cast to float32
Return type:: iris.cube.CubeList