GSTools

GSTools is a comprehensive geostatistical toolbox for Python that provides advanced spatial analysis and modeling capabilities. It offers functionality for random field generation with periodic boundaries, various kriging methods, conditioned field generation, automated variogram estimation and fitting, directional variogram modeling, data normalization and transformation, numerous built-in and user-defined covariance models, metric spatio-temporal modeling, plurigaussian field simulations, and comprehensive plotting and export routines.

Package Information

• Package Name: gstools
• Language: Python
• Installation: pip install gstools
• Documentation: https://gstools.readthedocs.io
• Version: 1.7.0
• License: LGPL-3.0

Core Imports

import gstools as gs

Import specific components:

from gstools import Gaussian, SRF, Krige, vario_estimate, PGS

Basic Usage

import gstools as gs
import numpy as np

# Define a covariance model
model = gs.Gaussian(dim=2, var=1.0, len_scale=10.0)

# Generate a random field
srf = gs.SRF(model)
grid = [np.arange(0, 100, 1), np.arange(0, 100, 1)]
field = srf.structured(grid)

# Estimate variogram from data
pos = [grid[0].flatten(), grid[1].flatten()]
data = field.flatten()
bin_edges = gs.standard_bins(pos)
gamma = gs.vario_estimate(pos, data, bin_edges)

# Fit covariance model to variogram
fit_model = gs.Exponential(dim=2)
fit_model.fit_variogram(gamma[0], gamma[1])

# Perform kriging interpolation
krige = gs.Krige(fit_model, cond_pos=pos[:, ::100], cond_val=data[::100])
krige_field = krige.structured(grid)

Architecture

GSTools follows a modular architecture with distinct components:

• Covariance Models: Base classes and 20+ built-in models for spatial correlation
• Field Generation: Classes for unconditional and conditioned random field generation
• Kriging: Comprehensive kriging interpolation methods (Simple, Ordinary, Universal, External Drift)
• Variogram Estimation: Empirical variogram calculation and directional analysis
• Utilities: Export, transformation, normalization, and geometric operations

This design enables flexible geostatistical workflows from basic random field generation to complex spatial analysis and modeling tasks.

Capabilities

Covariance Models

Base classes and 20+ built-in covariance models including Gaussian, Exponential, Matérn, and Truncated Power Law variants. All models support anisotropy, rotation, and spatio-temporal extensions.

class CovModel:
    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=None, temporal=False, spatial_dim=None, **kwargs): ...
    def variogram(self, r): ...
    def covariance(self, r): ...
    def fit_variogram(self, x_data, y_data, **kwargs): ...

class Gaussian(CovModel): ...
class Exponential(CovModel): ...
class Matern(CovModel): 
    def __init__(self, nu=1.0, **kwargs): ...

Covariance Models

Field Generation

Classes for generating unconditional and conditioned spatial random fields, including plurigaussian simulations for categorical fields.

class SRF:
    def __init__(self, model, mean=None, normalizer=None, trend=None, 
                 upscaling='no_scaling', generator='RandMeth', **kwargs): ...
    def __call__(self, pos, seed=None, mesh_type='unstructured'): ...
    def structured(self, pos, **kwargs): ...
    def unstructured(self, pos, **kwargs): ...

class CondSRF(SRF):
    def __init__(self, krige, generator='RandMeth', **kwargs): ...

class PGS:
    def __init__(self, dim, fields, **kwargs): ...

Field Generation

Kriging

Comprehensive kriging interpolation methods including Simple, Ordinary, Universal, and External Drift kriging with uncertainty quantification.

class Krige:
    def __init__(self, model, cond_pos, cond_val, drift_functions=None, 
                 ext_drift=None, mean=None, unbiased=True, exact=True, 
                 cond_err='nugget', pseudo_inv=True): ...
    def __call__(self, pos, mesh_type='unstructured', return_var=False): ...
    def structured(self, pos, **kwargs): ...
    def get_mean(self, **kwargs): ...
    def get_variance(self, **kwargs): ...

Kriging

Variogram Estimation

Functions for empirical variogram estimation from spatial data including directional analysis and structured/unstructured data support.

def vario_estimate(pos, field, bin_edges=None, sampling_size=None, 
                   estimator='matheron', mesh_type='unstructured'): ...
def vario_estimate_axis(pos, field, direction, bin_edges=None, 
                        angles_tol=np.pi/8, bandwidth=None): ...
def standard_bins(pos, bin_no=50, max_dist=None): ...

Variogram Estimation

Utilities

Comprehensive utility functions including VTK export, geometric operations, field transformations, data normalization, and spatial analysis tools.

def vtk_export(filename, pos, fields, fieldnames=None): ...
def generate_grid(x, y=None, z=None, **kwargs): ...
def rotated_main_axes(dim, angles): ...

# Constants
EARTH_RADIUS: float = 6371.0
KM_SCALE: float = 6371.0
DEGREE_SCALE: float = 57.29577951308232

Utilities

Error Handling

GSTools functions may raise the following exceptions:

• ValueError: Invalid parameter values or incompatible dimensions
• RuntimeError: Numerical computation failures or convergence issues
• NotImplementedError: Unsupported feature combinations
• ImportError: Missing optional dependencies for specific functionality

Dependencies

Required:

• numpy >= 1.20.0
• scipy >= 1.1.0
• gstools-cython >= 1.0
• emcee >= 3.0.0
• hankel >= 1.0.0
• meshio >= 5.1.0
• pyevtk >= 1.1.1

Optional:

• matplotlib >= 3.7 (plotting)
• pyvista >= 0.40 (3D visualization)
• gstools_core >= 1.0.0 (Rust acceleration)