ds.rst.subsample() or Raster.subsample()

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

RasterBase.subsample(subsample, *, bands=None, mask=None, skip_nodata=True, random_state=None, as_array=False, return_indices=False, strategy='topk', force_pixel_offset='ul', force_output_to_memory=False, mp_config=None, pointcloud_return_type=None)[source]#

Randomly sample raster cells without replacement.

Overloads:

The first selected band defines eligible cells when skip_nodata=True. Its selected row and column positions are applied to every requested band, so values and point coordinates remain aligned. Auxiliary band nodata alone does not remove a point.

Raster inputs return a PointCloud by default. Xarray accessor outputs follow config[“pointcloud_return_type”], which defaults to a DataArray. Dask outputs stay lazy. With as_array=True, return values from one band or their source row and column positions.

Parameters:

  • subsample (float | int) – Fraction of eligible cells to extract when at most 1, otherwise the maximum cell count.

  • bands (int | Iterable[int] | Mapping[str, int] | None) – Bands to return. By default, point output includes every band and array output includes band one. An integer selects one band. An iterable selects bands with default b<band> column names, while a mapping gives column names as keys and band numbers as values. The first selected band controls eligible cells. Array output accepts only one integer band.

  • mask (RasterBase | DataArray | geoutils.vector.base.VectorBase | GeoDataFrame | ArrayLike | None) – With as_array=True, restrict eligible raster cells with a boolean or spatial mask.

  • skip_nodata (bool) – Whether to exclude cells where the first selected band is nodata.

  • random_state (int | Generator | None) – Random generator or seed used to make sampling reproducible.

  • as_array (bool) – Return sampled values or positions instead of a point cloud or dataframe.

  • return_indices (bool) – With as_array=True, return row and column positions instead of values.

  • strategy (Literal['sequential', 'topk']) – Use chunk-independent top-k sampling or sequential sampling.

  • force_pixel_offset (Literal['center', 'ul', 'ur', 'll', 'lr']) – Pixel position used to calculate each point coordinate.

  • force_output_to_memory (bool) – Keep the complete output in memory instead of using the automatic chunked path.

  • mp_config (MultiprocConfig | None) – Worker, tile, and output settings for multiprocessing. Point output uses GeoPackage, LAS or LAZ; LAS/LAZ stores the first selected band as elevation. Large array output uses NumPy format.

  • pointcloud_return_type (Literal['dataarray', 'dataset', 'geodataframe'] | None) – Returned representation: dataarray, dataset, or geodataframe. None uses config[“pointcloud_return_type”] for accessors, or returns a PointCloud for GeoUtils objects.

Returns:

Point output with one row per sampled cell, one-dimensional sampled values, or row/column positions.