_kriging module

_kriging.py

Ordinary kriging of scattered 2D data and hole filling in the (u, v) plane of a CurvilinearFrame.

class pyrockfall._kriging.Variogram(model: str = 'spherical', psill: float = 1.0, range: float = 1.0, nugget: float = 0.0, aniso: float = 1.0, angle: float = 0.0)[source]

Bases: object

Variogram model with geometric anisotropy.

model

One of VARIOGRAM_MODELS.

Type:

str

psill

Partial sill (sill minus nugget). For "linear" the value reached at range, i.e. the slope is psill / range.

Type:

float

range

Range along the major axis (practical range for "exponential" and "gaussian").

Type:

float

nugget

Nugget: discontinuity at the origin. The model is zero at zero distance, so kriging honours the data exactly.

Type:

float

aniso

Range along the major axis divided by the range across it (1 = isotropic).

Type:

float

angle

Direction of the major axis, in degrees counter-clockwise from the first coordinate.

Type:

float

model: str = 'spherical'
psill: float = 1.0
range: float = 1.0
nugget: float = 0.0
aniso: float = 1.0
angle: float = 0.0
gamma(h) → ndarray[source]

Semivariance at (isotropic) distance h.

transform(xy) → ndarray[source]

Rotate and scale coordinates so that the model is isotropic in them.

to_dict() → dict[source]
pyrockfall._kriging.fit_variogram(xy, values, model: str = 'spherical', *, nlags: int = 20, aniso: float = 1.0, angle: float = 0.0, max_points: int = 2000, max_lag: float | None = None, seed: int = 0) → Variogram[source]

Fit a variogram model to scattered data.

The experimental variogram is computed from all pairs of (at most max_points randomly chosen) data points, binned into nlags lags up to max_lag, and the model is fitted by weighted least squares with more weight on short, well-populated lags.

Parameters:
  • xy ((n, 2) array) – Data locations.

  • values ((n,) array) – Data values.

  • model (str) – One of VARIOGRAM_MODELS.

  • nlags (int) – Number of lag bins.

  • aniso (float) – Geometric anisotropy (see Variogram). They are imposed, not fitted.

  • angle (float) – Geometric anisotropy (see Variogram). They are imposed, not fitted.

  • max_points (int) – Largest number of points used for the experimental variogram.

  • max_lag (float, optional) – Largest lag. Defaults to half the largest distance between points.

Return type:

Variogram

pyrockfall._kriging.ordinary_kriging(xy, values, xy_new, variogram: Variogram, *, n_closest: int | None = None, chunk_bytes: float = 150000000.0) → Tuple[ndarray, ndarray][source]

Ordinary kriging at scattered locations.

Parameters:
  • xy ((n, 2) array) – Data locations.

  • values ((n,) or (n, k) array) – Data values. Several columns are kriged with the same weights (one factorisation), e.g. the indicators of all classes.

  • xy_new ((m, 2) array) – Locations to estimate.

  • variogram (Variogram) – Variogram model (with its anisotropy).

  • n_closest (int, optional) – None (default) uses all data for every estimate: one system is factorised once, so the estimate is continuous. A number uses only the n_closest nearest data for each estimate (moving neighbourhood), which scales to very large data sets.

Returns:

  • estimate ((m,) or (m, k) array)

  • variance ((m,) array) – Kriging variance, in the units of the variogram.

pyrockfall._kriging.poly_design(uv, order: int, center, scale: float) → ndarray[source]

Design matrix of a 2D polynomial of total degree <= order, on coordinates normalised as (uv - center) / scale.

pyrockfall._kriging.find_holes(uv, cell: float, *, extra_uv=None, min_cells: int = 4)[source]

Locate the missing parts of a 2D point set.

The points are rasterised on a grid of square cells. A cell is missing if it is empty and either enclosed by occupied cells, or contains one of the extra_uv locations (e.g. points that were removed). Connected missing cells form a hole.

Parameters:
  • uv ((n, 2) array) – Point locations.

  • cell (float) – Cell size.

  • extra_uv ((r, 2) array, optional) – Locations known to be missing.

  • min_cells (int) – Holes with fewer cells are ignored (sampling noise).

Returns:

  • labels ((nu, nv) int array) – 0 where nothing is missing, otherwise the hole number (1..n_holes).

  • n_holes (int)

  • origin ((2,) array) – Coordinates of the corner of cell [0, 0].

  • counts ((nu, nv) int array) – Number of points per cell.

pyrockfall._kriging.fill_holes_uv(uvw, attrs: Dict[str, Tuple[ndarray, str]] | None = None, *, cell: float, removed_uv=None, spacing: float | None = None, min_cells: int = 4, ring_scale: float = 0.5, attr_ring_scale: float = 1.0, max_train: int = 2000, n_closest: int | None = None, variogram: str = 'spherical', attr_variogram: str | None = None, trend_order: int = 1, nlags: int = 20, aniso: float = 10.0, angle: float = 0.0, w_aniso: float = 1.0, shared_variogram: bool = True, seed: int = 0) → dict[source]

Create points in the holes of a point set and krige their height and attributes.

Parameters:
  • uvw ((n, 3) array) – Existing points: (u, v) in the plane and height w above it.

  • attrs (dict) – name -> (values, kind) with values of shape (n,) or (n, k) and kind either "categorical" (indicator kriging: a probability per class) or "continuous" (ordinary kriging).

  • cell (float) – Cell size of the occupancy grid used to find the holes.

  • removed_uv ((r, 2) array, optional) – Locations of points that were removed; lets holes that reach the edge of the point set be found.

  • spacing (float, optional) – Spacing of the new points. Defaults to the spacing that matches the density of the existing points.

  • min_cells (int) – Smallest hole, in cells.

  • ring_scale (float) – Width of the ring of existing points used for the height and for the attributes, as a fraction of the hole’s equivalent diameter.

  • attr_ring_scale (float) – Width of the ring of existing points used for the height and for the attributes, as a fraction of the hole’s equivalent diameter.

  • max_train (int) – Largest number of ring points used per kriging system (the ring is thinned evenly to this number).

  • n_closest (int, optional) – Moving neighbourhood size (see ordinary_kriging()).

  • variogram (str) – Variogram model for the height and for the attributes (default: the same).

  • attr_variogram (str) – Variogram model for the height and for the attributes (default: the same).

  • trend_order (int) – Order (0, 1 or 2) of the polynomial trend removed from w before kriging.

  • aniso (float) – Anisotropy of the attributes: ranges along the direction angle (degrees CCW from u) are aniso times longer than across it.

  • angle (float) – Anisotropy of the attributes: ranges along the direction angle (degrees CCW from u) are aniso times longer than across it.

  • w_aniso (float) – Same ratio for the height w (1 = isotropic), along the same direction.

  • shared_variogram (bool) – Use one variogram for all classes of a categorical attribute (fitted on the class whose proportion is closest to 0.5), so the probabilities sum to 1 before any correction.

Returns:

  • dict with keys

  • uvw (m, 3), std (m,) kriging standard deviation of w, hole

  • (m,) hole number of each new point, nearest (m,) index of the nearest

  • existing point, attrs (name -> dict) and holes (one dict of

  • diagnostics per hole).

class pyrockfall._kriging.GaussianField(xy, variogram: Variogram, *, cells_per_range: int = 20, max_cells: int = 1024)[source]

Bases: object

Unit-variance stationary Gaussian random field at fixed 2D points.

The correlation is that of a Variogram (shape, range, anisotropy and nugget): rho(h) = 1 - gamma(h) / (psill + nugget) away from the origin. The field is simulated on a regular grid by circulant embedding (FFT) and interpolated bilinearly to the points. A bilinear average of correlated grid values has a variance slightly below 1; this is corrected exactly per point, so the field has unit variance at every point. The nugget is added as independent noise.

A "linear" variogram has no stationary covariance; it is replaced by a spherical one with the same range.

Parameters:
  • xy ((n, 2) array) – Points at which the field is evaluated.

  • variogram (Variogram) – Correlation model.

  • cells_per_range (int) – Grid resolution, in cells per range (across the shortest axis).

  • max_cells (int) – Largest number of grid cells along an axis (the grid is coarsened if needed).

sample(rng: Generator, k: int) → ndarray[source]

k independent realisations of the field at the points, shape (k, n).