tessl/pypi-gstools

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

—

Pending

Overview

Eval results

Files

Covariance Models

Name: tessl/pypi-gstools
Author: tessl

Covariance models define the spatial correlation structure for geostatistical fields. GSTools provides base classes for custom model development and 20+ built-in models covering standard geostatistical applications and specialized scenarios.

Capabilities

Base Classes

Core classes for defining covariance models, with full support for anisotropy, rotation, spatio-temporal modeling, and geographic coordinate systems.

class CovModel:
    """
    Base class for all covariance models.
    
    Parameters:
    - dim (int): Spatial dimension (1, 2, or 3)
    - var (float): Variance (sill) of the covariance model
    - len_scale (float or array-like): Correlation length scale(s)
    - nugget (float): Nugget effect (measurement error variance)
    - anis (float or array-like): Anisotropy ratios
    - angles (float or array-like): Rotation angles for anisotropy
    - integral_scale (float or array-like): Integral scale(s)
    - rescale (float or array-like): Rescaling factor(s)
    - latlon (bool): Use geographic coordinates
    - geo_scale (float): Geographic scaling factor (default: RADIAN_SCALE)
    - temporal (bool): Include temporal dimension
    - spatial_dim (int): Number of spatial dimensions when temporal=True
    - hankel_kw (dict): Keywords for Hankel transformation
    - **opt_arg: Optional arguments for specific model implementations
    """
    def __init__(self, dim=3, var=1.0, len_scale=1.0, nugget=0.0, anis=1.0, 
                 angles=0.0, *, integral_scale=None, rescale=None, latlon=False, 
                 geo_scale=RADIAN_SCALE, temporal=False, spatial_dim=None, 
                 hankel_kw=None, **opt_arg): ...
    
    def variogram(self, r):
        """
        Calculate variogram values.
        
        Parameters:
        - r (array-like): Distances
        
        Returns:
        - array: Variogram values
        """
    
    def covariance(self, r):
        """
        Calculate covariance values.
        
        Parameters:
        - r (array-like): Distances
        
        Returns:
        - array: Covariance values
        """
    
    def correlation(self, r):
        """
        Calculate correlation values.
        
        Parameters:
        - r (array-like): Distances
        
        Returns:
        - array: Correlation values
        """
    
    def vario_spatial(self, pos):
        """Calculate variogram at spatial positions."""
    
    def cov_spatial(self, pos):
        """Calculate covariance at spatial positions."""
    
    def cor_spatial(self, pos):
        """Calculate correlation at spatial positions."""
    
    def spectrum(self, k):
        """Calculate power spectrum."""
        
    def spectral_density(self, k):
        """Calculate spectral density."""
    
    def fit_variogram(self, x_data, y_data, nugget=True, sill=True, 
                      weights=None, method='trf', loss='soft_l1', **kwargs):
        """
        Fit model parameters to empirical variogram.
        
        Parameters:
        - x_data (array-like): Distance values
        - y_data (array-like): Variogram values
        - nugget (bool): Fit nugget parameter
        - sill (bool): Fit sill parameter
        - weights (array-like): Data weights
        - method (str): Optimization method
        - loss (str): Loss function
        
        Returns:
        - dict: Fitted parameters and optimization results
        """
    
    def plot(self, func='variogram', x_min=0.0, x_max=None, fig=None, ax=None): ...
    def calc_integral_scale(self): ...
    def set_arg_bounds(self, **kwargs): ...

class SumModel(CovModel):
    """
    Sum of multiple covariance models.
    
    Parameters:
    - models (list): List of CovModel instances
    - **kwargs: Additional CovModel parameters
    """
    def __init__(self, *models, **kwargs): ...
    
    def set_var_weights(self, weights):
        """Set variance weights for component models."""
    
    def set_len_weights(self, weights):
        """Set length scale weights for component models."""

Standard Covariance Models

Built-in covariance models for common geostatistical applications. All inherit from CovModel and support its full parameter set.

class Nugget(CovModel):
    """Pure nugget effect model (white noise)."""

class Gaussian(CovModel):
    """Gaussian (squared exponential) covariance model."""

class Exponential(CovModel):
    """Exponential covariance model."""

class Matern(CovModel):
    """
    Matérn covariance model.
    
    Additional Parameters:
    - nu (float): Shape parameter controlling smoothness (default: 1.0)
    """
    def __init__(self, nu=1.0, **kwargs): ...

