:orphan:

.. _tutorial_05_kriging:

Kriging
=======

The subpackage :py:mod:`gstools.krige` provides routines for Gaussian process regression,
also known as kriging.
Kriging is a method of data interpolation based on predefined covariance models.

The aim of kriging is to derive the value of a field at some point :math:`x_0`,
when there are fixed observed values :math:`z(x_1)\ldots z(x_n)` at given points :math:`x_i`.

The resluting value :math:`z_0` at :math:`x_0` is calculated as a weighted mean:

.. math::

   z_0 = \sum_{i=1}^n w_i \cdot z_i

The weights :math:`W = (w_1,\ldots,w_n)` depent on the given covariance model and the location of the target point.

The different kriging approaches provide different ways of calculating :math:`W`.

The :any:`Krige` class provides everything in one place and you can switch on/off
the features you want:

* `unbiased`: the weights have to sum up to `1`. If true, this results in
  :any:`Ordinary` kriging, where the mean is estimated, otherwise it will result in
  :any:`Simple` kriging, where the mean has to be given.
* `drift_functions`: you can give a polynomial order or a list of self defined
  functions representing the internal drift of the given values. This drift will
  be fitted internally during the kriging interpolation. This results in :any:`Universal` kriging.
* `ext_drift`: You can also give an external drift per point to the routine.
  In contrast to the internal drift, that is evaluated at the desired points with
  the given functions, the external drift has to given for each point form an "external"
  source. This results in :any:`ExtDrift` kriging.
* `trend`, `mean`, `normalizer`: These are used to pre- and post-process data.
  If you already have fitted a trend model that is provided as a callable function,
  you can give it to the kriging routine. Normalizer are power-transformations
  to gain normality.
  `mean` behaves similar to `trend` but is applied at another position:

      1. conditioning data is de-trended (substracting trend)
      2. detrended conditioning data is then normalized (in order to follow a normal distribution)
      3. normalized conditioning data is set to zero mean (subtracting mean)

  Cosequently, when there is no normalizer given, trend and mean are the same thing
  and only one should be used.
  :any:`Detrended` kriging is a shortcut to provide only a trend and simple kriging
  with normal data.
* `exact` and `cond_err`: To incorporate the nugget effect and/or measurement errors,
  one can set `exact` to `False` and provide either individual measurement errors
  for each point or set the nugget as a constant measurement error everywhere.
* `pseudo_inv`: Sometimes the inversion of the kriging matrix can be numerically unstable.
  This occurs for examples in cases of redundant input values. In this case we provide a switch to
  use the pseudo-inverse of the matrix. Then redundant conditional values will automatically
  be averaged.

.. note::

   All mentioned features can be combined within the :any:`Krige` class.
   All other kriging classes are just shortcuts to this class with a limited list
   of input parameters.

The routines for kriging are almost identical to the routines for spatial random fields,
with regard to their handling.
First you define a covariance model, as described in :ref:`tutorial_02_cov`,
then you initialize the kriging class with this model:

.. code-block:: python

    import gstools as gs
    # condtions
    cond_pos = [...]
    cond_val = [...]
    model = gs.Gaussian(dim=1, var=0.5, len_scale=2)
    krig = gs.krige.Simple(model, cond_pos=cond_pos, cond_val=cond_val, mean=1)

The resulting field instance ``krig`` has the same methods as the
:any:`SRF` class.
You can call it to evaluate the kriged field at different points,
you can plot the latest field or you can export the field and so on.

Provided Kriging Methods
------------------------

.. currentmodule:: gstools.krige

The following kriging methods are provided within the
submodule :any:`gstools.krige`.

.. autosummary::
    Krige
    Simple
    Ordinary
    Universal
    ExtDrift
    Detrended

Examples
--------



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Simple kriging assumes a known mean of the data. For simplicity we assume a mean of 0, which can be achieved by subtracting the mean from the observed values and subsequently adding it to the resulting data.">

