geostatspy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GeostatsPy - Geostatistical Analysis

GeostatsPy - 地统计学分析

Quick Reference

快速参考

python

import geostatspy.GSLIB as GSLIB
import geostatspy.geostats as geostats
import pandas as pd

df = pd.read_csv('data.csv')
df['npor'], tvpor, tnspor = geostats.nscore(df, 'porosity')  # Transform

lag, gamma, npairs = geostats.gamv(df, 'X', 'Y', 'npor',      # Variogram
    tmin=-9999, tmax=9999, xlag=50, xltol=25, nlag=15,
    azm=0, atol=22.5, bandwh=9999, bandwd=9999)

vario = GSLIB.make_variogram(nug=0.0, nst=1, it1=1, cc1=1.0,  # Model
                              azi1=0, hmaj1=300, hmin1=300)

est, var = geostats.kb2d(df, 'X', 'Y', 'npor', ..., vario=vario)  # Krige

python

import geostatspy.GSLIB as GSLIB
import geostatspy.geostats as geostats
import pandas as pd

df = pd.read_csv('data.csv')
df['npor'], tvpor, tnspor = geostats.nscore(df, 'porosity')  # 正态得分变换

lag, gamma, npairs = geostats.gamv(df, 'X', 'Y', 'npor',      # 计算Variogram
    tmin=-9999, tmax=9999, xlag=50, xltol=25, nlag=15,
    azm=0, atol=22.5, bandwh=9999, bandwd=9999)

vario = GSLIB.make_variogram(nug=0.0, nst=1, it1=1, cc1=1.0,  # 创建Variogram模型
                              azi1=0, hmaj1=300, hmin1=300)

est, var = geostats.kb2d(df, 'X', 'Y', 'npor', ..., vario=vario)  # Kriging插值

Key Functions

核心函数

Category	Functions
Visualization	`locmap` , `pixelplt` , `hist`
Variogram	`gamv` , `vmodel`
Kriging	`kb2d` , `kb3d`
Simulation	`sgsim` , `sisim`
Transforms	`nscore` , `backtr`
Declustering	`declus`

类别	函数
可视化	`locmap` , `pixelplt` , `hist`
Variogram	`gamv` , `vmodel`
Kriging	`kb2d` , `kb3d`
模拟	`sgsim` , `sisim`
变换	`nscore` , `backtr`
去聚类	`declus`

Common Operations

常见操作

1. Normal Score Transform

1. 正态得分变换

python

df['npor'], tvpor, tnspor = geostats.nscore(df, 'porosity')
original = geostats.backtr(nscore_data, tvpor, tnspor, zmin=0, zmax=0.3)

python

df['npor'], tvpor, tnspor = geostats.nscore(df, 'porosity')
original = geostats.backtr(nscore_data, tvpor, tnspor, zmin=0, zmax=0.3)

2. Experimental Variogram

2. 实验Variogram计算

python

lag, gamma, npairs = geostats.gamv(
    df, 'X', 'Y', 'npor',
    tmin=-9999, tmax=9999,    # Trimming limits
    xlag=50, xltol=25,        # Lag distance, tolerance
    nlag=15, azm=0, atol=22.5, bandwh=9999, bandwd=9999)

python

lag, gamma, npairs = geostats.gamv(
    df, 'X', 'Y', 'npor',
    tmin=-9999, tmax=9999,    # 数据截断范围
    xlag=50, xltol=25,        # 滞后距离、容差
    nlag=15, azm=0, atol=22.5, bandwh=9999, bandwd=9999)

3. Variogram Model

3. Variogram模型构建

python

undefined

python

undefined

Types: 1=spherical, 2=exponential, 3=gaussian

类型：1=球状模型, 2=指数模型, 3=高斯模型

