krigekit.variogram_empirical#

Empirical variogram clouds, binning, directions, and anisotropy estimates.

Functions#

raw_vgm(coords, vals[, cutoff, times, t_cutoff, ...])

Compute the raw empirical variogram cloud (all admissible pairs).

raw_cross_vgm(coords, valsA, valsB[, cutoff, times, ...])

Traditional (LMC) cross-variogram cloud on collocated data.

cross_vgm(coordsA, valsA, coordsB, valsB[, cutoff, ...])

Cross-variogram cloud between two co-located variables A and B.

avg_vgm(rawvgm[, h_col, t_col, cutoff, t_cutoff, ...])

Bin a variogram cloud and average it.

distance_pnt_line(dx, dy, azimuth)

Perpendicular distance from offset vectors (dx, dy) to a line through

filter_vgm(dx, dy, azimuth, azimuth_anis[, bandwidth, ...])

Boolean mask selecting pairs aligned with azimuth_anis.

estimate_aniso_angle(rawvgm[, x, y, dist, vgm, r_max, ...])

Estimate anisotropy directions from a variogram cloud via weighted PCA.

fit_aniso_angle(rawvgm[, n_struct, x, y, z, dist, ...])

Fit the 3-D anisotropy orientation by a model-based profile search.

estimate_angle_angular_profile(rawvgm[, angle, dist, ...])

Mean variogram as a function of azimuth, within a near-origin radius.

directional_vgm(rawvgm, directions[, h_width, h_bins, ...])

Experimental directional variograms along arbitrary (2D/3D) axes.

Module Contents#

krigekit.variogram_empirical.raw_vgm(coords, vals, cutoff=np.inf, times=None, t_cutoff=np.inf, calc_angle=False, maxobs=None, nmax=None, metric=None, seed=None, verbose=True, great_circle=False, anisotropy=None, n_jobs=None, max_memory_fraction=0.8)#

Compute the raw empirical variogram cloud (all admissible pairs).

Parameters:

  • coords (array-like, shape (n, dim)) – Sample coordinates; dim may be 1, 2 or 3.

  • vals (array-like, shape (n,)) – Sample values.

  • cutoff (float, optional) – Maximum spatial lag |h| to keep (default: no cutoff).

  • times (array-like, optional) – Per-sample time stamps for a space-time variogram.

  • t_cutoff (float, optional) – Maximum absolute time lag to keep.

  • calc_angle (bool, optional) – Also compute angle_h (and angle_v in 3D) for each pair.

  • maxobs (int, optional) – Randomly subsample to at most maxobs points before pairing.

  • seed (int, optional) – Random seed for the subsampling.

  • verbose (bool, optional) – Print a progress indicator.

  • great_circle (bool, optional) – Treat 2D coordinates as (lon, lat) in degrees and use the great-circle distance (km) for the distance lag and cutoff.

  • anisotropy (dict, optional) – Arguments accepted by calc_anisotropic_lag(). When supplied, cutoff is applied to the equivalent major-axis lag and the cloud includes an anisotropic_distance column. The physical Euclidean lag remains available as distance.

  • n_jobs (int, optional) – Number of worker threads for vectorized pair chunks. None (default) chooses adaptively from the post-maxobs candidate-pair count, up to four workers. 1 is sequential and -1 uses all available CPUs.

  • max_memory_fraction (float or None, optional) – Refuse clouds whose estimated final numeric columns exceed this fraction of currently available RAM (default 0.8). None disables the safety check.

Returns:

pandas.DataFrame – The variogram cloud (see module docstring for the columns).

krigekit.variogram_empirical.raw_cross_vgm(coords, valsA, valsB, cutoff=np.inf, times=None, t_cutoff=np.inf, calc_angle=False, maxobs=None, nmax=None, metric=None, seed=None, verbose=True, anisotropy=None, n_jobs=None, max_memory_fraction=0.8)#

Traditional (LMC) cross-variogram cloud on collocated data.

Both variables are measured at the same coords (isotopic data). Pairs are formed within the single point set and the cross-semivariance:

gamma_AB(h) = 0.5 * (A_i - A_j) * (B_i - B_j)

is stored in the variogram column. Unlike the pseudo estimator in cross_vgm(), this is symmetric in A/B, its sill is the LMC cross-sill you can feed into cokriging, and it costs O(n**2 / 2) rather than O(nA*nB).

The returned cloud has exactly the same columns as raw_vgm(), so it flows straight into avg_vgm(), estimate_aniso_angle(), directional_vgm() and the variogram-map plots. Calling it with valsB is valsA reproduces the direct variogram of A.

For heterotopic data (A and B at different locations) the true cross-variogram is not computable; use cross_vgm() (pseudo estimator) or restrict to a collocated subset before calling this function.

n_jobs=None adaptively selects up to four pair-chunk workers after maxobs and cutoff candidate generation. 1 is sequential and -1 uses all available CPUs.

