Utils API

Utils contains a number of helpful functions for doing common cube operations.

For example, applying masks to cubes, taking latitude-longitude means and getting timeseries from a cube as datetime values.

netcdf_scm.utils.apply_mask(in_scmcube, in_mask)

Apply a mask to an scm cube’s data

Parameters

• in_scmcube (ScmCube) – An ScmCube instance.

• in_mask (np.ndarray) – The mask to apply

Returns

A copy of the input cube with the mask applied to its data

Return type

ScmCube

netcdf_scm.utils.assert_all_time_axes_same(time_axes)

Assert all time axes in a set are the same.

Parameters

time_axes (list_like of array_like) – List of time axes to compare.

Raises

AssertionError – If not all time axes are the same.

netcdf_scm.utils.broadcast_onto_lat_lon_grid(cube, array_in)

Broadcast an array onto the latitude-longitude grid of cube.

Here, broadcasting means taking the array and ‘duplicating’ it so that it has the same number of dimensions as the cube’s underlying data.

For example, given a cube with a time dimension of length 3, a latitude dimension of length 4 and a longitude dimension of length 2 (shape 3x4x2) and array_in of shape 4x2, results in a 3x4x2 array where each slice in the broadcasted array’s time dimension is identical to array_in.

Parameters

• cube (ScmCube) – ScmCube instance whose lat-lon grid we want to check agains

• array_in (np.ndarray) – The array we want to broadcast

Returns

The original array, broadcast onto the cube’s lat-lon grid (i.e. duplicated along all dimensions except for latitude and longitude). Note: If the cube has lazy data, we return a da.Array, otherwise we return an np.ndarray.

Return type

array_out

Raises

• AssertionError – array_in cannot be broadcast onto the cube’s lat-lon grid because their shapes are not compatible

• ValueError – array_in cannot be broadcast onto the cube’s lat-lon grid by iris.util.broadcast_to_shape

netcdf_scm.utils.cube_lat_lon_grid_compatible_with_array(cube, array_in)

Assert that an array can be broadcast onto the cube’s lat-lon grid

Parameters

cube (ScmCube) – ScmCube instance whose lat-lon grid we want to check agains

array_innp.ndarray

The array we want to ensure is able to be broadcast

Returns

True if the cube’s lat-lon grid is compatible with array_in, otherwise False

Return type

bool

Raises

AssertionError – The array cannot be broadcast onto the cube’s lat-lon grid

netcdf_scm.utils.get_cube_timeseries_data(scm_cube, realise_data=False)

Get a timeseries from a cube.

This function only works on cubes which are on a time grid only i.e. have no other dimension coordinates.

Parameters

• scm_cube (ScmCube) – An ScmCube instance with only a ‘time’ dimension.

• realise_data (bool) – If True, force the data to be realised before returning

Returns

The cube’s timeseries data. If realise_data is False then a da.Array will be returned if the data is lazy.

Return type

np.ndarray

netcdf_scm.utils.get_scm_cube_time_axis_in_calendar(scm_cube, calendar)

Get a cube’s time axis in a given calendar

Parameters

• scm_cube (ScmCube) – An ScmCube instance.

• calendar (str) – The calendar to return the time axis in e.g. ‘365_day’, ‘gregorian’.

Returns

Array of datetimes, containing the cube’s calendar.

Return type

np.ndarray

netcdf_scm.utils.take_lat_lon_mean(in_scmcube, in_weights)

Take the latitude longitude mean of a cube with given weights

Parameters

• in_scmcube (ScmCube) – An ScmCube instance.

• in_weights (np.ndarray) – Weights to use when taking the mean.

Returns

First output is a copy of the input cube in which the data is now the latitude-longitude mean of the input cube’s data. Second output is the sum of weights i.e. normalisation used in the weighted mean.

Return type

ScmCube, float

netcdf_scm.utils.unify_lat_lon(cubes, rtol=1e-06)

Unify latitude and longitude co-ordinates of cubes in place.

The co-ordinates will only be unified if they already match to within a given tolerance.

Parameters

• cubes (iris.cube.CubeList) – List of iris cubes whose latitude and longitude co-ordinates should be unified.

• rtol (float) – Maximum relative difference which can be accepted between co-ordinate values.

Raises

ValueError – If the co-ordinates differ by more than relative tolerance or are not compatible (e.g. different shape).