ds.rst.stats() or Raster.stats()

ds.rst.stats() or Raster.stats()#

RasterBase.stats(statistics=None, *, by=None, values=None, bins=None, categories=None, at=None, mask=None, mask_mode='inside', subsample=1, subsample_per_group=False, random_state=None, strategy='auto', backend='geoutils', subsampling_strategy='topk', interpolation='linear', align='raise', observed=True, return_masks=False, mp_config=None, fractional=False, overlap_backend='auto', error_structure=None, uncertainty_kwargs=None)[source]#

Calculate summary statistics or statistics grouped by categories, bins, or vector zones.

Omit by to summarize raster values. With by, provide categories for discrete groups, bins for continuous groups, or a vector feature column for zonal statistics:

# Global statistics
raster.stats()
raster.stats("mean")
raster.stats(["mean", "std", "nmad"])

# Categorical stats
raster.stats(["mean", "std"], by={"landcover": landcover}, categories={"landcover": classes})
# Binned stats
raster.stats(["mean", "std"], by={"elevation": elevation}, bins={"elevation": elevation_bins})
# Zonal stats
raster.stats(["mean", "std"], by={"glacier": (glacier_outlines, "id")})

# Multiple grouping
raster.stats(["mean", "std"], by={"elevation": elevation, "glacier": (glacier_outlines, "id")},
bins={"elevation": elevation_bins})
Parameters:

  • statistics (str | Callable[[Any], Any] | Reducer | Iterable[str | Callable[[Any], Any] | Reducer] | None) – Statistics to calculate (e.g. “mean”, [“mean”, “nmad”], or np.nanmedian). None returns “min”, “max”, “mean”, “median”, “std”, “nmad”, “validcount”, “totalcount” and “percentagevalidpoints”. “all” also includes “sum”, “sumofsquares”, “90thpercentile”, “iqr”, “le90” and “rmse”, plus inlier counts for masked global statistics. Grouped defaults replace “validcount” with “count”; every grouped result includes “count”.

  • by (Mapping[str, Any] | None) – Named variables to group by (e.g. {“elevation”: elevation}); use {“glacier”: (outlines, “id”)} for vector zones. Arrays must match the selected locations. Omit for global statistics.

  • values (int | Iterable[int] | Mapping[str, Any] | None) – Bands to summarize, counting from one (e.g. [1, 3]); defaults to all bands. Use a mapping for named inputs (e.g. {“elevation”: (dem, 1)}).

  • bins (Mapping[str, Any] | None) – Continuous bins keyed by grouping name (e.g. {“elevation”: 10}). Each definition is a count of equal-width bins, increasing edges (e.g. [0, 2, 5]), or a Pandas IntervalIndex to choose open/closed sides.

  • categories (Mapping[str, Iterable[Any]] | None) – Ordered categories keyed by grouping name (e.g. {“landcover”: [100, 110, 120]}). Values outside these categories are excluded.

  • at (Literal['self'] | RasterBase | DataArray | PointCloudBase | GeoDataFrame | None) – Grid or ordered point locations on which to calculate statistics (e.g. at=reference or at=”self”). Defaults to the first point input, if present, otherwise the source locations.

  • mask (RasterBase | DataArray | geoutils.vector.base.VectorBase | GeoDataFrame | ArrayLike | None) – Locations to include (True in a boolean mask, e.g. mask=dem > 1000, or features in a vector mask). Global counts describe values before this mask; “all” adds counts for values kept by the mask.

  • mask_mode (Literal['inside', 'outside']) – Keep locations “inside” or “outside” vector features; ignored for boolean masks.

  • subsample (int | float) – Fraction (e.g. 0.1 for 10%) or maximum count (e.g. 10000) of eligible locations to use. A value of 1 keeps all locations. Counts describe the sampled locations.

  • subsample_per_group (bool) – Apply subsample within each combined group (True, stratified sampling) or once across all groups (False). Without by, both use one global sample.

  • random_state (int | Generator | None) – Seed to reproduce subsampling (e.g. 42), or an existing random generator.

  • strategy (Literal['auto', 'dense', 'sparse', 'groupwise']) – Combine chunk statistics for all groups (“dense”), only groups present in each chunk (“sparse”), or gather each complete group (“groupwise”). “auto” chooses from the statistics and group count; exact quantiles and custom functions require “auto” or “groupwise” for chunked data.

  • backend (Literal['geoutils', 'flox']) – Use the GeoUtils reducer (“geoutils”) or optional Flox reducer (“flox”) for grouped statistics; see stats() for the Flox restrictions.

  • subsampling_strategy (Literal['sequential', 'topk']) – “topk” keeps the same sampled locations across chunk layouts for a fixed seed; “sequential” draws random locations using traversal order and can depend on the chunks.

  • interpolation (Literal['nearest', 'linear', 'cubic', 'quintic', 'slinear', 'pchip', 'splinef2d']) – Raster values at point locations use interp_points() with SciPy methods “nearest”, “linear”, “slinear”, “cubic”, “quintic”, “pchip” or “splinef2d”. Raster groupers listed in categories use “nearest”.

  • align (Literal['raise', 'reproject']) – “raise” rejects different grids or coordinate systems; “reproject” aligns them to the output locations. Point inputs must still share the same ordered coordinates.

  • observed (bool) – Omit declared group combinations with no eligible locations (True), or include them (False).

  • return_masks (bool) – Also return masks keyed by group labels (e.g. table, masks = raster.stats(…)). Masks cover complete groups before subsampling. Requires by.

  • mp_config (MultiprocConfig | None) – Worker and tile settings for multiprocessing, e.g. MultiprocConfig(chunks=512). Cannot be combined with Dask inputs.

  • fractional (bool) – Use the exact area covered by each polygon for one vector grouping. Overlapping groups are calculated independently, and Reducers such as Mean() and Sum() receive the covered cell fractions.

  • overlap_backend (Literal['auto', 'exactextract', 'shapely']) – Library used to calculate polygon coverage of raster cells. Auto uses ExactExtract when it is installed and the grid is compatible, and otherwise uses Shapely.

  • error_structure (ErrorStructure | None) – Optional source error model for one supplied Reducer.

  • uncertainty_kwargs (Mapping[str, Any] | None) – Options passed to geoutils.uncertainty.propagate().

Return type:

Any

Returns:

A statistic, summary dictionary, grouped dataframe, or grouped dataframe and mask mapping.