# Network Functions
A group of network-related functions used for geospatial analysis.
## Modules
### `functions` (also accessed as pure `network_functions`)
#### `inject_crossing`
```
inject_crossing(Graph: nx.MultiDiGraph, G: nx.MultiDiGraph, alternatives: gpd.GeoDataFrame,
crossing, typedict={'normal': 1.0, 'bridge': 1.25, 'tunnel': 1.15}) -> list
```
Inject the new alternative into the graph
Inputs:
- Graph (nx.MultiDiGraph): The parent graph, which should *not* be modified
- G (nx.MultiDiGraph): The child graph, which will be modified to produce the new graph
- alternatives (gpd.GeoDataFrame): Shapefiles of alternative crossings
- crossing (str): The name of the crossing, extracted from alternatives['name']
- typedict (dict): Dictionary of scaling factor for elevated or submerged segments
Outputs:
- endpoint_ids (list): The list of the node ids of the two new endpoints of the injected segment
#### `path_dijkstra`
```
path_dijkstra(origins: int | list | np.ndarray, destinations: int | list, G: nx.MultiDiGraph = None,
nodes: gpd.GeoDataFrame = None, edges: gpd.GeoDataFrame = None, *, dist_param: str = 'length',
origins_in_nodes: bool = False, destinations_in_nodes: bool = False, pairs: bool = False,
verbose: bool = True) -> tuple[dict[tuple:float], dict[tuple:list]]
```
An data-structure optimized algorithm for computing shortest paths between sets of points. Utilizes
compressed sparse row (CSR) matricies for efficient adjacent-node searching across the graph.
Can compute between one origin and one destination, many origins and one destination, one origin
and many destinations, or many origins and many destinations, which will compute pairwise if `pairs`
is specified, and every possible combination otherwise. Note that unreachable paths will have a distance
of 'inf' and a path list of length 1 (the origin node only).
Parameters:
origins: int | list | np.ndarray
- The origin points to be used. Can be a point, list of points, or array of points (like pd.Series).
If `origins_in_nodes` is `True`, this must be a node or list/array of nodes in `G` (by OSMID)
destinations: int | list
- The destination points to be used. Can be a point, list of points, or array of points (like pd.Series).
If `destinations_in_nodes` is `True`, this must be a node or list/array of nodes in `G` (by OSMID)
G: nx.MultiDiGraph = None
- The graph to be used in the calculation. If left as None, both a `nodes` GeoDataFrame and an
`edges` GeoDataFrame must be passed in. The function expects that G is well-connected; if
not, it will not find paths and throw an error. This can be fixed beforehand with
`nx.connected_components()`.
nodes: gpd.GeoDataFrame = None
- If a graph is not passed, the nodes to be used in the construction of the graph. The call
relies on `ox.graph_from_gdfs`, so it must be indexed by `osmid`.
edges: gpd.GeoDataFrame = None
- If a graph is not passed, the edges to be used in the construction of the graph. The call
relies on `ox.graph_from_gdfs`, so it must be indexed by `u`, `v`, and `key`.
dist_param: str = 'length'
- The distance parameter to be used for computing distance. Defaults to `length` (natively
in OSM). Useful if passing uniquely weighted edges. Must be one of the edge attributes.
origins_in_nodes: bool = False
- Whether or not the origins list is in `G.nodes()`. If True, the origins list must be a list
of `osmid`'s in `G`. Otherwise, the origins list needs to be a list of geometries.
destinations_in_nodes: bool = False
- Whether or not the destinations list is in `G.nodes()`. If True, the destinations list must
be a list of `osmid`'s in `G`. Otherwise, the destinations list needs to be list of
geometries.
pairs: bool = False
- Whether the origins and destinations should be interpreted as OD pairs. Will perform single
routings between each pair
verbose: bool = True
- If passing multiorigin/multidestination, will add a `tqdm` wrapper and verbosity to the calculations,
so the user can get a sense of how long it will take to run.
Outputs:
- A Dictionary of points and the distances to or from them (in the multiple -> multiple case,
every combination of Origin/Destination)
- A list of nodes forming the paths between each (o, d) pair being analyzed.
#### `geomerge`
```
geomerge(df: gpd.GeoDataFrame, field: str, base_osm: gpd.GeoDataFrame,
*, name: str = None, categories: list = None, road_id: str = None,
area: gpd.GeoDataFrame | gpd.GeoSeries = None, type_join: str = 'range',
buffer_ft: float = 10, n_samples: int = 10, threshold: float = 0.85,
crs_ft: str = "EPSG:2236", verbose: bool = False,
) -> gpd.GeoDataFrame
```
Approximate the n%-overlap of `df` with `base_osm` via interpolated point-sampling along each
OSM segment. $n$ is set by `threshold`. Note that n_samples does not include the two endpoints,
so $n$% is mathematically $\lceil t\times\text{n samples} \rceil / (\text{n samples} + 2)$. Any
values computed as `NaN` will be imputed as -1, for convenience.
Parameters
- df: gpd.GeoDataFrame
Vendor GeoDataFrame containing the attribute `field`. This will be merged
*onto* `base_osm`.
- field: str
column in df with the raw attribute values to be merged onto `base_osm`.
- base_osm: gpd.GeoDataFrame
OSM road GeoDataFrame. Output will have the same geometry and attributes.
- name: str
name of the new categorical column to add. If not passed, will be inferred
from the `field` parameter.
- categories: list
list of thresholds (for "range") or exact values (for "exact"). If `categories`
is not passed, it will be inferred as a linspace or a logspace (if `mean >= 3x median`).
- road_id: str
column in `base_osm` GeoFrames that uniquely identifies roads. If not passed, will
default to a new column set as the index of `base_osm`.
- area: gpd.GeoDataFrame | gpd.GeoSeries
polygon boundary of the study area. If not passed, defaults to a the minimum
bounding rectangle of `df`.
- type_join: str
"range" ⇒ bin by intervals; "exact" ⇒ only keep exact matches. Defaults to `range`
- buffer_ft: float
distance to buffer each line/point by to find its match. Defaults to 10 of CRS unit
- n_samples: int
number of points to interpolate along each segment. Defaults to 10 (meaning 12 total)
- threshold: float
percentage threshold used to "match" segments. Defaults to 0.85 (85%)
- crs_ft: str
projected CRS in feet for geometry ops. Defaults to `EPSG:2236` (Florida)
- verbose: bool
Whether to show print statements and progress bars. Default is False
Returns
- GeoDataFrame in the CRS of base_osm with the extra column `name`.
#### `compute_area_access`
```
compute_area_access(G: nx.MultiDiGraph, endpoints: LineString | Point, *,
return_nodes: bool = False, return_edges: bool = False,
return_graph: bool = False, step: int | float = 1609,
n_steps: int = 4, dist_param: str = 'length',
etwork_type: str = 'all', edge_exclusions: dict = None)
-> gpd.GeoDataFrame | nx.MultiDiGraph
```
A function to compute consecutive ego graphs. It computes n ego graphs at each step to create a GeoDataFrame of edges in the access area with a new dist calculation classifying each edge into a 'distance band'. Useful for visualizations and is less complicated than `path_dijkstra`.
Parameters:
G: nx.MultiDiGraph
The graph to be used for computation.
endpoints: LineString, MultiLineString, Point, MultiPoint
The points to be used for centering the ego graphs.
return_nodes: bool
Whether the function should return a nodes GeoDataFrame. Default is False.
return_edges: bool
Whether the function should return an edges GeoDataFrame. Default is False.
return_graph: bool
Whether the function should return a graph. Default is False. Exactly *one* of the returns must be true.
step: int, float
The size of the distance steps the output will contain, in meters. Default is set at 1 mile (1609 meters).
n_steps: int
The number of distance steps the function will check.
dist_param: str
The attribute in the graph's edges that will be used to compute distance. The function will raise a ValueError
if it is not a valid attribute.
network_type: str - {"all", "all_public", "bike", "drive", "drive_service", "walk"}
The network type to compute the distances on. Passing an invalid type will default to "all".
edge_exclusions: dict
A dictionary of the form {_field_: str | list}; exclude edge values in _field_ attribute
Outputs:
output: geopandas.GeoDataFrame, nx.MultiDiGraph
Either the resulting graph, the nodes of the resulting graph, or the edges of the resulting graph, based on the user's inputs
### `classifiers`
#### `fill_holes_and_dissolve`
```
fill_holes_and_dissolve(geom)
```
Remove every interior ring, then dissolve overlaps.
• Polygon → Polygon without holes
• MultiPolygon → each part without holes, then unioned into a single valid geometry (islands kept)
#### `classify_node`
```
classify_node(G, n)
```
Return number of edges in and out of each node.
#### `find_bridges`
```
find_bridges(G, max_len_ft=100)
```
Find bridges between two sides of a dual carriageway, topologically
#### `find_res_links` (DEPRECATED)
```
find_res_links(G, max_len_ft=300)
```
Currently in use to find misclassified slip lanes, but needs future modification. Avoid usage.
#### `collapse_one_in_one_out`
```
collapse_one_in_one_out(G)
```
Collapses nodes with only one edge in and one edge out. Similar to `ox.simplify_graph`, but less greedy.
Raw data
{
"_id": null,
"home_page": null,
"name": "network-functions",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "graphs, networkx, shortest path, csr, transportation, geospatial",
"author": "Luca Butera",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/63/69/d37b7871462a19c00832ec41db0c8d31275934a8f81a8ca3b64d2a6ed4d4/network_functions-0.1.5.tar.gz",
"platform": null,
"description": "# Network Functions\nA group of network-related functions used for geospatial analysis.\n\n## Modules\n\n### `functions` (also accessed as pure `network_functions`)\n\n#### `inject_crossing`\n```\ninject_crossing(Graph: nx.MultiDiGraph, G: nx.MultiDiGraph, alternatives: gpd.GeoDataFrame, \n crossing, typedict={'normal': 1.0, 'bridge': 1.25, 'tunnel': 1.15}) -> list\n```\n\nInject the new alternative into the graph\n\nInputs:\n- Graph (nx.MultiDiGraph): The parent graph, which should *not* be modified\n- G (nx.MultiDiGraph): The child graph, which will be modified to produce the new graph\n- alternatives (gpd.GeoDataFrame): Shapefiles of alternative crossings\n- crossing (str): The name of the crossing, extracted from alternatives['name']\n- typedict (dict): Dictionary of scaling factor for elevated or submerged segments\n\nOutputs:\n- endpoint_ids (list): The list of the node ids of the two new endpoints of the injected segment\n\n#### `path_dijkstra`\n\n```\npath_dijkstra(origins: int | list | np.ndarray, destinations: int | list, G: nx.MultiDiGraph = None,\n nodes: gpd.GeoDataFrame = None, edges: gpd.GeoDataFrame = None, *, dist_param: str = 'length',\n origins_in_nodes: bool = False, destinations_in_nodes: bool = False, pairs: bool = False,\n verbose: bool = True) -> tuple[dict[tuple:float], dict[tuple:list]]\n```\n \n An data-structure optimized algorithm for computing shortest paths between sets of points. Utilizes\n compressed sparse row (CSR) matricies for efficient adjacent-node searching across the graph. \n Can compute between one origin and one destination, many origins and one destination, one origin\n and many destinations, or many origins and many destinations, which will compute pairwise if `pairs`\n is specified, and every possible combination otherwise. Note that unreachable paths will have a distance\n of 'inf' and a path list of length 1 (the origin node only).\n\n Parameters:\n\n origins: int | list | np.ndarray\n - The origin points to be used. Can be a point, list of points, or array of points (like pd.Series). \n If `origins_in_nodes` is `True`, this must be a node or list/array of nodes in `G` (by OSMID)\n\n destinations: int | list\n - The destination points to be used. Can be a point, list of points, or array of points (like pd.Series). \n If `destinations_in_nodes` is `True`, this must be a node or list/array of nodes in `G` (by OSMID)\n\n G: nx.MultiDiGraph = None\n - The graph to be used in the calculation. If left as None, both a `nodes` GeoDataFrame and an \n `edges` GeoDataFrame must be passed in. The function expects that G is well-connected; if\n not, it will not find paths and throw an error. This can be fixed beforehand with\n `nx.connected_components()`. \n\n nodes: gpd.GeoDataFrame = None\n - If a graph is not passed, the nodes to be used in the construction of the graph. The call \n relies on `ox.graph_from_gdfs`, so it must be indexed by `osmid`.\n\n edges: gpd.GeoDataFrame = None\n - If a graph is not passed, the edges to be used in the construction of the graph. The call \n relies on `ox.graph_from_gdfs`, so it must be indexed by `u`, `v`, and `key`.\n\n dist_param: str = 'length'\n - The distance parameter to be used for computing distance. Defaults to `length` (natively\n in OSM). Useful if passing uniquely weighted edges. Must be one of the edge attributes.\n\n origins_in_nodes: bool = False\n - Whether or not the origins list is in `G.nodes()`. If True, the origins list must be a list\n of `osmid`'s in `G`. Otherwise, the origins list needs to be a list of geometries.\n\n destinations_in_nodes: bool = False\n - Whether or not the destinations list is in `G.nodes()`. If True, the destinations list must \n be a list of `osmid`'s in `G`. Otherwise, the destinations list needs to be list of \n geometries.\n\n pairs: bool = False\n - Whether the origins and destinations should be interpreted as OD pairs. Will perform single \n routings between each pair\n\n verbose: bool = True\n - If passing multiorigin/multidestination, will add a `tqdm` wrapper and verbosity to the calculations,\n so the user can get a sense of how long it will take to run.\n\n Outputs:\n - A Dictionary of points and the distances to or from them (in the multiple -> multiple case, \n every combination of Origin/Destination)\n\n - A list of nodes forming the paths between each (o, d) pair being analyzed.\n\n#### `geomerge`\n\n```\ngeomerge(df: gpd.GeoDataFrame, field: str, base_osm: gpd.GeoDataFrame,\n *, name: str = None, categories: list = None, road_id: str = None,\n area: gpd.GeoDataFrame | gpd.GeoSeries = None, type_join: str = 'range',\n buffer_ft: float = 10, n_samples: int = 10, threshold: float = 0.85,\n crs_ft: str = \"EPSG:2236\", verbose: bool = False,\n ) -> gpd.GeoDataFrame\n```\n\nApproximate the n%-overlap of `df` with `base_osm` via interpolated point-sampling along each \n OSM segment. $n$ is set by `threshold`. Note that n_samples does not include the two endpoints,\n so $n$% is mathematically $\\lceil t\\times\\text{n samples} \\rceil / (\\text{n samples} + 2)$. Any\n values computed as `NaN` will be imputed as -1, for convenience.\n Parameters\n - df: gpd.GeoDataFrame\n Vendor GeoDataFrame containing the attribute `field`. This will be merged \n *onto* `base_osm`.\n - field: str\n column in df with the raw attribute values to be merged onto `base_osm`.\n - base_osm: gpd.GeoDataFrame\n OSM road GeoDataFrame. Output will have the same geometry and attributes.\n - name: str \n name of the new categorical column to add. If not passed, will be inferred\n from the `field` parameter.\n - categories: list\n list of thresholds (for \"range\") or exact values (for \"exact\"). If `categories`\n is not passed, it will be inferred as a linspace or a logspace (if `mean >= 3x median`).\n - road_id: str\n column in `base_osm` GeoFrames that uniquely identifies roads. If not passed, will\n default to a new column set as the index of `base_osm`. \n - area: gpd.GeoDataFrame | gpd.GeoSeries\n polygon boundary of the study area. If not passed, defaults to a the minimum\n bounding rectangle of `df`.\n - type_join: str\n \"range\" \u21d2 bin by intervals; \"exact\" \u21d2 only keep exact matches. Defaults to `range`\n - buffer_ft: float\n distance to buffer each line/point by to find its match. Defaults to 10 of CRS unit\n - n_samples: int\n number of points to interpolate along each segment. Defaults to 10 (meaning 12 total)\n - threshold: float\n percentage threshold used to \"match\" segments. Defaults to 0.85 (85%)\n - crs_ft: str\n projected CRS in feet for geometry ops. Defaults to `EPSG:2236` (Florida)\n - verbose: bool\n Whether to show print statements and progress bars. Default is False\n Returns\n - GeoDataFrame in the CRS of base_osm with the extra column `name`.\n\n#### `compute_area_access`\n\n```\ncompute_area_access(G: nx.MultiDiGraph, endpoints: LineString | Point, *, \n return_nodes: bool = False, return_edges: bool = False,\n return_graph: bool = False, step: int | float = 1609, \n n_steps: int = 4, dist_param: str = 'length',\n etwork_type: str = 'all', edge_exclusions: dict = None) \n -> gpd.GeoDataFrame | nx.MultiDiGraph\n```\n\nA function to compute consecutive ego graphs. It computes n ego graphs at each step to create a GeoDataFrame of edges in the access area with a new dist calculation classifying each edge into a 'distance band'. Useful for visualizations and is less complicated than `path_dijkstra`.\n\nParameters:\n G: nx.MultiDiGraph\n The graph to be used for computation.\n endpoints: LineString, MultiLineString, Point, MultiPoint\n The points to be used for centering the ego graphs.\n return_nodes: bool\n Whether the function should return a nodes GeoDataFrame. Default is False.\n return_edges: bool\n Whether the function should return an edges GeoDataFrame. Default is False.\n return_graph: bool\n Whether the function should return a graph. Default is False. Exactly *one* of the returns must be true. \n step: int, float\n The size of the distance steps the output will contain, in meters. Default is set at 1 mile (1609 meters).\n n_steps: int\n The number of distance steps the function will check. \n dist_param: str\n The attribute in the graph's edges that will be used to compute distance. The function will raise a ValueError \n if it is not a valid attribute.\n network_type: str - {\"all\", \"all_public\", \"bike\", \"drive\", \"drive_service\", \"walk\"} \n The network type to compute the distances on. Passing an invalid type will default to \"all\".\n edge_exclusions: dict\n A dictionary of the form {_field_: str | list}; exclude edge values in _field_ attribute\nOutputs:\n output: geopandas.GeoDataFrame, nx.MultiDiGraph\n Either the resulting graph, the nodes of the resulting graph, or the edges of the resulting graph, based on the user's inputs\n\n\n\n### `classifiers`\n\n#### `fill_holes_and_dissolve`\n\n```\nfill_holes_and_dissolve(geom)\n```\n\nRemove every interior ring, then dissolve overlaps.\n \u2022 Polygon \u2192 Polygon without holes\n \u2022 MultiPolygon \u2192 each part without holes, then unioned into a single valid geometry (islands kept)\n\n#### `classify_node`\n\n```\nclassify_node(G, n)\n```\nReturn number of edges in and out of each node.\n\n#### `find_bridges`\n\n```\nfind_bridges(G, max_len_ft=100)\n```\nFind bridges between two sides of a dual carriageway, topologically\n\n#### `find_res_links` (DEPRECATED)\n\n```\nfind_res_links(G, max_len_ft=300)\n```\nCurrently in use to find misclassified slip lanes, but needs future modification. Avoid usage.\n\n#### `collapse_one_in_one_out`\n\n```\ncollapse_one_in_one_out(G)\n```\nCollapses nodes with only one edge in and one edge out. Similar to `ox.simplify_graph`, but less greedy.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Highly optimized and aggregated network functions",
"version": "0.1.5",
"project_urls": null,
"split_keywords": [
"graphs",
" networkx",
" shortest path",
" csr",
" transportation",
" geospatial"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b05e00ba1c98384c1ef11bcfa1511ee5abccc054e00ceed0c3a20e215f275dbc",
"md5": "e4a15f73d443782226fc76ca899bd824",
"sha256": "7779f6423090a39f1d29540bd5bf21cb2affb9e8c26b6ad3b77b5edba25b5558"
},
"downloads": -1,
"filename": "network_functions-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e4a15f73d443782226fc76ca899bd824",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 19534,
"upload_time": "2025-08-23T06:48:06",
"upload_time_iso_8601": "2025-08-23T06:48:06.371931Z",
"url": "https://files.pythonhosted.org/packages/b0/5e/00ba1c98384c1ef11bcfa1511ee5abccc054e00ceed0c3a20e215f275dbc/network_functions-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6369d37b7871462a19c00832ec41db0c8d31275934a8f81a8ca3b64d2a6ed4d4",
"md5": "b419fcb2877fed93fc302692c0ff5745",
"sha256": "ce5268800dd453b27a098e827ad76d73bfda928a79aa2adddca5ef45e411848c"
},
"downloads": -1,
"filename": "network_functions-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "b419fcb2877fed93fc302692c0ff5745",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 22657,
"upload_time": "2025-08-23T06:48:07",
"upload_time_iso_8601": "2025-08-23T06:48:07.417429Z",
"url": "https://files.pythonhosted.org/packages/63/69/d37b7871462a19c00832ec41db0c8d31275934a8f81a8ca3b64d2a6ed4d4/network_functions-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-23 06:48:07",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "network-functions"
}
JSON