ants.utils package#

Submodules#

ants.utils.coord module#

ants.utils.coord.guess_bounds(coord, strict=True)[source]#

Guess bounds wrapper around the iris guess bounds functionality.

Additional capability from iris includes sensible guessing of latitude bounds to ensure they remain contiguous and guessing of time bounds for any calendar where points are in the middle of a month.

Parameters:

coord (iris.coords.Coord) – Iris coordinate in which to guess its bounds.
strict (bool) – Define whether an existing bounds on the coordinate should raise an exception (True - default iris/ants behaviour). When strict is False, coordinates with only one point should continue without failure.

Raises:

ValueError – Raised if guessing time coordinate bounds isn’t possible. Currently, guessing time bounds is only supported for the case where points are the middle of each month.

ants.utils.coord.relaxed_equality(coord1, coord2)[source]#

Return whether the provided coordinate is equal to the other provided.

Equality is performed with some tolerance as defined by ants.config.TOLERANCE, however in the case of bounds, a more relaxed independent arbitrary tolerance specified. Where bounds are present on one but not both coordinates, a temporary guess is made of these bounds where possible and a comparison made.

Parameters:

coord1 (iris.coords.Coord) –
coord2 (iris.coords.Coord) –

Returns:

True if coord1 == coord2. False if coord1 != coord2

Return type:

bool

ants.utils.coord.set_crs(coord, axis=None, crs=None)[source]#

Set coord coordinate system.

Set coordinate system of the coordinate, correcting and populating metadata where possible.

Parameters:

coord (iris.coords.Coord) – Coordinate object to infer a suitable coordinate_system.
axis (str, optional) – The desired coordinate axis. If not specified, it will be guessed, see iris.util.guess_coord_axis().
crs (iris.coord_systems.CoordSystem, optional) – Defaults to a UM Sphere where unspecified and undefined by the coord (ants.coord_systems.UM_SPHERE).

Returns:

Inplace operation

Return type:

None

ants.utils.cube module#

class ants.utils.cube.CubeBuilder(crs, shape=None, data=None, xlim=None, ylim=None, with_bounds=True, name=None, stash=None)[source]#

Bases: object

__init__(crs, shape=None, data=None, xlim=None, ylim=None, with_bounds=True, name=None, stash=None)[source]#

Initialises a basic cube with the parameters passed in.

The cube must have a coordinate reference system specified and either a shape or data passed in.

By default, with a iris.coord_systems.GeogCS(6371229.0) and a shape of (2,2), CubeBuilder will create a cube with the cube.summary() of:

unknown / (unknown)                 (latitude: 2; longitude: 2)
    Dimension coordinates:
        latitude                             x             -
        longitude                            -             x

New in version 2.2.

Parameters:

crs (A subclass of iris.coord_systems.CoordSystem) –
shape (tuple, optional) – The shape of the cube to be created.
data (ndarray optional) – An array of data the cube will have.
xlim (tuple) – A tuple(x0, x1) defining the upper and lower range for axis=’x’.
ylim (tuple) – A tuple(y0, y1) defining the upper and lower range for axis=’y’.
with_bounds (bool, optional) – The option for the latitude and longitude coordinates on the cube to contain bounds
name (str, optional) – The name of the cube.

Returns:

Inplace operation

Return type:

None

add_3d_time_coord(times)[source]#

Adds a time coordinate to the cube.

Parameters:: times (int) –
Returns:: Inplace operation
Return type:: None

add_hybrid_height_coordinate_factory(longitude)[source]#

Adds a hybrid height coordinate factory to the cube.

This is required to create a cube with hybrid heights.

Parameters:: longitude (int) –
Returns:: Inplace operation
Return type:: None

add_hybrid_pressure_coordinate_factory()[source]#

Adds a hybrid pressure coordinate factory to the cube.

This is required to create a cube with hybrid pressure. ANTS does not support hybrid pressure cubes. This should only be used to test exceptions.

Parameters:: None –
Returns:: Inplace operation
Return type:: None

add_model_level_coordinate(additional_attributes=None)[source]#

Adds a model level coordinate to the cube.

Parameters:: additional_attributes (dict, optional) – The default option for additional attributes is None.
Returns:: Inplace operation
Return type:: None

add_sigma_aux_coord()[source]#

Adds a sigma auxillary coordinate to the cube.

Parameters:: None –
Returns:: Inplace operation
Return type:: None

static derive_crs(ellipsoid, north_pole_latitude, north_pole_longitude)[source]#

Checks the north pole coordinates and updates crs accordingly.

Parameters:

ellipsoid (A subclass of iris.coord_systems.CoordSystem.) –
north_pole_latitude (float) –
north_pole_longitude (float) –

Return type:

A subclass of iris.coord_systems.CoordSystem.

make_cube_curvilinear(crs)[source]#

Generate curvilinear lat-lon cube by translating 1D cube on the specified coordinate system.

Parameters:: crs (A subclass of iris.coord_systems.CoordSystem.) –
Returns:: Inplace operation
Return type:: None

set_name(name)[source]#: Rename the cube.

set_units(units)[source]#: Set the units of the cube.

ants.utils.cube.as_cubelist(cubes)[source]#

Function for ensuring that we return a Cubelist, irrespective of whether a Cube or a CubeList has been provided.

