GSTools
GSTools - A geostatistical toolbox: random fields, variogram estimation, covariance models, kriging and much more
Install / Use
/learn @GeoStat-Framework/GSToolsREADME
Welcome to GSTools
Purpose
<img align="right" width="450" src="https://raw.githubusercontent.com/GeoStat-Framework/GSTools/main/docs/source/pics/demonstrator.png" alt="">GSTools provides geostatistical tools for various purposes:
- random field generation, including periodic boundaries
- simple, ordinary, universal and external drift kriging
- conditioned field generation
- incompressible random vector field generation
- (automated) variogram estimation and fitting
- directional variogram estimation and modelling
- data normalization and transformation
- many readily provided and even user-defined covariance models
- metric spatio-temporal modelling
- plurigaussian field simulations (PGS)
- plotting and exporting routines
Installation
conda
GSTools can be installed via [conda][conda_link] on Linux, Mac, and Windows. Install the package by typing the following command in a command terminal:
conda install gstools
In case conda forge is not set up for your system yet, see the easy to follow instructions on [conda forge][conda_forge_link]. Using conda, the parallelized version of GSTools should be installed.
pip
GSTools can be installed via [pip][pip_link] on Linux, Mac, and Windows. On Windows you can install [WinPython][winpy_link] to get Python and pip running. Install the package by typing the following command in a command terminal:
pip install gstools
To install the latest development version via pip, see the [documentation][doc_install_link]. One thing to point out is that this way, the non-parallel version of GSTools is installed. In case you want the parallel version, follow these easy [steps][doc_install_link].
Citation
If you are using GSTools in your publication please cite our paper:
Müller, S., Schüler, L., Zech, A., and Heße, F.: GSTools v1.3: a toolbox for geostatistical modelling in Python, Geosci. Model Dev., 15, 3161–3182, https://doi.org/10.5194/gmd-15-3161-2022, 2022.
You can cite the Zenodo code publication of GSTools by:
Sebastian Müller & Lennart Schüler. GeoStat-Framework/GSTools. Zenodo. https://doi.org/10.5281/zenodo.1313628
If you want to cite a specific version, have a look at the Zenodo site.
Documentation for GSTools
You can find the documentation under [geostat-framework.readthedocs.io][doc_link].
Tutorials and Examples
The documentation also includes some [tutorials][tut_link], showing the most important use cases of GSTools, which are
- [Random Field Generation][tut1_link]
- [The Covariance Model][tut2_link]
- [Variogram Estimation][tut3_link]
- [Random Vector Field Generation][tut4_link]
- [Kriging][tut5_link]
- [Conditioned random field generation][tut6_link]
- [Field transformations][tut7_link]
- [Geographic Coordinates][tut8_link]
- [Spatio-Temporal Modelling][tut9_link]
- [Normalizing Data][tut10_link]
- [Plurigaussian Field Generation (PGS)][tut11_link]
- [Miscellaneous examples][tut0_link]
The associated python scripts are provided in the examples folder.
Spatial Random Field Generation
The core of this library is the generation of spatial random fields. These fields are generated using the randomisation method, described by Heße et al. 2014.
Examples
Gaussian Covariance Model
This is an example of how to generate a 2 dimensional spatial random field with a gaussian covariance model.
import gstools as gs
# structured field with a size 100x100 and a grid-size of 1x1
x = y = range(100)
model = gs.Gaussian(dim=2, var=1, len_scale=10)
srf = gs.SRF(model)
srf((x, y), mesh_type='structured')
srf.plot()
GSTools also provides support for geographic coordinates. This works perfectly well with cartopy.
import matplotlib.pyplot as plt
import cartopy.crs as ccrs
import gstools as gs
# define a structured field by latitude and longitude
lat = lon = range(-80, 81)
model = gs.Gaussian(latlon=True, len_scale=777, geo_scale=gs.KM_SCALE)
srf = gs.SRF(model, seed=12345)
field = srf.structured((lat, lon))
# Orthographic plotting with cartopy
ax = plt.subplot(projection=ccrs.Orthographic(-45, 45))
cont = ax.contourf(lon, lat, field, transform=ccrs.PlateCarree())
ax.coastlines()
ax.set_global()
plt.colorbar(cont)
A similar example but for a three dimensional field is exported to a VTK file, which can be visualized with ParaView or PyVista in Python:
import gstools as gs
# structured field with a size 100x100x100 and a grid-size of 1x1x1
x = y = z = range(100)
model = gs.Gaussian(dim=3, len_scale=[16, 8, 4], angles=(0.8, 0.4, 0.2))
srf = gs.SRF(model)
srf((x, y, z), mesh_type='structured')
srf.vtk_export('3d_field') # Save to a VTK file for ParaView
mesh = srf.to_pyvista() # Create a PyVista mesh for plotting in Python
mesh.contour(isosurfaces=8).plot()
Estimating and Fitting Variograms
The spatial structure of a field can be analyzed with the variogram, which contains the same information as the covariance function.
All covariance models can be used to fit given variogram data by a simple interface.
Example
This is an example of how to estimate the variogram of a 2 dimensional unstructured field and estimate the parameters of the covariance model again.
import numpy as np
import gstools as gs
# generate a synthetic field with an exponential model
x = np.random.RandomState(19970221).rand(1000) * 100.
y = np.random.RandomState(20011012).rand(1000) * 100.
model = gs.Exponential(dim=2, var=2, len_scale=8)
srf = gs.SRF(model, mean=0, seed=19970221)
field = srf((x, y))
# estimate the variogram of the field
bin_center, gamma = gs.vario_estimate((x, y), field)
# fit the variogram with a stable model. (no nugget fitted)
fit_model = gs.Stable(dim=2)
fit_model.fit_variogram(bin_center, gamma, nugget=False)
# output
ax = fit_model.plot(x_max=max(bin_center))
ax.scatter(bin_center, gamma)
print(fit_model)
Which gives:
Stable(dim=2, var=1.85, len_scale=7.42, nugget=0.0, anis=[1.0], angles=[0.0], alpha=1.09)
Kriging and Conditioned Random Fields
An important part of geostatistics is Kriging and conditioning spatial random fields to measurements. With conditioned random fields, an ensemble of field realizations with their variability depending on the proximity of the measurements can be generated.
Example
For better visualization, we will condition a 1d field to a few "measurements", generate 100 realizations and plot them:
import numpy as np
import matplotlib.pyplot as plt
import gstools as gs
# conditions
Related Skills
node-connect
340.5kDiagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps
claude-opus-4-5-migration
84.2kMigrate prompts and code from Claude Sonnet 4.0, Sonnet 4.5, or Opus 4.1 to Opus 4.5
frontend-design
84.2kCreate distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
model-usage
340.5kUse CodexBar CLI local cost usage to summarize per-model usage for Codex or Claude, including the current (most recent) model or a full model breakdown. Trigger when asked for model-level usage/cost data from codexbar, or when you need a scriptable per-model summary from codexbar cost JSON.
