Metadata-Version: 2.3
Name: pysgn
Version: 0.1.0
Summary: A Python package for constructing synthetic geospatial networks
Project-URL: homepage, https://github.com/wang-boyu/pysgn
Project-URL: repository, https://github.com/wang-boyu/pysgn
Author-email: Boyu Wang <bwang44@buffalo.edu>
License: MIT
Requires-Python: >=3.10
Requires-Dist: geopandas
Requires-Dist: loguru
Requires-Dist: networkx
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: tqdm
Provides-Extra: all
Requires-Dist: black[jupyter]; extra == 'all'
Requires-Dist: contextily; extra == 'all'
Requires-Dist: coverage; extra == 'all'
Requires-Dist: ipython; extra == 'all'
Requires-Dist: ipywidgets; extra == 'all'
Requires-Dist: isort; extra == 'all'
Requires-Dist: jupyterlab; extra == 'all'
Requires-Dist: jupyterlab-code-formatter; extra == 'all'
Requires-Dist: jupyterlab-execute-time; extra == 'all'
Requires-Dist: jupyterlab-lsp; extra == 'all'
Requires-Dist: matplotlib; extra == 'all'
Requires-Dist: myst-nb; extra == 'all'
Requires-Dist: myst-parser; extra == 'all'
Requires-Dist: pre-commit; extra == 'all'
Requires-Dist: pydata-sphinx-theme; extra == 'all'
Requires-Dist: pytest-cov; extra == 'all'
Requires-Dist: pytest-mock; extra == 'all'
Requires-Dist: pytest>=4.6; extra == 'all'
Requires-Dist: python-lsp-server; extra == 'all'
Requires-Dist: ruff; extra == 'all'
Requires-Dist: seaborn; extra == 'all'
Requires-Dist: sphinx; extra == 'all'
Provides-Extra: dev
Requires-Dist: black[jupyter]; extra == 'dev'
Requires-Dist: coverage; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-mock; extra == 'dev'
Requires-Dist: pytest>=4.6; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: sphinx; extra == 'dev'
Provides-Extra: docs
Requires-Dist: contextily; extra == 'docs'
Requires-Dist: ipython; extra == 'docs'
Requires-Dist: ipywidgets; extra == 'docs'
Requires-Dist: isort; extra == 'docs'
Requires-Dist: jupyterlab; extra == 'docs'
Requires-Dist: jupyterlab-code-formatter; extra == 'docs'
Requires-Dist: jupyterlab-execute-time; extra == 'docs'
Requires-Dist: jupyterlab-lsp; extra == 'docs'
Requires-Dist: matplotlib; extra == 'docs'
Requires-Dist: myst-nb; extra == 'docs'
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: pydata-sphinx-theme; extra == 'docs'
Requires-Dist: python-lsp-server; extra == 'docs'
Requires-Dist: seaborn; extra == 'docs'
Requires-Dist: sphinx; extra == 'docs'
Description-Content-Type: text/markdown

# PySGN: A Python package for constructing synthetic geospatial networks

[![GitHub CI](https://github.com/wang-boyu/pysgn/actions/workflows/build.yml/badge.svg)](https://github.com/wang-boyu/pysgn/actions) [![Read the Docs](https://readthedocs.org/projects/pysgn/badge/?version=stable)](https://pysgn.readthedocs.io/stable) [![Codecov](https://codecov.io/gh/wang-boyu/pysgn/branch/main/graph/badge.svg)](https://codecov.io/gh/wang-boyu/pysgn) [![PyPI](https://img.shields.io/pypi/v/pysgn.svg)](https://pypi.org/project/pysgn) [![PyPI - License](https://img.shields.io/pypi/l/pysgn)](https://pypi.org/project/pysgn/) [![PyPI - Downloads](https://img.shields.io/pypi/dw/pysgn)](https://pypistats.org/packages/pysgn) [![DOI](https://zenodo.org/badge/DOI/10.3847/xxxxx.svg)](https://doi.org/10.3847/xxxxx)


## Introduction

PySGN is a Python package for constructing synthetic geospatial networks. It is built on top of the [NetworkX](https://networkx.github.io/) package, which provides a flexible and efficient data structure for representing complex networks and [GeoPandas](https://geopandas.org/), 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
```

## 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:

```python
import geopandas as gpd
from pysgn import geo_erdos_renyi_network

# Load your geospatial data into a GeoDataFrame
gdf = gpd.read_file('path/to/your/geospatial_data.shp')

# Create a geospatial Erdős-Rényi network
graph = geo_erdos_renyi_network(gdf, a=3)

# Output the number of nodes and edges
print(f"Number of nodes: {graph.number_of_nodes()}")
print(f"Number of edges: {graph.number_of_edges()}")
```

### Geospatial Watts-Strogatz Network

Similarly you can use the `geo_watts_strogatz_network` function to create a geospatial Watts-Strogatz network:

```python
import geopandas as gpd
from pysgn import geo_watts_strogatz_network

# Load your geospatial data into a GeoDataFrame
gdf = gpd.read_file('path/to/your/geospatial_data.shp')

# Create a geospatial Watts-Strogatz network
graph = geo_watts_strogatz_network(gdf, k=4, p=0.1)

# Output the number of nodes and edges
print(f"Number of nodes: {graph.number_of_nodes()}")
print(f"Number of edges: {graph.number_of_edges()}")
```

## Documentation

For more information on how to use PySGN, please refer to the [documentation](https://pysgn.readthedocs.io/).

## Contributing

If you run into an issue, please file a [ticket](https://github.com/wang-boyu/pysgn/issues) 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](https://github.com/wang-boyu/pysgn/issues) or start a [discussion](https://github.com/wang-boyu/pysgn/discussions).
A feature is most likely to be added if you build it!

Don't forget to check out the [Contributors guide](https://github.com/wang-boyu/pysgn/blob/main/CONTRIBUTING.md).

## License

PySGN is released under the MIT License.

## Acknowledgements

The algorithms implemented in PySGN are based on the following paper, with some improvements and modifications:

- Ketevan Gallagher, Taylor Anderson, Andrew Crooks, and Andreas Züfle. 2023. Synthetic Geosocial Network Generation. In *Proceedings of the 7th ACM SIGSPATIAL Workshop on Location-based Recommendations, Geosocial Networks and Geoadvertising (LocalRec '23)*. Association for Computing Machinery, New York, NY, USA, 15–24. [https://doi.org/10.1145/3615896.3628345](https://doi.org/10.1145/3615896.3628345)