Parameters:: cubes (iris.cube.Cube or iris.cube.CubeList) –
Return type:: iris.cube.CubeList

ants.utils.cube.concatenate(cubes)[source]#

Concatenate cubes together.

Convenience wrapper around the iris concatentation functionality, allowing cubes with missing dimension coordinates to be concatenated where there are common aux coords.

Parameters:: cubes (iris.cube.CubeList objects) – Cubes in which to concatenate.
Returns:: New CubeList object of concatenated cubes.
Return type:: iris.cube.CubeList

Warning

ants.utils.cube.concatenate() is deprecated as of ANTS 2.0 and will be removed in a future release. Please use the iris method iris.cube.CubeList.concatenate().

ants.utils.dask module#

ants.utils.dask.deferred_data_update(data, overwrite_data, slices)[source]#

Assign new data to the specified slices of data lazily.

With the benefits of dask, override ‘data’ with ‘overwrite_data’ at the specified slices without realising any data.

Parameters:

data (array_like) – 2D array like object which includes numpy arrays or dask arrays. This represents the arrays which the other is transplanted onto.
new_data (array_like) – 2D array like object which includes numpy arrays or dask arrays. This represents the array which is transplanted into the other.
slices (tuple(slice, slice)) – Slices object representing the 2D slicing of ‘data’ to transplant the ‘overwrite_data’.

Returns:

Lazy array representing the original array with the new data transplanted onto it.

Return type:

dask.array.Array

Note

This function serves the purpose of replacing part of a dask array with some changes.

ants.utils.ndarray module#

ants.utils.ndarray.allclose(x1, x2, tolerance=None)[source]#: Returns True if two arrays are element-wise equal within ants.config.TOLERANCE.

ants.utils.ndarray.greater(x1, x2)[source]#: Return the truth value of (x1 > x2) element-wise with tolerance defined by ants.config.TOLERANCE.

ants.utils.ndarray.group_indices(array)[source]#

Group an array representing indices into an iterable of slice objects.

Parameters:

array (numpy.ndarray) – Numpy array representing indices.

Returns:

iterable of slice objects
>>> indices = np.array([0, 1, 2, 4, 5, 6, 8, 9])
>>> group_indices(indices)
[slice(0, 3, None), slice(4, 7, None), slice(8, 10, None)]

ants.utils.ndarray.in1d(array1, array2)[source]#: Return boolean array that is True where an element of array1 is in array2. The comparison of elements is within a tolerance defined by ants.config.TOLERANCE.

ants.utils.ndarray.isclose(x1, x2)[source]#: Return the truth value of (x1 == x2) element-wise with tolerance defined by ants.config.TOLERANCE.

ants.utils.ndarray.less(x1, x2)[source]#: Return the truth value of (x1 < x2) element-wise with tolerance defined by ants.config.TOLERANCE.

ants.utils.ndarray.merge_array(array1, array2)[source]#

Merge overlapping arrays.

This strictly works by stitching compatible arrays together. Compatible arrays are those considered an extension or a subset of one another. Arrays must also be monotonically increasing/decreasing and currently in the same direction as one another.

Parameters:

array1 (numpy.ndarray) – Input array.
array2 (numpy.ndarray) – Input array.

Returns:

numpy.ndarray – Merged array containing the values of both supplied arrays.
>>> arr = np.array([4, 5, 6])
>>> arr2 = np.array([1, 2, 3, 4, 5])
>>> merge_array(arr, arr2)
array([1, 2, 3, 4, 5, 6])

ants.utils.ndarray.transposed_view(array, axes=None)[source]#

Return a transposed view of the provided array.

A wrapper for numpy transpose which supports taking a transposed view of the mask where present (unlike with numpy transpose).

Parameters:

array (numpy.ndarray) –
axes (list of int, optional) – By default, reverse the dimensions, otherwise permute the axes according to the values given.

Returns:

Data array and masked arrays with their axes permuted. A view is returned whenever possible.

Return type:

(numpy.ndarray, numpy.ndarray)

Note

This wrapper exists to overcome the limitations of numpy when dealing with masked arrays, in that a masked array view is not returned but a copy within numpy. See numpy/numpy#7483 for further details.

ants.utils.ndarray.wrap_lons(points, base, period, endpoint=True)[source]#

Wrap longitudinal points into the closed interval of base to base + period.

The interval includes base and base + period. This differs from iris.analysis.cartography.wrap_lons() which wraps onto a longitude interval including the base but excluding base + period (in the iris version base + period are mapped to base). See examples.

Parameters:

points (numpy.ndarray) – Points to wrap.
base (int or float) – Base of wrap range.
period (int or float) – Period of wrap range.

Returns:

Points array wrapped to the specified [base, base+period] range at 64bit float.

Return type:

numpy.ndarray

Examples

This wrap_lons will not wrap points at base + period but will leave them as is:

>>> import numpy as np
>>> wrap_lons(np.linspace(-180, 180, 4), -180, 360)
array([-180.,  -60.,   60.,  180.])

This contrasts with iris’ wrap_lons which will wrap points at base + period to base:

>>> from iris.analysis.cartography import wrap_lons as iwrap_lons
>>> iwrap_lons(np.linspace(-180, 180, 4), -180, 360)
array([-180.,  -60.,   60., -180.])