Skip to content

Commit

Permalink
Merge pull request #162 from GeoStat-Framework/finalize_151
Browse files Browse the repository at this point in the history 
update Changelog, add pseudo-inv option to RK, update examples in documentation
  • Loading branch information
@MuellerSeb
MuellerSeb authored Aug 19, 2020
2 parents 83ae0a8 + 72b9c98 commit 1642a0d
Show file tree
Hide file tree
Showing 14 changed files with 284 additions and 208 deletions.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -121,3 +121,4 @@ pykrige/_version.py
*.vtr
examples/meuse_example_data/*
*.ipynb_checkpoints/*
examples/output.asc
16 changes: 16 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,22 @@ Changelog
=========


Version 1.5.1
-------------
*August 20, 2020*

**New features**

* update Regression Kriging class to be compatible with all kriging features (#158)
* added option to enable/disable "exact values" to all kriging routines (#153)
* added option to use the pseudo-inverse in all kriging routines (#151)

**Changes**

* removed compat-layer for sklearn (#157)
* updated examples in documentation


Version 1.5.0
-------------
*April 04, 2020*
Expand Down
198 changes: 30 additions & 168 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ PyKrige

Kriging Toolkit for Python.


Purpose
^^^^^^^

Expand All @@ -39,7 +40,9 @@ point and all grid points. With the 'functional' drift capability, the user may
of the spatial coordinates that define the drift(s). The package includes a module that contains functions
that should be useful in working with ASCII grid files (`*.asc`).

See the documentation at `http://pykrige.readthedocs.io/ <http://pykrige.readthedocs.io/>`_ for more details.
See the documentation at `http://pykrige.readthedocs.io/ <http://pykrige.readthedocs.io/>`_
for more details and examples.


Installation
^^^^^^^^^^^^
Expand All @@ -60,193 +63,52 @@ If you use conda, PyKrige can be installed from the `conda-forge` channel with,
conda install -c conda-forge pykrige
Ordinary Kriging Example
^^^^^^^^^^^^^^^^^^^^^^^^
Features
^^^^^^^^

First we will create a 2D dataset together with the associated x, y grids,
Krigging algorithms
-------------------

.. code:: python
* ``OrdinaryKriging``: 2D ordinary kriging with estimated mean
* ``UniversalKriging``: 2D universal kriging providing drift terms
* ``OrdinaryKriging3D``: 3D ordinary kriging
* ``UniversalKriging3D``: 3D universal kriging
* ``RegressionKriging``: An implementation of Regression-Kriging

import numpy as np
import pykrige.kriging_tools as kt
from pykrige.ok import OrdinaryKriging
data = np.array([[0.3, 1.2, 0.47],
[1.9, 0.6, 0.56],
[1.1, 3.2, 0.74],
[3.3, 4.4, 1.47],
[4.7, 3.8, 1.74]])
gridx = np.arange(0.0, 5.5, 0.5)
gridy = np.arange(0.0, 5.5, 0.5)
# Create the ordinary kriging object. Required inputs are the X-coordinates of
# the data points, the Y-coordinates of the data points, and the Z-values of the
# data points. If no variogram model is specified, defaults to a linear variogram
# model. If no variogram model parameters are specified, then the code automatically
# calculates the parameters by fitting the variogram model to the binned
# experimental semivariogram. The verbose kwarg controls code talk-back, and
# the enable_plotting kwarg controls the display of the semivariogram.
OK = OrdinaryKriging(data[:, 0], data[:, 1], data[:, 2], variogram_model='linear',
verbose=False, enable_plotting=False)
# Creates the kriged grid and the variance grid. Allows for kriging on a rectangular
# grid of points, on a masked rectangular grid of points, or with arbitrary points.
# (See OrdinaryKriging.__doc__ for more information.)
z, ss = OK.execute('grid', gridx, gridy)
# Writes the kriged grid to an ASCII grid file.
kt.write_asc_grid(gridx, gridy, z, filename="output.asc")
Universal Kriging Example
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code:: python
from pykrige.uk import UniversalKriging
import numpy as np
data = np.array([[0.3, 1.2, 0.47],
[1.9, 0.6, 0.56],
[1.1, 3.2, 0.74],
[3.3, 4.4, 1.47],
[4.7, 3.8, 1.74]])
gridx = np.arange(0.0, 5.5, 0.5)
gridy = np.arange(0.0, 5.5, 0.5)
# Create the ordinary kriging object. Required inputs are the X-coordinates of
# the data points, the Y-coordinates of the data points, and the Z-values of the
# data points. Variogram is handled as in the ordinary kriging case.
# drift_terms is a list of the drift terms to include; currently supported terms
# are 'regional_linear', 'point_log', and 'external_Z'. Refer to
# UniversalKriging.__doc__ for more information.
UK = UniversalKriging(data[:, 0], data[:, 1], data[:, 2], variogram_model='linear',
drift_terms=['regional_linear'])
# Creates the kriged grid and the variance grid. Allows for kriging on a rectangular
# grid of points, on a masked rectangular grid of points, or with arbitrary points.
# (See UniversalKriging.__doc__ for more information.)
z, ss = UK.execute('grid', gridx, gridy)
Three-Dimensional Kriging Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code:: python
from pykrige.ok3d import OrdinaryKriging3D
from pykrige.uk3d import UniversalKriging3D
import numpy as np
data = np.array([[0.1, 0.1, 0.3, 0.9],
[0.2, 0.1, 0.4, 0.8],
[0.1, 0.3, 0.1, 0.9],
[0.5, 0.4, 0.4, 0.5],
[0.3, 0.3, 0.2, 0.7]])
gridx = np.arange(0.0, 0.6, 0.05)
gridy = np.arange(0.0, 0.6, 0.01)
gridz = np.arange(0.0, 0.6, 0.1)
# Create the 3D ordinary kriging object and solves for the three-dimension kriged
# volume and variance. Refer to OrdinaryKriging3D.__doc__ for more information.
ok3d = OrdinaryKriging3D(data[:, 0], data[:, 1], data[:, 2], data[:, 3],
variogram_model='linear')
k3d, ss3d = ok3d.execute('grid', gridx, gridy, gridz)
# Create the 3D universal kriging object and solves for the three-dimension kriged
# volume and variance. Refer to UniversalKriging3D.__doc__ for more information.
uk3d = UniversalKriging3D(data[:, 0], data[:, 1], data[:, 2], data[:, 3],
variogram_model='linear', drift_terms=['regional_linear'])
k3d, ss3d = uk3d.execute('grid', gridx, gridy, gridz)
# To use the generic 'specified' drift term, the user must provide the drift values
# at each data point and at every grid point. The following example is equivalent to
# using a linear drift in all three spatial dimensions. Refer to
# UniversalKriging3D.__doc__ for more information.
zg, yg, xg = np.meshgrid(gridz, gridy, gridx, indexing='ij')
uk3d = UniversalKriging3D(data[:, 0], data[:, 1], data[:, 2], data[:, 3],
variogram_model='linear', drift_terms=['specified'],
specified_drift=[data[:, 0], data[:, 1]])
k3d, ss3d = uk3d.execute('grid', gridx, gridy, gridz, specified_drift_arrays=[xg, yg, zg])
# To use the generic 'functional' drift term, the user must provide a callable
# function that takes only the spatial dimensions as arguments. The following example
# is equivalent to using a linear drift only in the x-direction. Refer to
# UniversalKriging3D.__doc__ for more information.
func = lambda x, y, z: x
uk3d = UniversalKriging3D(data[:, 0], data[:, 1], data[:, 2], data[:, 3],
variogram_model='linear', drift_terms=['functional'],
functional_drift=[func])
k3d, ss3d = uk3d.execute('grid', gridx, gridy, gridz)
# Note that the use of the 'specified' and 'functional' generic drift capabilities is
# essentially identical in the two-dimensional universal kriging class (except for a
# difference in the number of spatial coordinates for the passed drift functions).
# See UniversalKriging.__doc__ for more information.
GSTools covariance models
^^^^^^^^^^^^^^^^^^^^^^^^^

You can also use `GSTools <https://github.com/GeoStat-Framework/GSTools>`_
covariance models as input for the ``variogram_model`` in the
PyKrige routines:

.. code:: python
import numpy as np
from gstools import Gaussian
from pykrige.ok import OrdinaryKriging
from matplotlib import pyplot as plt
# conditioning data
data = np.array([[0.3, 1.2, 0.47],
[1.9, 0.6, 0.56],
[1.1, 3.2, 0.74],
[3.3, 4.4, 1.47],
[4.7, 3.8, 1.74]])
# grid definition for output field
gridx = np.arange(0.0, 5.5, 0.1)
gridy = np.arange(0.0, 6.5, 0.1)
# a GSTools based covariance model
cov_model = Gaussian(dim=2, len_scale=1, anis=0.2, angles=-0.5, var=0.5, nugget=0.1)
# ordinary kriging with pykrige
OK1 = OrdinaryKriging(data[:, 0], data[:, 1], data[:, 2], cov_model)
z1, ss1 = OK1.execute('grid', gridx, gridy)
plt.imshow(z1, origin="lower")
plt.show()
Which gives:

.. image:: https://raw.githubusercontent.com/GeoStat-Framework/GSTools/master/docs/source/pics/20_pykrige.png
:width: 400px
:align: center

Have a look at the `documentation about the Covariance Model of GSTools <https://geostat-framework.readthedocs.io/projects/gstools/en/latest/tutorial_02_cov.html>`_.
Wrappers
--------

* ``rk.Krige``: A scikit-learn wrapper class for Ordinary and Universal Kriging


Tools
-----

* ``kriging_tools.write_asc_grid``: Writes gridded data to ASCII grid file (*.asc)
* ``kriging_tools.read_asc_grid``: Reads ASCII grid file (*.asc)


Kriging Parameters Tuning
^^^^^^^^^^^^^^^^^^^^^^^^^
-------------------------

A scikit-learn compatible API for parameter tuning by cross-validation is exposed in
`sklearn.model_selection.GridSearchCV <http://scikit-learn.org/stable/modules/generated/sklearn.model_selection.GridSearchCV.html>`_.
See the `Krige CV <http://pykrige.readthedocs.io/en/latest/examples/krige_cv.html#sphx-glr-examples-krige-cv-py>`_
See the `Krige CV <http://pykrige.readthedocs.io/en/latest/examples/08_krige_cv.html#sphx-glr-examples-08-krige-cv-py>`_
example for a more practical illustration.


Regression Kriging
^^^^^^^^^^^^^^^^^^
------------------

`Regression kriging <https://en.wikipedia.org/wiki/Regression-Kriging>`_ can be performed
with `pykrige.rk.RegressionKriging <http://pykrige.readthedocs.io/en/latest/examples/regression_kriging2d.html>`_.
with `pykrige.rk.RegressionKriging <http://pykrige.readthedocs.io/en/latest/examples/07_regression_kriging2d.html>`_.
This class takes as parameters a scikit-learn regression model, and details of either either
the ``OrdinaryKriging`` or the ``UniversalKriging`` class, and performs a correction steps on the ML regression prediction.

A demonstration of the regression kriging is provided in the
`corresponding example <http://pykrige.readthedocs.io/en/latest/examples/regression_kriging2d.html#sphx-glr-examples-regression-kriging2d-py>`_.
`corresponding example <http://pykrige.readthedocs.io/en/latest/examples/07_regression_kriging2d.html#sphx-glr-examples-07-regression-kriging2d-py>`_.


License
^^^^^^^
Expand Down
58 changes: 58 additions & 0 deletions examples/00_ordinary.py
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
"""
Ordinary Kriging Example
========================
First we will create a 2D dataset together with the associated x, y grids.
"""

import numpy as np
import pykrige.kriging_tools as kt
from pykrige.ok import OrdinaryKriging
import matplotlib.pyplot as plt


data = np.array(
[
[0.3, 1.2, 0.47],
[1.9, 0.6, 0.56],
[1.1, 3.2, 0.74],
[3.3, 4.4, 1.47],
[4.7, 3.8, 1.74],
]
)

gridx = np.arange(0.0, 5.5, 0.5)
gridy = np.arange(0.0, 5.5, 0.5)

###############################################################################
# Create the ordinary kriging object. Required inputs are the X-coordinates of
# the data points, the Y-coordinates of the data points, and the Z-values of the
# data points. If no variogram model is specified, defaults to a linear variogram
# model. If no variogram model parameters are specified, then the code automatically
# calculates the parameters by fitting the variogram model to the binned
# experimental semivariogram. The verbose kwarg controls code talk-back, and
# the enable_plotting kwarg controls the display of the semivariogram.

OK = OrdinaryKriging(
data[:, 0],
data[:, 1],
data[:, 2],
variogram_model="linear",
verbose=False,
enable_plotting=False,
)

###############################################################################
# Creates the kriged grid and the variance grid. Allows for kriging on a rectangular
# grid of points, on a masked rectangular grid of points, or with arbitrary points.
# (See OrdinaryKriging.__doc__ for more information.)

z, ss = OK.execute("grid", gridx, gridy)

###############################################################################
# Writes the kriged grid to an ASCII grid file and plot it.

kt.write_asc_grid(gridx, gridy, z, filename="output.asc")
plt.imshow(z)
plt.show()
50 changes: 50 additions & 0 deletions examples/01_universal.py
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
"""
Universal Kriging Example
=========================
In this example we apply a regional linear trend to the kriging system.
"""

from pykrige.uk import UniversalKriging
import numpy as np
import matplotlib.pyplot as plt


data = np.array(
[
[0.3, 1.2, 0.47],
[1.9, 0.6, 0.56],
[1.1, 3.2, 0.74],
[3.3, 4.4, 1.47],
[4.7, 3.8, 1.74],
]
)

gridx = np.arange(0.0, 5.5, 0.5)
gridy = np.arange(0.0, 5.5, 0.5)

###############################################################################
# Create the universal kriging object. Required inputs are the X-coordinates of
# the data points, the Y-coordinates of the data points, and the Z-values of the
# data points. Variogram is handled as in the ordinary kriging case.
# drift_terms is a list of the drift terms to include; currently supported terms
# are 'regional_linear', 'point_log', and 'external_Z'. Refer to
# UniversalKriging.__doc__ for more information.

UK = UniversalKriging(
data[:, 0],
data[:, 1],
data[:, 2],
variogram_model="linear",
drift_terms=["regional_linear"],
)

###############################################################################
# Creates the kriged grid and the variance grid. Allows for kriging on a rectangular
# grid of points, on a masked rectangular grid of points, or with arbitrary points.
# (See UniversalKriging.__doc__ for more information.)

z, ss = UK.execute("grid", gridx, gridy)
plt.imshow(z)
plt.show()
Loading

0 comments on commit 1642a0d

Please sign in to comment.