Package: gstools
Welcome to GSToolsGet in Touch!Youtube Tutorial on GSToolsPurposeGeoStatTools provides geostatistical tools for various purposes:random field generationsimple, ordinary, universal and external drift krigingconditioned field generationincompressible random vector field generation(automated) variogram estimation and fittingdirectional variogram estimation and modellingdata normalization and transformationmany readily provided and even user-defined covariance modelsmetric spatio-temporal modellingplotting and exporting routinesInstallationcondaGSTools can be installed viacondaon Linux, Mac, and Windows.
Install the package by typing the following command in a command terminal:conda install gstoolsIn case conda forge is not set up for your system yet, see the easy to follow
instructions onconda forge. Using conda, the parallelized
version of GSTools should be installed.pipGSTools can be installed viapipon Linux, Mac, and Windows.
On Windows you can installWinPythonto get Python and pip
running. Install the package by typing the following command in a command terminal:pip install gstoolsTo install the latest development version via pip, see thedocumentation.CitationIf 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.1313628If you want to cite a specific version, have a look at theZenodo site.Documentation for GSToolsYou can find the documentation undergeostat-framework.readthedocs.io.Tutorials and ExamplesThe documentation also includes sometutorials, showing the most important use cases of GSTools, which areRandom Field GenerationThe Covariance ModelVariogram EstimationRandom Vector Field GenerationKrigingConditioned random field generationField transformationsGeographic CoordinatesSpatio-Temporal ModellingNormalizing DataMiscellaneous examplesThe associated python scripts are provided in theexamplesfolder.Spatial Random Field GenerationThe core of this library is the generation of spatial random fields. These fields are generated using the randomisation method, described byHeße et al. 2014.ExamplesGaussian Covariance ModelThis is an example of how to generate a 2 dimensional spatial random field with a gaussian covariance model.importgstoolsasgs# structured field with a size 100x100 and a grid-size of 1x1x=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 forgeographic coordinates.
This works perfectly well withcartopy.importmatplotlib.pyplotaspltimportcartopy.crsasccrsimportgstoolsasgs# define a structured field by latitude and longitudelat=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 cartopyax=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 aVTKfile, which can be visualized withParaVieworPyVistain Python:importgstoolsasgs# structured field with a size 100x100x100 and a grid-size of 1x1x1x=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 ParaViewmesh=srf.to_pyvista()# Create a PyVista mesh for plotting in Pythonmesh.contour(isosurfaces=8).plot()Estimating and Fitting VariogramsThe 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.ExampleThis is an example of how to estimate the variogram of a 2 dimensional unstructured field and estimate the parameters of the covariance
model again.importnumpyasnpimportgstoolsasgs# generate a synthetic field with an exponential modelx=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 fieldbin_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)# outputax=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 FieldsAn 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.ExampleFor better visualization, we will condition a 1d field to a few "measurements", generate 100 realizations and plot them:importnumpyasnpimportmatplotlib.pyplotaspltimportgstoolsasgs# conditionscond_pos=[0.3,1.9,1.1,3.3,4.7]cond_val=[0.47,0.56,0.74,1.47,1.74]# conditioned spatial random field classmodel=gs.Gaussian(dim=1,var=0.5,len_scale=2)krige=gs.krige.Ordinary(model,cond_pos,cond_val)cond_srf=gs.CondSRF(krige)# same output positions for all ensemble membersgrid_pos=np.linspace(0.0,15.0,151)cond_srf.set_pos(grid_pos)# seeded ensemble generationseed=gs.random.MasterRNG(20170519)foriinrange(100):field=cond_srf(seed=seed(),store=f"field_{i}")plt.plot(grid_pos,field,color="k",alpha=0.1)plt.scatter(cond_pos,cond_val,color="k")plt.show()User Defined Covariance ModelsOne of the core-features of GSTools is the powerfulCovModelclass, which allows to easy define covariance models by the user.ExampleHere we re-implement the Gaussian covariance model by defining just acorrelationfunction, which takes a non-dimensional distanceh = r/l:importnumpyasnpimportgstoolsasgs# use CovModel as the base-classclassGau(gs.CovModel):defcor(self,h):returnnp.exp(-h**2)And that's it! WithGauyou now have a fully working covariance model,
which you could use for field generation or variogram fitting as shown above.Have a look at thedocumentationfor further information on incorporating
optional parameters and optimizations.Incompressible Vector Field GenerationUsing the originalKraichnan method, incompressible random
spatial vector fields can be generated.Exampleimportnumpyasnpimportgstoolsasgsx=np.arange(100)y=np.arange(100)model=gs.Gaussian(dim=2,var=1,len_scale=10)srf=gs.SRF(model,generator='VectorField',seed=19841203)srf((x,y),mesh_type='structured')srf.plot()yieldingVTK/PyVista ExportAfter you have created a field, you may want to save it to file, so we provide
a handyVTKexport routine using the.vtk_export()or you could
create a VTK/PyVista dataset for use in Python with to.to_pyvista()method:importgstoolsasgsx=y=range(100)model=gs.Gaussian(dim=2,var=1,len_scale=10)srf=gs.SRF(model)srf((x,y),mesh_type='structured')srf.vtk_export("field")# Saves to a VTK filemesh=srf.to_pyvista()# Create a VTK/PyVista dataset in memorymesh.plot()Which gives a RectilinearGrid VTK filefield.vtror creates a PyVista mesh
in memory for immediate 3D plotting in Python.Requirements:NumPy >= 1.14.5SciPy >= 1.1.0hankel >= 1.0.0emcee >= 3.0.0pyevtk >= 1.1.1meshio >= 5.1.0OptionalGSTools-Core >= 0.2.0matplotlibpyvistaContactYou can contact us viainfo@geostat-framework.org.LicenseLGPLv3© 2018-2021