ugants.filter package#

Submodules#

ugants.filter.example_filters module#

Demonstration examples of filter classes.

All built on ugants.filter.generic.UnstructuredFilterABC.

class ugants.filter.example_filters.NullMeshFilter(cube: Cube)[source]#

Bases: UnstructuredFilterABC

An example, minimal spatial filter.

Derived from UnstructuredFilterABC. This filter makes no change to the input at all.

inner_filter(cube, original_standard_name)[source]#: Inner filter routine : return input unchanged.

class ugants.filter.example_filters.FaceNeighbourhoodFilter(cube: Cube, *, central_fraction: float = 1.0, neighbours_fraction: float = 1.0)[source]#

Bases: UnstructuredFilterABC

A simple spatial filter based on the unstructured connectivity.

Makes a weighted combination of each face value with the average of its immediate neighbours. This enables a general smoothing or sharpening effect similar to a 3x3 window filter.

Notes

only applicable to face-based data
the mesh must have faces, and a face-face connectivity.
the calculation makes no allowance for different effective distances or areas of the various neighbouring faces. Also, different mesh faces may have different numbers of neighbours. This means that the results do not have any definite physical meaning, and at best only approximate a true spatial filter.
the calculation does not correctly account for masked input data. This is because, for simplicity and efficiency, it averages over a fixed set of neighbours at each point, without excluding masked datapoints.

So, this operation roughly emulates a traditional ‘patch kernel’ operation, but in the absence of a regular grid the results are less reliable.

__init__(cube: Cube, *, central_fraction: float = 1.0, neighbours_fraction: float = 1.0)[source]#

Create a face-neighbourhood block filter.

Parameters:

cube – reference cube or mesh, as-per UnstructuredFilterABC.
central_fraction – the weight applied to the centre face value at each point
neighbours_fraction – the weight applied to the mean of all neighbouring values at each point

Examples

>>> # block-average-like calculation over nearest neighbours only
>>> blur_filter = FaceNeighbourhoodFilter(input_cube, central_fraction=0.2, neighbours_fraction=0.8)
>>> # an edge-detection type operation
>>> edge_filter = FaceNeighbourhoodFilter(input_cube, central_fraction=1., neighbours_fraction=-1.)
>>> # a "sharpening" (anti-blur) effect
>>> sharpen_filter = FaceNeighbourhoodFilter(input_cube, central_fraction=2.0, neighbours_fraction=-1.0)
>>> # operation
>>> sharpened_result = sharpen_filter(input_cube)

Notes

cubes passed to both the constructor and __call__ methods must have mesh.location == 'face',
the mesh must have faces and a face-face connectivity.

inner_filter(cube, original_standard_name)[source]#: Inner filter routine : calculate the neighbourhood operation.

ugants.filter.generic module#

Generic support code for defining Mesh filtering objects.

class ugants.filter.generic.UnstructuredFilterABC(cube)[source]#

Bases: ABC

An abstract class from which specific types of mesh filter are derived.

Represents a spatial operation defined on a given unstructured mesh, provided at creation time. The operation itself will be defined by the inheriting subclass.

The general operation of this will consist of several steps :

creation via __init__() : e.g. filter = FilterClass(cube[, *args, **kwargs])

The initial __init__, i.e. constructor call : this specifies and records the target mesh on which the filter operates. Additional control arguments and keywords may also be provided, but these will be specific to the actual filter type (class).
call via __call__() : e.g. result_cube = filter(input_cube)

The actual filtering operation. The input_cube, and the result, contain data on the same, originally-specifed filter mesh and location. The input cube can have different dimensions to the original, but its mesh (and hence mesh dimension length) must be the same. The calculation will be repeated over non-mesh dimensions, and the result will have the same dimensions, and same mesh, as the input.

Notes

In defining a specific derived subclass, you define the UnstructuredFilterABC.inner_filter() method, which is the core calculation. However, it will usually also be useful to override the ‘__init__’ method. When providing an overriding ‘__init__’ method, it is essential that this also calls the parent UnstructuredFilterABC.__init__().

__init__(cube)[source]#

Create a filter object.

Parameters:: cube (Cube) – The Iris Cube or Mesh defining the mesh, and location, which the operation operates on. Only its .mesh and .location are relevant to the filter operation.

Notes

The input mesh+location are stored for this filter, along with any other (filter-type-specific) args and keywords. These apply to all subsequent operations.

mesh: Mesh#: The mesh on which the filter operation is defined.

location: str#: The mesh location on which the filter operation is defined.

precalculation_done: bool#: Whether the precalculation was already done.

__call__(cube)[source]#

Perform an actual filter calculation.

Parameters:

cube (Cube) – the input cube : it must have the expected mesh and mesh-location.

Raises:

TypeError – If the input cube or the result of the filter is not a Cube.
ValueError – If there is an inconsistency between the cube used to create a filter, the cube on which the filter is being called, and the cube returned by the filtering operation.

Returns:

A new cube, on the original mesh, with all other dimensions and components derived from the input cube. Unless the filter operation assigns a specific standard-name, it will not have one. The calculation is simply repeated over non-mesh dimensions, it cannot depend on them.

Return type:

iris.cube.Cube

abstract inner_filter(cube, standard_name)[source]#

Perform the actual filtering calculation.

This is the key operational method to be provided by every subclass, to implement its specific calculation. It is called by __call__().

Parameters:

cube (Cube) – an input cube, on the filter mesh + location. Its standard-name has been removed + is passed separately.
standard_name (str or None) – The original input cube.standard_name. Removed in expectation that the result may not have the original phenomenon type.

Returns:

a cube on the original mesh, with all other dimensions and components derived from the input cube.

Return type:

iris.cube.Cube

Notes

Regarding the subclass-provided inner_filter function :

it must return a cube, which may be just the input cube with the new data installed.
the calculation should be repeated over all the non-mesh dimensions.
the result must have the same shape, mesh and mesh-location as the original.
other metadata (e.g. cell-methods, units) may be modified as required.
the phenomenon type of the result (standard name and cell-methods) may be set, or left empty.