CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-gstools

GSTools is a comprehensive geostatistical toolbox for Python providing advanced spatial analysis and modeling capabilities.

—

Pending
Overview
Eval results
Files

kriging.mddocs/

Kriging

Kriging provides optimal spatial interpolation methods for estimating values at unobserved locations based on covariance models and observed data. GSTools implements comprehensive kriging variants with uncertainty quantification.

Capabilities

Universal Kriging Interface

Swiss-army-knife kriging class supporting all major kriging variants through unified interface.

class Krige:
    """
    Universal kriging interface supporting all kriging variants.
    
    Parameters:
    - model (CovModel): Covariance model defining spatial correlation
    - cond_pos (array-like): Positions of conditioning points
    - cond_val (array-like): Values at conditioning points
    - drift_functions (list): Drift functions for Universal Kriging (default: None)
    - ext_drift (array-like): External drift values (default: None)
    - mean (float or callable): Known mean value or function (default: None)
    - normalizer (Normalizer): Data normalization method (default: None)
    - trend (callable): Additional trend function (default: None)
    - unbiased (bool): Ensure unbiased estimates (default: True)
    - exact (bool): Honor conditioning values exactly (default: False)
    - cond_err (str or array-like): Conditioning error specification (default: 'nugget')
    - pseudo_inv (bool): Use pseudo-inverse for numerical stability (default: True)
    - pseudo_inv_type (str or callable): Pseudo-inverse method (default: 'pinv')
    - fit_normalizer (bool): Fit normalizer to data (default: False)
    - fit_variogram (bool): Fit variogram to data (default: False)
    """
    def __init__(self, model, cond_pos, cond_val, drift_functions=None, 
                 ext_drift=None, mean=None, normalizer=None, trend=None,
                 unbiased=True, exact=False, cond_err='nugget', pseudo_inv=True,
                 pseudo_inv_type='pinv', fit_normalizer=False, fit_variogram=False): ...
    
    def __call__(self, pos, mesh_type='unstructured', chunk_size=None, 
                 only_mean=False, return_var=False, store=True):
        """
        Perform kriging at specified positions.
        
        Parameters:
        - pos (array-like): Target positions for interpolation
        - mesh_type (str): Mesh type ('structured', 'unstructured')
        - chunk_size (int): Process data in chunks to manage memory
        - only_mean (bool): Return only kriging mean, skip variance
        - return_var (bool): Return kriging variance in addition to mean
        - store (bool): Store results in class instance
        
        Returns:
        - Kriging estimates (and variance if return_var=True)
        """
    
    def structured(self, pos, **kwargs):
        """
        Perform kriging on structured grid.
        
        Parameters:
        - pos (list): Grid coordinate arrays [x, y, z]
        - **kwargs: Additional kriging parameters
        
        Returns:
        - Kriging estimates on structured grid
        """
    
    def unstructured(self, pos, **kwargs):
        """
        Perform kriging at unstructured points.
        
        Parameters:
        - pos (array-like): Point coordinates
        - **kwargs: Additional kriging parameters
        
        Returns:
        - Kriging estimates at points
        """
    
    def get_mean(self, pos=None, mesh_type='unstructured', chunk_size=None):
        """
        Get kriging mean estimates.
        
        Parameters:
        - pos (array-like): Target positions (default: use stored positions)
        - mesh_type (str): Mesh type
        - chunk_size (int): Chunk size for processing
        
        Returns:
        - Kriging mean values
        """
    
    def get_variance(self, pos=None, mesh_type='unstructured', chunk_size=None):
        """
        Get kriging variance estimates.
        
        Parameters:
        - pos (array-like): Target positions (default: use stored positions)
        - mesh_type (str): Mesh type
        - chunk_size (int): Chunk size for processing
        
        Returns:
        - Kriging variance values
        """

Specialized Kriging Classes

Pre-configured kriging classes for specific applications and simplified usage.

