General principles of gstlearn¶

Didier RENARD, Nicolas DESASSIS, Mike PEREIRA, Xavier FREULON, Fabien ORS

Table of Contents

  • 1  General principles of gstlearn
    • 1.1  Introduction
      • 1.1.1  About C++ & Python
    • 1.2  Loading the package
    • 1.3  First code: Create and display a database

Introduction¶

The gstlearn Python package is a cross-platform Python package wrapping the gstlearn C++ Library. It offers to Python users all famous Geostatistical methodologies developed and/or invented by the Geostatistic Team of the Geosciences Research Center! It is the successor of the RGeostats R package, but in Python :-).

To install the gstlearn Python Package, you need Python 3.8 (or higher) and the following dependencies. Execute the following command:

In [1]:
!pip install gstlearn
Defaulting to user installation because normal site-packages is not writeable
Requirement already satisfied: gstlearn in /home/fors/.local/lib/python3.10/site-packages (0.3.3)
Requirement already satisfied: scipy in /home/fors/.local/lib/python3.10/site-packages (from gstlearn) (1.11.2)
Requirement already satisfied: pandas in /home/fors/.local/lib/python3.10/site-packages (from gstlearn) (2.0.3)
Requirement already satisfied: plotly in /home/fors/.local/lib/python3.10/site-packages (from gstlearn) (5.16.1)
Requirement already satisfied: matplotlib in /usr/lib/python3/dist-packages (from gstlearn) (3.5.1)
Requirement already satisfied: geopandas in /home/fors/.local/lib/python3.10/site-packages (from gstlearn) (0.13.0)
Requirement already satisfied: shapely in /home/fors/.local/lib/python3.10/site-packages (from gstlearn) (2.0.1)
Requirement already satisfied: numpy in /home/fors/.local/lib/python3.10/site-packages (from gstlearn) (1.25.2)
Requirement already satisfied: packaging in /usr/lib/python3/dist-packages (from geopandas->gstlearn) (21.3)
Requirement already satisfied: fiona>=1.8.19 in /home/fors/.local/lib/python3.10/site-packages (from geopandas->gstlearn) (1.9.3)
Requirement already satisfied: pyproj>=3.0.1 in /home/fors/.local/lib/python3.10/site-packages (from geopandas->gstlearn) (3.5.0)
Requirement already satisfied: pytz>=2020.1 in /usr/lib/python3/dist-packages (from pandas->gstlearn) (2022.1)
Requirement already satisfied: python-dateutil>=2.8.2 in /home/fors/.local/lib/python3.10/site-packages (from pandas->gstlearn) (2.8.2)
Requirement already satisfied: tzdata>=2022.1 in /home/fors/.local/lib/python3.10/site-packages (from pandas->gstlearn) (2023.3)
Requirement already satisfied: tenacity>=6.2.0 in /home/fors/.local/lib/python3.10/site-packages (from plotly->gstlearn) (8.2.2)
Requirement already satisfied: cligj>=0.5 in /home/fors/.local/lib/python3.10/site-packages (from fiona>=1.8.19->geopandas->gstlearn) (0.7.2)
Requirement already satisfied: attrs>=19.2.0 in /usr/lib/python3/dist-packages (from fiona>=1.8.19->geopandas->gstlearn) (21.2.0)
Requirement already satisfied: click~=8.0 in /usr/lib/python3/dist-packages (from fiona>=1.8.19->geopandas->gstlearn) (8.0.3)
Requirement already satisfied: certifi in /home/fors/.local/lib/python3.10/site-packages (from fiona>=1.8.19->geopandas->gstlearn) (2023.5.7)
Requirement already satisfied: munch>=2.3.2 in /home/fors/.local/lib/python3.10/site-packages (from fiona>=1.8.19->geopandas->gstlearn) (2.5.0)
Requirement already satisfied: click-plugins>=1.0 in /home/fors/.local/lib/python3.10/site-packages (from fiona>=1.8.19->geopandas->gstlearn) (1.1.1)
Requirement already satisfied: six>=1.5 in /usr/lib/python3/dist-packages (from python-dateutil>=2.8.2->pandas->gstlearn) (1.16.0)

