Software Open Access

Sebastian Müller; Lennart Schüler

**Release Notes**

A big step forward for GSTools. We now support geographical coordinates, directional variograms, auto-binning, arbitrary dimensions, normalizers and trends and much much more.

**Installation**

You can install GSTools with conda:

```
conda install -c conda-forge gstools
```

or with pip:

```
pip install gstools
```

**Documentation**

The documentation can be found at: https://gstools.readthedocs.io/

**What's new?**

**Topics**

Geographical Coordinates Support (#113)

- added boolean init parameter
`latlon`

to indicate a geographic model. When given, spatial dimension is fixed to`dim=3`

,`anis`

and`angles`

will be ignored, since anisotropy is not well-defined on a sphere. - add property
`field_dim`

to indicate the dimension of the resulting field. Will be 2 if`latlon=True`

- added yadrenko variogram, covariance and correlation method, since the geographic models are derived from standard models in 3D by plugging in the chordal distance of two points on a sphere derived from there great-circle distance
`zeta`

:`vario_yadrenko`

: given by`variogram(2 * np.sin(zeta / 2))`

`cov_yadrenko`

: given by`covariance(2 * np.sin(zeta / 2))`

`cor_yadrenko`

: given by`correlation(2 * np.sin(zeta / 2))`

- added plotting routines for yadrenko methods described above
- the
`isometrize`

and`anisometrize`

methods will convert`latlon`

tuples (given in degree) to points on the unit-sphere in 3D and vice versa - representation of geographical models don't display the
`dim`

,`anis`

and`angles`

parameters, but`latlon=True`

`fit_variogram`

will expect an estimated variogram with great-circle distances given in radians*Variogram estimation*`latlon`

switch implemented in`estimate_vario`

routine- will return a variogram estimated by the great-circle distance (haversine formula) given in radians

*Field*- added plotting routines for latlon fields
- no vector fields possible on latlon fields
- corretly handle pos tuple for latlon fields

Krige Unification (#97)

- Swiss Army Knife for kriging: The
`Krige`

class now provides everything in one place - "Kriging the mean" is now possible with the switch
`only_mean`

in the call routine `Simple`

/`Ordinary`

/`Universal`

/`ExtDrift`

/`Detrended`

are only shortcuts to`Krige`

with limited input parameter list- We now use the
`covariance`

function to build up the kriging matrix (instead of variogram) - An
`unbiased`

switch was added to enable simple kriging (where the unbiased condition is not given) - An
`exact`

switch was added to allow smother results, if a`nugget`

is present in the model - An
`cond_err`

parameter was added, where measurement error variances can be given for each conditional point - pseudo-inverse matrix is now used to solve the kriging system (can be disabled by the new switch
`pseudo_inv`

), this is equal to solving the system with least-squares and prevents numerical errors - added options
`fit_normalizer`

and`fit_variogram`

to automatically fit normalizer and variogram to given data

Directional Variograms and Auto-binning (#87, #106, #131)

- new routine name
`vario_estimate`

instead of`vario_estimate_unstructured`

(old kept for legacy code) for simplicity - new routine name
`vario_estimate_axis`

instead of`vario_estimate_structured`

(old kept for legacy code) for simplicity `vario_estimate`

- added simple automatic binning routine to determine bins from given data (one third of box diameter as max bin distance, sturges rule for number of bins)
- allow to pass multiple fields for joint variogram estimation (e.g. for daily precipitation) on same mesh
`no_data`

option added to allow missing values*masked fields*- user can now pass a masked array (or a list of masked arrays) to deselect data points.
- in addition, a
`mask`

keyword was added to provide an external mask

*directional variograms*- diretional variograms can now be estimated
- either provide a list of direction vectors or angles for directions (spherical coordinates)
- can be controlled by given angle tolerance and (optional) bandwidth
- prepared for nD

- structured fields (pos tuple describes axes) can now be passed to estimate an isotropic or directional variogram
- distance calculation in cython routines in now independent of dimension

`vario_estimate_axis`

- estimation along array axis now possible in arbitrary dimensions
`no_data`

option added to allow missing values (sovles #83)- axis can be given by name (
`"x"`

,`"y"`

,`"z"`

) or axis number (`0`

,`1`

,`2`

,`3`

, ...)

Better Variogram fitting (#78, #145)

- fixing sill possible now
`loss`

is now selectable for smoother handling of outliers- r2 score can now be returned to get an impression of the goodness of fitting
- weights can be passed
- instead of deselecting parameters, one can also give fix values for each parameter
- default init guess for
`len_scale`

is now mean of given bin-centers - default init guess for
`var`

and`nugget`

is now mean of given variogram values

- add new
`rescale`

argument and attribute to the`CovModel`

class to be able to rescale the`len_scale`

(usefull for unit conversion or rescaling`len_scale`

to coincide with the`integral_scale`

like it's the case with the Gaussian model) See: #90, GeoStat-Framework/PyKrige#119 - added new
`len_rescaled`

attribute to the`CovModel`

class, which is the rescaled`len_scale`

:`len_rescaled = len_scale / rescale`

- new method
`default_rescale`

to provide default rescale factor (can be overridden) - remove
`doctest`

calls - docstring updates in CovModel and derived models
- updated all models to use the
`cor`

routine and make use of the`rescale`

argument (See: #90) - TPL models got a separate base class to not repeat code
- added
*new models*(See: #88):`HyperSpherical`

: (Replaces the old`Intersection`

model) Derived from the intersection of hyper-spheres in arbitrary dimensions. Coincides with the linear model in 1D, the circular model in 2D and the classical spherical model in 3D`SuperSpherical`

: like the HyperSpherical, but the shape parameter derived from dimension can be set by the user. Coincides with the HyperSpherical model by default`JBessel`

: a hole model valid in all dimensions. The shape parameter controls the dimension it was derived from. For`nu=0.5`

this model coincides with the well known`wave`

hole model.`TPLSimple`

: a simple truncated power law controlled by a shape parameter`nu`

. Coincides with the truncated linear model for`nu=1`

`Cubic`

: to be compatible with scikit-gstat in the future

- string representation of the
`CovModel`

class is now using a float precision (`CovModel._prec=3`

) to truncate longish output - dimension validity check: raise a warning, if given model is not valid in the desired dimension (See: #86)

Normalizer, Trend and Mean (#124)

- new
`normalize`

submodule containing power-transforms for data to gain normality - Base-Class:
`Normalizer`

providing basic functionality including maximum likelihood fitting - added:
`LogNormal`

,`BoxCox`

,`BoxCoxShift`

,`YeoJohnson`

,`Modulus`

and`Manly`

- normalizer, trend and mean can be passed to SRF, Krige and variogram estimation routines
- A trend can be a callable function, that represents a trend in input data. For example a linear decrease of temperature with height.
- The normalizer will be applied after the data was detrended, i.e. the trend was substracted from the data, in order to gain normality.
- The mean is now interpreted as the mean of the normalized data. The user could also provide a callable mean, but it is mostly meant to be constant.

Arbitrary dimensions (#112)

- allow arbitrary dimensions in all routines (CovModel, Krige, SRF, variogram)
- anisotropy and rotation following a generalization of tait-bryan angles
- CovModel provides
`isometrize`

and`anisometrize`

routines to convert points

New Class for Conditioned Random Fields (#130)

- THIS BREAKS BACKWARD COMPATIBILITY
`CondSRF`

replaces the conditioning feature of the SRF class, which was cumbersome and limited to Ordinary and Simple kriging`CondSRF`

behaves similar to the`SRF`

class, but instead of a covariance model, it takes a kriging class as input. With this kriging class, all conditioning related settings are defined.

**Enhancements**

- Python 3.9 Support #107
- add routines to format struct. pos tuple by given
`dim`

or`shape`

- add routine to format struct. pos tuple by given
`shape`

(variogram helper) - remove
`field.tools`

subpackage - support
`meshio>=4.0`

and add as dependency - PyVista mesh support #59
- added
`EARTH_RADIUS`

as constant providing earths radius in km (can be used to rescale models) - add routines
`latlon2pos`

and`pos2latlon`

to convert lat-lon coordinates to points on unit-sphere and vice versa - a lot of new examples and tutorials
`RandMeth`

class got a switch to select the sampling strategy- plotter for n-D fields added #141
- antialias for contour plots of 2D fields #141
- building from source is now configured with
`pyproject.toml`

to care about build dependencies, see #154

**Changes**

- drop support for Python 3.5 #146
- added a finit limit for shape-parameters in some CovModels #147
- drop usage of
`pos2xyz`

and`xyz2pos`

- remove structured option from generators (structured pos need to be converted first)
- explicitly assert dim=2,3 when generating vector fields
- simplify
`pre_pos`

routine to save pos tuple and reformat it an unstructured tuple - simplify field shaping
- simplify plotting routines
- only the
`"unstructured"`

keyword is recognized everywhere, everything else is interpreted as`"structured"`

(e.g.`"rectilinear"`

) - use GitHub-Actions instead of TravisCI
- parallel build now controlled by env-var
`GSTOOLS_BUILD_PARALLEL=1`

, see #154 - install extra target for
`[dev]`

dropped, can be reproduced by`pip install gstools[test, doc]`

, see #154

**Bugfixes**

- typo in keyword argument for vario_estimate_structured #80
- isotropic rotation of SRF was not possible #100
`CovModel.opt_arg`

now sorted #103- CovModel.fit: check if weights are given as a string (numpy comparison error) #111

Files
(14.0 MB)

Name | Size | |
---|---|---|

GeoStat-Framework/GSTools-v1.3.0-rc2.zip
md5:1c96f2710102ce37377985284860f66d |
14.0 MB | Download |

978

94

views

downloads

All versions | This version | |
---|---|---|

Views | 978 | 10 |

Downloads | 94 | 0 |

Data volume | 621.5 MB | 0 Bytes |

Unique views | 799 | 8 |

Unique downloads | 58 | 0 |