snkit package

snkit - a spatial networks toolkit

class snkit.Network(nodes: GeoDataFrame | None = None, edges: GeoDataFrame | None = None)

Bases: object

A Network is composed of nodes (points in space) and edges (lines)

Parameters:

• nodes (geopandas.geodataframe.GeoDataFrame, optional)

• edges (geopandas.geodataframe.GeoDataFrame, optional)

nodes

Type:

geopandas.geodataframe.GeoDataFrame

edges

Type:

geopandas.geodataframe.GeoDataFrame

set_crs(crs: CRS | None = None, epsg: int | None = None, allow_override: bool = False) → None

Set the coordinate reference system (CRS) of the network nodes and edges.

Parameters:

• crs (optional if epsg is specified) – The value can be anything accepted by pyproj.CRS.from_user_input(), such as an authority string (eg “EPSG:4326”) or a WKT string.

• epsg (optional if crs is specified) – EPSG code specifying output projection.

• allow_override (default False) – If the nodes or edges GeoDataFrame already has a CRS, allow to replace the existing CRS, even when both are not equal.

to_crs(crs: CRS | None = None, epsg: int | None = None) → None

Transform network nodes and edges geometries to a new coordinate reference system (CRS).

Parameters:

• crs (optional if epsg is specified) – The value can be anything accepted by pyproj.CRS.from_user_input(), such as an authority string (eg “EPSG:4326”) or a WKT string.

• epsg (optional if crs is specified) – EPSG code specifying output projection.

to_file(filename: str, nodes_layer: str | None = 'nodes', edges_layer: str | None = 'edges', **kwargs: Any) → None

Write nodes and edges to a geographic data file with layers.

Any additional keyword arguments are passed through to geopandas.GeoDataFrame.to_file.

Parameters:

• filename (str) – Path to geographic data file with layers

• nodes_layer (str, optional, default 'nodes') – Layer name for nodes.

• edges_layer (str, optional, default 'edges') – Layer name for edges.

Submodules

snkit.network module

Network representation and utilities

class snkit.network.Network(nodes: GeoDataFrame | None = None, edges: GeoDataFrame | None = None)

Bases: object

A Network is composed of nodes (points in space) and edges (lines)

Parameters:

• nodes (geopandas.geodataframe.GeoDataFrame, optional)

• edges (geopandas.geodataframe.GeoDataFrame, optional)

nodes

Type:

geopandas.geodataframe.GeoDataFrame

edges

Type:

geopandas.geodataframe.GeoDataFrame

set_crs(crs: CRS | None = None, epsg: int | None = None, allow_override: bool = False) → None

Set the coordinate reference system (CRS) of the network nodes and edges.

Parameters:

• crs (optional if epsg is specified) – The value can be anything accepted by pyproj.CRS.from_user_input(), such as an authority string (eg “EPSG:4326”) or a WKT string.

• epsg (optional if crs is specified) – EPSG code specifying output projection.

• allow_override (default False) – If the nodes or edges GeoDataFrame already has a CRS, allow to replace the existing CRS, even when both are not equal.

to_crs(crs: CRS | None = None, epsg: int | None = None) → None

Transform network nodes and edges geometries to a new coordinate reference system (CRS).

Parameters:

• crs (optional if epsg is specified) – The value can be anything accepted by pyproj.CRS.from_user_input(), such as an authority string (eg “EPSG:4326”) or a WKT string.

• epsg (optional if crs is specified) – EPSG code specifying output projection.

to_file(filename: str, nodes_layer: str | None = 'nodes', edges_layer: str | None = 'edges', **kwargs: Any) → None

Write nodes and edges to a geographic data file with layers.

Any additional keyword arguments are passed through to geopandas.GeoDataFrame.to_file.

Parameters:

• filename (str) – Path to geographic data file with layers

• nodes_layer (str, optional, default 'nodes') – Layer name for nodes.

• edges_layer (str, optional, default 'edges') – Layer name for edges.

snkit.network.add_component_ids(network: Network, id_col: str = 'component_id') → Network

