ugants.utils package#

General processing utility routines.

ugants.utils.move_one_dimension(content, from_dim, to_dim)[source]#

Move one dimension of an array.

Transpose the input, to shift the selected dimension from one place to another in the index order. Negative indices are also supported.

Parameters:

content (numpy.ndarray or iris.cube.Cube) – an array-like (cube, numpy or Dask array) to be transposed
from_dim (int) – the dimension number to ‘move’. -1 means the last
to_dim (int) – index of the ‘moved’ dimension within the output. 0 means to the first dimension, -1 to the last.

Returns:

the result of an appropriate content.transpose() operation.

Return type:

numpy.ndarray or iris.cube.Cube

Submodules#

ugants.utils.cube module#

Utility functions for handling UGrid cubes.

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

Return a CubeList, irrespective of whether a Cube or a CubeList has been provided.

Parameters:: cubes (iris.cube.Cube or iris.cube.CubeList)
Raises:: TypeError – If provided with anything other than a iris.cube.Cube or iris.cube.CubeList
Return type:: iris.cube.CubeList

ugants.utils.cube.is_ugrid(cube)[source]#

Check if the provided cube contains UGrid data.

Parameters:: cube (iris.cube.Cube) – Cube to check.
Return type:: bool

ugants.utils.cube.get_connectivity_indices(cube, connectivity)[source]#

Get the connectivity indices array for a cube’s mesh.

The start_index is subtracted from the connectivity array, so that the returned array is guaranteed to have zero-based indexing. For more information about zero- and one-based indexing, see the UGRID conventions.

Parameters:

cube (iris.cube.Cube) – The cube from which to extract the connectivity indices.
connectivity (str) – The connectivity to extract.

Returns:

connectivity_indices – The cube’s zero-indexed connectivity array.

Return type:

numpy.ndarray

ugants.utils.cube.prepare_for_save(cubes: Cube | CubeList)[source]#

Add or amend attributes on a cube or cubes prior to saving to disk.

Each cube is updated so that its history attribute acquires a new entry, specifying the operation performed by the invoked application. A history entry records a timestamp and the application (i.e. command-line) name and arguments of the current operation. History “entries” are delimited by newlines: the most recent appears first.

The CF Conventions provide further description of the history attribute.

A “ugants_status” attribute is added to indicate whether the version of UG-ANTS is stable.

A “suite_provenance” attribute is added to provide information on the suite (if applicable) taken from the SUITE_PROVENANCE environment variable.

Note

A copy of the provided cube(s) is returned, the operation is not performed in place.

Parameters:: cubes (iris.cube.Cube | iris.cube.CubeList) – Cube(s) to be saved.
Returns:: A copy of the cube(s) with relevant metadata updated. If a single Cube is provided, then a single Cube will be returned. If a CubeList is provided, then a CubeList will be returned.
Return type:: iris.cube.Cube | iris.cube.CubeList

class ugants.utils.cube.Stencil(cube, iterations=1)[source]#

Bases: object

Get indices of all cells in the neighbourhood of a given central cell.

The algorithm follows that outlined in section 4.1 of this paper.

Examples

The following table shows three panels of the C4 cubed sphere, which is used here to illustrate creating stencils on an unstructured grid. The numbers in the table represent the cell indices. In the example below, cell 0 neighbours cells 1, 4, 51, and 64. Cell 50 neighbours cells 49, 51, 54, and 65.

				67	71	75	79
				66	70	74	78
				65	69	73	77
				64	68	72	76
48	49	50	51	0	1	2	3
52	53	54	55	4	5	6	7
56	57	58	59	8	9	10	11
60	61	62	63	12	13	14	15

By default the stencil will only include the four immediate neighbours, plus the central cell itself:

>>> stencil = Stencil(cube)
>>> stencil[0]
[0, 64, 1, 51, 4]
>>> stencil[10]
[6, 9, 10, 11, 14]

Negative indices are permitted, and will be interpreted in the usual Python way, i.e. for a positive integer M, the index -M will be replaced with N - M where N is the length of the array. For example, index -1 refers to the final element of the array, -2 the penultimate element, etc. If the provided central index is negative, then it will appear in the returned list as its positive counterpart.

>>> cube.shape
(96,)
>>> stencil[-96]
[0, 64, 1, 51, 4]
>>> stencil[-86]
[6, 9, 10, 11, 14]

Passing iterations=2 generates an extended stencil with the eight surrounding cells, or seven if the central cell is on the corner of a face:

>>> extended_stencil = Stencil(cube, iterations=2)
>>> extended_stencil[0]
[0, 64, 1, 51, 4, 68, 5, 55]
>>> extended_stencil[10]
[5, 6, 7, 9, 10, 11, 13, 14, 15]

Further iterations can be specified if a larger neighbourhood is required:

>>> third_iteration_stencil = Stencil(cube, iterations=3)
>>> third_iteration_stencil[0]
[0, 64, 1, 65, 4, 68, 5, 2, 69, 6, 8, 72, 9, 50, 51, 54, 55, 59]
>>> third_iteration_stencil[10]
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 80, 20, 84, 24, 88, 28]

__init__(cube, iterations=1)[source]#

Generate a stencil of a given size on a cube.

Parameters:

cube (iris.cube.Cube) – Cube on which to generate stencil.
iterations (int, optional) –
The number of iterations for which to run the stencil generation algorithm.
- If 1 (the default), use only the four immediate neighbours around the central cell.
- If 2, use the extended neighbourhood by filling the corner cells, i.e. those which are connected to two cells in the immediate neighbourhood.

Raises:

TypeError – If the provided iterations is not an int.
ValueError – If the provided iterations is not a positive integer.

__getitem__(central_cell_index)[source]#

Retrieve the indices of the neighbourhood of central_cell_index.

Parameters:: central_cell_index (int) – Index of the central cell around which the stencil is defined. Negative indices are permitted, and will be interpreted in the usual Python way, i.e. index -1 refers to the final element of the array, -2 the penultimate element, etc.
Returns:: All indices in the stencil, including the central cell index. The list is unordered, and contains only positive indices.
Return type:: list[int]

Note

Negative indices are permitted, and will be interpreted in the usual Python way, i.e. index -1 refers to the final element of the array, -2 the penultimate element, etc. If the provided central index is negative, then it will appear in the returned list as its positive counterpart, e.g. -1 will be replaced with N - 1 where N is the number of faces of the cube.

ugants.utils.cube.align_mask(cube_input)[source]#

Added in version 0.4.0.

Adjust a cube’s mask so that it is of the same shape as the associated data.

Tests the input to see if it should be handled as a cube or cubelist and uses `_expand_cube_mask(cube)` to carry out the work of adjusting the mask(s).

Parameters:: cube_input (iris.cube.Cube or iris.cube.CubeList)
Returns:: In-place operation.
Return type:: None

				67	71	75	79
				66	70	74	78
				65	69	73	77
				64	68	72	76
48	49	50	51	0	1	2	3
52	53	54	55	4	5	6	7
56	57	58	59	8	9	10	11
60	61	62	63	12	13	14	15

				67	71	75	79
				66	70	74	78
				65	69	73	77
				64	68	72	76
48	49	50	51	0	1	2	3
52	53	54	55	4	5	6	7
56	57	58	59	8	9	10	11
60	61	62	63	12	13	14	15

				67	71	75	79
				66	70	74	78
				65	69	73	77
				64	68	72	76
48	49	50	51	0	1	2	3
52	53	54	55	4	5	6	7
56	57	58	59	8	9	10	11
60	61	62	63	12	13	14	15