xdem.spatialstats.patches_method

Contents

xdem.spatialstats.patches_method#

xdem.spatialstats.patches_method(values, areas, gsd=None, stable_mask=None, unstable_mask=None, statistics_in_patch=(<function nanmean>, ), statistic_between_patches=<function nmad>, perc_min_valid=80.0, patch_shape='circular', vectorized=True, convolution_method='scipy', n_patches=1000, return_in_patch_statistics=False, random_state=None)[source]#

Monte Carlo patches method that samples multiple patches of terrain, square or circular, of a certain area and computes a statistic in each patch. Then, another statistic is computed between all patches. Typically, a statistic of central tendency (e.g., the mean) is computed for each patch, then a statistic of spread (e.g., the NMAD) is computed on the central tendency of all the patches. This specific procedure gives an empirical estimate of the standard error of the mean.

Overloads:

  • values (NDArrayf | RasterType), areas (list[float]), gsd (float), stable_mask (NDArrayf | VectorType | gpd.GeoDataFrame), unstable_mask (NDArrayf | VectorType | gpd.GeoDataFrame), statistics_in_patch (tuple[Callable[[NDArrayf], np.floating[Any]] | str]), statistic_between_patches (Callable[[NDArrayf], np.floating[Any]]), perc_min_valid (float), patch_shape (str), vectorized (bool), convolution_method (str), n_patches (int), return_in_patch_statistics (Literal[False]), random_state (int | np.random.Generator | None) → pd.DataFrame

  • values (NDArrayf | RasterType), areas (list[float]), gsd (float), stable_mask (NDArrayf | VectorType | gpd.GeoDataFrame), unstable_mask (NDArrayf | VectorType | gpd.GeoDataFrame), statistics_in_patch (tuple[Callable[[NDArrayf], np.floating[Any]] | str]), statistic_between_patches (Callable[[NDArrayf], np.floating[Any]]), perc_min_valid (float), patch_shape (str), vectorized (bool), convolution_method (str), n_patches (int), return_in_patch_statistics (Literal[True]), random_state (int | np.random.Generator | None) → tuple[pd.DataFrame, pd.DataFrame]

The function returns the exact areas of the patches, which might differ from the input due to rasterization of the shapes.

By default, the fast vectorized method based on a convolution of all pixels is used, but only works with the mean. To compute other statistics (possibly a list), the non-vectorized method that randomly samples quadrants of the input array up to a certain number of patches “n_patches” can be used.

The per-patch statistics can be returned as a concatenated dataframe using the “return_in_patch_statistics” argument, not done by default due to large sizes.

Parameters:

  • values (NDArray[floating[Any]] | TypeVar(RasterType, bound= Raster)) – Values as array or Raster

  • areas (list[float]) – List of patch areas to process (squared unit of ground sampling distance; exact patch areas might not always match these accurately due to rasterization, and are returned as outputs)

  • gsd (float) – Ground sampling distance

  • stable_mask (NDArray[floating[Any]] | TypeVar(VectorType, bound= Vector) | GeoDataFrame) – Vector shapefile of stable terrain (if values is Raster), or boolean array of same shape as values

  • unstable_mask (NDArray[floating[Any]] | TypeVar(VectorType, bound= Vector) | GeoDataFrame) – Vector shapefile of unstable terrain (if values is Raster), or boolean array of same shape as values

  • statistics_in_patch (tuple[Callable[[NDArray[floating[Any]]], floating[Any]] | str]) – List of statistics to compute in each patch (count is computed by default; only mean and count supported for vectorized version)

  • statistic_between_patches (Callable[[NDArray[floating[Any]]], floating[Any]]) – Statistic to compute between all patches, typically a measure of spread, applied to the first in-patch statistic, which is typically the mean

  • perc_min_valid (float) – Minimum valid area in the patch

  • patch_shape (str) – Shape of patch, either “circular” or “square”

  • vectorized (bool) – Whether to use the vectorized (convolution) method or the for loop in quadrants

  • convolution_method (str) – Convolution method to use, either “scipy” or “numba” (only for vectorized)

  • n_patches (int) – Maximum number of patches to sample (only for non-vectorized)

  • return_in_patch_statistics (bool) – Whether to return the dataframe of statistics for all patches and areas

  • random_state (int | Generator | None) – Random state or seed number to use for calculations (only for non-vectorized, for testing)

Returns:

Dataframe of statistic between patches with independent patches count and exact areas, (Optional) Dataframe of per-patch statistics

Contents