Metadata-Version: 2.4
Name: tesspy
Version: 0.2.0
Summary: Tessellation of Urban Areas
Project-URL: Homepage, https://github.com/siavash-saki/tesspy
Project-URL: Repository, https://github.com/siavash-saki/tesspy
Project-URL: Documentation, https://tesspy.readthedocs.io
Author: Siavash Saki
Author-email: Jonas Hamann <jonas.hamann@fb3.fra-uas.de>
License: BSD 3-Clause License
        
        Copyright (c) 2021, tesspy Developers
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE.md
Keywords: GIS,OpenStreetMap,tessellation,urban
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.11
Requires-Dist: geopandas>=1.0
Requires-Dist: h3>=4.0
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: mercantile>=1.2
Requires-Dist: numpy>=1.26
Requires-Dist: osmnx>=1.9
Requires-Dist: pandas>=2.0
Requires-Dist: requests>=2.28
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.11
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.10; extra == 'dev'
Requires-Dist: pytest-timeout>=2.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: types-requests; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo; extra == 'docs'
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: nbsphinx; extra == 'docs'
Requires-Dist: pypandoc-binary; extra == 'docs'
Requires-Dist: sphinx; extra == 'docs'
Provides-Extra: examples
Requires-Dist: contextily; extra == 'examples'
Requires-Dist: esda; extra == 'examples'
Requires-Dist: ipykernel; extra == 'examples'
Requires-Dist: jupyterlab; extra == 'examples'
Requires-Dist: libpysal; extra == 'examples'
Requires-Dist: mapclassify; extra == 'examples'
Requires-Dist: seaborn; extra == 'examples'
Requires-Dist: statsmodels; extra == 'examples'
Description-Content-Type: text/markdown