class Simple:
    """
    Simple Kriging with known mean.
    
    Parameters:
    - model (CovModel): Covariance model
    - cond_pos (array-like): Conditioning positions
    - cond_val (array-like): Conditioning values
    - mean (float): Known mean value (default: 0.0)
    - normalizer (Normalizer): Data normalization method (default: None)
    - trend (callable): Trend function (default: None)
    - exact (bool): Honor conditioning values exactly (default: False)
    - cond_err (str or array-like): Conditioning error (default: 'nugget')
    - pseudo_inv (bool): Use pseudo-inverse (default: True)
    - pseudo_inv_type (str): Pseudo-inverse method (default: 'pinv')
    - fit_normalizer (bool): Fit normalizer to data (default: False)
    - fit_variogram (bool): Fit variogram to data (default: False)
    """
    def __init__(self, model, cond_pos, cond_val, mean=0.0, normalizer=None, 
                 trend=None, exact=False, cond_err='nugget', pseudo_inv=True,
                 pseudo_inv_type='pinv', fit_normalizer=False, fit_variogram=False): ...

class Ordinary:
    """
    Ordinary Kriging with estimated mean.
    
    Parameters:
    - model (CovModel): Covariance model
    - cond_pos (array-like): Conditioning positions
    - cond_val (array-like): Conditioning values
    - **kwargs: Additional kriging parameters
    """
    def __init__(self, model, cond_pos, cond_val, **kwargs): ...

class Universal:
    """
    Universal Kriging with drift functions.
    
    Parameters:
    - model (CovModel): Covariance model
    - cond_pos (array-like): Conditioning positions
    - cond_val (array-like): Conditioning values
    - drift_functions (list): List of drift functions
    - **kwargs: Additional kriging parameters
    """
    def __init__(self, model, cond_pos, cond_val, drift_functions, **kwargs): ...

class ExtDrift:
    """
    External Drift Kriging with auxiliary variable.
    
    Parameters:
    - model (CovModel): Covariance model
    - cond_pos (array-like): Conditioning positions
    - cond_val (array-like): Conditioning values
    - ext_drift (array-like): External drift values at conditioning points
    - **kwargs: Additional kriging parameters
    """
    def __init__(self, model, cond_pos, cond_val, ext_drift, **kwargs): ...

class Detrended:
    """
    Detrended Kriging with trend removal.
    
    Parameters:
    - model (CovModel): Covariance model
    - cond_pos (array-like): Conditioning positions
    - cond_val (array-like): Conditioning values
    - trend (callable): Trend function to remove
    - **kwargs: Additional kriging parameters
    """
    def __init__(self, model, cond_pos, cond_val, trend, **kwargs): ...

Usage Examples

Simple Kriging

import gstools as gs
import numpy as np

# Conditioning data
cond_pos = [[0, 10, 20], [0, 5, 15]]  # (x, y) coordinates  
cond_val = [1.0, 2.5, 1.8]           # Observed values
known_mean = 2.0

# Define covariance model
model = gs.Exponential(dim=2, var=1.5, len_scale=10.0)

# Simple kriging with known mean
sk = gs.krige.Simple(model, cond_pos, cond_val, mean=known_mean)

# Interpolate on grid
x = np.arange(0, 30, 1.0)
y = np.arange(0, 20, 1.0)
sk_mean, sk_var = sk.structured([x, y], return_var=True)

Ordinary Kriging

# Ordinary kriging (estimates mean from data)
ok = gs.krige.Ordinary(model, cond_pos, cond_val)

# Perform interpolation
ok_mean = ok.structured([x, y])
ok_var = ok.get_variance([x, y], mesh_type='structured')

Universal Kriging

# Define drift functions (e.g., linear trend)
def drift_linear_x(x, y):
    return x

def drift_linear_y(x, y):
    return y

drift_functions = [drift_linear_x, drift_linear_y]

# Universal kriging with drift
uk = gs.krige.Universal(model, cond_pos, cond_val, drift_functions)
uk_mean = uk.structured([x, y])

External Drift Kriging

# External variable at conditioning points
ext_cond = [100, 150, 120]  # e.g., elevation values

# External variable at prediction locations  
X, Y = np.meshgrid(x, y)
ext_pred = 100 + 2*X + Y  # External drift field

