:orphan:

Field transformations
=====================

The generated fields of gstools are ordinary Gaussian random fields.
In application there are several transformations to describe real world
problems in an appropriate manner.

GStools provides a submodule :py:mod:`gstools.transform` with a range of
common transformations:

.. currentmodule:: gstools.transform

.. autosummary::
   binary
   discrete
   boxcox
   zinnharvey
   normal_force_moments
   normal_to_lognormal
   normal_to_uniform
   normal_to_arcsin
   normal_to_uquad
   apply_function


All the transformations take a field class, that holds a generated field,
as input and will manipulate this field inplace or store it with a given name.

Simply apply a transformation to a field class:

.. code-block:: python

    import gstools as gs
    ...
    srf = gs.SRF(model)
    srf(...)
    gs.transform.normal_to_lognormal(srf)

Or use the provided wrapper:

.. code-block:: python

    import gstools as gs
    ...
    srf = gs.SRF(model)
    srf(...)
    srf.transform("lognormal")

Examples
--------



.. raw:: html

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

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Here we transform a field to a log-normal distribution:">

.. only:: html

  .. image:: /examples/07_transformations/images/thumb/sphx_glr_00_log_normal_thumb.png
    :alt:

  :ref:`sphx_glr_examples_07_transformations_00_log_normal.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">log-normal fields</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Here we transform a field to a binary field with only two values. The dividing value is the mean by default and the upper and lower values are derived to preserve the variance.">

.. only:: html

  .. image:: /examples/07_transformations/images/thumb/sphx_glr_01_binary_thumb.png
    :alt:

  :ref:`sphx_glr_examples_07_transformations_01_binary.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">binary fields</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Here we transform a field to a discrete field with values. If we do not give thresholds, the pairwise means of the given values are taken as thresholds. If thresholds are given, arbitrary values can be applied to the field.">

.. only:: html

  .. image:: /examples/07_transformations/images/thumb/sphx_glr_02_discrete_thumb.png
    :alt:

  :ref:`sphx_glr_examples_07_transformations_02_discrete.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Discrete fields</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Here, we transform a field with the so called &quot;Zinn &amp; Harvey&quot; transformation presented in Zinn &amp; Harvey (2003). With this transformation, one could overcome the restriction that in ordinary Gaussian random fields the mean values are the ones being the most connected.">

.. only:: html

  .. image:: /examples/07_transformations/images/thumb/sphx_glr_03_zinn_harvey_thumb.png
    :alt:

  :ref:`sphx_glr_examples_07_transformations_03_zinn_harvey.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Zinn & Harvey transformation</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="We provide two transformations to obtain bimodal distributions:">

.. only:: html

  .. image:: /examples/07_transformations/images/thumb/sphx_glr_04_bimodal_thumb.png
    :alt:

  :ref:`sphx_glr_examples_07_transformations_04_bimodal.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Bimodal fields</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="You can combine different transformations simply by successively applying them.">

.. only:: html

  .. image:: /examples/07_transformations/images/thumb/sphx_glr_05_combinations_thumb.png
    :alt:

  :ref:`sphx_glr_examples_07_transformations_05_combinations.py`

.. raw:: html

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


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:

   /examples/07_transformations/00_log_normal
   /examples/07_transformations/01_binary
   /examples/07_transformations/02_discrete
   /examples/07_transformations/03_zinn_harvey
   /examples/07_transformations/04_bimodal
   /examples/07_transformations/05_combinations



.. only:: html

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

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