# tesspy
[![Tests](https://github.com/siavash-saki/tesspy/actions/workflows/tests_package.yml/badge.svg)](https://github.com/siavash-saki/tesspy/actions/workflows/tests_package.yml)
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
[![Documentation Status](https://readthedocs.org/projects/tesspy/badge/?version=latest)](https://tesspy.readthedocs.io/en/latest/?badge=latest)
![version](https://img.shields.io/badge/version-0.2.0-blue)
[![Conda Version](https://img.shields.io/conda/vn/conda-forge/tesspy.svg)](https://anaconda.org/conda-forge/tesspy)

<img align="left" src="docs/readme_pics/logo.jpg">

`tesspy` is a python library for geographical tessellation.

The process of discretization of space into subspaces without overlaps and gaps is called tessellation and is of interest to researchers in the field of spatial analysis. Tessellation is essential in understanding geographical space and provides a framework for analyzing geospatial data. Different tessellation methods are implemented in `tesspy`. They can be divided into two groups. The first group is regular tessellation methods: square grid and hexagon grid. The second group is irregular tessellation methods based on geospatial data. These methods are adaptive squares, Voronoi diagrams, and city blocks. The geospatial data used for tessellation is retrieved from the OpenStreetMap database.


## Installation

Install `tesspy` using [uv](https://docs.astral.sh/uv/) (**Recommended**):
```shell
uv pip install tesspy
```

or using pip:
```shell
pip install tesspy
```

`tesspy` is also available on conda-forge:
```shell
conda install -c conda-forge tesspy
```

## Creating a new environment for tesspy

We recommend using uv to create and manage a virtual environment:

```shell
uv venv tesspy_env
source tesspy_env/bin/activate  # Linux/macOS
# tesspy_env\Scripts\activate   # Windows
uv pip install tesspy
```

To also install dependencies for running the example notebooks:

```shell
uv pip install "tesspy[examples]"
```

## Dependencies

`tesspy`'s dependencies are: `geopandas`, `scipy`, `h3-py`, `osmnx`, `hdbscan`, `mercantile`, `matplotlib` and `scikit-learn`.


## Documentation
The official documentation is hosted on **[ReadTheDocs](https://tesspy.readthedocs.io)**.

## Logging
`tesspy` uses Python's standard `logging` module. By default, library logging is
silent unless you configure it.

Basic progress logs:
```python
from tesspy import Tessellation, configure_logging

configure_logging("INFO")
t = Tessellation("Frankfurt am Main")
t.city_blocks(verbose=True)
```

Use `verbose=True` on POI-driven methods to emit progress events.


## Examples
The city of "Frankfurt am Main" in Germany is used to showcase different tessellation methods. This is how a tessellation object is built, and different methods are called. For the tessellation methods based on Points of Interests (adaptive squares, Voronoi polygons, and City Blocks), we use `amenity` data from the OpenStreetMap.
```python
from tesspy import Tessellation
ffm= Tessellation('Frankfurt am Main')
```


### Squares 
```python
ffm_sqruares = ffm.squares(resolution=15)
```
![Squares_tessellation](docs/readme_pics/Squares.png)

### Hexagons
```python
ffm_hex_8 = ffm.hexagons(resolution=8)
```
![hexagon_tessellation](docs/readme_pics/Hexagons.png)


### Adaptive Squares
```python
ffm_asq = ffm.adaptive_squares(start_resolution=14, threshold=100, poi_categories=['amenity'])
```

![adaptive_squares_tessellation](docs/readme_pics/Adaptive_Squares.png)

### Voronoi Polygons
```python
ffm_voronoi = ffm.voronoi(poi_categories=['amenity'], n_polygons=500)
```
![Voronoi_tessellation](docs/readme_pics/Voronoi.png)

### City Blocks
```python
ffm_city_blocks = ffm.city_blocks(n_polygons=500)
```
![city_blocks_tessellation](docs/readme_pics/CB.png)

## Citing Tesspy

We would be very grateful if you would cite Tesspy in your scientific publications. Please feel free to use the following citation for this purpose: 
Saki et al., (2022). TessPy: a python package for geographical tessellation. Journal of Open Source Software, 7(76), 4620, https://doi.org/10.21105/joss.04620

or the bibtex citation directly:
```{bibtex}
@article{Saki2022, 
        doi = {10.21105/joss.04620}, 
        url = {https://doi.org/10.21105/joss.04620}, 
        year = {2022}, 
        publisher = {The Open Journal}, 
        volume = {7}, 
        number = {76}, 
        pages = {4620}, 
        author = {Siavash Saki and Jonas Hamann and Tobias Hagen}, 
        title = {TessPy: a python package for geographical tessellation}, 
        journal = {Journal of Open Source Software}}
```


## Contributing to tesspy
All kind of contributions are welcome:
* Improvement of code with new features, bug fixes, and  bug reports
* Improvement of documentation
* Additional tests

To set up a development environment, clone the repo and install in editable mode:

```shell
git clone https://github.com/siavash-saki/tesspy.git
cd tesspy
uv pip install -e ".[dev,examples]"
```

Follow the instructions [here](https://tesspy.readthedocs.io/en/latest/Contribution.html)
for submitting a PR.

If you have any ideas or questions, feel free to open an issue.


## Acknowledgements
`tesspy` is the result of the research project [ClusterMobil](https://www.frankfurt-university.de/de/hochschule/fachbereich-1-architektur-bauingenieurwesen-geomatik/forschungsinstitut-ffin/fachgruppen-des-ffin/fg-neue-mobilitat/relut/forschungsprojekte-relut/clustermobil/) conducted by the [Research Lab for Urban Transport](https://www.frankfurt-university.de/en/about-us/faculty-1-architecture-civil-engineering-geomatics/research-institute-ffin/specialist-groups-of-the-ffin/specialist-group-new-mobility/relut/). This research project is funded by the state of Hesse and [HOLM](https://frankfurt-holm.de/) funding under the “Innovations in Logistics and Mobility” measure of the Hessian Ministry of Economics, Energy, Transport and Housing. [HA Project No.: 1017/21-19]