# External drift kriging
edk = gs.krige.ExtDrift(model, cond_pos, cond_val, ext_cond)
edk_mean = edk.structured([x, y], ext_drift=ext_pred)

Advanced Kriging Options

# Kriging with measurement errors
measurement_errors = [0.1, 0.2, 0.15]  # Error variances
krige = gs.Krige(
    model, 
    cond_pos, 
    cond_val,
    cond_err=measurement_errors,  # Specify conditioning errors
    exact=False,                  # Allow inexact interpolation
    pseudo_inv=True              # Use pseudo-inverse for stability
)

# Chunked processing for large datasets
krige_mean = krige.structured([x, y], chunk_size=10000)

Uncertainty Quantification

# Get both mean and variance
ok = gs.krige.Ordinary(model, cond_pos, cond_val)
mean, variance = ok.structured([x, y], return_var=True)

# Calculate confidence intervals (assuming Gaussian distribution)
std_dev = np.sqrt(variance)
ci_lower = mean - 1.96 * std_dev  # 95% confidence interval
ci_upper = mean + 1.96 * std_dev

# Probability of exceedance
threshold = 3.0
prob_exceed = 1 - scipy.stats.norm.cdf(threshold, mean, std_dev)

Cross-Validation

# Leave-one-out cross-validation
n_points = len(cond_val)
cv_residuals = []

for i in range(n_points):
    # Remove point i
    cv_pos = [np.delete(cond_pos[0], i), np.delete(cond_pos[1], i)]
    cv_val = np.delete(cond_val, i)
    
    # Krige at removed point
    cv_krige = gs.krige.Ordinary(model, cv_pos, cv_val)
    pred = cv_krige.unstructured([[cond_pos[0][i]], [cond_pos[1][i]]])
    
    # Calculate residual
    cv_residuals.append(cond_val[i] - pred[0])

# Calculate validation statistics
rmse = np.sqrt(np.mean(np.array(cv_residuals)**2))
mae = np.mean(np.abs(cv_residuals))

Kriging System and Linear Algebra

Kriging System Components

The kriging system solves the linear system:

[C + N] [λ] = [c]
[1ᵀ   ] [μ]   [1]

Where:

  • C: Covariance matrix between conditioning points
  • N: Nugget/error matrix
  • λ: Kriging weights
  • μ: Lagrange multiplier for unbiasedness constraint
  • c: Covariance vector between conditioning and prediction points

Numerical Considerations

# Handle numerical instability
krige = gs.Krige(
    model, 
    cond_pos, 
    cond_val,
    pseudo_inv=True,    # Use SVD pseudo-inverse
    cond_err='nugget'   # Add nugget for regularization
)

# Check condition number of kriging matrix
krige_matrix = krige._get_krige_matrix()  # Internal method
cond_number = np.linalg.cond(krige_matrix)
print(f"Condition number: {cond_number}")

Error Handling and Validation

Common kriging errors and solutions:

  • LinAlgError: Singular kriging matrix - increase nugget or use pseudo_inv=True
  • ValueError: Incompatible dimensions - check pos and val array shapes
  • RuntimeError: Convergence issues - check model parameters and data quality
try:
    krige = gs.Krige(model, cond_pos, cond_val)
    result = krige.structured([x, y])
except np.linalg.LinAlgError:
    # Handle singular matrix
    krige = gs.Krige(model, cond_pos, cond_val, pseudo_inv=True)
    result = krige.structured([x, y])

Properties and Methods

Kriging objects provide:

Properties:

  • model: Covariance model
  • cond_pos: Conditioning positions
  • cond_val: Conditioning values
  • mean: Kriging mean field
  • krige_var: Kriging variance field
  • pos: Prediction positions

Key Methods:

  • Interpolation: __call__(), structured(), unstructured()
  • Estimation: get_mean(), get_variance()
  • Validation: Cross-validation capabilities
  • Export: vtk_export(), plotting methods

Install with Tessl CLI

npx tessl i tessl/pypi-gstools

docs

covariance-models.md

field-generation.md

index.md

kriging.md

utilities.md

variogram-estimation.md

tile.json