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)[source]¶ Apply a mask to an scm cube’s data
- Parameters
in_scmcube (
ScmCube
) – AnScmCube
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)[source]¶ 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)[source]¶ 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 toarray_in
.- Parameters
cube (
ScmCube
) –ScmCube
instance whose lat-lon grid we want to check againsarray_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 annp.ndarray
.- Return type
array_out
- Raises
AssertionError –
array_in
cannot be broadcast onto the cube’s lat-lon grid because their shapes are not compatibleValueError –
array_in
cannot be broadcast onto the cube’s lat-lon grid byiris.util.broadcast_to_shape
-
netcdf_scm.utils.
cube_lat_lon_grid_compatible_with_array
(cube, array_in)[source]¶ 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 witharray_in
, otherwiseFalse
- Return type
- 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)[source]¶ 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
) – AnScmCube
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
isFalse
then ada.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)[source]¶ Get a cube’s time axis in a given calendar
- Parameters
scm_cube (
ScmCube
) – AnScmCube
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)[source]¶ Take the latitude longitude mean of a cube with given weights
- Parameters
in_scmcube (
ScmCube
) – AnScmCube
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)[source]¶ 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).