improver.generate_ancillaries.generate_distance_to_feature module

A module for generating a distance to feature ancillary cube.

class DistanceToFeature(epsg_projection, new_name, buffer=30000, clip_geometry=False, parallel=False, n_parallel_jobs=2)

Bases: BasePlugin

Plugin to calculate the distance from sites to the nearest feature in a geometry. This is a generic plugin that can be used for any type of feature (e.g., coastlines, rivers, lakes, etc.). Distances are calculated to the nearest metre.

Given a cube containing site locations and a GeoDataFrame, the distance to each site from the nearest point of the feature geometry is calculated. This is done by converting the feature geometry and sites to a common target projection that must be specified using a European Petroleum Survey Group (EPSG) code that identifies the projection. For the UK, EPSG code 3035 may be used to provide a Lambert Azimuthal Equal Area projection that is suitable for the region. The chosen projection should match the projection on which the ancillary will be used. The distance method from Shapely is used to find the distance from each site to every point in the feature geometry. The minimum of these distances is returned as the distance to the nearest feature in the feature geometry and this is rounded to the nearest metre.

If requested, the provided geometry will be clipped to the bounds of the site locations with a buffer to improve performance by reducing computation. This is useful when the geometry is large and it would be expensive to calculate the distance to all features in the geometry but information may be lost at the edges of the domain.

Optionally, an exclusion geometry can be provided to the process method. For sites outside the exclusion geometry, the distance to the feature will be set to 0. This is useful for cases where the target region cannot be represented as a GeoDataFrame directly (e.g. for distance to ocean, you would provide the coastline as the feature geometry and the land geometry as the exclusion geometry, so that sites outside the land geometry — i.e. in the ocean — have a distance of 0).

__init__(epsg_projection, new_name, buffer=30000, clip_geometry=False, parallel=False, n_parallel_jobs=2)

Initialise the DistanceToFeature plugin.

Parameters:

• epsg_projection (int) – The EPSG code of the coordinate reference system on to which latitudes and longitudes will be projected to calculate distances. This is a projected coordinate system in which distances are measured in metres, for example, EPSG code 3035, which defines a Lambert Azimuthal Equal Areas projection suitable for the UK.

• new_name (str) – The name of the output cube. E.g. ‘distance_to_coast’.

• buffer (float) – A buffer distance in m. If the geometry is clipped, this distance will be added onto the outermost site locations to define the domain to clip the geometry to.

• clip_geometry (bool) – A flag to indicate whether the geometry should be clipped to the bounds of the site locations with a buffer distance added to the bounds. If set to False, the full geometry will be used to calculate the distance to the nearest feature.

• parallel (bool) – A flag to indicate whether to use parallel processing when calculating distances.

• n_parallel_jobs (Optional[int]) – The number of parallel jobs to use when calculating distances. By default, os.sched_getaffinity(0) is used to give the number of cores that the process is eligible to use.

_abc_impl = <_abc._abc_data object>

_apply_exclusion(site_coords, distance_results, exclude_outside_of, exclusion_buffer)

Apply exclusion geometry logic: set distances to 0 for sites outside of the provided geometry.

Parameters:

• site_coords (GeoSeries) – A GeoSeries containing the projected site coordinates.

• distance_results (List[int]) – The calculated distances to the feature.

• exclude_outside_of (GeoDataFrame) – A GeoDataFrame containing the geometry defining the valid region. Sites outside of this geometry will have their distance set to 0.

• exclusion_buffer (float) – A buffer distance in m used when clipping the exclusion geometry.

Return type:

List[int]

Returns:

The distance results with distances set to 0 for sites outside the exclusion geometry.

check_target_crs(site_points)

Check that the provided target projection is suitable for the sites being used.

Parameters:

site_points (GeoSeries) – A GeoSeries containing the site points.

Raises:

ValueError – If the provided target coordinate reference system is not suitable for the site points.

clip_geometry(geometry, bounds_x, bounds_y)

Clip the geometry to the provided bounds.

Parameters:

• geometry (GeoDataFrame) – The geometry to clip.

• bounds_x (List[float]) – A list containing the minimum and maximum x coordinates.

• bounds_y (List[float]) – A list containing the minimum and maximum y coordinates.

Return type:

GeoDataFrame

Returns:

The clipped geometry.

Raises:

• ValueError – If the clipped geometry is empty after clipping with the

• provided bounds. –

create_output_cube(site_cube, data)

Create an output cube that will have the same metadata as the input site cube except the units are changed to metres and, if requested, the name of the output cube will be changed.

Parameters:

• site_cube (Cube) – The input cube containing site locations that are defined by latitude and longitude coordinates.

• data (List[int]) – A list of distances from each site point to the nearest feature in the geometry.

• Returns – A new cube containing the distances with the same metadata as input site cube but with updated units and name.

Return type:

Cube

distance_to(site_points, geometry)

Calculate the distance from each site point to the nearest feature in the geometry.

Parameters:

• site_points (GeoSeries) – A GeoSeries containing the site points in the target projection.

• geometry (GeoDataFrame) – A GeoDataFrame containing the geometry in the target projection.

Return type:

List[int]

Returns:

A list of distances from each site point to the nearest feature in the geometry rounded to the nearest metre.

static get_clip_values(points, buffer)

Get the coordinates to use when clipping the geometry. This is determined by finding the maximum and minimum coordinate points from a list. A buffer distance may then be added/subtracted to the max/min.

Parameters:

• points (List[float]) – A list of points to find the min and max from.

• buffer (float) – The buffer distance to add/subtract to the max/min points.

Return type:

List[float]

Returns:

A list containing the maximum and minimum points with the buffer added or subtracted respectively.

process(site_cube, geometry, exclude_outside_of=None, exclusion_buffer=10)

Generate a cube of the distance from sites in site_cube to the nearest point in geometry.

The latitude, longitude coordinates in the site_cube are extracted to define the location of the sites. The sites and feature geometry are reprojected to the target projection.

If requested the feature geometry will be clipped to the smallest square possible such that all sites in site_cube are included. A buffer distance is then added to each edge of the square which defines the size the feature geometry will be clipped to. This is useful when the feature geometry size is large and it would be expensive to calculate the distance to all features in the geometry or where the domain of the feature geometry is much larger than the area containing the site locations. Information may be lost at the edges of the domain if the feature is sparsely located in the geometry.

The distance from each site to every point in the feature geometry is then calculated and the minimum of these distances is returned. The distances are rounded to the nearest metre.

If a geometry is provided, distances are set to 0 for sites outside that geometry.

The output cube will have the same metadata as the input site_cube except the units will be changed to meters and, if requested, the name of the output cube will be updated.

Parameters:

• site_cube (Cube) – The input cube containing site locations. This cube must have x and y axis which contain the site coordinates in latitude and longitude.

• geometry (GeoDataFrame) – The GeoDataFrame containing the geometry to calculate distances to.

• exclude_outside_of (Optional[GeoDataFrame]) – An optional GeoDataFrame containing the geometry defining the valid region. For sites outside this geometry, the distance to the feature will be set to 0. This is useful when the target region cannot be represented as a GeoDataFrame directly (e.g., providing land geometry so that ocean sites, which lie outside the land, receive a distance of 0).

• exclusion_buffer (Optional[float]) – A buffer distance in m used when clipping the optional geometry for performance. Default is 10m. Only used if exclude_outside_of is provided. This is independent of the clip_geometry / buffer settings, which apply only to clipping the feature geometry used for the initial distance calculation.

Return type:

Cube

Returns:

A new cube containing the distances from each site to the nearest feature in the geometry rounded to the nearest metre.

project_geometry(geometry, site_cube)

Project the geometry and site cube to the target projection.

Parameters:

• geometry (GeoDataFrame) – The geometry to reproject.

• site_cube (Cube) – The cube containing the site locations. It is assumed that the site coordinates are defined as latitude and longitude on a WGS84 coordinate system (EPSG:4326).

Return type:

Tuple[GeoSeries, GeoDataFrame]

Returns:

A tuple containing the projected site locations and geometry.

class DistanceToNearestFeature

Bases: BasePlugin

Plugin to calculate the distance to the closest feature from multiple distance cubes, intended to be used following the DistanceToFeature plugin. This is useful when you have distances to multiple features and want to find the minimum distance to any feature (e.g., creating a distance to water ancillary cube from distance to river, lake, and ocean) cubes.

This plugin does not support parallelisation unlike the DistanceToFeature plugin as the distance cubes provided to this plugin should already have been generated and therefore the computationally expensive distance calculation has already been performed.

_abc_impl = <_abc._abc_data object>

process(distance_to_features, new_name, ignored_coords_for_validation=None)

Calculate the distance to the closest feature from a CubeList of distance cubes. The distance to closest feature is the minimum of all the provided distance to feature cubes.

Example use case: if we want to generate a distance to water ancillary cube, we could use this function with distance to river, distance to lake, and distance to ocean cubes as the input. The output cube would then give the distance to the closest water feature for each site.

The first cube in distance_to_features is used as a template for the output metadata with the name updated to the provided new_name.

Parameters:

• distance_to_features (CubeList) – A CubeList containing distance to feature cubes from sites (e.g., distance to rivers, lakes, oceans, or any other features). Each cube should have the same set of sites defined.

• new_name (str) – The name to assign to the output cube. E.g. “distance_to_water” If None, then the name of the output cube will be set to the same name as the first cube in distance_to_features.

• ignored_coords_for_validation (Optional[List[str]]) – A list of coordinate names to ignore when validating that the cubes in distance_to_features have matching coordinates.

Return type:

Cube

Returns:

A cube containing the distance to closest feature ancillary data.

Raises:

• ValueError – If the input CubeList is empty.

• ValueError – If the cubes in the input CubeList have unmatched coordinates (other than those specified in ignored_coords_for_validation).