revrt.routing.utilities.PointToFeatureMapper#

class PointToFeatureMapper(crs, features_fp, regions=None, region_identifier_column='rid', connection_identifier_column='end_feat_id', batch_size=500, max_workers=None)[source]#

Bases: object

Map points to features within specified regions and/or radii

Parameters:

  • crs (str or pyproj.crs.CRS) – Coordinate reference system to use for all spatial data.

  • features_fp (path-like) – File path to transmission features to map points to.

  • regions (geopandas.GeoDataFrame or path-like, optional) – Regions to use for clipping features around points. Features will not extend beyond these regions, and point will only map to features within their own region. This input can be paired with the radius parameter (e.g. to forbid any connections to cross state boundaries, even if that connection would be shorter than some desired length). At least one of regions or radius must be provided; otherwise, an error is raised. By default, None.

  • region_identifier_column (str, default "rid") – Column in regions data to use as the identifier for that region. If not given, a simple index will be put under the rid column. By default, "rid".

  • connection_identifier_column (str, optional) – Column in output data (both features and points) that will be used to link the points to the features that should be routed to. By default, "end_feat_id".

  • batch_size (int, default 500) – Number of points to process in each batch when writing clipped features to file. By default, 500.

  • max_workers (int, optional) – Number of parallel workers to use for point-to-feature clipping. If None or >1, clipping is performed in parallel using Dask’s process scheduler. By default, None, which uses all CPU cores.

Methods

map_points(points, feature_out_fp[, ...])

Map points to features within the point region
map_points(points, feature_out_fp, route_table_out_fp=None, radius=None, expand_radius=True, clip_points_to_regions=False, voltages=None, polarities=None)[source]#

Map points to features within the point region

Parameters:

  • points (geopandas.GeoDataFrame) – Points to map to features.

  • feature_out_fp (path-like) – File path to save clipped features to. This should end in ‘.gpkg’ to ensure proper format. If not, the extension will be added automatically. This file will contain all features clipped to each point (with a feature ID column added to link back to the points).

  • route_table_out_fp (path-like, optional) – Optional file path to incrementally persist mapped point assignments. If the route table and feature outputs already exist, the mapper resumes from the previously completed points. By default, None.

  • radius (float or str, optional) – Radius (in CRS units) around each point to clip features to. If str, the column in points to use for radius values. If None, only regions are used for clipping. By default, None.

  • expand_radius (bool, optional) – If True, the radius is expanded until at least one feature is found. By default, True.

  • clip_points_to_regions (bool, default False) – If True, points are clipped to the given regions before mapping to features. If the regions input is not set, this parameter has no effect. If False, all points are used as-is, which means points outside of the regions domain are mapped to the closest region. By default, False.

  • voltages (dict of list of str or int, optional) – Voltage values to assign to the output route table, keyed by routing option. If provided, each mapped point-to-feature connection is duplicated once per per-option voltage combination and explicit voltage_<option> columns are added for each configured routing option. By default, None.

  • polarities (dict of list of str, optional) – Polarity values to assign to the output route table, keyed by routing option. If provided, each mapped point-to-feature connection is duplicated once per per-option polarity combination and explicit polarity_<option> columns are added for each configured routing option. By default, None.

Returns:

geopandas.GeoDataFrame – Input points with added column giving mapped feature IDs.