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 execute the following command:
!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.4.2) Requirement already satisfied: numpy in /home/fors/.local/lib/python3.10/site-packages (from gstlearn) (1.25.2) Requirement already satisfied: scipy in /home/fors/.local/lib/python3.10/site-packages (from gstlearn) (1.11.2) Requirement already satisfied: matplotlib in /usr/lib/python3/dist-packages (from gstlearn) (3.5.1) Requirement already satisfied: pandas in /home/fors/.local/lib/python3.10/site-packages (from gstlearn) (2.0.3) Requirement already satisfied: shapely in /home/fors/.local/lib/python3.10/site-packages (from gstlearn) (2.0.1) Requirement already satisfied: plotly in /home/fors/.local/lib/python3.10/site-packages (from gstlearn) (5.16.1) Requirement already satisfied: tzdata>=2022.1 in /home/fors/.local/lib/python3.10/site-packages (from pandas->gstlearn) (2023.3) 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: pytz>=2020.1 in /usr/lib/python3/dist-packages (from pandas->gstlearn) (2022.1) 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: packaging in /usr/lib/python3/dist-packages (from plotly->gstlearn) (21.3) Requirement already satisfied: six>=1.5 in /usr/lib/python3/dist-packages (from python-dateutil>=2.8.2->pandas->gstlearn) (1.16.0)
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
grid.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.
All basic C++ types (
bool, etc...) are automatically converted to/from Python native types (
The C++ classes
VectorInt, etc... are automatically converted to/from Python/numpy nd.array
The C++ classes
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:
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
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
Dbobject. In that case, the newly created
DataFramewill contain all variables from the Db (but locators and grid parameters (for DbGrid) will be lost)
import gstlearn as gl import gstlearn.plot as gp import gstlearn.document as gdoc import matplotlib.pyplot as plt gdoc.setNoScroll()
Calling the next function (acknowledge_gstlearn) at startup is a good practice in order to check the version of gstlearn you are currently running:
# Uncomment and execute if needed #gl.acknowledge_gstlearn()
We create a regular 2-D grid and simulate a variable using a geostatistical Model
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
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:
Data Base Grid Characteristics ============================== Data Base Summary ----------------- File is organized as a regular grid Space dimension = 2 Number of Columns = 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