or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdindex.mdio-utilities.mdpoint-queries.mdzonal-statistics.md
tile.json

tessl/pypi-rasterstats

Summarize geospatial raster datasets based on vector geometries

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/rasterstats@0.20.x

To install, run

npx @tessl/cli install tessl/pypi-rasterstats@0.20.0

index.mddocs/

rasterstats

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.

Package Information

  • Package Name: rasterstats
  • Language: Python
  • Installation: pip install rasterstats
  • Python Version: >=3.7
  • License: BSD-3-Clause

Core Imports

import rasterstats

Common imports for specific functionality:

from rasterstats import zonal_stats, point_query
from rasterstats import gen_zonal_stats, gen_point_query
from rasterstats import raster_stats  # Deprecated alias for zonal_stats
from rasterstats import cli  # Command-line interface module

For advanced usage with I/O utilities:

from rasterstats.io import Raster, read_features, read_featurecollection
from rasterstats.utils import check_stats, stats_to_csv, DEFAULT_STATS, VALID_STATS

Basic Usage

from rasterstats import zonal_stats, point_query

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

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

# Using numpy arrays with affine transforms
import numpy as np
from affine import Affine

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

stats = zonal_stats(polygons, raster_array, affine=transform)

Architecture

rasterstats operates through a layered architecture:

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

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

Capabilities

Zonal Statistics

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.

def zonal_stats(vectors, raster, layer=0, band=1, nodata=None, affine=None, 
                stats=None, all_touched=False, categorical=False, 
                category_map=None, add_stats=None, zone_func=None, 
                raster_out=False, prefix=None, geojson_out=False, 
                boundless=True, progress=False, **kwargs):
    """Calculate zonal statistics for vector geometries."""

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

Zonal Statistics

Point Queries

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

def point_query(vectors, raster, band=1, layer=0, nodata=None, affine=None,
                interpolate="bilinear", property_name="value", 
                geojson_out=False, boundless=True):
    """Query raster values at point locations."""

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

Point Queries

Command Line Interface

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

@click.command()
def zonalstats(features, raster, all_touched, band, categorical, 
               indent, info, nodata, prefix, stats, sequence, use_rs):
    """CLI for zonal statistics with GeoJSON input/output."""

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

Command Line Interface

I/O and Data Utilities

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.

class Raster:
    """Raster abstraction for unified access to file-based and array-based raster data."""
    def __init__(self, raster, affine=None, nodata=None, band=1): ...
    def index(self, x, y): ...
    def read(self, bounds=None, window=None, masked=False, boundless=True): ...

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

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

I/O and Data Utilities

Version Information

__version__: str  # Package version string

Core Types

from typing import Union, List, Dict, Any, Optional, Callable, Tuple
from numpy import ndarray
from affine import Affine

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

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

# Warning classes
class NodataWarning(UserWarning):
    """Warning raised for nodata handling issues."""