ants.cli package#

Submodules#

ants.cli.ancil_2anc module#

Conversion to ancillary file format application#

Loads one or more cubes from the provided filepath(s) and saves them to the specified output file path as both NetCDF and ancillary. See ants.load for details on supported fileformats.

This is a file format translation utility. It assumes all fields in the input file are to be added to the output file. It will also infer most of the metadata for the ancillary file format from the metadata in the input files. To do this the metadata in the input files has to be complete and accurate. This is discussed in more detail in Appendix A: F03 Ancillary file time metadata.

As ancil_2anc is only a file format translation utility you may need to edit the metadata of your input file to make it complete and accurate. You will often need to specify the grid staggering as this usually can not be inferred from the metadata in input files.

ants.cli.ancil_create_shapefile module#

Shapefile creation application#

Creates and saves a shapefile from a list of pairs of longitude, latitude points defining a single polygon in a specified polygon file.

ants.cli.ancil_create_shapefile.cli_interface()[source]#

ants.cli.ancil_create_shapefile.main(json_file, output)[source]#

Loads in a provided json file that defines pairs of longitude, latitude points to create a polygon from. That polygon is then used to create a shape file that is saved to the specified output location.

Parameters:

json_file (str) – Path to json file
output (str) – Location to store generated shape file

ants.cli.ancil_fill_n_merge module#

Ancillary fill and merge application#

This application fulfils two requirements: to merge datasets and to fill missing values.

ants.cli.ancil_fill_n_merge.cli_interface()[source]#

ants.cli.ancil_fill_n_merge.load_data(primary_source, alternate_source=None, validity_polygon_filepath=None, target_mask_filepath=None, land_fraction_threshold=None, begin=None, end=None)[source]#

Load the necessary data for performing a merge and fill operation.

Parameters:

primary_source (str) – Primary source filepath.
alternate_source (str, optional) – Alternate source filepath used when merging.
validity_polygon_filepath (str, optional) – Filepath to the validity polygon which represents the data from the primary dataset which is valid.
target_mask_filepath (str, optional) – Filepath to the target field mask.
land_fraction_threshold (str, optional) –
begin (datetime, optional) – Datetime to start the processing.
end (datetime, optional) – Datetime to end the processing.

Returns:

The tuple contains the primary cube(s) (CubeList), alternate cube(s) (CubeList), validity polygon (shapely.Polygon) and target mask (Cube) respectively.

Return type:

tuple

ants.cli.ancil_fill_n_merge.main(primary_source, output, alternate_source, validity_polygon_filepath, target_mask_filepath, invert_mask, land_fraction_threshold, begin, end, netcdf_only, search_method)[source]#

Perform merge and fill operation on the provided sources.

The merge stage requires both a primary_source and an alternate_source to be provided, and may optionally have a polygon shapefile. The resulting data takes values from the primary_source within the polygon (or everywhere where valid data is present, if the polygon is not provided), and values from the alternate_source everywhere else. See ants.analysis.merge() for further details.

The fill stage replaces missing data values with valid data, where missing is defined as data that is either masked or NaN. If a landseamask is provided, this mask is honoured by only filling missing land points with valid land values (and similarly, missing sea points with valid sea values). The fill stage occurs after the merge if multiple source files are provided. If the alternate_source file is not provided, only the fill stage is performed.

Parameters:

primary_source (str) – Primary source filepath.
alternate_source (str, optional) – Alternate source filepath, used when merging.
output (str) – Merged output filepath.
validity_polygon_filepath (str, optional) – Filepath to the validity polygon which represents the data from the primary dataset which is valid.
target_mask_filepath (str, optional) – Filepath to the target mask.
invert_mask (bool, optional) – When set to True, treat target mask True (1) values as unmasked. When set to False, treat target mask True (1) values as masked. Default is True.
land_fraction_threshold (str, optional) –
begin (datetime, optional) – If provided, all source data prior to this year is discarded. Default is to include all source data.
end (datetime, optional) – If provided, all source data after this year is discarded. Default is to include all source data.
search_method (str) – Select the search method to be used when filling missing points. The methods currently supported are “spiral” and “kdtree”.

Returns:

Merged result.

Return type:

CubeList

Raises:

RuntimeError – If the primary source is wholly within a provided validity polygon.

ants.cli.ancil_general_regrid module#

A general regrid application#

Regrids data from a source to a target grid using ants.regrid.GeneralRegridScheme. The result is written to an output file. The application supports both horizontal and vertical regridding. The regrid algorithm can be specified in the ants configuration file as described in ants.config.GlobalConfiguration. See ants.regrid for further details.

If a landseamask is provided using the target-lsm argument, this mask is honoured by only filling missing land points with valid land values (or similarly, missing sea points with valid sea values).

Zonal mean behaviour#

If the source and target provided have global extent in the ‘x’ axis, or if the source has only one column (‘x’), then the target will be processed to ensure it fits the definition of a zonal mean. This ensures that a zonal mean output is produced, regardless of the number of longitude points in the regrid target.

ants.cli.ancil_general_regrid.cli_interface()[source]#

ants.cli.ancil_general_regrid.load_data(source, target_grid=None, target_landseamask=None, land_fraction_threshold=None, begin=None, end=None)[source]#

ants.cli.ancil_general_regrid.main(source_path, output_path, target_path, target_lsm_path, invert_mask, land_fraction_threshold, begin, end, save_ukca, netcdf_only, search_method)[source]#

General regrid application top level call function.

Loads source data cubes, regrids them to match target data cube co-ordinates, and saves result to output. In addition to writing the resulting data cube to disk, also returns the regridded data cube.

Parameters:

source_path (str) – File path for one or more files which contain the data to be regridded.
target_path (str) – File path for files that provide the grid to which the source data cubes will be mapped. Separate files can be provided to generate a complete grid i.e. a namelist for vertical levels can be used with a data file for the horizontal coordinates.
target_lsm_path (str) – File path for a land sea mask that provides the grid to which the source data cube will be mapped. The output will be made consistent with this land sea mask.
invert_mask (bool, optional) – Determines whether to invert the mask for the target_lsm_path argument. When set to True, treat target mask True (1) values as unmasked. When set to False, treat target mask True (1) values as masked. Default is True.
output_path (str) – Output file path to write the regridded data to.
land_fraction_threshold (str) –
begin (datetime, optional) – If provided, all source data prior to this year is discarded. Default is to include all source data.
end (datetime, optional) – If provided, all source data after this year is discarded. Default is to include all source data.
search_method (str) – This specifies which search routine is used in making the provided source(s) consistent with the provided land sea mask. This should only be provided if a target land sea mask is also provided via target_lsm_path.

Returns:

Cube
A single data cube with the regridded data.

ants.cli.ancil_general_regrid.regrid(sources, target)[source]#