About C++ & Python¶

The gstlearn Python package is generated using SWIG See here. We have chosen SWIG in order to mutualize the wrapper code of gstlearn C++ library for several different target languages.

The classes and functions documentation is provided with the gstlearn C++ library as html files generated by Doxygen. Please, refer to gstlearn C++ library API See here for more details. Only the public methods are exported by SWIG and must be considered in the Python package.

Their is currently poor Python documentation for the gstlearn Python package. The user can refer to the C++ documentation and have to learn how to adapt the code into Python language following these "conversion rules":

  • C++ classes are automatically converted into Python classes. After creating an instance of a class, methods (i.e. class function) must be called using . applied to the instance (i.e. an object) of that class (see db.display() in the example below).

  • Static C++ methods (e.g. createFromNF method in DbGrid class) defined in a class (e.g. DbGrid) are renamed by joining the class name and the method name (e.g. DbGrid.createFromNF). Note: Static methods do not apply to object instances (e.g. mygrid.createFromNF() has no sense)

  • Static C++ variables (e.g. X locator) defined in a class (e.g. ELoc 'enum' class) must be accessed in Python using the same rules as static methods (e.g. ELoc.X)

  • All basic C++ types (double, int, bool, etc...) are automatically converted to/from Python native types (float, int, bool,...)

  • The C++ classes VectorDouble, VectorInt, etc... are automatically converted to/from Python/numpy nd.array

  • The C++ classes VectorVectorDouble, VectorVectorInt, etc... are automatically converted to/from Python/numpy nd.array of nd.array(s)

  • Some classes of the gstlearn C++ library have been extended in Python:

    • Almost all classes are 'stringable' (those which inherit from AStringable), that means that you can type the object name in the Python console prompt and hit 'Enter' key to obtain a detailed description of the object content. The same output text is obtained using the display method (e.g. mygrid.display())
    • Some classes have an additional Python method named toTL (i.e. 'to Target Language') that permits to convert an object into the corresponding Python type. For example, the instruction df = mygrid.toTL() permits to create a pandas DataFrame from a Db object. In that case, the newly created DataFrame will contain all variables from the Db (but locators and grid parameters (for DbGrid) will be lost)

Loading the package¶

In [2]:
import gstlearn as gl
import gstlearn.plot as gp
import matplotlib.pyplot as plt

The following code snippet only permits to prevent Jupyter from showing scrollbars in the output cells

In [3]:
%%javascript
IPython.OutputArea.prototype._should_scroll = function(lines) {
    return false;
}

Calling the next function (acknowledge_gstlearn) at startup is a good practice in order to check the version of gstlearn you are currently running:

In [4]:
# Uncomment and execute if needed
#gl.acknowledge_gstlearn()

First code: Create and display a database¶

We create a regular 2-D grid and simulate a variable using a geostatistical Model

In [5]:
grid = gl.DbGrid.create(nx=[100,100])
model = gl.Model.createFromParam(type = gl.ECov.CUBIC, range = 30)
err = gl.simtub(None, grid, model, None, nbsimu=1, seed=13126, nbtuba = 1000)

The simulated result is plotted

In [6]:
ax = grid.plot()
plt.show()

If you obtain a nice looking image corresponding to the simulation result on the grid ... the installation of gstlearn is successfull. Here is the description of your grid database content:

In [7]:
grid.display()
Data Base Grid Characteristics
==============================

Data Base Summary
-----------------
File is organized as a regular grid
Space dimension              = 2
Number of Columns            = 4
Maximum Number of UIDs       = 4
Total number of samples      = 10000

Grid characteristics:
---------------------
Origin :      0.000     0.000
Mesh   :      1.000     1.000
Number :        100       100

Variables
---------
Column = 0 - Name = rank - Locator = NA
Column = 1 - Name = x1 - Locator = x1
Column = 2 - Name = x2 - Locator = x2
Column = 3 - Name = Simu - Locator = z1
 
In [ ]: