geoutils.uncertainty.random_field

Contents

geoutils.uncertainty.random_field#

geoutils.uncertainty.random_field(error_structure, like=None, *, coordinates=None, predictors=None, n_fields=1, random_state=None, chunksizes=None, mp_config=None, backend='gpytorch', gpytorch_inducing_points='auto')[source]#

Generate random correlated error fields.

This function supports chunked execution with Dask/Multiprocessing, with spatial correlation that continues across chunk boundaries by sharing component seeds across the field.

The random field can be generated on a raster or point cloud support passed to like, and can account for multiple independent error component and heteroscedasticity as described in ErrorStructure.

Two backends are supported, with a slightly different approach: - GSTools, which reuses a global coordinate seed for chunk invariance, - GPyTorch, which reuses a shared inducing grid for chunk invariance.

Parameters:

  • error_structure (ErrorStructure) – Error model defined by magnitude and correlation components.

  • like (Any | None) – Optional Raster, Xarray DataArray, PointCloud, or GeoDataFrame defining output locations and type.

  • coordinates (ArrayLike | None) – Array of shape (n_observations, n_dimensions), in the correlation model’s distance units.

  • predictors (Mapping[str, Any] | None) – Named values used to calculate each component’s error magnitude (e.g. slope or elevation).

  • n_fields (int) – Number of independent fields.

  • random_state (int | Generator | None) – Seed or generator used for reproducible fields.

  • chunksizes (int | tuple[int, int] | None) – Dask raster chunk size as (rows, columns), or target point rows per Dask partition. Requires an Xarray raster or Dask GeoDataFrame so the result has the same type as the input.

  • mp_config (MultiprocConfig | None) – Worker and output file settings for multiprocessing fields. Xarray rasters and Dask GeoDataFrames cannot use multiprocessing because its output has a different type.

  • backend (Literal['gstools', 'gpytorch']) – Library used to draw correlated errors; GPyTorch is the default.

  • gpytorch_inducing_points (int | Literal['auto'] | None) – Target grid size for approximate GPyTorch fields. The default, “auto”, uses 256 points for spatial inputs and an exact draw for plain coordinates. Pass None for an exact eager draw.

Return type:

Any

Returns:

With like, a result of the same spatial object type, or a list when n_fields > 1. Dask results remain lazy. Multiprocessing Raster and PointCloud results are file-backed. Without like, an array of shape (n_observations,) or (n_fields, n_observations).

Contents