General principles of gstlearn¶

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

Table of Contents

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:

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¶

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

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

First code: Create and display a database¶

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

The simulated result is plotted

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: