Main classes¶

GeoGraph¶

class GeoGraph(incoming_graph_data=None, **attr)[source]¶

Bases: networkx.classes.graph.Graph

This class extends the networkx.Graph to represent a graph that have a geographical meaning. Nodes are located with their coordinates (x, y) (using shapely.geometry.Point objects) and edges can be represented with a given broken line (using shapely.geometry.LineString objects). Each graph has its own keys for naming nodes and edges geometry (nodes_geometry_key, edges_geometry_key). A coordinate reference system (CRS) can be defined for a graph and will be used for some methods managing earth coordinates (especially for distances). All nodes must have defined coordinates, otherwise a default coordinates are used.

Raises: ValueError – If the all nodes don’t have valid coordinates.

See also

networkx.Graph, GeoDiGraph, GeoMultiGraph, GeoMultiDiGraph

Initialize a graph with edges, name, or graph attributes.

Parameters

incoming_graph_data (input graph (optional, default: None)) – Data to initialize graph. If None (default) an empty graph is created. The data can be an edge list, or any NetworkX graph object. If the corresponding optional Python packages are installed the data can also be a NumPy matrix or 2d ndarray, a SciPy sparse matrix, or a PyGraphviz graph.
attr (keyword arguments, optional (default= no attributes)) – Attributes to add to graph as key=value pairs.

See also

convert

Examples

>>> G = nx.Graph()  # or DiGraph, MultiGraph, MultiDiGraph, etc
>>> G = nx.Graph(name='my graph')
>>> e = [(1, 2), (2, 3), (3, 4)]  # list of edges
>>> G = nx.Graph(e)

Arbitrary graph attribute pairs (key=value) may be assigned

>>> G = nx.Graph(e, day="Friday")
>>> G.graph
{'day': 'Friday'}

_get_nodes_geometries_from_edge_geometry(u, v, geometry)[source]¶: For each node of the edge, return the node geometry deduced from the linestring if it not already present.

_get_nodes_geometries_to_set_for_edges_adding(ebunch_to_add, attr)[source]¶: Return a dictionary of nodes geometries to set when adding a set of edges.

add_edge(u_of_edge, v_of_edge, **attr)[source]¶

Add an edge between u and v.

If one of the node is not already in the graph and a geometry is provided, the node geometry is deduced from the first or last point of the linestring.

Examples

>>> import geonetworkx as gnx
>>> g = gnx.GeoGraph()
>>> g.add_edge(1, 2, geometry=gnx.LineString([(0, 0), (1, 1)]))
>>> print(g.nodes[2]["geometry"])
POINT (1 1)

add_edges_from(ebunch_to_add, **attr)[source]¶

Add all the edges in ebunch_to_add and add nodes geometry if they are not present.

If one of the node is not already in the graph and a geometry is provided, the node geometry is deduced from the first or last point of the linestring.

Examples

>>> import geonetworkx as gnx
>>> g = gnx.GeoGraph()
>>> g.add_edges_from([(0, 1, dict(geometry=gnx.LineString([(0, 0), (1, 1)]))),
...                  (1, 2, dict(geometry=gnx.LineString([(1, 1), (2, 2)])))])
>>> print(g.nodes[2]["geometry"])
POINT (2 2)

>>> g = gnx.GeoMultiGraph()
>>> g.add_edges_from([(0, 1, 7, dict(geometry=gnx.LineString([(-1, 0), (1, 1)]))),
...                   (1, 2, 8, dict(geometry=gnx.LineString([(1, 1), (2, 2)])))])
[7, 8]
>>> print(g.nodes[1]["geometry"])
POINT (1 1)

See also

add_edge, nx.Graph.add_edges_from

add_edges_from_gdf(gdf, edge_first_node_attr=None, edge_second_node_attr=None)[source]¶

Add edges with the given GeoDataFrame. If no dataframe columns are specified for first and second node, the dataframe index must be a multi-index (u, v).

Parameters

gdf – GeoDataFrame representing edges to add (one row for one edge).
edge_first_node_attr – Edge first node attribute. If None, the dataframe index is used, else the given column is used. Must be used with edge_second_node_attr. (Default value = None)
edge_second_node_attr – Edge second node attribute. If None, the dataframe index is used, else the given column is used. Must be used with edge_first_node_attr. (Default value = None)

See also

add_nodes_from_gdf

