_kriging module¶
_kriging.py¶
Ordinary kriging of scattered 2D data and hole filling in the (u, v) plane
of a CurvilinearFrame.
Variogram,fit_variogram()andordinary_kriging()are general-purpose and work on plain arrays.find_holes()locates the missing parts of a point set on an occupancy grid andfill_holes_uv()creates new points there, kriging their heightwabove the(u, v)plane and any number of attributes.
- 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:
objectVariogram model with geometric anisotropy.
- psill¶
Partial sill (sill minus nugget). For
"linear"the value reached atrange, i.e. the slope ispsill / range.- Type:
- nugget¶
Nugget: discontinuity at the origin. The model is zero at zero distance, so kriging honours the data exactly.
- Type:
- angle¶
Direction of the major axis, in degrees counter-clockwise from the first coordinate.
- Type:
- 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:
- 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:
- 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 heightwabove it.attrs (dict) –
name -> (values, kind)withvaluesof shape(n,)or(n, k)andkindeither"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
wbefore 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 ofw,hole(m,) hole number of each new point,
nearest(m,) index of the nearestexisting point,
attrs(name -> dict) andholes(one dict ofdiagnostics per hole).
- class pyrockfall._kriging.GaussianField(xy, variogram: Variogram, *, cells_per_range: int = 20, max_cells: int = 1024)[source]¶
Bases:
objectUnit-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: