0
# rasterstats
1

2
A Python library for summarizing geospatial raster datasets based on vector geometries. It provides zonal statistics and interpolated point queries functionality, enabling analysis of how raster values vary across different geographic regions defined by vector data.
3

4
## Package Information
5

6
- **Package Name**: rasterstats
7
- **Language**: Python
8
- **Installation**: `pip install rasterstats`
9
- **Python Version**: >=3.7
10
- **License**: BSD-3-Clause
11

12
## Core Imports
13

14
```python
15
import rasterstats
16
```
17

18
Common imports for specific functionality:
19

20
```python
21
from rasterstats import zonal_stats, point_query
22
from rasterstats import gen_zonal_stats, gen_point_query
23
from rasterstats import raster_stats  # Deprecated alias for zonal_stats
24
from rasterstats import cli  # Command-line interface module
25
```
26

27
For advanced usage with I/O utilities:
28

29
```python
30
from rasterstats.io import Raster, read_features, read_featurecollection
31
from rasterstats.utils import check_stats, stats_to_csv, DEFAULT_STATS, VALID_STATS
32
```
33

34
## Basic Usage
35

36
```python
37
from rasterstats import zonal_stats, point_query
38

39
# Zonal statistics: calculate summary statistics for polygons
40
stats = zonal_stats("path/to/polygons.shp", "path/to/raster.tif")
41
print(stats[0])  # {'min': 1.0, 'max': 100.0, 'mean': 45.5, 'count': 200}
42

43
# Point query: extract raster values at point locations
44
point = {'type': 'Point', 'coordinates': (245309.0, 1000064.0)}
45
values = point_query(point, "path/to/raster.tif")
46
print(values)  # [74.09817594635244]
47

48
# Using numpy arrays with affine transforms
49
import numpy as np
50
from affine import Affine
51

52
raster_array = np.random.rand(100, 100)
53
transform = Affine.identity()
54
polygons = [{'type': 'Polygon', 'coordinates': [[(0, 0), (10, 0), (10, 10), (0, 10), (0, 0)]]}]
55

56
stats = zonal_stats(polygons, raster_array, affine=transform)
57
```
58

59
## Architecture
60

61
rasterstats operates through a layered architecture:
62

63
- **I/O Layer**: Handles reading vector data (Fiona/Shapely) and raster data (rasterio/numpy)
64
- **Geometry Processing**: Converts vector geometries to raster masks using rasterio.features
65
- **Statistics Engine**: Computes summary statistics on masked arrays using numpy operations
66
- **Output Formatting**: Returns results as dictionaries or GeoJSON features
67

68
The library integrates seamlessly with the Python geospatial ecosystem including rasterio, fiona, shapely, and numpy, supporting various file formats and coordinate reference systems.
69

70
## Capabilities
71

72
### Zonal Statistics
73

74
Calculate summary statistics (mean, min, max, count, etc.) of raster values within vector polygon boundaries. Supports categorical analysis, custom statistics functions, and various output formats.
75

76
```python { .api }
77
def zonal_stats(vectors, raster, layer=0, band=1, nodata=None, affine=None, 
78
                stats=None, all_touched=False, categorical=False, 
79
                category_map=None, add_stats=None, zone_func=None, 
80
                raster_out=False, prefix=None, geojson_out=False, 
81
                boundless=True, progress=False, **kwargs):
82
    """Calculate zonal statistics for vector geometries."""
83

84
def gen_zonal_stats(vectors, raster, layer=0, band=1, nodata=None, affine=None,
85
                    stats=None, all_touched=False, categorical=False,
86
                    category_map=None, add_stats=None, zone_func=None,
87
                    raster_out=False, prefix=None, geojson_out=False,
88
                    boundless=True, **kwargs):
89
    """Generator version of zonal statistics."""
90
```
91

92
[Zonal Statistics](./zonal-statistics.md)
93

94
### Point Queries
95

96
Extract raster values at specific point locations or along vector geometry vertices using nearest neighbor or bilinear interpolation.
97

98
```python { .api }
99
def point_query(vectors, raster, band=1, layer=0, nodata=None, affine=None,
100
                interpolate="bilinear", property_name="value", 
101
                geojson_out=False, boundless=True):
102
    """Query raster values at point locations."""
103

104
def gen_point_query(vectors, raster, band=1, layer=0, nodata=None, affine=None,
105
                    interpolate="bilinear", property_name="value",
106
                    geojson_out=False, boundless=True):
107
    """Generator version of point queries."""
108
```
109

110
[Point Queries](./point-queries.md)
111

112
### Command Line Interface
113

114
Command-line tools for processing GeoJSON data through rasterio plugins, enabling integration with other geospatial command-line workflows.
115

116
```python { .api }
117
@click.command()
118
def zonalstats(features, raster, all_touched, band, categorical, 
119
               indent, info, nodata, prefix, stats, sequence, use_rs):
120
    """CLI for zonal statistics with GeoJSON input/output."""
121

122
@click.command()
123
def pointquery(features, raster, band, indent, nodata, interpolate,
124
               property_name, sequence, use_rs):
125
    """CLI for point queries with GeoJSON input/output."""
126
```
127

128
[Command Line Interface](./cli.md)
129

130
### I/O and Data Utilities
131

132
Core utilities for reading vector data, managing raster access, and handling coordinate transformations. Includes the Raster class abstraction and functions for working with various data sources.
133

134
```python { .api }
135
class Raster:
136
    """Raster abstraction for unified access to file-based and array-based raster data."""
137
    def __init__(self, raster, affine=None, nodata=None, band=1): ...
138
    def index(self, x, y): ...
139
    def read(self, bounds=None, window=None, masked=False, boundless=True): ...
140

141
def read_features(obj, layer=0):
142
    """Read vector features from files, GeoJSON, or geometric objects."""
143

144
def read_featurecollection(obj, layer=0):
145
    """Read vector features and return as GeoJSON FeatureCollection."""
146
```
147

148
[I/O and Data Utilities](./io-utilities.md)
149

150
## Version Information
151

152
```python { .api }
153
__version__: str  # Package version string
154
```
155

156
## Core Types
157

158
```python { .api }
159
from typing import Union, List, Dict, Any, Optional, Callable, Tuple
160
from numpy import ndarray
161
from affine import Affine
162

163
# Input types
164
VectorInput = Union[str, Dict, List[Dict]]  # File path, GeoJSON Feature/FeatureCollection, or list of features
165
RasterInput = Union[str, ndarray]  # File path or numpy array
166
StatsInput = Union[str, List[str], None]  # Statistics specification
167
CategoryMap = Dict[Union[int, float], str]  # Mapping raster values to category names
168
AddStats = Dict[str, Callable]  # Custom statistics functions
169

170
# Output types
171
ZonalResult = Dict[str, Union[float, int, None]]  # Statistics dictionary
172
PointResult = Union[List[float], float, None]  # Point query values
173
GeoJSONFeature = Dict[str, Any]  # GeoJSON feature with properties
174

175
# Warning classes
176
class NodataWarning(UserWarning):
177
    """Warning raised for nodata handling issues."""
178
```