Metadata-Version: 2.4
Name: verus
Version: 1.1.0
Summary: A scientific tool to extract and analyze urban spatiotemporal vulnerability.
Author-email: "João Carlos N. Bittencourt" <joaocarlos@ufrb.edu.br>
Maintainer: LES2 FEUP faculty memebers
License: MIT License
Project-URL: Homepage, https://github.com/les2feup/verus
Project-URL: Bug Tracker, https://github.com/les2feup/verus/issues
Project-URL: Documentation, https://les2feup.github.io/verus/
Project-URL: Code Repository, https://github.com/les2feup/verus
Keywords: GIS,Vulnerability,Assessment,OpenStreetMap,Clustering
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: geopandas>=0.10.0
Requires-Dist: shapely>=1.8.0
Requires-Dist: pyproj>=3.0.0
Requires-Dist: osmnx>=1.1.0
Requires-Dist: rtree>=1.0.0
Requires-Dist: folium>=0.12.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: plotly>=5.3.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: colorama>=0.4.4
Requires-Dist: tqdm>=4.62.0
Requires-Dist: requests>=2.26.0
Requires-Dist: haversine>=2.3.0
Requires-Dist: branca>=0.4.0
Requires-Dist: h3>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest>=6.2.5; extra == "dev"
Requires-Dist: black>=22.1.0; extra == "dev"
Requires-Dist: isort>=5.10.1; extra == "dev"
Requires-Dist: flake8>=4.0.1; extra == "dev"
Requires-Dist: mypy>=0.910; extra == "dev"
Requires-Dist: coverage>=6.2; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.3.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: nbsphinx>=0.8.8; extra == "docs"
Provides-Extra: viz
Requires-Dist: seaborn>=0.11.2; extra == "viz"
Requires-Dist: plotly>=5.3.0; extra == "viz"
Dynamic: license-file

![LES2 Logo](./src/figures/les2banner.png)

# VERUS

_Vulnerability Evaluation for Resilient Urban Systems_

![Python](https://img.shields.io/badge/Python-3.8%2B-blue?style=for-the-badge&logo=python)
![Jupyter Notebook](https://img.shields.io/badge/Jupyter-Notebook-orange?style=for-the-badge&logo=jupyter)
![OSMnx](https://img.shields.io/badge/OSMnx-1.1.1-blue?style=for-the-badge&logo=openstreetmap)
![Folium](https://img.shields.io/badge/Folium-0.12.1-green?style=for-the-badge&logo=folium)
[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen?style=for-the-badge)](https://les2feup.github.io/verus/)
[![DOI](https://img.shields.io/badge/doi-10.5281/zenodo.19113788-yellow?style=for-the-badge)](https://doi.org/10.5281/zenodo.19113788)

## Description

VERUS (Vulnerability Evaluation for Resilient Urban Systems) is a Python library for extracting points of interest from OpenStreetMap, clustering them based on spatial proximity and time-based vulnerability indices, and analyzing urban vulnerability patterns.

## Documentation

Comprehensive documentation is available at [https://les2feup.github.io/verus/](https://les2feup.github.io/verus/)

## Publications

-   Bittencourt, J. C. N., Costa, D. G., Portugal, P., Peixoto, M. L. M., & Vasques, F. (2025). On the spatiotemporal knowledge-driven vulnerability assessment of urban areas: A clustering-based approach. International Journal of Disaster Risk Reduction, 127, 105681. <https://doi.org/10.1016/j.ijdrr.2025.105681>


## Installation

```bash
pip install verus
```

## Reproducing Results

To reproduce the results from the latest article, run the following Jupyter Notebooks:

-   [Porto, Portugal](./notebooks/experiments/01-Porto.ipynb)
-   [Lisbon, Portugal](./notebooks/experiments/02-Lisbon.ipynb)
-   [Paris, France](./notebooks/experiments/03-Paris.ipynb)

## Basic Usage

```python
from verus import VERUS
from verus.data import DataExtractor, TimeWindowGenerator
from verus.grid import HexagonGridGenerator

# Extract default urban data from OpenStreetMap
extractor = DataExtractor(region="Porto, Portugal")
poi_data = extractor.run()

# Define default time-based vulnerability scenarios
twg = TimeWindowGenerator(reference_date="2023-11-06")
time_windows = twg.generate_from_schedule()

# Generate analysis grid
grid = HexagonGridGenerator(region="Porto, Portugal", edge_length=250)
hex_grid = grid.run()

# Run vulnerability assessment
assessor = VERUS(place_name="Porto")

# Load extracted data
assessor.load(
    potis_df=poi_data,
    time_windows_dict=time_windows,
    zones_gdf=hex_grid,
)

# Perform assessment and get results
evaluation_time = tw_gen.to_unix_epoch("2023-11-06 17:30:00")
results = assessor.run(evaluation_time=evaluation_time)

# Visualize results
map_obj = assessor.visualize()

# Save results to file
assessor.save("./results/porto/")
```

## Features

-   Extract points of interest from OpenStreetMap for any city
-   Create hexagonal grid systems for spatial analysis
-   Implement OPTICS density-based clustering for identifying urban patterns
-   Apply K-means clustering with Haversine distance for geographic data
-   Generate time-dependent vulnerability assessments
-   Create interactive maps for visualization with folium
-   Export results in various formats (GeoJSON, CSV, HTML)

## Contributions

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Commit changes: `git commit -m 'Add amazing feature'`
4. Push to branch: `git push origin feature/amazing-feature`
5. Open a pull request

Please make sure to update tests and documentation as appropriate.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

-   Research developed at the Laboratory of Emerging Smart Systems (LES2) at the Faculty of Engineering of University of Porto
-   This work was supported by the Associate Laboratory Advanced Production and Intelligent Systems – ARISE LA/P/0112/2020 (DOI 10.54499/LA/P/0112/2020), by the Base Funding (UIDB/00147/2020) and Programmatic Funding (UIDP/00147/2020) of the R\&D Unit Center for Systems and Technologies -- SYSTEC, and by the Fundação para a Ciência e a Tecnologia (FCT) through the PhD scholarship (2024.02446.BD).
