:orphan:

.. _tutorial_02_cov:

The Covariance Model
====================

One of the core-features of GSTools is the powerful :any:`CovModel`
class, which allows you to easily define arbitrary covariance models by
yourself. The resulting models provide a bunch of nice features to explore the
covariance models.

A covariance model is used to characterize the
`semi-variogram <https://en.wikipedia.org/wiki/Variogram#Semivariogram>`_,
denoted by :math:`\gamma`, of a spatial random field.
In GSTools, we use the following form for an isotropic and stationary field:

.. math::
   \gamma\left(r\right)=
   \sigma^2\cdot\left(1-\mathrm{cor}\left(s\cdot\frac{r}{\ell}\right)\right)+n

Where:

  - :math:`r` is the lag distance
  - :math:`\ell` is the main correlation length
  - :math:`s` is a scaling factor for unit conversion or normalization
  - :math:`\sigma^2` is the variance
  - :math:`n` is the nugget (subscale variance)
  - :math:`\mathrm{cor}(h)` is the normalized correlation function depending on
    the non-dimensional distance :math:`h=s\cdot\frac{r}{\ell}`

Depending on the normalized correlation function, all covariance models in
GSTools are providing the following functions:

  - :math:`\rho(r)=\mathrm{cor}\left(s\cdot\frac{r}{\ell}\right)`
    is the so called
    `correlation <https://en.wikipedia.org/wiki/Autocovariance#Normalization>`_
    function
  - :math:`C(r)=\sigma^2\cdot\rho(r)` is the so called
    `covariance <https://en.wikipedia.org/wiki/Covariance_function>`_
    function, which gives the name for our GSTools class

.. note::

   We are not limited to isotropic models. GSTools supports anisotropy ratios
   for length scales in orthogonal transversal directions like:

   - :math:`x_0` (main direction)
   - :math:`x_1` (1. transversal direction)
   - :math:`x_2` (2. transversal direction)
   - ...

   These main directions can also be rotated.
   Just have a look at the corresponding examples.

Provided Covariance Models
--------------------------

.. currentmodule:: gstools.covmodel

The following standard covariance models are provided by GSTools

.. autosummary::
    Gaussian
    Exponential
    Matern
    Integral
    Stable
    Rational
    Cubic
    Linear
    Circular
    Spherical
    HyperSpherical
    SuperSpherical
    JBessel
    TPLSimple

As a special feature, we also provide truncated power law (TPL) covariance models

.. autosummary::
    TPLGaussian
    TPLExponential
    TPLStable

These models provide a lower and upper length scale truncation
for superpositioned models.

Examples
--------



.. raw:: html

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

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Let us start with a short example of a self defined model (Of course, we provide a lot of predefined models [See: gstools.covmodel], but they all work the same way). Therefore we reimplement the Gaussian covariance model by defining just the &quot;normalized&quot; correlation function:">

.. only:: html

  .. image:: /examples/02_cov_model/images/thumb/sphx_glr_00_intro_thumb.png
    :alt:

  :ref:`sphx_glr_examples_02_cov_model_00_intro.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Introductory example</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The covariance model class CovModel of GSTools provides a set of handy methods.">

.. only:: html

  .. image:: /examples/02_cov_model/images/thumb/sphx_glr_01_basic_methods_thumb.png
    :alt:

  :ref:`sphx_glr_examples_02_cov_model_01_basic_methods.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Basic Methods</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The internally used (semi-) variogram represents the isotropic case for the model. Nevertheless, you can provide anisotropy ratios by:">

.. only:: html

  .. image:: /examples/02_cov_model/images/thumb/sphx_glr_02_aniso_rotation_thumb.png
    :alt:

  :ref:`sphx_glr_examples_02_cov_model_02_aniso_rotation.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Anisotropy and Rotation</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The spectrum of a covariance model is given by:">

.. only:: html

  .. image:: /examples/02_cov_model/images/thumb/sphx_glr_03_spectral_methods_thumb.png
    :alt:

  :ref:`sphx_glr_examples_02_cov_model_03_spectral_methods.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Spectral methods</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Besides the length-scale, there are many other ways of characterizing a certain scale of a covariance model. We provide two common scales with the covariance model.">

.. only:: html

  .. image:: /examples/02_cov_model/images/thumb/sphx_glr_04_different_scales_thumb.png
    :alt:

  :ref:`sphx_glr_examples_02_cov_model_04_different_scales.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Different scales</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Let&#x27;s pimp our self-defined model Gau from the introductory example by setting the exponent as an additional parameter:">

.. only:: html

  .. image:: /examples/02_cov_model/images/thumb/sphx_glr_05_additional_para_thumb.png
    :alt:

  :ref:`sphx_glr_examples_02_cov_model_05_additional_para.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Additional Parameters</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The model class comes with a routine to fit the model-parameters to given variogram data. In the following we will use the self defined stable model from a previous example.">

.. only:: html

  .. image:: /examples/02_cov_model/images/thumb/sphx_glr_06_fitting_para_ranges_thumb.png
    :alt:

  :ref:`sphx_glr_examples_02_cov_model_06_fitting_para_ranges.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Fitting variogram data</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:

   /examples/02_cov_model/00_intro
   /examples/02_cov_model/01_basic_methods
   /examples/02_cov_model/02_aniso_rotation
   /examples/02_cov_model/03_spectral_methods
   /examples/02_cov_model/04_different_scales
   /examples/02_cov_model/05_additional_para
   /examples/02_cov_model/06_fitting_para_ranges



.. only:: html

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

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