add_node(node_for_adding, geometry=None, **attr)[source]¶

Add a single node node_for_adding with its given geometry.

See also

nx.Graph.add_node

Examples

>>> import geonetworkx as gnx
>>> g = gnx.GeoGraph()
>>> g.add_node(1, gnx.Point(2, 3))
>>> print(g.nodes[1]["geometry"])
POINT (2 3)

add_nodes_from(nodes_for_adding, **attr)[source]¶

Add multiple nodes with potentially given geometries.

If no geometry is provided, behaviour is same as the nx.Graph.add_nodes_from method.

See also

nx.Graph.add_nodes_from

Examples

>>> import geonetworkx as gnx
>>> g = gnx.GeoGraph()
>>> g.add_nodes_from([(1, gnx.Point(1, 1)),
...                   (2, gnx.Point(2, 1)),
...                   (3, gnx.Point(3, 1))])
>>> print(g.nodes[2]["geometry"])
POINT (2 1)

add_nodes_from_gdf(gdf, node_index_attr=None)[source]¶

Add nodes with the given GeoDataFrame and fill nodes attributes with the geodataframe columns.

Parameters

gdf – GeoDataFrame representing nodes to add (one row for one node).
node_index_attr – Node index attribute for labeling nodes. If None, the dataframe index is used, else the given column is used. (Default value = None)

See also

add_edges_from_gdf

check_nodes_validity()[source]¶: Check that all nodes have geometries.

copy(as_view=False)[source]¶: Return a copy of the graph (see networkx.Graph.copy).

property crs¶: Coordinate Reference System of the graph. This graph attribute appears in the attribute dict G.graph keyed by the string "crs" as well as an attribute G.crs

property edges_geometry_key¶: Attribute name for the edges geometry attributes. This graph attribute appears in the attribute dict G.graph keyed by the string "edges_geometry_key" as well as an attribute G.edges_geometry_key

edges_to_gdf()[source]¶

Create a gpd.GeoDataFrame from edges of the current graph. The column representing the geometry is named after the current edges_geometry_key attribute.

Returns: gdf_edges – The resulting GeoDataFrame : one row is an edge
Return type: geopandas.GeoDataFrame

Return type: GeoDataFrame

get_default_node_dict()[source]¶: Return the default node attribute dictionary.

get_edges_as_line_series()[source]¶

Return the edges as a geopandas.GeoSeries of shapely.geometry.LineString.

Returns: Series containing all edges geometries. Its CRS is the graph CRS.
Return type: gpd.GeoSeries

Return type: GeoSeries

get_node_as_point(node_name)[source]¶

Return a node as a shapely.geometry.Point object.

Parameters: node_name – Name of the node on which the geometry is browsed.
Returns: The point representing the located node.
Return type: shapely.geometry.Point

get_node_coordinates(node_name)[source]¶

Return the coordinates of the given node.

Parameters: node_name – Name of the node on which the coordinates are browsed.
Returns: A two-element list containing (x,y) coordinates of the given node.
Return type: list

Return type: list

get_nodes_as_multipoint()[source]¶

Return nodes geometries as a shapely.geometry.MultiPoint.

Returns: MutltiPoint containing all nodes geometries.
Return type: MultiPoint
Return type: MultiPoint

get_nodes_as_point_series()[source]¶

Return the nodes as a geopandas.GeoSeries of shapely.geometry.Point.

Returns: Series containing all nodes geometries. Its CRS is the graph CRS.
Return type: gpd.GeoSeries

Return type: GeoSeries

get_nodes_as_points()[source]¶

Return all nodes as shapely.geometry.Point objects within a dictionary.

Returns: Dictionary containing the geometry of each node of the graph.
Return type: dict

Return type: dict

get_nodes_coordinates()[source]¶

Return all nodes coordinates within a dictionary.

Returns: Dictionary containing the coordinates of the each node of the graph.
Return type: dict

Return type: dict

get_spatial_keys()[source]¶

Return the current graph spatial keys.

Returns: Dictionary containing spatial keys (nodes and edges geometry keys and crs).
Return type: dict
Return type: dict

node_attr_dict_check(attr)[source]¶: Check that the given attribute dictionary contains mandatory fields for a node.

property nodes_geometry_key¶: Attribute name for the edges geometry attributes. This graph attribute appears in the attribute dict G.graph keyed by the string "edges_geometry_key" as well as an attribute G.nodes_geometry_key

