Metadata-Version: 2.4
Name: raptor-stats
Version: 0.0.5
Summary: Raptor Zonal Statistics
Author-email: Simon Pedro Gonzalez <simon.pedro.g@gmail.com>
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: affine>=2.4.0
Requires-Dist: geopandas>=1.0.1
Requires-Dist: rasterio>=1.4.3
Requires-Dist: rtree>=1.4.0
Provides-Extra: dev
Requires-Dist: tqdm>=4.67.1; extra == "dev"
Requires-Dist: rasterstats>=0.20.0; extra == "dev"
Requires-Dist: xarray>=2025.1.1; extra == "dev"
Requires-Dist: line-profiler>=4.2.0; extra == "dev"
Requires-Dist: memory-profiler>=0.61.0; extra == "dev"
Requires-Dist: ruff>=0.11.2; extra == "dev"
Requires-Dist: seaborn>=0.13.2; extra == "dev"
Requires-Dist: pyqt6>=6.8.0; extra == "dev"
Requires-Dist: rasterstats>=0.20.0; extra == "dev"
Requires-Dist: psutil>=7.0.0; extra == "dev"
Requires-Dist: matplotlib>=3.7.1; extra == "dev"
Requires-Dist: pytest>=8.4.1; extra == "dev"
Requires-Dist: isort>=6.0.1; extra == "dev"
Requires-Dist: black>=25.1.0; extra == "dev"
Requires-Dist: docformatter>=1.7.7; extra == "dev"
Requires-Dist: pydocstyle>=6.3.0; extra == "dev"
Requires-Dist: m2r>=0.3.1; extra == "dev"
Requires-Dist: sphinx>=8.2.3; extra == "dev"
Requires-Dist: sphinx_rtd_theme>=3.0.2; extra == "dev"
Requires-Dist: build>=1.3.0; extra == "dev"
Dynamic: license-file

# raptor-stats

[![Docs: latest](https://img.shields.io/badge/Docs-latest-blue)](https://simonpedrogonzalez.github.io/raptor-stats-docs/index.html)
[![PyPI](https://img.shields.io/pypi/v/raptor-stats)](https://pypi.org/project/raptor-stats/)
[![Python  3.12.8+](https://img.shields.io/badge/python-3.12.8+-blue.svg)](https://github.com/simonpedrogonzalez/raptor-stats)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
#### Compute zonal statistics using efficient Raptor (Raster+Vector) methods.

## Installation

```bash
pip install raptor-stats
```

## Usage

```python
from raptorstats import zonal_stats

stats = zonal_stats("path/to/vector.shp", "path/to/raster.tif", method="scanline")
```
See the [zonal_stats API docs](https://simonpedrogonzalez.github.io/raptor-stats-docs/raptorstats.api.html#raptorstats.api.zonal_stats) for more details on input types and additional parameters.

## Methods

- `scanline`: Scans the raster file once, line by line, and computes all the intersections with the vector layer in a single pass. Suitable for fast one-time run results.
- `agqt`: Builds a QuadTree with precomputed statistics, then combines it with the scanline method to answer queries more efficiently. Suitable for systems that repeatedly query changing vector layers over the same raster.

## Performance

Raptor methods performance advantage increases with the size of the input raster and number of features. For example, with an ~1.9 billion pixel raster and 50 features (US states):

![See images at https://github.com/simonpedrogonzalez/raptor-stats/blob/main/README.md](assets/total_time_s_states.svg)

For the same raster, on but around 3000 features (US counties):

![See images at https://github.com/simonpedrogonzalez/raptor-stats/blob/main/README.md](assets/total_time_s_counties.svg)


NOTES:
- These tests were made on a i7-8750H (2019) 16GB RAM Linux machine.
- The performance of the agqt method depends on the depth of the tree selected and the size of the features.

## Credits

- Author: [Simon Pedro Gonzalez](https://simonpedrogonzalez.github.io/).
- This package is based on the following <a href="https://simonpedrogonzalez.github.io/raptor-stats-docs/_static/mdml_final_report.pdf" download>project</a>, where you can read more about the zonal stats problem, methods and performance comparison.
- This package API is inspired in the [rasterstats](https://github.com/perrygeo/python-rasterstats) package by [Matthew Perry](https://github.com/perrygeo).
