0
# Covariance Models
1

2
Covariance models define the spatial correlation structure for geostatistical fields. GSTools provides base classes for custom model development and 20+ built-in models covering standard geostatistical applications and specialized scenarios.
3

4
## Capabilities
5

6
### Base Classes
7

8
Core classes for defining covariance models, with full support for anisotropy, rotation, spatio-temporal modeling, and geographic coordinate systems.
9

10
```python { .api }
11
class CovModel:
12
    """
13
    Base class for all covariance models.
14
    
15
    Parameters:
16
    - dim (int): Spatial dimension (1, 2, or 3)
17
    - var (float): Variance (sill) of the covariance model
18
    - len_scale (float or array-like): Correlation length scale(s)
19
    - nugget (float): Nugget effect (measurement error variance)
20
    - anis (float or array-like): Anisotropy ratios
21
    - angles (float or array-like): Rotation angles for anisotropy
22
    - integral_scale (float or array-like): Integral scale(s)
23
    - rescale (float or array-like): Rescaling factor(s)
24
    - latlon (bool): Use geographic coordinates
25
    - geo_scale (float): Geographic scaling factor (default: RADIAN_SCALE)
26
    - temporal (bool): Include temporal dimension
27
    - spatial_dim (int): Number of spatial dimensions when temporal=True
28
    - hankel_kw (dict): Keywords for Hankel transformation
29
    - **opt_arg: Optional arguments for specific model implementations
30
    """
31
    def __init__(self, dim=3, var=1.0, len_scale=1.0, nugget=0.0, anis=1.0, 
32
                 angles=0.0, *, integral_scale=None, rescale=None, latlon=False, 
33
                 geo_scale=RADIAN_SCALE, temporal=False, spatial_dim=None, 
34
                 hankel_kw=None, **opt_arg): ...
35
    
36
    def variogram(self, r):
37
        """
38
        Calculate variogram values.
39
        
40
        Parameters:
41
        - r (array-like): Distances
42
        
43
        Returns:
44
        - array: Variogram values
45
        """
46
    
47
    def covariance(self, r):
48
        """
49
        Calculate covariance values.
50
        
51
        Parameters:
52
        - r (array-like): Distances
53
        
54
        Returns:
55
        - array: Covariance values
56
        """
57
    
58
    def correlation(self, r):
59
        """
60
        Calculate correlation values.
61
        
62
        Parameters:
63
        - r (array-like): Distances
64
        
65
        Returns:
66
        - array: Correlation values
67
        """
68
    
69
    def vario_spatial(self, pos):
70
        """Calculate variogram at spatial positions."""
71
    
72
    def cov_spatial(self, pos):
73
        """Calculate covariance at spatial positions."""
74
    
75
    def cor_spatial(self, pos):
76
        """Calculate correlation at spatial positions."""
77
    
78
    def spectrum(self, k):
79
        """Calculate power spectrum."""
80
        
81
    def spectral_density(self, k):
82
        """Calculate spectral density."""
83
    
84
    def fit_variogram(self, x_data, y_data, nugget=True, sill=True, 
85
                      weights=None, method='trf', loss='soft_l1', **kwargs):
86
        """
87
        Fit model parameters to empirical variogram.
88
        
89
        Parameters:
90
        - x_data (array-like): Distance values
91
        - y_data (array-like): Variogram values
92
        - nugget (bool): Fit nugget parameter
93
        - sill (bool): Fit sill parameter
94
        - weights (array-like): Data weights
95
        - method (str): Optimization method
96
        - loss (str): Loss function
97
        
98
        Returns:
99
        - dict: Fitted parameters and optimization results
100
        """
101
    
102
    def plot(self, func='variogram', x_min=0.0, x_max=None, fig=None, ax=None): ...
103
    def calc_integral_scale(self): ...
104
    def set_arg_bounds(self, **kwargs): ...
105

106
class SumModel(CovModel):
107
    """
108
    Sum of multiple covariance models.
109
    
110
    Parameters:
111
    - models (list): List of CovModel instances
112
    - **kwargs: Additional CovModel parameters
113
    """
114
    def __init__(self, *models, **kwargs): ...
115
    
116
    def set_var_weights(self, weights):
117
        """Set variance weights for component models."""
118
    
119
    def set_len_weights(self, weights):
120
        """Set length scale weights for component models."""
121
```
122

123
### Standard Covariance Models
124

125
Built-in covariance models for common geostatistical applications. All inherit from CovModel and support its full parameter set.
126

