ants.fileformats.ancil package#

This module supports saving cubes as UM ancillary files.

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

Loading ancillary data#

The following additional functionality is provided on load by ANTS, independent of which load function is used:

Pseudo-level order from the fieldsfile is preserved.
Grid staggering is stored on the cube and made available via cube.attributes[‘grid_staggering’].

ants.fileformats.ancil.load_cubes(*args, **kwargs)[source]#

Loads cubes from a list of fields files filenames.

This function acts as a wrapper to iris.fileformats.um.load_cubes(). Adds grid staggering to the loaded data.

Submodules#

ants.fileformats.ancil.preprocessing module#

A collection of frequently required preprocessing steps for mule.UMFile objects.

Available functionality includes:

Update time origin to avoid issues with dates defined in year 0 (update_reference_year).
Make the existing bounds on a time coordinate contiguous (make_time_bounds_contiguous).
Explicitly set and override climatology year (set_climatology_year).
Fix lbproc value where possible (correct_lbproc).
Create a metadata.ini file for climatology time information (write_metadata_file)

ants.fileformats.ancil.preprocessing.correct_lbproc(ffv)[source]#

Set lbproc value to 0 where it is found to be negative.

Commonly, field.lbproc values are incorrectly set to the integer missing data indicator value (-32768), intending to denote that no processing has been done. However this is incorrect, and so this function overrides this with the value 0 as per F03.

Parameters:: ffv (mule.UMFile object.) –
Returns:: In-place operation
Return type:: None

Warning

To be used at the users discretion.

ants.fileformats.ancil.preprocessing.make_time_bounds_contiguous(ffv, final_bound=None)[source]#

Make exising time bounds contiguous.

The definition of contiguous used is that the start time of one cell is exactly the same as the end time of the preceding cell chronologically.

In addition, the final cells (in terms of time - i.e. all the cells with the same time value as the final cell) are adjusted such that they end exactly one year after start of the first cells. This means that the data spans exactly one year.

If the data should not span exactly a year, or if the automatic upper bound detection fails on the final cells, call this function with a tuple provided to the final_bound keyword argument, where the first element is the desired lbyrd, second element is the desired lbmond and so on, through to the final element being lbsecd.

Parameters:

ffv (mule.UMFile object.) – The input UM file which we want to update.
final_bound (tuple, optional) – A six element tuple, where the first element is the desired lbyrd, second element is the desired lbmond and so on, through to the final element being lbsecd.

Warning

No checking is done to ensure that the data is appropriate to be made contiguous or that the provided final_bound is consistent with the data.
If the final_bound parameter is not supplied, the file is assumed to be intended to cover exactly one year. If this is not the case, the end time of the final cells will be wrong: there is no attempt to compute the end time of the final cell based on the times in the preceding cells.

ants.fileformats.ancil.preprocessing.set_climatology_year(ffv, year)[source]#

Set the climatology year.

Set the climatology year, overriding all fixed length header time information and field time information in the process. This is most useful for those files where a year of 0 has been used to denote a periodic climatology. The calendar is determined from the time bounds specified in the fields. The only assumption is that field.lbmon values are correct as this determines ordering.

Parameters:

ffv (mule.UMFile object.) – The input UM file which we wish to fill the climatology year information.
year (int) – Year of the climatology.

Returns:

In-place operation

Return type:

None

Warning

To be used at the users discretion.

ants.fileformats.ancil.preprocessing.update_reference_year(ffv, year=None)[source]#

Update origin year of the time coordinate.

Either sets the year to the provided year, or defaults to setting it to 4AD. If the file to be fixed does not correspond to a leap year, please provide a year to over-ride the 4AD default.

Parameters:

ffv (mule.UMFile object.) – The input UM file which we want to update.
year (int, optional) – The year to switch the origin of the time coordinate to. The provided year must be greater than 0.

Warning

If no year is provided, it is assumed that the data should be shifted to a leap year. To avoid this, provide a year parameter that is not a leap year.

ants.fileformats.ancil.preprocessing.write_metadata_file(ffv, output_filepath)[source]#

Write a metadata.ini file for time metadata.

Write a metadata.ini file for time metadata in cases where the time information in the fixed length header and field has been changed (typically for climatologies, by set_climatology year()). Therefore, if this is to be used alongside set_climatology_year(), it should be called first. It is only suitable for use with monthly mean multi year climatologies. The format of the output file will be, for example: [climatology] cell_methods: time: mean within years time: mean over years bounds_diff: month start: 1998-01-01 end: 2008-01-01

Parameters:

ffv (mule.UMFile object.) – The input UM file which we wish to fill the climatology year information.
output_filepath (str) – The location for the output metadata.ini file.

Returns:

In-place operation

Return type:

None

Warning

To be used at the users discretion.

ants.fileformats.ancil.template module#

Tools for generating the template required for saving ancillary files.

ants.fileformats.ancil.template.GRIDS = {'endgame': 6, 'newdynamics': 3}#

Map of model formulation to grid staggering fixed length header value.

Used in saving ancillaries, to set the grid staggering in the fixed length header.

Type:: dict

ants.fileformats.ancil.template.create(cubes, field)[source]#

Creates a template set of headers.

The template is designed to be compatible with “from_template” method of mule.ancil.AncilFile.

Parameters:

cubes (iris.cube.CubeList) – The cubes used to derive the some of the header values.
field (mule.Field3) – A realised reference field used to derive the remaining header values.

Returns:

Contains the derived header values in a format suitable to be used to generate a mule AncilFile via the “from_template” method of mule.ancil.AncilFile.

Return type:

dict

ants.fileformats.ancil.time_headers module#

This module provides functions related to time handling for ancillary files.

ants.fileformats.ancil.time_headers.is_periodic(times)[source]#

Tests whether a time coordinate corresponds to a periodic ancillary.

It is not easy to determine whether a time coordinate should be treated as periodic or not. This implementation only looks for annual periodicity. If you have times with different periodicity then this function will need adapting.

A time coordinate is annual and periodic if the end bound of the last time is exactly one year after the start bound of the first time. If this does not work for your time coordinate first ensure that your time coordinate is consistent with CF use of bounds. You may need to pre-process the bounds values as necessary.

If your time coordinate is annually periodic, is not recognised as periodic by this function and editing would change the meaning of the data then this function may need adapting.

Parameters:: times (iris.coords.Coord) – Time coordinate to examine.
Returns:: Whether times are identified as periodic or time series. True means the time coordinate is periodic.
Return type:: bool
Raises:: ValueError – If the provided times coordinate is not recognised as a time.

ants.fileformats.ancil.time_headers.set_headers_time_information(cube, headers)[source]#

Modifies the provided headers with time information derived from the cube.

Parameters:

cube (iris.cube.Cube) – The cube used to derive the time information to insert into the headers.
headers (dict) – Dictionary of values describing the headers of an ancillary file to which time information needs to be added. The headers dictionary is edited in place.