def process(
cube: cli.inputcube,
mask: cli.inputcube,
weights: cli.inputcube = None,
*,
neighbourhood_shape="square",
radii: cli.comma_separated_list,
lead_times: cli.comma_separated_list = None,
area_sum=False,
):
""" Module to process land and sea separately before combining them.
Neighbourhood the input dataset over two distinct regions of land and sea.
If performed as a single level neighbourhood, a land-sea mask should be
provided. If instead topographic_zone neighbourhooding is being employed,
the mask should be one of topographic zones. In the latter case a weights
array is also needed to collapse the topographic_zone coordinate. These
weights are created with the improver generate-topography-bands-weights
CLI and should be made using a land-sea mask, which will then be employed
within this code to draw the distinction between the two surface types.
Args:
cube (iris.cube.Cube):
A cube to be processed.
mask (iris.cube.Cube):
A cube containing either a mask of topographic zones over land or
a land-sea mask. If this is a land-sea mask, land points should be
set to one and sea points set to zero.
weights (iris.cube.Cube):
A cube containing the weights which are used for collapsing the
dimension gained through masking. These weights must have been
created using a land-sea mask. (Optional).
neighbourhood_shape (str):
Name of the neighbourhood method to use.
Options: "circular", "square".
Default: "square".
radii (list of float):
The radius or a list of radii in metres of the neighbourhood to
apply.
If it is a list, it must be the same length as lead_times, which
defines at which lead time to use which nbhood radius. The radius
will be interpolated for intermediate lead times.
lead_times (list of int):
The lead times in hours that correspond to the radii to be used.
If lead_times are set, radii must be a list the same length as
lead_times. Lead times must be given as integer values.
area_sum (bool):
Return sum rather than fraction over the neighbourhood area.
Returns:
(tuple): tuple containing:
**result** (iris.cube.Cube):
A cube of the processed data.
Raises:
ValueError:
If the topographic zone mask has the attribute
topographic_zones_include_seapoints.
IOError:
if a weights cube isn't given and a topographic_zone mask is given.
ValueError:
If the weights cube has the attribute
topographic_zones_include_seapoints.
RuntimeError:
If lead times are not None and has a different length to radii.
TypeError:
A weights cube has been provided but no topographic zone.
"""
import numpy as np
from improver.nbhood.nbhood import NeighbourhoodProcessing
from improver.nbhood.use_nbhood import ApplyNeighbourhoodProcessingWithAMask
masking_coordinate = None
if any(
"topographic_zone" in coord.name() for coord in mask.coords(dim_coords=True)
):
if mask.attributes["topographic_zones_include_seapoints"] == "True":
raise ValueError(
"The topographic zones mask cube must have been "
"masked to exclude sea points, but "
"topographic_zones_include_seapoints = True"
)
if not weights:
raise TypeError(
"A weights cube must be provided if using a mask "
"of topographic zones to collapse the resulting "
"vertical dimension."
)
if weights.attributes["topographic_zones_include_seapoints"] == "True":
raise ValueError(
"The weights cube must be masked to exclude sea "
"points, but topographic_zones_include_seapoints "
"= True"
)
masking_coordinate = "topographic_zone"
land_sea_mask = weights[0].copy(data=weights[0].data.mask)
land_sea_mask.rename("land_binary_mask")
land_sea_mask.remove_coord(masking_coordinate)
# Create land and sea masks in IMPROVER format (inverse of
# numpy standard) 1 - include this region, 0 - exclude this region.
land_only = land_sea_mask.copy(
data=np.logical_not(land_sea_mask.data).astype(int)
)
sea_only = land_sea_mask.copy(data=land_sea_mask.data.astype(int))
else:
if weights is not None:
raise TypeError("A weights cube has been provided but will not be " "used")
land_sea_mask = mask
# In this case the land is set to 1 and the sea is set to 0 in the
# input mask.
sea_only = land_sea_mask.copy(
data=np.logical_not(land_sea_mask.data).astype(int)
)
land_only = land_sea_mask.copy(data=land_sea_mask.data.astype(int))
if lead_times is None:
radius_or_radii = float(radii[0])
else:
if len(radii) != len(lead_times):
raise RuntimeError(
"If leadtimes are supplied, it must be a list"
" of equal length to a list of radii."
)
radius_or_radii = [float(x) for x in radii]
lead_times = [int(x) for x in lead_times]
# Section for neighbourhood processing land points.
if land_only.data.max() > 0.0:
if masking_coordinate is None:
result_land = NeighbourhoodProcessing(
neighbourhood_shape,
radius_or_radii,
lead_times=lead_times,
sum_only=area_sum,
re_mask=True,
)(cube, land_only)
else:
result_land = ApplyNeighbourhoodProcessingWithAMask(
masking_coordinate,
neighbourhood_shape,
radius_or_radii,
lead_times=lead_times,
collapse_weights=weights,
sum_only=area_sum,
)(cube, mask)
result = result_land
# Section for neighbourhood processing sea points.
if sea_only.data.max() > 0.0:
result_sea = NeighbourhoodProcessing(
neighbourhood_shape,
radius_or_radii,
lead_times=lead_times,
sum_only=area_sum,
re_mask=True,
)(cube, sea_only)
result = result_sea
# Section for combining land and sea points following land and sea points
# being neighbourhood processed individually.
if sea_only.data.max() > 0.0 and land_only.data.max() > 0.0:
# Recombine cubes to be a single output.
combined_data = result_land.data.filled(0) + result_sea.data.filled(0)
result = result_land.copy(data=combined_data)
return result
def process(cube: cli.inputcube,
mask: cli.inputcube,
weights: cli.inputcube = None,
*,
radii: cli.comma_separated_list,
lead_times: cli.comma_separated_list = None,
area_sum=False,
return_intermediate=False):
""" Module to process land and sea separately before combining them.
Neighbourhood the input dataset over two distinct regions of land and sea.
If performed as a single level neighbourhood, a land-sea mask should be
provided. If instead topographic_zone neighbourhooding is being employed,
the mask should be one of topographic zones. In the latter case a weights
array is also needed to collapse the topographic_zone coordinate. These
weights are created with the improver generate-topography-bands-weights
CLI and should be made using a land-sea mask, which will then be employed
within this code to draw the distinction between the two surface types.
Args:
cube (iris.cube.Cube):
A cube to be processed.
mask (iris.cube.Cube):
A cube containing either a mask of topographic zones over land or
a land-sea mask.
weights (iris.cube.Cube):
A cube containing the weights which are used for collapsing the
dimension gained through masking. These weights must have been
created using a land-sea mask. (Optional).
radii (list of float):
The radius or a list of radii in metres of the neighbourhood to
apply.
If it is a list, it must be the same length as lead_times, which
defines at which lead time to use which nbhood radius. The radius
will be interpolated for intermediate lead times.
lead_times (list of int):
The lead times in hours that correspond to the radii to be used.
If lead_times are set, radii must be a list the same length as
lead_times. Lead times must be given as integer values.
area_sum (bool):
Return sum rather than fraction over the neighbourhood area.
return_intermediate (bool):
Include this option to return a cube with results following
topographic masked neighbourhood processing of land points and
prior to collapsing the topographic_zone coordinate. If no
topographic masked neighbourhooding occurs, there will be no
intermediate cube and a warning.
Returns:
(tuple): tuple containing:
**result** (iris.cube.Cube):
A cube of the processed data.
**intermediate_cube** (iris.cube.Cube):
A cube of the intermediate data, before collapsing.
Raises:
ValueError:
If the topographic zone mask has the attribute
topographic_zones_include_seapoints.
IOError:
if a weights cube isn't given and a topographic_zone mask is given.
ValueError:
If the weights cube has the attribute
topographic_zones_include_seapoints.
RuntimeError:
If lead times are not None and has a different length to radii.
TypeError:
A weights cube has been provided but no topographic zone.
"""
import warnings
import numpy as np
from improver.nbhood.nbhood import NeighbourhoodProcessing
from improver.nbhood.use_nbhood import (
ApplyNeighbourhoodProcessingWithAMask,
CollapseMaskedNeighbourhoodCoordinate)
sum_or_fraction = 'sum' if area_sum else 'fraction'
masking_coordinate = intermediate_cube = None
if any([
'topographic_zone' in coord.name()
for coord in mask.coords(dim_coords=True)
]):
if mask.attributes['topographic_zones_include_seapoints'] == 'True':
raise ValueError('The topographic zones mask cube must have been '
'masked to exclude sea points, but '
'topographic_zones_include_seapoints = True')
if not weights:
raise TypeError('A weights cube must be provided if using a mask '
'of topographic zones to collapse the resulting '
'vertical dimension.')
if weights.attributes['topographic_zones_include_seapoints'] == 'True':
raise ValueError('The weights cube must be masked to exclude sea '
'points, but topographic_zones_include_seapoints '
'= True')
masking_coordinate = 'topographic_zone'
land_sea_mask = weights[0].copy(data=weights[0].data.mask)
land_sea_mask.rename('land_binary_mask')
land_sea_mask.remove_coord(masking_coordinate)
# Create land and sea masks in IMPROVER format (inverse of
# numpy standard) 1 - include this region, 0 - exclude this region.
land_only = land_sea_mask.copy(
data=np.logical_not(land_sea_mask.data).astype(int))
sea_only = land_sea_mask.copy(data=land_sea_mask.data.astype(int))
else:
if weights is not None:
raise TypeError('A weights cube has been provided but will not be '
'used')
land_sea_mask = mask
# In this case the land is set to 1 and the sea is set to 0 in the
# input mask.
sea_only = land_sea_mask.copy(
data=np.logical_not(land_sea_mask.data).astype(int))
land_only = land_sea_mask.copy(data=land_sea_mask.data.astype(int))
if lead_times is None:
radius_or_radii = float(radii[0])
else:
if len(radii) != len(lead_times):
raise RuntimeError("If leadtimes are supplied, it must be a list"
" of equal length to a list of radii.")
radius_or_radii = [float(x) for x in radii]
lead_times = [int(x) for x in lead_times]
if return_intermediate is not None and masking_coordinate is None:
warnings.warn('No topographic_zone coordinate found, so no '
'intermediate file will be saved.')
# Section for neighbourhood processing land points.
if land_only.data.max() > 0.0:
if masking_coordinate is None:
result_land = NeighbourhoodProcessing(
'square',
radius_or_radii,
lead_times=lead_times,
sum_or_fraction=sum_or_fraction,
re_mask=True).process(cube, land_only)
else:
result_land = ApplyNeighbourhoodProcessingWithAMask(
masking_coordinate,
radius_or_radii,
lead_times=lead_times,
sum_or_fraction=sum_or_fraction,
re_mask=False).process(cube, mask)
if return_intermediate:
intermediate_cube = result_land.copy()
# Collapse the masking coordinate.
result_land = CollapseMaskedNeighbourhoodCoordinate(
masking_coordinate, weights=weights).process(result_land)
result = result_land
# Section for neighbourhood processing sea points.
if sea_only.data.max() > 0.0:
result_sea = NeighbourhoodProcessing('square',
radius_or_radii,
lead_times=lead_times,
sum_or_fraction=sum_or_fraction,
re_mask=True).process(
cube, sea_only)
result = result_sea
# Section for combining land and sea points following land and sea points
# being neighbourhood processed individually.
if sea_only.data.max() > 0.0 and land_only.data.max() > 0.0:
# Recombine cubes to be a single output.
combined_data = result_land.data.filled(0) + result_sea.data.filled(0)
result = result_land.copy(data=combined_data)
return result, intermediate_cube
def process(cube,
mask,
radius=None,
radii_by_lead_time=None,
weights=None,
sum_or_fraction="fraction",
return_intermediate=False):
""" Module to process land and sea separately before combining them.
Neighbourhood the input dataset over two distinct regions of land and sea.
If performed as a single level neighbourhood, a land-sea mask should be
provided. If instead topographic_zone neighbourhooding is being employed,
the mask should be one of topographic zones. In the latter case a weights
array is also needed to collapse the topographic_zone coordinate. These
weights are created with the improver generate-topography-bands-weights
CLI and should be made using a land-sea mask, which will then be employed
within this code to draw the distinction between the two surface types.
Args:
cube (iris.cube.Cube):
A cube to be processed.
mask (iris.cube.Cube):
A cube containing either a mask of topographic zones over land or
a land-sea mask.
radius (float):
The radius in metres of the neighbourhood to apply.
Rounded up to convert into integer number of grid points east and
north, based on the characteristic spacing at the zero indices of
the cube projection-x and y coordinates.
Default is None.
radii_by_lead_time (list):
A list with the radius in metres at [0] and the lead_time at [1]
Lead time is a List of lead times or forecast periods, at which
the radii within 'radii' are defined. The lead times are expected
in hours.
Default is None
weights (iris.cube.Cube):
A cube containing the weights which are used for collapsing the
dimension gained through masking. These weights must have been
created using a land-sea mask.
Default is None.
sum_or_fraction (str):
The neighbourhood output can either be in the form of a sum of the
neighbourhood, or a fraction calculated by dividing the sum of the
neighbourhood by the neighbourhood area.
Default is 'fraction'
return_intermediate (bool):
If True will return a cube with results following topographic
masked neighbourhood processing of land points and prior to
collapsing the topographic_zone coordinate. If no topographic
masked neighbourhooding occurs, there will be no intermediate cube
and a warning.
Default is False.
Returns:
(tuple): tuple containing:
**result** (iris.cube.Cube):
A cube of the processed data.
**intermediate_cube** (iris.cube.Cube or None):
A cube of the intermediate data, before collapsing.
Raises:
ValueError:
If the topographic zone mask has the attribute
topographic_zones_include_seapoints.
IOError:
if a weights cube isn't given and a topographic_zone mask is given.
ValueError:
If the weights cube has the attribute
topographic_zones_include_seapoints.
Warns:
warning:
A weights cube has been provided but no topographic zone.
"""
masking_coordinate = intermediate_cube = None
if any([
'topographic_zone' in coord.name()
for coord in mask.coords(dim_coords=True)
]):
if mask.attributes['topographic_zones_include_seapoints'] == 'True':
raise ValueError('The topographic zones mask cube must have been '
'masked to exclude sea points, but '
'topographic_zones_include_seapoints = True')
if not weights:
raise TypeError('A weights cube must be provided if using a mask '
'of topographic zones to collapse the resulting '
'vertical dimension.')
if weights.attributes['topographic_zones_include_seapoints'] == 'True':
raise ValueError('The weights cube must be masked to exclude sea '
'points, but topographic_zones_include_seapoints '
'= True')
masking_coordinate = 'topographic_zone'
landmask = weights[0].copy(data=weights[0].data.mask)
landmask.rename('land_binary_mask')
landmask.remove_coord(masking_coordinate)
# Create land and sea masks in IMPROVER format (inverse of
# numpy standard) 1 - include this region, 0 - exclude this region.
land_only = landmask.copy(
data=np.logical_not(landmask.data).astype(int))
sea_only = landmask.copy(data=landmask.data.astype(int))
else:
if weights is None:
warnings.warn('A weights cube has been provided but will not be '
'used as there is no topographic zone coordinate '
'to collapse.')
landmask = mask
# In this case the land is set to 1 and the sea is set to 0 in the
# input mask.
sea_only = landmask.copy(
data=np.logical_not(landmask.data).astype(int))
land_only = landmask.copy(data=landmask.data.astype(int))
radius_or_radii, lead_times = radius_or_radii_and_lead(
radius, radii_by_lead_time)
if return_intermediate is not None and masking_coordinate is None:
warnings.warn('No topographic_zone coordinate found, so no '
'intermediate file will be saved.')
# Section for neighbourhood processing land points.
if land_only.data.max() > 0.0:
if masking_coordinate is None:
result_land = NeighbourhoodProcessing(
'square',
radius_or_radii,
lead_times=lead_times,
sum_or_fraction=sum_or_fraction,
re_mask=True).process(cube, land_only)
else:
result_land = ApplyNeighbourhoodProcessingWithAMask(
masking_coordinate,
radius_or_radii,
lead_times=lead_times,
sum_or_fraction=sum_or_fraction,
re_mask=False).process(cube, mask)
if return_intermediate:
intermediate_cube = result_land.copy()
# Collapse the masking coordinate.
result_land = CollapseMaskedNeighbourhoodCoordinate(
masking_coordinate, weights=weights).process(result_land)
result = result_land
# Section for neighbourhood processing sea points.
if sea_only.data.max() > 0.0:
result_sea = NeighbourhoodProcessing('square',
radius_or_radii,
lead_times=lead_times,
sum_or_fraction=sum_or_fraction,
re_mask=True).process(
cube, sea_only)
result = result_sea
# Section for combining land and sea points following land and sea points
# being neighbourhood processed individually.
if sea_only.data.max() > 0.0 and land_only.data.max() > 0.0:
# Recombine cubes to be a single output.
combined_data = result_land.data.filled(0) + result_sea.data.filled(0)
result = result_land.copy(data=combined_data)
return result, intermediate_cube
def _calculate_ratio(self, cube: Cube, cube_name: str, radius: float) -> Cube:
"""
Calculates the ratio of actual to potential value transitions in a
neighbourhood about each cell.
The process is as follows:
1. For each grid cell find the number of cells of value 1 in a surrounding
neighbourhood of a size defined by the arg radius. The potential
transitions within that neighbourhood are defined as the number of
orthogonal neighbours (up, down, left, right) about cells of value 1.
This is 4 times the number of cells of value 1.
2. Calculate the number of actual transitions within the neighbourhood,
that is the number of cells of value 0 that orthogonally abut cells
of value 1.
3. Calculate the ratio of actual to potential transitions.
Ratios approaching 1 indicate that there are many transitions, so the field
is highly textured (rough). Ratios close to 0 indicate a smoother field.
A neighbourhood full of cells of value 1 will return ratios of 0; the
diagnostic that has been thresholded to produce the binary field is found
everywhere within that neighbourhood, giving a smooth field. At the other
extreme, in neighbourhoods in which there are no cells of value 1 the ratio
is set to 1.
Args:
cube:
Input data in cube format containing a two-dimensional field
of binary data.
cube_name:
Name of input data cube, used for determining output texture cube name.
radius:
Radius for neighbourhood in metres.
Returns:
A ratio between 0 and 1 of actual transitions over potential transitions.
"""
# Calculate the potential transitions within neighbourhoods.
potential_transitions = NeighbourhoodProcessing(
"square", radius, sum_only=True
).process(cube)
potential_transitions.data = 4 * potential_transitions.data
# Calculate the actual transitions for each grid cell of value 1 and
# store them in a cube.
actual_transitions = potential_transitions.copy(
data=self._calculate_transitions(cube.data)
)
# Sum the number of actual transitions within the neighbourhood.
actual_transitions = NeighbourhoodProcessing(
"square", radius, sum_only=True
).process(actual_transitions)
# Calculate the ratio of actual to potential transitions in areas where the
# original diagnostic value was greater than zero. Where the original value
# was zero, set ratio value to one.
ratio = np.ones_like(actual_transitions.data)
ratio[cube.data > 0] = (
actual_transitions.data[cube.data > 0]
/ potential_transitions.data[cube.data > 0]
)
# Create a new cube to contain the resulting ratio data.
ratio = create_new_diagnostic_cube(
"texture_of_{}".format(cube_name),
"1",
cube,
mandatory_attributes=generate_mandatory_attributes(
[cube], model_id_attr=self.model_id_attr
),
data=ratio,
)
return ratio