127
```python { .api }
128
class Nugget(CovModel):
129
    """Pure nugget effect model (white noise)."""
130

131
class Gaussian(CovModel):
132
    """Gaussian (squared exponential) covariance model."""
133

134
class Exponential(CovModel):
135
    """Exponential covariance model."""
136

137
class Matern(CovModel):
138
    """
139
    Matérn covariance model.
140
    
141
    Additional Parameters:
142
    - nu (float): Shape parameter controlling smoothness (default: 1.0)
143
    """
144
    def __init__(self, nu=1.0, **kwargs): ...
145

146
class Integral(CovModel):
147
    """
148
    Exponential integral covariance model.
149
    
150
    Additional Parameters:
151
    - nu (float): Shape parameter (default: 1.0)
152
    """
153
    def __init__(self, nu=1.0, **kwargs): ...
154

155
class Stable(CovModel):
156
    """
157
    Stable (powered exponential) covariance model.
158
    
159
    Additional Parameters:
160
    - alpha (float): Shape parameter, 0 < alpha <= 2 (default: 1.5)
161
    """
162
    def __init__(self, alpha=1.5, **kwargs): ...
163

164
class Rational(CovModel):
165
    """
166
    Rational quadratic covariance model.
167
    
168
    Additional Parameters:
169
    - alpha (float): Shape parameter (default: 1.0)
170
    """
171
    def __init__(self, alpha=1.0, **kwargs): ...
172

173
class Cubic(CovModel):
174
    """Cubic covariance model."""
175

176
class Linear(CovModel):
177
    """Linear covariance model (1D only)."""
178

179
class Circular(CovModel):
180
    """Circular covariance model (1D-2D)."""
181

182
class Spherical(CovModel):
183
    """Spherical covariance model (1D-3D)."""
184

185
class HyperSpherical(CovModel):
186
    """Hyper-spherical covariance model."""
187

188
class SuperSpherical(CovModel):
189
    """
190
    Super-spherical covariance model.
191
    
192
    Additional Parameters:
193
    - nu (float): Shape parameter (default: (dim-1)/2)
194
    """
195
    def __init__(self, nu=None, **kwargs): ...
196

197
class JBessel(CovModel):
198
    """
199
    J-Bessel hole model.
200
    
201
    Additional Parameters:
202
    - nu (float): Shape parameter (default: dim/2)
203
    """
204
    def __init__(self, nu=None, **kwargs): ...
205
```
206

207
### Truncated Power Law Models
208

209
Specialized models with truncated power law behavior for complex spatial structures.
210

211
```python { .api }
212
class TPLGaussian(CovModel):
213
    """
214
    Truncated Power Law with Gaussian modes.
215
    
216
    Additional Parameters:
217
    - hurst (float): Hurst coefficient (default: 0.5)  
218
    - len_low (float): Lower length scale cutoff (default: 0.0)
219
    """
220
    def __init__(self, hurst=0.5, len_low=0.0, **kwargs): ...
221

222
class TPLExponential(CovModel):
223
    """
224
    Truncated Power Law with Exponential modes.
225
    
226
    Additional Parameters:
227
    - hurst (float): Hurst coefficient (default: 0.25)
228
    - len_low (float): Lower length scale cutoff (default: 0.0)
229
    """
230
    def __init__(self, hurst=0.25, len_low=0.0, **kwargs): ...
231

232
class TPLStable(CovModel):
233
    """
234
    Truncated Power Law with Stable modes.
235
    
236
    Additional Parameters:
237
    - hurst (float): Hurst coefficient (default: 0.5)
238
    - alpha (float): Stable shape parameter (default: 1.5)
239
    - len_low (float): Lower length scale cutoff (default: 0.0)
240
    """
241
    def __init__(self, hurst=0.5, alpha=1.5, len_low=0.0, **kwargs): ...
242

243
class TPLSimple(CovModel):
244
    """
245
    Simple truncated power law model.
246
    
247
    Additional Parameters:
248
    - nu (float): Shape parameter (default: (dim+1)/2)
249
    """
250
    def __init__(self, nu=None, **kwargs): ...
251
```
252

253
## Usage Examples
254

255
### Basic Model Creation
256

257
```python
258
import gstools as gs
259

260
# Simple Gaussian model
261
model = gs.Gaussian(dim=2, var=2.0, len_scale=10.0)
262

263
# Anisotropic exponential model with rotation
264
model = gs.Exponential(
265
    dim=2, 
266
    var=1.5, 
267
    len_scale=[20.0, 5.0],  # Different scales in each direction
268
    angles=np.pi/4,         # 45-degree rotation
269
    nugget=0.1              # Small nugget effect
270
)
271

272
# Matérn model with custom smoothness
273
model = gs.Matern(dim=3, var=3.0, len_scale=15.0, nu=2.5)
274
```
275

276
### Model Fitting to Empirical Variogram
277

278
```python
279
# Create empirical variogram data
280
bin_edges = gs.standard_bins(pos, max_dist=50)
281
emp_vario = gs.vario_estimate(pos, field_data, bin_edges)
282

283
# Fit Gaussian model
284
model = gs.Gaussian(dim=2)
285
fit_results = model.fit_variogram(emp_vario[0], emp_vario[1])
286
print(f"Fitted variance: {model.var}")
287
print(f"Fitted length scale: {model.len_scale}")
288
```
289

290
### Composite Models
291

292
```python
293
# Sum of exponential and nugget
294
nugget = gs.Nugget(var=0.2)
295
exponential = gs.Exponential(var=1.8, len_scale=20.0)
296
composite = gs.SumModel(nugget, exponential)
297

298
# Nested structures
299
short_range = gs.Gaussian(var=0.5, len_scale=5.0)
300
long_range = gs.Exponential(var=1.0, len_scale=50.0)
301
nested = gs.SumModel(short_range, long_range)
302
```
303

304
## Properties and Methods
305

306
All covariance models provide the following key properties:
307

308
- **var**: Model variance (sill)
309
- **len_scale**: Correlation length scale(s)  
310
- **nugget**: Nugget effect
311
- **anis**: Anisotropy ratios
312
- **angles**: Rotation angles
313
- **sill**: Total sill (var + nugget)
314
- **dim**: Spatial dimension
315
- **latlon**: Geographic coordinate flag
316
- **temporal**: Temporal modeling flag
317

318
Key methods include:
319
- Correlation functions: `variogram()`, `covariance()`, `correlation()`
320
- Spatial evaluation: `vario_spatial()`, `cov_spatial()`, `cor_spatial()`  
321
- Spectral analysis: `spectrum()`, `spectral_density()`
322
- Parameter estimation: `fit_variogram()`
323
- Visualization: `plot()`
324
- Scale calculations: `calc_integral_scale()`