gdf.pc.stats() or PointCloud.stats()

gdf.pc.stats() or PointCloud.stats()#

PointCloudBase.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]#

Compute statistics, global or grouped by categories, bins, or vector zones.

Omit by to summarize the active point values. Grouped inputs follow the same by, categories, bins, and vector-zone interface as Raster.stats().

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 (str | Iterable[str] | Mapping[str, Any] | None) – Point columns to summarize (e.g. “height” or [“height”, “intensity”]); defaults to the main data attribute. 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'] | geoutils.raster.base.RasterBase | DataArray | PointCloudBase | GeoDataFrame | None) – Grid or ordered point locations on which to calculate statistics (e.g. at=reference or at=”self”). Defaults to this point cloud’s locations.

  • mask (geoutils.raster.base.RasterBase | DataArray | geoutils.vector.base.VectorBase | GeoDataFrame | ArrayLike | None) – Locations to include (True in a boolean mask, e.g. mask=points.data > 1000, or vector features). 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 = points.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 when grouping values from a raster grid.

  • overlap_backend (Literal['auto', 'exactextract', 'shapely']) – Library used to calculate polygon coverage of raster cells.

  • 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.