max_memory_fraction defaults to 0.8 and raises MemoryError when the estimated final cloud exceeds that fraction of available RAM. Pass None to disable the guard.

krigekit.variogram_empirical.cross_vgm(coordsA, valsA, coordsB, valsB, cutoff=np.inf, residual=True, timesA=None, timesB=None, t_cutoff=np.inf, calc_angle=False, maxobs=None, maxobsA=None, maxobsB=None, seed=None, verbose=True, anisotropy=None, n_jobs=None, max_memory_fraction=0.8)#

Cross-variogram cloud between two co-located variables A and B.

Pairs are formed across the two data sets (every A vs every B). When residual is True the means are removed first so the result is a cross-covariance-style estimator.

Warning

This is the pseudo cross-variogram 0.5 * E[(A(x) - B(x+h))**2], not the linear-model-of-coregionalisation (LMC) cross-variogram 0.5 * E[(A(x) - A(x+h)) * (B(x) - B(x+h))]. Its sill mixes var(A) + var(B) - 2*cov(A, B), so do not read an LMC cross-sill directly off it. For heterotopic data (A and B at different locations) the true cross-variogram is not computable and this pseudo form is a reasonable substitute; for a cokriging cross-sill, derive cov(A, B) from collocated hard-data pairs instead.

n_jobs=None adaptively selects up to four pair-chunk workers after subsampling and cutoff candidate generation. 1 is sequential and -1 uses all available CPUs.

max_memory_fraction defaults to 0.8 and raises MemoryError when the estimated final cloud exceeds that fraction of available RAM. Pass None to disable the guard.

krigekit.variogram_empirical.avg_vgm(rawvgm, h_col='distance', t_col=None, cutoff=None, t_cutoff=None, h_width=None, t_width=None, h_bins=None, t_bins=None, tor_hori=None, tor_vert=None, angleh=None, anglev=None, angleh_tor=15, anglev_tor=10, robust=None, estimator='matheron', vgm_col='variogram')#

Bin a variogram cloud and average it.

Supports distance (and optional time) binning, directional and bandwidth filtering, and either the classic (Matheron) mean or the robust Cressie–Hawkins estimator (estimator="cressie"), Dowd ("dowd"), or Genton. h_width and t_width may be positive scalars for fixed-width bins or one-dimensional arrays of explicit bin edges. Edge-array bins are left-closed and right-open, except that the final edge is included; lags outside the edge range are omitted. Arrays passed through the legacy h_bins and t_bins arguments use the same edge convention.

Directional filtering follows variogram-axis symmetry. If only angleh is supplied, azimuths angleh and angleh + 180 are treated as the same horizontal axis. If both angleh and anglev are supplied, the same 3D axis is represented by (angleh, anglev) and the reversed lag vector (angleh + 180, -anglev).

Returns:

pandas.DataFrame – Grouped variogram table whose columns are a (variable, statistic) MultiIndex with statistics mean, std and count. The averaged semivariogram is available as result[(vgm_col, "mean")].

krigekit.variogram_empirical.distance_pnt_line(dx, dy, azimuth)#

Perpendicular distance from offset vectors (dx, dy) to a line through the origin with the given azimuth (degrees, clockwise from +Y).

krigekit.variogram_empirical.filter_vgm(dx, dy, azimuth, azimuth_anis, bandwidth=None, angle_tol=10)#

Boolean mask selecting pairs aligned with azimuth_anis.

This is a 2D/horizontal-axis helper. A pair is kept when its azimuth is within angle_tol of the target axis, treating azimuth_anis and azimuth_anis + 180 as equivalent. If bandwidth is given, the pair must also fall within bandwidth / 2 of the directional line.

For 3D azimuth+dip filtering, use avg_vgm(), which flips the sign of dip for the reversed azimuth.

krigekit.variogram_empirical.estimate_aniso_angle(rawvgm, x='d0', y='d1', dist='distance', vgm='variogram', r_max=None, z='d2', dim3d=False, robust=False, get_eigens=False, dx=None, dy=None, dz=None)#

Estimate anisotropy directions from a variogram cloud via weighted PCA.

Near-origin lags are grouped into cells, each cell weighted inversely by its (normalised) mean variogram – low variogram means strong continuity – and an eigen-decomposition of the weighted second moment about the origin yields the principal axes. Each cell contributes its mean lag vector (not the bin edge), so the estimate is insensitive to the bin size. Bins are sized per axis from each axis’s own lag extent, so a thin or short axis (e.g. a shallow z slab) is still resolved rather than collapsing under a single horizontal-scale spacing. Pass dx / dy / dz to override the spacing per axis.

The estimate is sensitive to r_max: too small and a gridded cloud is dominated by axis-aligned lags (the sampling lattice – which can throw the azimuth off by tens of degrees), too large and it mixes nested structures. A good choice is roughly half the shortest structure’s range. Sweeping r_max to find a stable value does not help reliably – there is no clean plateau – so prefer one principled near-origin radius. This is an approximate orientation estimate (a few degrees at best), best used to seed a fixed-orientation fit (VariogramModel.fit_anisotropy()), not as a final answer.

