improver.generate_ancillaries.generate_distance_to_feature module

A module for generating a distance to feature ancillary cube.

class DistanceTo(epsg_projection, new_name=None, buffer=30000, clip_geometry_flag=False, parallel=False, n_parallel_jobs=2)

Bases: BasePlugin

Plugin to calculate the distance to the nearest feature in a geometry from sites 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 orography 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.

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

Initialise the DistanceTo 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 (Optional[str]) – The name of the output cube.

• 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_flag (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>

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)

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.

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.

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.