.. only:: html

  .. image:: /examples/05_kriging/images/thumb/sphx_glr_00_simple_kriging_thumb.png
    :alt:

  :ref:`sphx_glr_examples_05_kriging_00_simple_kriging.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Simple Kriging</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Ordinary kriging will estimate an appropriate mean of the field, based on the given observations/conditions and the covariance model used.">

.. only:: html

  .. image:: /examples/05_kriging/images/thumb/sphx_glr_01_ordinary_kriging_thumb.png
    :alt:

  :ref:`sphx_glr_examples_05_kriging_01_ordinary_kriging.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Ordinary Kriging</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="To use fancier methods like regression kriging, we provide an interface to PyKrige (&gt;v1.5), which means you can pass a GSTools covariance model to the kriging routines of PyKrige.">

.. only:: html

  .. image:: /examples/05_kriging/images/thumb/sphx_glr_02_pykrige_interface_thumb.png
    :alt:

  :ref:`sphx_glr_examples_05_kriging_02_pykrige_interface.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Interface to PyKrige</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Compare Kriging">

.. only:: html

  .. image:: /examples/05_kriging/images/thumb/sphx_glr_03_compare_kriging_thumb.png
    :alt:

  :ref:`sphx_glr_examples_05_kriging_03_compare_kriging.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Compare Kriging</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="External Drift Kriging">

.. only:: html

  .. image:: /examples/05_kriging/images/thumb/sphx_glr_04_extdrift_kriging_thumb.png
    :alt:

  :ref:`sphx_glr_examples_05_kriging_04_extdrift_kriging.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">External Drift Kriging</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="You can give a polynomial order or a list of self defined functions representing the internal drift of the given values. This drift will be fitted internally during the kriging interpolation.">

.. only:: html

  .. image:: /examples/05_kriging/images/thumb/sphx_glr_05_universal_kriging_thumb.png
    :alt:

  :ref:`sphx_glr_examples_05_kriging_05_universal_kriging.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Universal Kriging</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Detrended Kriging">

.. only:: html

  .. image:: /examples/05_kriging/images/thumb/sphx_glr_06_detrended_kriging_thumb.png
    :alt:

  :ref:`sphx_glr_examples_05_kriging_06_detrended_kriging.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Detrended Kriging</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Detrended Ordinary Kriging">

.. only:: html

  .. image:: /examples/05_kriging/images/thumb/sphx_glr_07_detrended_ordinary_kriging_thumb.png
    :alt:

  :ref:`sphx_glr_examples_05_kriging_07_detrended_ordinary_kriging.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Detrended Ordinary Kriging</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="To incorporate the nugget effect and/or given measurement errors, one can set exact to False and provide either individual measurement errors for each point or set the nugget as a constant measurement error everywhere.">

.. only:: html

  .. image:: /examples/05_kriging/images/thumb/sphx_glr_08_measurement_errors_thumb.png
    :alt:

  :ref:`sphx_glr_examples_05_kriging_08_measurement_errors.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Incorporating measurement errors</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="It can happen, that the kriging system gets numerically unstable. One reason could be, that the input data contains redundant conditioning points that hold different values.">

.. only:: html

  .. image:: /examples/05_kriging/images/thumb/sphx_glr_09_pseudo_inverse_thumb.png
    :alt:

  :ref:`sphx_glr_examples_05_kriging_09_pseudo_inverse.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Redundant data and pseudo-inverse</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:

   /examples/05_kriging/00_simple_kriging
   /examples/05_kriging/01_ordinary_kriging
   /examples/05_kriging/02_pykrige_interface
   /examples/05_kriging/03_compare_kriging
   /examples/05_kriging/04_extdrift_kriging
   /examples/05_kriging/05_universal_kriging
   /examples/05_kriging/06_detrended_kriging
   /examples/05_kriging/07_detrended_ordinary_kriging
   /examples/05_kriging/08_measurement_errors
   /examples/05_kriging/09_pseudo_inverse



.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_