Returns:

  • If ``get_eigens`` is True ((eigvals, eigvecs) sorted descending.)

  • If ``dim3d`` is False (((azimuth_deg,), (anis1,)).)

  • If ``dim3d`` is True (((azimuth_deg, dip_deg, plunge_deg), (anis1, anis2)).)

  • azimuth_deg is the compass azimuth (0 = North, 90 = East) of the major

  • (maximum-continuity) axis, dip_deg its tilt below the horizontal plane

  • (positive downward), and plunge_deg the twist of the minor axes about

  • the major axis – exactly the azimuth / dip / plunge convention of

  • the model and the Fortran engine, so the angles feed straight into

  • VariogramModel.set_vgm(). anis1 and anis2 are the

  • minor1/major and minor2/major axis-length ratios (the same meaning as the

  • engine’s anis1 / anis2 minor-axis ratios), estimated from the

  • eigenvalue spectrum. plunge is folded into (-90, 90] and is the

  • least well-determined angle from sparse clouds.

krigekit.variogram_empirical.fit_aniso_angle(rawvgm, n_struct=1, x='d0', y='d1', z='d2', dist='distance', vgm='variogram', n_bins=16, starts=None, use_seed=True, max_nfev=500)#

Fit the 3-D anisotropy orientation by a model-based profile search.

Unlike estimate_aniso_angle() (a fast PCA of the lag cloud), this fits the model to the data: for each candidate orientation, n_struct spherical structures’ sills and anisotropic ranges are fitted with the orientation held fixed, against a denoised binned cloud, and the orientation giving the lowest residual is kept. The objective is multi-modal, so the search is multi-started over a coarse (azimuth, dip) grid plus the estimate_aniso_angle() seed.

Returns ((azimuth, dip, plunge), (anis1, anis2)) – the same shape as estimate_aniso_angle() – but anis1 / anis2 are the fitted minor/major range ratios of the strongest structure (true ratios, not the PCA spread proxy).

This is far more robust on scattered, strongly anisotropic clouds, where the PCA seed can be tens of degrees wrong, at a higher cost. It is not immune to a regular sampling lattice: on gridded clouds the lattice biases the residual, and the near-origin PCA seed may be better. Spherical structures are used as the orientation probe regardless of the eventual model type.

Parameters:

  • rawvgm (pandas.DataFrame) – Raw variogram cloud with signed lag columns x/y/z and a vgm value column.

  • n_struct (int) – Number of nested spherical structures to fit while probing orientation.

  • n_bins (int) – Cells per cutoff radius for the denoising bins (lag cells use the cell mean lag vector, so the result is insensitive to the exact bin size).

  • starts (sequence of (azimuth, dip, plunge), optional) – Override the default coarse start grid.

  • use_seed (bool) – Also start from the estimate_aniso_angle() PCA estimate.

krigekit.variogram_empirical.estimate_angle_angular_profile(rawvgm, angle='angle_h', dist='distance', r_profile=None, da=10, a_tol=2.5, close=False, vgm='variogram', dim3d=False)#

Mean variogram as a function of azimuth, within a near-origin radius.

Sweeps the azimuth in steps of da degrees (overlapping by a_tol) and returns the per-sector mean of angle, dist and vgm.

krigekit.variogram_empirical.directional_vgm(rawvgm, directions, h_width=None, h_bins=15, bandwidth=None, angle_tol=22.5, dist='distance', vgm='variogram', robust=False, dim=None)#

Experimental directional variograms along arbitrary (2D/3D) axes.

For each direction the pairs whose lag vector falls within angle_tol of that axis (and within the perpendicular bandwidth) are selected and binned by lag distance – the multi-dimensional analogue of the gstools vario_estimate(direction=...) workflow.

Parameters:

  • rawvgm (DataFrame) – Variogram cloud with d0..d{dim-1} lag components.

  • directions (array-like, shape (n_dir, dim)) – Direction vectors (need not be normalised). Use rotation_matrix_3d() to obtain a rotated orthonormal axis set.

  • h_width (float, optional) – Fixed bin width applied to every direction. When None (default) the width is computed per direction as max_proj / h_bins, where max_proj is the largest projected lag along that axis. This gives equal resolution across all axes regardless of range, which matters for strongly anisotropic data where a single cutoff-derived width would leave the short-range axes with very few bins.

  • h_bins (int) – Number of bins per direction when h_width is None.

  • bandwidth (float, optional) – Maximum perpendicular distance from the directional line.

  • angle_tol (float, optional) – Angular tolerance (degrees) between a lag and the direction.

Returns:

DataFrame – Long format with columns direction (axis index), lag (mean projected lag in the bin), variogram and count.