class Integral(CovModel):
    """
    Exponential integral covariance model.
    
    Additional Parameters:
    - nu (float): Shape parameter (default: 1.0)
    """
    def __init__(self, nu=1.0, **kwargs): ...

class Stable(CovModel):
    """
    Stable (powered exponential) covariance model.
    
    Additional Parameters:
    - alpha (float): Shape parameter, 0 < alpha <= 2 (default: 1.5)
    """
    def __init__(self, alpha=1.5, **kwargs): ...

class Rational(CovModel):
    """
    Rational quadratic covariance model.
    
    Additional Parameters:
    - alpha (float): Shape parameter (default: 1.0)
    """
    def __init__(self, alpha=1.0, **kwargs): ...

class Cubic(CovModel):
    """Cubic covariance model."""

class Linear(CovModel):
    """Linear covariance model (1D only)."""

class Circular(CovModel):
    """Circular covariance model (1D-2D)."""

class Spherical(CovModel):
    """Spherical covariance model (1D-3D)."""

class HyperSpherical(CovModel):
    """Hyper-spherical covariance model."""

class SuperSpherical(CovModel):
    """
    Super-spherical covariance model.
    
    Additional Parameters:
    - nu (float): Shape parameter (default: (dim-1)/2)
    """
    def __init__(self, nu=None, **kwargs): ...

class JBessel(CovModel):
    """
    J-Bessel hole model.
    
    Additional Parameters:
    - nu (float): Shape parameter (default: dim/2)
    """
    def __init__(self, nu=None, **kwargs): ...

Truncated Power Law Models

Specialized models with truncated power law behavior for complex spatial structures.

class TPLGaussian(CovModel):
    """
    Truncated Power Law with Gaussian modes.
    
    Additional Parameters:
    - hurst (float): Hurst coefficient (default: 0.5)  
    - len_low (float): Lower length scale cutoff (default: 0.0)
    """
    def __init__(self, hurst=0.5, len_low=0.0, **kwargs): ...

class TPLExponential(CovModel):
    """
    Truncated Power Law with Exponential modes.
    
    Additional Parameters:
    - hurst (float): Hurst coefficient (default: 0.25)
    - len_low (float): Lower length scale cutoff (default: 0.0)
    """
    def __init__(self, hurst=0.25, len_low=0.0, **kwargs): ...

class TPLStable(CovModel):
    """
    Truncated Power Law with Stable modes.
    
    Additional Parameters:
    - hurst (float): Hurst coefficient (default: 0.5)
    - alpha (float): Stable shape parameter (default: 1.5)
    - len_low (float): Lower length scale cutoff (default: 0.0)
    """
    def __init__(self, hurst=0.5, alpha=1.5, len_low=0.0, **kwargs): ...

class TPLSimple(CovModel):
    """
    Simple truncated power law model.
    
    Additional Parameters:
    - nu (float): Shape parameter (default: (dim+1)/2)
    """
    def __init__(self, nu=None, **kwargs): ...

Usage Examples

Basic Model Creation

import gstools as gs

# Simple Gaussian model
model = gs.Gaussian(dim=2, var=2.0, len_scale=10.0)

# Anisotropic exponential model with rotation
model = gs.Exponential(
    dim=2, 
    var=1.5, 
    len_scale=[20.0, 5.0],  # Different scales in each direction
    angles=np.pi/4,         # 45-degree rotation
    nugget=0.1              # Small nugget effect
)

# Matérn model with custom smoothness
model = gs.Matern(dim=3, var=3.0, len_scale=15.0, nu=2.5)

Model Fitting to Empirical Variogram

# Create empirical variogram data
bin_edges = gs.standard_bins(pos, max_dist=50)
emp_vario = gs.vario_estimate(pos, field_data, bin_edges)

# Fit Gaussian model
model = gs.Gaussian(dim=2)
fit_results = model.fit_variogram(emp_vario[0], emp_vario[1])
print(f"Fitted variance: {model.var}")
print(f"Fitted length scale: {model.len_scale}")

Composite Models

# Sum of exponential and nugget
nugget = gs.Nugget(var=0.2)
exponential = gs.Exponential(var=1.8, len_scale=20.0)
composite = gs.SumModel(nugget, exponential)

# Nested structures
short_range = gs.Gaussian(var=0.5, len_scale=5.0)
long_range = gs.Exponential(var=1.0, len_scale=50.0)
nested = gs.SumModel(short_range, long_range)