Add column of connected component IDs to network edges and nodes

snkit.network.add_endpoints(network: Network) → Network

Add nodes at line endpoints

snkit.network.add_ids(network: Network, id_col: str | None = 'id', edge_prefix: str | None = 'edge', node_prefix: str | None = 'node') → Network

Add or replace an id column with ascending ids

snkit.network.add_topology(network: Network, id_col: str = 'id') → Network

Add or replace from_id, to_id to edges

snkit.network.add_vertex(line: LineString, point: Point) → LineString

Add a vertex to a line at a point

snkit.network.concat_dedup(dfs: List[DataFrame]) → GeoDataFrame

Concatenate a list of GeoDataFrames, dropping duplicate geometries - note: repeatedly drops indexes for deduplication to work

snkit.network.d_within(geom: Geometry, gdf: GeoDataFrame, distance: int | float) → GeoDataFrame

Find the subset of a GeoDataFrame within some distance of a shapely geometry

snkit.network.drop_duplicate_geometries(gdf: GeoDataFrame, keep: str | None = 'first') → GeoDataFrame

Drop duplicate geometries from a dataframe

snkit.network.edges_intersecting(line: LineString, edges: GeoDataFrame, tolerance: int | float | None = 1e-09) → GeoDataFrame

Find edges intersecting line

snkit.network.edges_intersecting_points(line: LineString, edges: GeoDataFrame, tolerance: int | float | None = 1e-09) → GeoDataFrame

Return intersection points of intersecting edges

snkit.network.edges_within(point: Point, edges: GeoDataFrame, distance: int | float) → GeoDataFrame

Find edges within a distance of point

snkit.network.geometry_column_name(gdf: GeoDataFrame) → str

Get geometry column name, fall back to ‘geometry’

snkit.network.geoms_to_array(geoms: List[Geometry]) → ArrayLike

snkit.network.get_connected_components(network: Network) → List[Set[Any]]

Get connected components within network and id to each individual graph

snkit.network.get_endpoints(network: Network) → GeoDataFrame

Get nodes for each edge endpoint

snkit.network.intersection_endpoints(geom: Geometry, output: List[Point] | None = None) → List[Point]

Return the points from an intersection geometry

It extracts the starting and ending points of intersection geometries recursively and appends them to output. This doesn’t handle polygons or collections of polygons.

snkit.network.intersects(geom: Geometry, gdf: GeoDataFrame, tolerance: int | float | None = 1e-09) → GeoDataFrame

Find the subset of a GeoDataFrame intersecting with a shapely geometry

snkit.network.line_endpoints(line: LineString) → Tuple[Point, Point]

Return points at first and last vertex of a line

snkit.network.link_nodes_to_edges_within(network: Network, distance: Number, condition: NodeEdgeCondition | None = None, tolerance: Number = 1e-09) → Network

Link nodes to all edges within some distance

snkit.network.link_nodes_to_nearest_edge(network: Network, condition: NodeEdgeCondition | None = None) → Network

Link nodes to all edges within some distance

snkit.network.matching_gdf_from_geoms(gdf: GeoDataFrame, geoms: List[Geometry]) → GeoDataFrame

Create a geometry-only GeoDataFrame with column name to match an existing GeoDataFrame

snkit.network.merge_edges(network: Network, id_col: str | None = 'id', by: List[str] | None = None) → Network

Merge edges that share a node with a connectivity degree of 2

Parameters:

• network (snkit.network.Network)

• id_col (string)

• by (List[string], optional) – list of columns to use when merging an edge path - will not merge if edges have different values.

snkit.network.merge_multilinestring(geom: Geometry) → Geometry

Merge a MultiLineString to LineString

snkit.network.nearest(geom: Geometry, gdf: GeoDataFrame) → pandas.Series[Any]

Find the element of a GeoDataFrame nearest a shapely geometry

snkit.network.nearest_edge(point: Point, edges: GeoDataFrame) → pandas.Series[Any]

Find nearest edge to a point

snkit.network.nearest_node(point: Point, nodes: GeoDataFrame) → pandas.Series[Any]

Find nearest node to a point

snkit.network.nearest_point_on_edges(point: Point, edges: GeoDataFrame) → Point

Find nearest point on edges to a point

snkit.network.nearest_point_on_line(point: Point, line: LineString) → Point

Return the nearest point on a line

snkit.network.nearest_vertex_idx_on_line(point: Point, line: LineString) → int

Return the index of nearest vertex to a point on a line

snkit.network.node_connectivity_degree(node: str, network: Network) → int

snkit.network.nodes_intersecting(line: LineString, nodes: GeoDataFrame, tolerance: int | float | None = 1e-09) → GeoDataFrame

Find nodes intersecting line

snkit.network.read_file(filename: str, nodes_layer: str | None = 'nodes', edges_layer: str | None = 'edges', **kwargs: Any) → Network

Read a geographic data file with layers containing nodes and edges.

Any additional keyword arguments are passed through to geopandas.read_file.

Parameters:

• filename – Path to geographic data file with layers

• nodes_layer (, optional, default 'nodes') – Layer name for nodes, or None if nodes should not be read.

• edges_layer (, optional, default 'edges') – Layer name for edges, or None if edges should not be read.

snkit.network.round_geometries(network: Network, precision: int = 3) → Network

Round coordinates of all node points and vertices of edge linestrings to some precision

snkit.network.set_precision(geom: Geometry, precision: int) → Geometry

Set geometry precision

snkit.network.snap_line(line: LineString, points: Point | MultiPoint, tolerance: int | float | None = 1e-09) → LineString

Snap a line to points within tolerance, inserting vertices as necessary

snkit.network.snap_nodes(network: Network, threshold: int | float | None = None) → Network

Move nodes (within threshold) to edges

snkit.network.split_edge_at_points(edge: GeoSeries, points: Point | MultiPoint, tolerance: int | float | None = 1e-09) → GeoDataFrame

Split edge at point/multipoint

snkit.network.split_edges_at_intersections(network: Network, tolerance: int | float | None = 1e-09) → Network

Split network edges where they intersect line geometries

snkit.network.split_edges_at_nodes(network: Network, tolerance: int | float = 1e-09, chunk_size: int | None = None) → Network

Split network edges where they intersect node geometries.

N.B. Can operate in parallel if SNKIT_PROCESSES is in the environment and a positive integer.

Parameters:

• network – Network object to split edges for.

• tolerance – Proximity within which nodes are said to intersect an edge.

• chunk_size – When splitting in parallel, set the number of edges per unit of work.

Returns:

Network with edges split at nodes (within proximity tolerance).

snkit.network.split_line(line: LineString, points: Point | MultiPoint, tolerance: int | float | None = 1e-09) → List[LineString]

Split line at point or multipoint, within some tolerance

snkit.network.split_multilinestrings(network: Network, merge_parts: bool = False) → Network

Create multiple edges from any MultiLineString edge

Ensures that edge geometries are all LineStrings, duplicates attributes over any created multi-edges.

Parameters:

merge_parts (default False) – Merge parts of geometries if they are connected, before splitting to multiple edges

snkit.network.to_igraph(network: Network, directed: bool = False, weight_col: str | None = None) → igraph.Graph

Return an igraph Graph representation of the network

Parameters:

• network (snkit.network.Network) – The network to convert

• directed (bool, optional) – If True, create a directed graph. Default is False (undirected)

• weight_col (str, optional) – Column name to use for edge weights. If None, uses geometry length.

Returns:

An igraph Graph object with nodes and edges from the network

Return type:

igraph.Graph

Raises:

ImportError – If igraph is not installed

snkit.network.to_networkx(network: Network, directed: bool = False, weight_col: str | None = None) → Graph | DiGraph

Return a networkx graph

snkit.utils module

Generic utilities

snkit.utils.tqdm_standin(iterator: Iterator[Any], *_: Any, **__: Any) → Iterator[Any]

Alternative to tqdm, with no progress bar - ignore any arguments after the first