vario = GSLIB.make_variogram( nug=0.0, nst=1, # Nugget, number of structures it1=1, cc1=1.0, # Type, sill contribution azi1=0, hmaj1=300, hmin1=300) # Azimuth, major/minor range

undefined

vario = GSLIB.make_variogram( nug=0.0, nst=1, # 块金值、结构数量 it1=1, cc1=1.0, # 模型类型、基台贡献 azi1=0, hmaj1=300, hmin1=300) # 方位角、主次变程

undefined

4. Kriging (kb2d)

4. Kriging插值（kb2d）

python

est, var = geostats.kb2d(
    df, 'X', 'Y', 'npor', tmin=-9999, tmax=9999,
    nx=50, xmn=25, xsiz=50,    # Grid X: ncells, origin, size
    ny=50, ymn=25, ysiz=50,    # Grid Y
    nxdis=1, nydis=1, ndmin=1, ndmax=10,
    radius=500, ktype=0, skmean=0.0, vario=vario)  # ktype: 0=simple, 1=ordinary

python

est, var = geostats.kb2d(
    df, 'X', 'Y', 'npor', tmin=-9999, tmax=9999,
    nx=50, xmn=25, xsiz=50,    # X网格：单元格数、原点、尺寸
    ny=50, ymn=25, ysiz=50,    # Y网格
    nxdis=1, nydis=1, ndmin=1, ndmax=10,
    radius=500, ktype=0, skmean=0.0, vario=vario)  # ktype: 0=简单kriging（已知均值）, 1=普通kriging

5. Sequential Gaussian Simulation

5. 序贯高斯模拟（SGSIM）

python

sim = geostats.sgsim(
    df, 'X', 'Y', 'npor', wcol=-1, scol=-1,
    tmin=-9999, tmax=9999, itrans=0,
    ismooth=0, dession=0, dmession=0,
    zmin=-4, zmax=4, ltail=1, ltpar=0, utail=1, utpar=0,
    nsim=1, nx=50, xmn=25, xsiz=50, ny=50, ymn=25, ysiz=50,
    nz=1, zmn=0, zsiz=1, seed=73073,
    ndmin=1, ndmax=10, nodmax=10, radius=500, radius1=500,
    sang1=0, sang2=0, sang3=0, mxctx=10, mxcty=10, mxctz=1,
    ktype=0, vario=vario)

python

sim = geostats.sgsim(
    df, 'X', 'Y', 'npor', wcol=-1, scol=-1,
    tmin=-9999, tmax=9999, itrans=0,
    ismooth=0, dession=0, dmession=0,
    zmin=-4, zmax=4, ltail=1, ltpar=0, utail=1, utpar=0,
    nsim=1, nx=50, xmn=25, xsiz=50, ny=50, ymn=25, ysiz=50,
    nz=1, zmn=0, zsiz=1, seed=73073,
    ndmin=1, ndmax=10, nodmax=10, radius=500, radius1=500,
    sang1=0, sang2=0, sang3=0, mxctx=10, mxcty=10, mxctz=1,
    ktype=0, vario=vario)

6. Declustering

6. 数据去聚类

python

wts, cell_size, ncut = geostats.declus(
    df, 'X', 'Y', 'porosity', iminmax=1, noff=10, ncell=20, cmin=10, cmax=500)
declustered_mean = np.average(df['porosity'], weights=wts)

python

wts, cell_size, ncut = geostats.declus(
    df, 'X', 'Y', 'porosity', iminmax=1, noff=10, ncell=20, cmin=10, cmax=500)
declustered_mean = np.average(df['porosity'], weights=wts)

Variogram Models

Variogram模型

Code	Model	Use Case
1	Spherical	Most common, finite range
2	Exponential	Reaches sill asymptotically
3	Gaussian	Very smooth, parabolic near origin
4	Power	Unbounded, fractal-like

代码	模型	适用场景
1	球状模型	最常用，有限变程
2	指数模型	渐近趋近基台值
3	高斯模型	平滑性高，原点附近呈抛物线
4	幂函数模型	无边界，类分形特征

Key Parameters

核心参数

Parameter	Description
`nug`	Nugget effect (measurement error + micro-scale variation)
`sill`	Total variance (nugget + structure contributions)
`range`	Distance where correlation becomes negligible
`azimuth`	Direction of maximum continuity (degrees from N)
`ktype`	0=simple kriging (known mean), 1=ordinary kriging

参数	描述
`nug`	块金效应（测量误差+微尺度变异）
`sill`	总方差（块金值+结构贡献）
`range`	相关性可忽略的距离阈值
`azimuth`	最大连续性方向（正北方向夹角，单位：度）
`ktype`	0=简单kriging（已知均值），1=普通kriging

When to Use vs Alternatives

适用场景与替代工具对比

Use Case	Tool	Why
GSLIB-style workflows	GeostatsPy	Direct port of GSLIB programs to Python
SGSIM / SISIM simulation	GeostatsPy	Full GSLIB simulation engine
Declustering spatial data	GeostatsPy	Built-in `declus` function
Modern variogram API	scikit-gstat	Cleaner API, sklearn integration
Kriging only (no simulation)	pykrige	Focused API, universal kriging support
Random field generation	gstools	Flexible covariance models, field generation
Large-scale 3D geomodelling	SGeMS / Petrel	GUI-based, industrial workflows
Indicator simulation	GeostatsPy ( `sisim` )	Categorical property simulation

Choose GeostatsPy when: You need GSLIB-compatible workflows in Python, especially for sequential simulation (SGSIM/SISIM), declustering, or if you are familiar with GSLIB parameter conventions. Best for reservoir characterization workflows.

Choose scikit-gstat when: You prefer a modern scikit-learn-style API for variogram analysis and kriging, with better integration into Python data science workflows.

Choose pykrige when: You only need kriging interpolation (no simulation) and want universal kriging with external drift or regression kriging capabilities.

场景	工具	原因
GSLIB风格工作流	GeostatsPy	GSLIB程序的Python直接移植版本
SGSIM/SISIM模拟	GeostatsPy	完整的GSLIB模拟引擎
空间数据去聚类	GeostatsPy	内置 `declus` 函数
现代Variogram API	scikit-gstat	API更简洁，支持sklearn集成
仅需Kriging插值（无需模拟）	pykrige	API专注，支持泛kriging
随机场生成	gstools	灵活的协方差模型，支持场生成
大规模3D地质建模	SGeMS / Petrel	基于GUI，适用于工业级工作流
指示模拟	GeostatsPy ( `sisim` )	适用于分类属性模拟

选择GeostatsPy的场景：需要在Python中实现GSLIB兼容的工作流，尤其是序贯模拟（SGSIM/SISIM）、去聚类操作，或者熟悉GSLIB参数约定时。最适用于储层表征工作流。

选择scikit-gstat的场景：偏好现代scikit-learn风格的API进行Variogram分析和Kriging，且需要更好地融入Python数据科学工作流时。

选择pykrige的场景：仅需Kriging插值（无需模拟），且需要支持外部漂移的泛kriging或回归kriging功能时。

Common Workflows

常见工作流

Variogram Analysis and Kriging Interpolation

Variogram分析与Kriging插值

Load spatial data into a pandas DataFrame
Explore data with
```
GSLIB.locmap()
```
and
```
GSLIB.hist()
```
Check for clustering and decluster with
```
geostats.declus()
```
if needed
Apply normal score transform with
```
geostats.nscore()
```
Compute experimental variogram with
```
geostats.gamv()
```
(isotropic first)
Check directional variograms for anisotropy (azimuths 0, 45, 90, 135)
Fit variogram model with
```
GSLIB.make_variogram()
```
Overlay model on experimental variogram to verify fit
Run kriging with
```
geostats.kb2d()
```
(ktype=1 for ordinary)
Run SGSIM for uncertainty quantification (50-100 realizations)
Back-transform results with
```
geostats.backtr()
```
Validate with cross-validation or holdout data

将空间数据加载至pandas DataFrame
使用
```
GSLIB.locmap()
```
和
```
GSLIB.hist()
```
探索数据
检查数据聚类情况，必要时使用
```
geostats.declus()
```
进行去聚类
使用
```
geostats.nscore()
```
应用正态得分变换
使用
```
geostats.gamv()
```
计算实验Variogram（先采用各向同性）
检查方向Variogram以判断各向异性（方位角0°、45°、90°、135°）
使用
```
GSLIB.make_variogram()
```
拟合Variogram模型
将模型叠加至实验Variogram以验证拟合效果
使用
```
geostats.kb2d()
```
执行Kriging（ktype=1为普通kriging）
运行SGSIM进行不确定性量化（50-100个实现）
使用
```
geostats.backtr()
```
对结果进行逆变换
通过交叉验证或预留数据验证结果

Common Issues

常见问题

Issue	Solution
Variogram doesn't reach sill	Increase `nlag` or `xlag` to capture full range
Kriging produces negative values	Back-transform after kriging, not before
SGSIM artifacts	Check grid definition (xmn, xsiz) matches data extent
Too few variogram pairs	Increase `atol` (angular tolerance) or `xltol` (lag tolerance)
Hole effect in variogram	May indicate periodicity; try nested structures

问题	解决方案
Variogram未达到基台值	增大 `nlag` 或 `xlag` 以覆盖完整变程
Kriging产生负值	在Kriging之后进行逆变换，而非之前
SGSIM出现伪影	检查网格定义（xmn、xsiz）是否与数据范围匹配
Variogram配对数过少	增大 `atol` （角度容差）或 `xltol` （滞后容差）
Variogram出现孔穴效应	可能存在周期性，尝试使用嵌套结构

Tips

提示

Always transform to normal scores - Most methods assume Gaussian
Start isotropic - Add anisotropy only if justified by directional variograms
Check variogram pairs - Ensure enough pairs at each lag
Multiple realizations - Use 50-100+ for uncertainty quantification
Back-transform last - Apply to final results only

始终转换为正态得分 - 大多数方法假设数据服从高斯分布
从各向同性开始 - 仅当方向Variogram证明存在各向异性时再添加该设置
检查Variogram配对数 - 确保每个滞后距离有足够的配对数
生成多个实现 - 使用50-100+个实现进行不确定性量化
最后进行逆变换 - 仅对最终结果应用逆变换

References

参考资料

GSLIB Programs - GSLIB program reference
Simulation Methods - SGSIM, SISIM, and other methods

GSLIB程序文档 - GSLIB程序参考
模拟方法文档 - SGSIM、SISIM及其他方法说明

Scripts

脚本示例

scripts/kriging_example.py - Complete kriging workflow

scripts/kriging_example.py - 完整Kriging工作流示例