ds.rst.cosample() or Raster.cosample()

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

RasterBase.cosample(other, *, band=1, other_band=1, auxiliary=None, auxiliary_at=None, at=None, mask=None, mask_mode='inside', subsample=1, random_state=None, strategy='topk', raster_point_mode=None, grid_method='linear', resample_method='linear', grid_kwargs=None, resample_kwargs=None, align='raise', mp_config=None)[source]#

Sample this raster and another dataset at common finite locations.

By default, raster values are resampled at point locations when either primary input is a point cloud. Use raster_point_mode="grid_points" to grid point values onto the raster instead. An explicit at chooses the exact output locations and must agree with any explicit mode. Raw auxiliary arrays must identify the primary input whose grid or point ordering they follow.

Spatial inputs, explicit output support and raster or point masks must use one family: Raster/PointCloud objects, or DataArray/GeoDataFrame objects. The latter may mix eager and Dask storage. Plain arrays and vector outlines are accepted with either family.

Parameters:

  • other (RasterBase | DataArray | PointCloudBase | GeoDataFrame | ArrayLike) – Dataset to sample alongside this raster. A plain array follows this raster’s grid.

  • band (int) – Band selected from this raster, counting from one.

  • other_band (int) – Band selected from other if it is a raster, counting from one.

  • auxiliary (Mapping[str, Any] | None) – Additional values by output name (e.g. {“slope”: slope_raster}). Select a raster band with {“slope”: (slope_raster, 2)} or a point column with {“intensity”: (points, “intensity”)}. Spatial inputs without a selector use the first raster band or active point values.

  • auxiliary_at (Literal['self', 'other'] | Mapping[str, Literal['self', 'other']] | None) – Input locations followed by plain auxiliary arrays: “self”, “other”, or a choice per name (e.g. {“slope”: “other”}). Spatial auxiliaries use their own coordinates.

  • at (Literal['self', 'other'] | RasterBase | DataArray | PointCloudBase | GeoDataFrame | None) – Output locations: “self”, “other”, or a reference raster/point cloud. Defaults to the other point cloud’s locations when present, or this raster’s grid otherwise.

  • mask (RasterBase | DataArray | geoutils.vector.base.VectorBase | GeoDataFrame | ArrayLike | None) – Locations eligible for sampling, defined by a boolean array, spatial mask, or vector outlines.

  • mask_mode (Literal['inside', 'outside']) – Whether a vector mask keeps locations “inside” or “outside” its geometries.

  • subsample (int | float) – Fraction of common finite locations (e.g. 0.1), or maximum count (e.g. 1000); 1 keeps all.

  • random_state (int | Generator | None) – Seed or random generator for reproducible sampling (e.g. 42).

  • strategy (Literal['sequential', 'topk']) – Sampling with “topk” or “sequential”; “topk” keeps the same seeded sample across chunk sizes.

  • raster_point_mode (Literal['grid_points', 'resample_raster'] | None) – Conversion direction: “grid_points” places points on a raster, “resample_raster” reads rasters at points. Defaults to at’s locations, or point locations when available. Must agree with at.

  • grid_method (Literal['nearest', 'linear', 'cubic', 'idw'] | Literal['mean', 'average', 'minimum', 'min', 'maximum', 'max', 'range', 'count', 'stdev', 'average_distance', 'average_distance_pts'] | Interpolator | Reducer) – Point gridding by SciPy interpolation (“nearest”, “linear”, “cubic”), or circular “idw”, “mean”, “minimum”, “maximum”, “range”, “count”, “stdev”, “average_distance”, “average_distance_pts”. The aliases “average”, “min” and “max” select “mean”, “minimum” and “maximum”.

  • resample_method (Literal['nearest', 'linear', 'cubic', 'quintic', 'slinear', 'pchip', 'splinef2d'] | Literal['reduce']) – Raster interpolation using the SciPy methods “nearest”, “linear”, “cubic”, “quintic”, “slinear”, “pchip” or “splinef2d”. Window reduction (“reduce”) is not implemented.

  • grid_kwargs (Mapping[str, Any] | None) – Options for PointCloud.grid(), e.g. {“radius”: 2, “min_points”: 3} sets a two-pixel radius and minimum of three finite points for circular methods. Other options include “distance_power” for IDW and “engine” (“scipy” or “numba”). Set locations and method with at and grid_method.

  • resample_kwargs (Mapping[str, Any] | None) – Options for Raster.interp_points(), e.g. {“nodata_handling”: “ignore”}. The choices are “nearest”, “ignore”, “propagate”, a half-order rule, or a non-negative distance in pixels. Set locations, band and method with the corresponding cosample() arguments.

  • align (Literal['raise', 'reproject']) – Handling of mismatched grids or coordinate systems: “raise” an error, or “reproject” to match at. Point inputs must still share the same ordered coordinates when sampled at points.

  • mp_config (MultiprocConfig | None) – Worker and tile settings for multiprocessing. Raster output uses its outfile; cannot be combined with Dask inputs.

Return type:

RasterBase | DataArray | PointCloudBase | GeoDataFrame

Returns:

Raster or point cloud on the selected support; Xarray DataArray or eager/lazy GeoDataFrame for accessor calls. Bands or columns contain “self”, “other”, then auxiliaries in mapping order. Raster band names are stored in tags["long_name"] (Xarray attrs["long_name"]). Point outputs use “self” as their active data attribute and preserve the support index and order.