GeostatsPy

<h1 align="center"<p> <img src="https://github.com/GeostatsGuy/GeostatsPy/blob/master/geostatspy_logo.png?raw=true" width="200" height="200" /> </p></h1>

<h1 align="center">GeostatsPy Python Package: Open-source Spatial Data Analytics and Geostatistics</h1> <h3 align="center"> Now in 3D! </h3> <h3 align="center"></h3>

Cite As:

Pyrcz, M.J., Jo. H., Kupenko, A., Liu, W., Gigliotti, A.E., Salomaki, T., and Santos, J., 2021, GeostatsPy Python Package: Open-source Spatial Data Analytics and Geostatistics, DOI: /doi/10.5281/zenodo.13835444.

---

NEW: 3D Sequential Indicator Simulation (SISIM) and 3D Sequential Gaussian Simulation (SGSIM)

I have a confession: many of the GSLIB functions in the GeostatsPy Python package were ported or written from scratch by me—often late at night and into the early morning hours—just in time for the next day’s lecture.

Back in 2018, I desperately needed a usable, open-source geostatistics Python package to teach my courses. I found one, but on the first day of the semester, it broke due to an update in a dependent package. With no alternatives, I decided to build my own. My goal was simple: implement the minimum necessary tools to teach geostatistics in practice, not just in theory.

Because:

• you can’t teach geostatistics without algorithms, and…

• students weren’t going to edit parameter files and run old FORTRAN GSLIB executables. (I tried that once—many students dropped the course in the first week!)

• my Excel demonstrations are great for theory and math, but they don’t support building full models.

So, in those early days, I made a key decision, everything would be in 2D only. Why?

• it made testing and debugging much easier.

• it was perfect for live demos and slides: easy to explain, visualize, and diagnose.

Fast forward to now... I’m lucky to have an amazing graduate student team—typically 12–15 students, mostly PhDs—and many of them want to build 3D geostatistical models. So, I couldn’t help myself. I went back and updated everything—search algorithms, kriging, distance metrics with geometric anisotropy, and more... and finally,

• sgsim_3D - a 3D implimentation of sequential Gaussian simulation

• sisim_3D - a 3D implimentation of sequetial indicator simulation

Notes on this First Version:

Tested:

1. simple and ordinary kriging

2. stationary mean or proportion realizations

3. data conditioning

Not yet tested:

1. locally variable mean / proportion

2. collocated cokriging

I’ll be asking one of my PhD students to test these soon!

Improvements Along the Way

I made some improvements over the current 2D implimentations,

1. continued to replace legacy FORTRAN-style loops from GSLIB with NumPy broadcasting, making the code more readable, robust, and concise.

2. fixed the reference distribution option in sgsim_3D, allowing users to transform/back-transform with limited conditioning data using an external Gaussian table.

I did make a couple of improvements,

• I'm always looking to replace the FORTRAN loops of GSLIB with broadcast methods from NumPy for more robust, readable and concise codes.

• I have fixed the reference distribution option for SGSIM, so you can use few data and another file to provide the Gaussian transformation and back-transformation table.

Special Thanks

Huge thanks to Professor Honggeun Jo, whose prior work on 3D variograms, covariance functions, and more made this possible. Your contributions to GeostatsPy have been incredible.

---

NEW: Check out the new e-book, Applied Geostatistics in Python: A Hands-on Guide with GeostatsPy, by Michael J. Pyrcz

The goal of this e-book is to teach the application of geostatistics in Python, for those new to geostatistics I provide theory and links to my course content, and for those experienced practitioners I provide example workflows and plots that you can implement.

e-book citation and link:

Pyrcz, M.J., 2024, Applied Geostatistics in Python: A Hands-on Guide with GeostatsPy, https://geostatsguy.github.io/GeostatsPyDemos_Book.

---

GeostatsPy Python Package

The GeostatsPy Package brings GSLIB: Geostatistical Library (Deutsch and Journel, 1998) functions to Python. GSLIB is a practical and extremely robust set of code for building spatial modeling workflows.

I created the GeostatsPy Package to support my students in my Data Analytics, Geostatistics and Machine Learning courses. I find my students benefit from hands-on opportunities, in fact it is hard to imagine teaching these topics without providing the opportunity to handle the numerical methods and build workflows. Last year, I tried to have them use the original FORTRAN executables and even with support and worked out examples, it was an uphill battle. In addition, all my students and I are now working in Python for our research. Thus, having access to geostatistical methods in Python directly impacts and facilitates the research of my group. This package retains the spirit of GSLIB:

• modularity - a collection of standalone functions that may be applied in sequence for maximum flexibility for building workflows
• minimalistic - the simplest possible code to support the "look at the code" approach to learning
• fundamental - based on the well-established geostatistical theory by avoiding ad hoc methods and assumptions

This package contains 2 parts:

1. geostatspy.geostats includes GSLIB functions rewritten in Python. This currently includes all the variogram, distribution transformations, and spatial estimation and simulation methods. I will continue adding functions to support modeling operations for practical subsurface model cosntruction.

2. geostatspy.GSLIB includes reimplimentation of the GSLIB visualizations and low tech wrappers of the numerical methods (note: the low-tech wrapper require access to GSLIB executables).

Getting Started

I have built out many well-documented workflow in Jupyter Notebooks using GeostatsPy functions to complete common workflows in spatial data analytics and geostatistics. They are available in my GeostatsPy_Demos Repository. I hope these are helpful!

Setup

A minimum environment includes:

• Python 3.10 - 3.13, numpy < 2.2.x - due to the depdendency of GeostatsPy on the Numba package for code acceleration with a Just-In-Time compiler for numerical functions in Python

---

Installing GeostatsPy

GeostatsPy is available on the Python Package Index (PyPI) GeostatsPy PyPI.

To install GeostatsPy, use pip command,

pip install geostatspy

To update GeostatsPy to the most recent version, use pip,

pip install --upgrade --force-reinstall geostatspy

---

GeostatsPy Package Dependencies

The functions rely on the following packages:

| Package / Component | Included by Default in Anaconda? | Notes | Application in GeostatsPy | |------------------------------|----------------------------------|--------------------------------------------------------|-------------------------------------------------| | numpy | ✅ Yes | Core numerical package | arrays with ndarrays | | pandas | ✅ Yes | Essential for dataframes and time series | data tables with DataFrames | | numpy.linalg | ✅ Yes | Part of NumPy (not a separate package) | linear algebra for solving kriging systems | | scipy | ✅ Yes | Scientific computing tools, including optimization | fast data search with KD Trees, | | matplotlib.pyplot | ✅ Yes | From the Matplotlib library for plotting | standard plots, location maps, pixel plots, etc. | | numba | ✅ Yes (often included) | JIT compiler; included in most full Anaconda installs | for numerical speed up of array math | | tqdm | ❌ No | Not included by default — install manually | for progress bar | | statsmodels | ❌ No | Often used, but not in the default distribution | for weighted (debiased) statistics |

Most of these packages should be available with any modern Python distribution, like Anaconda.

• pip and conda installs may be applied to install tqdm and statsmodels.

pip install tqdm
pip install statsmodels

If you get a package import error, you may have to first install some of these packages. This can usually be accomplished by opening up a command window on Windows and then typing

python -m pip install [package-name]

More assistance is available with the respective package docs.

---

Recent Updates

Here's some highlights from recent updates:

What's New with Version 0.70

New contributions from Dr. Misael