:orphan:

Geographic Coordinates
======================

GSTools provides support for
`geographic coordinates <https://en.wikipedia.org/wiki/Geographic_coordinate_system>`_
given by:

- latitude ``lat``: specifies the north–south position of a point on the Earth's surface
- longitude ``lon``: specifies the east–west position of a point on the Earth's surface

If you want to use this feature for field generation or Kriging, you
have to set up a geographical covariance Model by setting ``latlon=True``
in your desired model (see :any:`CovModel`):

.. code-block:: python

    import numpy as np
    import gstools as gs

    model = gs.Gaussian(latlon=True, var=2, len_scale=np.pi / 16)

By doing so, the model will use the associated `Yadrenko` model on a sphere
(see `here <https://onlinelibrary.wiley.com/doi/abs/10.1002/sta4.84>`_).
The `len_scale` is given in radians to scale the arc-length.
In order to have a more meaningful length scale, one can use the ``geo_scale``
argument:

.. code-block:: python

    import gstools as gs

    model = gs.Gaussian(latlon=True, var=2, len_scale=500, geo_scale=gs.KM_SCALE)

Then ``len_scale`` can be interpreted as given in km.

A `Yadrenko` model :math:`C` is derived from a valid
isotropic covariance model in 3D :math:`C_{3D}` by the following relation:

.. math::
   C(\zeta)=C_{3D}\left(2r \cdot \sin\left(\frac{\zeta}{2r}\right)\right)

Where :math:`\zeta` is the
`great-circle distance <https://en.wikipedia.org/wiki/Great-circle_distance>`_
and :math:`r` is the ``geo_scale``.

.. note::

   ``lat`` and ``lon`` are given in degree, whereas the great-circle distance
   :math:`zeta` is given in units of the ``geo_scale``.

Note, that :math:`2r \cdot \sin(\frac{\zeta}{2r})` is the
`chordal distance <https://en.wikipedia.org/wiki/Chord_(geometry)>`_
of two points on a sphere with radius :math:`r`, which means we simply think of the
earth surface as a sphere, that is cut out of the surrounding three dimensional space,
when using the `Yadrenko` model.

.. note::

   Anisotropy is not available with the geographical models, since their
   geometry is not euclidean. When passing values for :any:`CovModel.anis`
   or :any:`CovModel.angles`, they will be ignored.

   Since the Yadrenko model comes from a 3D model, the model dimension will
   be 3 (see :any:`CovModel.dim`) but the `field_dim` will be 2 in this case
   (see :any:`CovModel.field_dim`).

Examples
--------


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

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

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we demonstrate how to generate a random field on geographical coordinates.">

.. only:: html

  .. image:: /examples/08_geo_coordinates/images/thumb/sphx_glr_00_field_generation_thumb.png
    :alt:

  :doc:`/examples/08_geo_coordinates/00_field_generation`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Working with lat-lon random fields</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example we are going to interpolate actual temperature data from the German weather service DWD.">

.. only:: html

  .. image:: /examples/08_geo_coordinates/images/thumb/sphx_glr_01_dwd_krige_thumb.png
    :alt:

  :doc:`/examples/08_geo_coordinates/01_dwd_krige`

.. raw:: html

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


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:

   /examples/08_geo_coordinates/00_field_generation
   /examples/08_geo_coordinates/01_dwd_krige



.. only:: html

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

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