nodes_to_gdf()[source]¶

Create a geopandas.GeoDataFrame from nodes of the current graph. The column representing the geometry is named after the current nodes_geometry_key attribute.

Returns: The resulting GeoDataFrame : one row is a node
Return type: gpd.GeoDataFrame

Return type: GeoDataFrame

set_nodes_coordinates(coordinates)[source]¶

Set nodes coordinates with a given dictionary of coordinates (can be used for a subset of all nodes).

Parameters: coordinates (dict :) – Dictionary mapping node names and two-element list of coordinates.

to_crs(crs=None, epsg=None, inplace=False)[source]¶

Transform nodes and edges geometries to a new coordinate reference system.

Parameters

crs (dict or str) – Output projection parameters as string or in dictionary form (Default value = None).
epsg (int) – EPSG code specifying output projection.
inplace (bool) – If True, the modification is done inplace, otherwise a new graph is created (Default value = False).

Returns

Nothing is returned if the transformation is inplace, a new GeoGraph is returned otherwise.

Return type

None or GeoGraph

See also

geopandas.GeoSeries.to_crs

to_directed(as_view=False)[source]¶: Return a directed representation of the graph (see networkx.Graph.to_directed).

to_directed_class()[source]¶: Returns the class to use for empty directed copies (see networkx.Graph.to_directed_class).

to_nx_class()[source]¶: Return the closest networkx class (in the inheritance graph).

to_undirected(as_view=False)[source]¶: Return an undirected copy of the graph (see networkx.Graph.to_undirected).

to_undirected_class()[source]¶: Returns the class to use for empty undirected copies (see networkx.Graph.to_undirected_class).

to_utm(inplace=False)[source]¶

Project graph coordinates to the corresponding UTM (Universal Transverse Mercator)

Parameters: inplace (bool) – If True, the modification is done inplace, otherwise a new graph is returned (Default value = False).

Example

>>> import geonetworkx as gnx
>>> from shapely.geometry import Point
>>> g = gnx.GeoGraph(crs=gnx.WGS84_CRS)
>>> g.add_edge(1, 2, geometry=gnx.LineString([(4.28, 45.5), (4.32, 45.48)]))
>>> g.to_utm(inplace=True)
>>> print(g.crs)
+proj=utm +zone=31 +ellps=WGS84 +datum=WGS84 +units=m +no_defs +type=crs
>>> print(g.nodes[1]["geometry"])
POINT (600002.1723317318 5039293.296216004)

See also

to_crs

GeoMultiGraph¶

class GeoMultiGraph(incoming_graph_data=None, **attr)[source]¶

Bases: geonetworkx.geograph.GeoGraph, networkx.classes.multigraph.MultiGraph

A undirected geographic graph class that can store multiedges.

Initialize a graph with edges, name, or graph attributes.

Parameters

incoming_graph_data (input graph (optional, default: None)) – Data to initialize graph. If None (default) an empty graph is created. The data can be an edge list, or any NetworkX graph object. If the corresponding optional Python packages are installed the data can also be a NumPy matrix or 2d ndarray, a SciPy sparse matrix, or a PyGraphviz graph.
attr (keyword arguments, optional (default= no attributes)) – Attributes to add to graph as key=value pairs.

See also

convert

Examples

>>> G = nx.Graph()  # or DiGraph, MultiGraph, MultiDiGraph, etc
>>> G = nx.Graph(name='my graph')
>>> e = [(1, 2), (2, 3), (3, 4)]  # list of edges
>>> G = nx.Graph(e)

Arbitrary graph attribute pairs (key=value) may be assigned

>>> G = nx.Graph(e, day="Friday")
>>> G.graph
{'day': 'Friday'}

add_edge(u_for_edge, v_for_edge, key=None, **attr)[source]¶

Add a single edge.

This method exists only for reflecting nx.MultiGraph method so that the multiple inheritance scheme works.

Examples

>>> import geonetworkx as gnx
>>> g = gnx.GeoMultiGraph()
>>> g.add_edge(1, 2, 0, geometry=gnx.LineString([(5, 4), (2, 7)]))
0
>>> print(g.nodes[1]["geometry"])
POINT (5 4)

to_directed(as_view=False)[source]¶: Return a directed representation of the graph (see networkx.MultiGraph.to_directed).

