ds.rst.variogram() or Raster.variogram()

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

RasterBase.variogram(*, band=1, n_pairs=1000000, sampling='loglag', estimator='dowd', bins='log', n_lags=24, min_lag=None, max_lag=None, n_runs=1, model=None, fit_kwargs=None, random_state=None, mask=None, **pair_sampling_kwargs)[source]#

Estimate a lightweight empirical variogram from raster pairs.

Parameters:

  • band (int) – Raster band to sample, counting from 1.

  • n_pairs (int) – Number of finite pairs targeted in each run (e.g. 100_000).

  • sampling (Literal['loglag', 'random_xy']) – How to select pairs: "loglag" balances short and long distances, while "random_xy" selects endpoints independently.

  • estimator (str | Callable[[NDArray[floating[Any] | integer[Any]]], float]) – Semivariance estimator from SciKit-GStat: "dowd", "matheron", "cressie", "genton", "minmax", "entropy" or "percentile". A function can instead map absolute pair differences to one value per distance bin.

  • bins (Literal['log', 'uniform'] | Iterable[float]) – Distance bins: "log" for logarithmic spacing, "uniform" for equal widths, or explicit edges (e.g. [1, 10, 100]).

  • n_lags (int) – Number of distance bins when bins is "log" or "uniform".

  • min_lag (float | None) – Minimum sampled distance in CRS units; defaults to the smaller pixel dimension.

  • max_lag (float | None) – Maximum sampled distance in CRS units; defaults to the diagonal between outermost cell centers.

  • n_runs (int) – Independent samples to average; repeat sampling to estimate each distance bin’s standard error.

  • model (str | Callable[..., Any] | list[str | Callable[..., Any]] | None) – SciKit-GStat model to fit: "spherical", "exponential", "gaussian", "cubic", "stable" or "matern", or the corresponding model function. Sum a list of models ordered from short to long range (e.g. [“spherical”, “exponential”]). None keeps only the empirical variogram.

  • fit_kwargs (dict[str, Any] | None) – Options for Variogram.fit(): use_nugget, bounds, p0 or maxfev (e.g. {“use_nugget”: True}); optimization uses SciPy curve_fit().

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

  • mask (RasterBase | DataArray | geoutils.vector.base.VectorBase | GeoDataFrame | ArrayLike | None) – Cells to keep: True values in a boolean mask or aligned mask raster, or cells inside vector geometries.

  • pair_sampling_kwargs (Any) – Extra pairsample() options (e.g. strategy or max_rounds).

Return type:

Variogram

Returns:

Variogram with distance bins, pair counts and semivariance, plus sampling errors and a fitted model when requested.