ants.io package#

Submodules#

ants.io.load module#

Loading Target grids#

The ANTS library provides a grid loading capability via ants.io.load.load_grid(). This function will return an iris cube that can be used to define the target grid for processing. The cube can have a constant data field or a land sea mask depending on the data source.

Grid loading supports the following formats:

Ancillary (CAP) compliant Fortran Namelist grid definition files (further information can be found at ants.io.load.load_grid()). Use this format in applications that do not need to use the land sea mask of the target field as part of their processing.
Any fileformat that can be interpreted by iris. Use this format to read a grid with a land sea mask.

Loading data#

ANTS uses iris to load common fileformats and therefore has access to all formats that are supported by iris.

In most cases you should, however, use ants.io.load(), ants.io.load.load_cube() etc. to load data as cubes from files. These ANTS functions perform additional processing on the input data. They will attempt to:

Derive the global/regional status of the input data and set the metadata on the cube accordingly.
Guess bounds of latitude and longitude for any sources without horizontal grid bounds.
Remove any forecast_reference_time and forecast_period coordinates.

The ANTS functions add extra capability, depending on the fileformat, over the base iris functions. You should read the documentation for the ANTS module for the specific fileformat being used, for example ants.fileformats.ancil for ancillary fields file loading.

ants.io.load.ants_format_agent()[source]#: Customises iris.fileformats.FORMAT_AGENT for ants loading and reverts the FORMAT_AGENT once the loading is complete.

ants.io.load.load(*args, **kwargs)[source]#

Loads any number of Cubes for each constraint.

Wraps iris.load(). Different to the iris functionality, this will remove any forecast_reference_time and forecast_period coordinates. The order of pseudolevels will be preserved from the source file.

Parameters:

*args – See iris.load()
**kwargs – See iris.load()

Return type:

A CubeList.

ants.io.load.load_cube(*args, **kwargs)[source]#

Loads a single cube.

Wraps iris.load_cube(). Different to the iris functionality, this will remove any forecast_reference_time and forecast_period coordinates. The order of pseudolevels will be preserved from the source file.

Parameters:

*args – See iris.load_cube()
**kwargs – See iris.load_cube()

Return type:

A Cube.

ants.io.load.load_cubes(*args, **kwargs)[source]#

Loads exactly one Cube for each constraint.

Wraps iris.load_cubes(). Different to the iris functionality, this will remove any forecast_reference_time and forecast_period coordinates. The order of pseudolevels will be preserved from the source file.

Parameters:

*args – See iris.load_cubes()
**kwargs – See iris.load_cubes()

Return type:

A CubeList.

ants.io.load.load_grid(filenames, *args, **kwargs)[source]#

Load a grid definition and return an iris cube.

The purpose of this function is to load a single grid definition, without the data payload, from components derived from one or more file. That is, to merge these components where possible to return a single grid definition. Examples include the merging of a vertical definition with one defining the horizontal domain. Surface altitude (orography) is also supported as a merge component. A hybrid height coordinate will ensue. Where source datasets have conflicting components, an exception will be raised. Where more than one source dataset has identical components, a single grid will still be returned.

Parameters:

filenames (str) – Pathname of a file, or a list of such paths that contain the grid definition.
*args – See iris.load()
**kwargs – See iris.load()

Returns:

Cube representing the grid defined with no data disk dependence and negligible data memory usage (using dummy data).

Return type:

iris.cube.Cube

Raises:

ValueError – Where we are unable to resolve a single grid due to a conflicting coordinate.
iris.exceptions.ConstraintMismatchError – Where no cubes have been found.

ants.io.load.load_landsea_mask(filename, land_threshold=None)[source]#

Load a landsea mask from either a landsea mask file or a landfraction file.

Parameters:

filename (str) – Landsea mask or landsea fraction filepath.
land_threshold (float, optional) – Threshold for converting the land fraction field into a landsea mask field. 0.5 would mean that any fraction greater than this will be masked. This argument is used when loading a land fraction field.

Returns:

Landsea mask cube.

Return type:

iris.cube.Cube

ants.io.load.load_raw(*args, **kwargs)[source]#

Loads non-merged cubes.

Wraps iris.load_raw(). Different to the iris functionality, this will remove any forecast_reference_time and forecast_period coordinates. The order of pseudolevels will be preserved from the source file.

Parameters:

*args – See iris.load_raw()
**kwargs – See iris.load_raw()

Return type:

A CubeList.

ants.io.save module#

This module contains code used to save cubes.

Saving data#

Like loading, ANTS save adds extra file format dependent capability over the base iris save. Saving the cube to NetCDF uses ants.io.save.netcdf(). Saving to an F03 UM ancillary file (using saver='ancil') uses ants.io.save.ancil(). NetCDF is easier to use for verification and diagnostic purposes, while the fields file is currently needed for the UM.

Additionally, ANTS has support for ‘ukca’ flavoured NetCDF, chosen by specifying saver='ukca' (see ants.io.save.ukca_netcdf()).

ants.io.save.ancil(cubes, filename)[source]#

Save one or more cubes to a F03 UM ancillary file.

UM documentation paper UM input and output file formats (F03) defines the ancillary file format.

Every provided cube must have a STASH code attribute defined.

The fields are written to the output file in this order:

for time in time_list:
    for STASH in STASH_list:
        for level in level_list:
            <write out field>

The time_list is sorted into ascending order.

The STASH_list is sorted into the order in which the STASH codes are first found in the cubes being passed into this function. If your use case requires fields with a particular STASH order, sort the cubes into that order prior to calling the save.

The level_list is either pseudo levels or model level numbers. The behaviour depends on the kind: model level numbers are sorted into ascending order like times, while pseudo levels are sorted in the order first found in the cubes, like STASH codes.

Saving cubes with both pseudo levels and model level numbers is not supported.

Parameters:

cubes (iris.cube.Cube or iris.cube.CubeList) – One or more cubes to be saved.
filename (str) – The name of the F03 UM ancillary file, including any extension.

Notes

To save a cube as a fields file, it must have a grid staggering set. To set the grid staggering manually you can use the grid_staggering attribute. For example, to set an ENDGame grid staggering:

cube.attributes['grid_staggering'] = 6

See UM doc F03 for suitable grid staggering values. Some metadata is set so applications apart from the UM can read the ancillary. This includes:

integer_constants(3) is set to 1 if there’s no valid value for it to support XCONV

ants.io.save.netcdf(cubes, filename, netcdf_format='NETCDF4_CLASSIC', local_keys=None, unlimited_dimensions=None, zlib=False, complevel=4, fill_value=None, update_history=True, history_message=None)[source]#

Save one or more cubes to a netCDF file.

Parameters:

cubes (iris.cube.Cube or iris.cube.CubeList) – One or more cubes to be saved.
filename (str) – The name of the netCDF file. If the .nc extension is missing then it it will be added to enforce CF compliance.
netcdf_format (str) – Underlying netCDF file format, one of NETCDF4, NETCDF4_CLASSIC, NETCDF3_CLASSIC or NETCDF3_64BIT. Default is NETCDF4_CLASSIC format.
local_keys (Iterable of str) – Cube attribute keys. Any cube attributes with matching keys will become attributes on the data variable rather than global attributes.
unlimited_dimensions (Iterable of str and/or iris.coords.Coord) – Coordinate dimensions of cube to save with the netCDF dimension variable length UNLIMITED. By default there are no dimensions assigned with length UNLIMITED.
zlib (bool) – If True, the data will be compressed in the netCDF file using gzip compression (default False).
complevel (int) – An integer between 1 and 9 describing the level of compression desired (default 4). Ignored if zlib is False.
fill_value (Number or list) – The value to use for the _FillValue attribute on the netCDF variable. If this argument is a list it must have the same number of elements as cubes if cubes is a iris.cube.CubeList, or a single element, and each element of this argument will be applied to each cube separately.
update_history (bool) – If True, the history attribute will be updated with the timestamped command line arguments (default True).
history_message (str) – The message to use instead of the command line arguments when updating the history attribute. This argument will only be used if update_history is set to True.

Notes

If the cubes being saved have lazy data, this saver has two potential side effects:

The data of any cubes with a datatype int64 and being saved as NETCDF4_CLASSIC are realised.
The data for each cube is rechunked such that the innermost dimension is a single chunk. This can be disabled via configuration, see ants_tuning in ants.config.GlobalConfiguration.