ugants.analysis package#

Submodules#

ugants.analysis.command_line module#

Implementation for the fill missing points application.

class ugants.analysis.command_line.FillMissingPoints(source: CubeList, target_mask: CubeList | None = None)[source]#

Bases: Application

Fill missing points for UGrid data.

Uses the KDTreeFill algorithm.

source: CubeList#

target_mask: CubeList = None#

run()[source]#

Fill missing points in the source cube.

The ugants.analysis.fill.KDTreeFill class is used with the provided target mask to fill missing points in the source cube. The filled result is stored in self.result.

ugants.analysis.coord_transforms module#

Provides functions to convert between coordinate reference systems.

ugants.analysis.coord_transforms.convert_to_cartesian(source: Cube) → ndarray[source]#

Convert the data locations of an iris UGrid cube to a 3D Cartesian point cloud.

The coordinate system of the source cube is assumed to be spherical, and the points are mapped to the unit sphere.

Parameters:: source (iris.cube.Cube) – A UGrid cube to transform
Returns:: An nx3 array representing the coordinates of the n data locations in 3D space.
Return type:: numpy.ndarray

Warning

This function assumes a spherical geocentric coordinate system for conversion to 3D cartesian coordinates. If the provided cube is not defined on this coordinate system then unexpected results may occur.

ugants.analysis.fill module#

Provides functionality for filling missing data on UGrid.

class ugants.analysis.fill.FillABC(source: Cube, target_mask: Cube | None = None)[source]#

Bases: ABC

An abstract base class which provides an interface for fill operations.

The abstract methods to be provided when subclassing the FillABC are:

calculate_fill_lookup() - Perform precalculation prior to filling
missing data.
__call__() - Perform the missing data fill on the supplied cube.

source#

UGrid cube with missing data to be filled, identified by masked data.

Type:: iris.cube.Cube

target_mask#

Target mask to be applied to constrain the search, by default None. The filled cube will inherit this target mask.

Type:: iris.cube.Cube

indices_to_be_filled#

A boolean array specifying the cells in the source data that need to be filled.

Type:: numpy.ndarray

indices_to_fill_from#

A boolean array specifying the cells in the source data that are considered valid fill candidates.

Type:: numpy.ndarray

__init__(source: Cube, target_mask: Cube | None = None)[source]#

Identify cells to fill, cells to fill from, and calculate_fill_lookup.

Missing points are identified by either masked or nan values. The target_mask is used to constrain the valid fill points, so that only unmasked points are considered valid fill candidates. In addition, the target_mask is applied to the filled cube.

The following truth table shows the behaviour of a given cell for the various combinations of being masked in source and target_mask:

Masked in `source`	Value in `target_mask`	Cell requires filling	Valid fill candidate
False	False	False	True
False	True	False	False
True	False	True	False
True	True	False	False

Parameters:

source – UGrid cube with missing data to be filled, identified by either NaN or masked data.
target_mask – Target mask to be applied to constrain the search, by default None. Cells that are True in the target mask are considered invalid fill candidates.

abstract calculate_fill_lookup()[source]#

Perform precalculation for filling missing data.

Initialise any data structures used in the __call__() method, and return None.

abstract __call__(cube: Cube) → Cube[source]#

Perform the missing data fill on the supplied cube.

Make use of any data structures created during the calculate_fill_lookup() method. Return a new iris.cube.Cube with the missing data filled.

identify_cells_to_fill()[source]#

Identify cells within source cube to be filled.

Sets the indices_to_be_filled attribute.

Returns:: In-place operation.
Return type:: None

identify_valid_fill_cells()[source]#

Identify cells within source cube which are valid fill candidates.

Sets the indices_to_fill_from attribute.

Returns:: In-place operation.
Return type:: None

__repr__() → str[source]#: Provide a string representation of the class instance.

class ugants.analysis.fill.KDTreeFill(source: Cube, target_mask: Cube | None = None)[source]#

Bases: FillABC

Fill points with data from nearest neighbour, identified using a KDTree.

Warning

The KDTree fill assumes that the data is located on a spherical geocentric coordinate system. Attempting to use this fill algorithm with a different coordinate system may lead to unexpected results.

calculate_fill_lookup()[source]#

Train and query a KDTree to identify nearest neighbours.

The location of every face of the source cube is converted to a 3D vector. This ‘point cloud’ is then split into two sets: ‘points to be filled’ and ‘points to fill from’. The ‘points to fill from’ are used to train a KDTree, which is then queried using the ‘points to be filled’. This provides a mapping from every missing point in the source cube to the index of its nearest neighbour in the valid subset.

__call__(cube: Cube) → Cube[source]#

Fill missing points in cube.

Missing data are filled with nearest neighbour data using the precalculated KDTree to look up valid data.

Parameters:: cube – Cube with missing points to be filled.
Returns:: Cube with missing points filled with data from nearest neighbour.
Return type:: iris.cube.Cube

ugants.analysis.fill.flood_fill(cube: Cube, seed_point: int, fill_value: float)[source]#

Fill a contiguous region in cube, starting at seed point.

The flood fill algorithm identifies a contiguous region, starting at the seed_point and extending outwards to neighbouring cells with the same data value as the seed point. Neighbours are identified using the mesh’s face_face_connectivity.

Parameters:

cube – Cube to flood fill.
seed_point – Index of the cube’s data array to start the flood fill.
fill_value – Value with which to fill all cells in the contiguous region. To mask out the region, set fill_value=np.ma.masked.

Returns:

Flood filled copy of the original cube.

Return type:

iris.cube.Cube

Raises:

ValueError – If the provided cube has a non-horizontal dimension.
ValueError – If the specified seed point already has the specified fill value.

Note

There is no way to specify an extended neighbourhood in the same way as regular ANTS. Only immediate neighbours as identified by the cube’s face_face_connectivity are considered, not diagonals.

Wraparound is always enabled since there is no meaningful boundary in the unstructured grid.

Currently the flood fill can only be used on horizontal data. Cubes with vertical levels, time coordinates or other non-mesh coordinates are not supported.

ugants.analysis.fill.convert_nan_to_masked(cube: Cube) → Cube[source]#

Mask NaN values in the provided cube.

Parameters:: cube – Source cube with missing data identified by np.nan values.
Returns:: Cube with NaN values masked.
Return type:: iris.cube.Cube