PySGN: A Python package for constructing synthetic geospatial networks

Introduction

PySGN (Python for Synthetic Geospatial Networks) is a Python package for constructing synthetic geospatial networks. It is built on top of the NetworkX package, which provides a flexible and efficient data structure for representing complex networks and GeoPandas, which extends the datatypes used by pandas to allow spatial operations on geometric types. PySGN is designed to be easy to use and flexible, allowing users to generate networks with a wide range of characteristics.

Installation

PySGN can be installed using pip:

bash pip install pysgn

If you plan to run the code snippets below or the Getting Started notebook docs/getting_started.ipynb locally, install the optional docs extras to get the other dependencies such as geodatasets, Jupyter and Sphinx:

bash pip install "pysgn[docs]"

Alternatively, PySGN is available on conda-forge and can be installed with:

bash conda install -c conda-forge pysgn

To work from source, you may clone this repository:

bash git clone https://github.com/wang-boyu/pysgn.git cd pysgn

then either:

• using pip in editable mode

bash pip install -e . # or with extras pip install -e ".[docs]"

• using conda with the provided environment.yml.

bash conda env create -f environment.yml conda activate pysgn

This installs PySGN in editable mode (pip install -e .), so no additional installation step is required.

Usage Example

Geospatial Erdős-Rényi Network

Here's a simple example of how to use the geo_erdos_renyi_network function to create a geospatial Erdős-Rényi network. It generates a network where each pair of nodes is connected with probability p, which depends on the spatial distance between the nodes. The parameter a controls the rate of decay of the connection probability with distance.

All PySGN functions expect the input GeoDataFrame to contain a single geometry type (Points or Polygons).

```python import geodatasets import geopandas as gpd from pysgn import geoerdosrenyi_network

Load the sample grocery-store points from geodatasets

and explode the GeoDataFrame into single points (one point per row).

gdf = ( gpd.readfile(geodatasets.getpath("geoda.groceries")) .explode(indexparts=False) .resetindex(drop=True) .to_crs("EPSG:26971") )

Create a geospatial Erdős-Rényi network

graph = geoerdosrenyi_network(gdf, a=3)

Output the number of nodes and edges

print(f"Number of nodes: {graph.numberofnodes()}") print(f"Number of edges: {graph.numberofedges()}") ```

Geospatial Watts-Strogatz Network

Similarly you can use the geo_watts_strogatz_network function to create a geospatial Watts-Strogatz network. It first creates a network where each node is connected to its k nearest neighbors. Then, it rewires each edge with probability p. If an edge is chosen to be rewired, it is replaced with a new edge to a random node, where the probability of connecting to this new node is inversely proportional to the spatial distance.

```python import geodatasets import geopandas as gpd from pysgn import geowattsstrogatz_network

gdf = ( gpd.readfile(geodatasets.getpath("geoda.groceries")) .explode(indexparts=False) .resetindex(drop=True) .to_crs("EPSG:26971") )

Create a geospatial Watts-Strogatz network

graph = geowattsstrogatz_network( gdf, k=4, # Each node is connected to k nearest neighbors p=0.1, # Probability of rewiring each edge a=2, # Distance decay exponent )

Output the number of nodes and edges

print(f"Number of nodes: {graph.numberofnodes()}") print(f"Number of edges: {graph.numberofedges()}") ```

Geospatial Barabási-Albert Network

You can also use the geo_barabasi_albert_network function to create a geospatial Barabási-Albert network. It creates a network using geospatial preferential attachment, where the probability of connecting to existing nodes depends on both their degrees and the spatial distances.

```python import geodatasets import geopandas as gpd from pysgn import geobarabasialbertnetwork from pysgn.ordering import densityorder

gdf = ( gpd.readfile(geodatasets.getpath("geoda.groceries")) .explode(indexparts=False) .resetindex(drop=True) .to_crs("EPSG:26971") )

Create a geospatial Barabási-Albert network

graph = geobarabasialbertnetwork( gdf, m=3, # Each new node connects to 3 existing nodes a=2, # Distance decay exponent maxdegree=150, # Maximum degree constraint # Use density-based node ordering (nodes in dense areas join first) nodeorder=lambda gdf: densityorder(gdf, method='knn'), )

Output the number of nodes and edges

print(f"Number of nodes: {graph.numberofnodes()}") print(f"Number of edges: {graph.numberofedges()}") ```

Export to GeoDataFrames

Once you have a graph, you can convert it back to GeoPandas GeoDataFrames for GIS workflows or file export.

```python from pysgn import graphtogdf

nodesgdf, edgesgdf = graphtogdf(graph) ```

Documentation

For more information on how to use PySGN, please refer to the documentation.

Contributing

If you run into an issue, please file a ticket for us to discuss. If possible, follow up with a pull request.

If you would like to add a feature, please reach out via ticket or start a discussion. A feature is most likely to be added if you build it!

Don't forget to check out the Contributors guide.

License

PySGN is released under the MIT License.