to_directed_class()[source]¶: Returns the class to use for empty directed copies (see networkx.MultiGraph.to_directed_class).

to_nx_class()[source]¶: Return the closest networkx class (in the inheritance graph).

to_undirected(as_view=False)[source]¶: Return an undirected copy of the graph (see networkx.MultiGraph.to_undirected).

to_undirected_class()[source]¶: Returns the class to use for empty undirected copies (see networkx.MultiGraph.to_undirected_class)..

GeoDiGraph¶

class GeoDiGraph(incoming_graph_data=None, **attr)[source]¶

Bases: geonetworkx.geograph.GeoGraph, networkx.classes.digraph.DiGraph

Base class for directed geographic graphs.

Because edges are directed, it supposes that the edges lines are well-ordered. Namely, that the first point of the line matches with the coordinates of the first vertex of the edge (or is at least close) and vice versa with the last point of the line and the second. If this is not the case, the method order_well_lines can be useful to make sure of that.

Initialize a graph with edges, name, or graph attributes.

Parameters

incoming_graph_data (input graph (optional, default: None)) – Data to initialize graph. If None (default) an empty graph is created. The data can be an edge list, or any NetworkX graph object. If the corresponding optional Python packages are installed the data can also be a NumPy matrix or 2d ndarray, a SciPy sparse matrix, or a PyGraphviz graph.
attr (keyword arguments, optional (default= no attributes)) – Attributes to add to graph as key=value pairs.

See also

convert

Examples

>>> G = nx.Graph()  # or DiGraph, MultiGraph, MultiDiGraph, etc
>>> G = nx.Graph(name='my graph')
>>> e = [(1, 2), (2, 3), (3, 4)]  # list of edges
>>> G = nx.Graph(e)

Arbitrary graph attribute pairs (key=value) may be assigned

>>> G = nx.Graph(e, day="Friday")
>>> G.graph
{'day': 'Friday'}

to_directed(as_view=False)[source]¶: Return a directed representation of the graph (see networkx.DiGraph.to_directed).

to_directed_class()[source]¶: Returns the class to use for empty directed copies (see networkx.DiGraph.to_directed_class).

to_nx_class()[source]¶

to_undirected(reciprocal=False, as_view=False)[source]¶: Return an undirected copy of the graph (see networkx.DiGraph.to_undirected).

to_undirected_class()[source]¶: Returns the class to use for empty undirected copies (see networkx.DiGraph.to_undirected_class).

GeoMultiDiGraph¶

class GeoMultiDiGraph(incoming_graph_data=None, **attr)[source]¶

Bases: geonetworkx.geomultigraph.GeoMultiGraph, geonetworkx.geodigraph.GeoDiGraph, networkx.classes.multidigraph.MultiDiGraph

A directed geographic graph class that can store multiedges.

Initialize a graph with edges, name, or graph attributes.

Parameters

incoming_graph_data (input graph (optional, default: None)) – Data to initialize graph. If None (default) an empty graph is created. The data can be an edge list, or any NetworkX graph object. If the corresponding optional Python packages are installed the data can also be a NumPy matrix or 2d ndarray, a SciPy sparse matrix, or a PyGraphviz graph.
attr (keyword arguments, optional (default= no attributes)) – Attributes to add to graph as key=value pairs.

See also

convert

Examples

>>> G = nx.Graph()  # or DiGraph, MultiGraph, MultiDiGraph, etc
>>> G = nx.Graph(name='my graph')
>>> e = [(1, 2), (2, 3), (3, 4)]  # list of edges
>>> G = nx.Graph(e)

Arbitrary graph attribute pairs (key=value) may be assigned

>>> G = nx.Graph(e, day="Friday")
>>> G.graph
{'day': 'Friday'}

to_directed(as_view=False)[source]¶: Return a directed representation of the graph (see networkx.MultiDiGraph.to_directed).

to_directed_class()[source]¶: Returns the class to use for empty directed copies (see networkx.MultiDiGraph.to_directed_class).

to_nx_class()[source]¶: Return the closest networkx class (in the inheritance graph).

to_undirected(reciprocal=False, as_view=False)[source]¶: Return an undirected copy of the graph (see networkx.MultiDiGraph.to_undirected).

to_undirected_class()[source]¶: Returns the class to use for empty undirected copies (see networkx.MultiDiGraph.to_undirected_class).