:orphan:

Spatio-Temporal Modeling
========================

Spatio-Temporal modelling can provide insights into time dependent processes
like rainfall, air temperature or crop yield.

GSTools provides the metric spatio-temporal model for all covariance models
by setting ``temporal=True``, which enhances the spatial model dimension with
a time dimension to result in the spatio-temporal dimension.
Since the model dimension is then higher than the spatial dimension, you can use
the ``spatial_dim`` argument to explicitly set the spatial dimension.
Doing that and setting a spatio-temporal anisotropy ratio looks like this:

.. code-block:: python

    import gstools as gs
    dim = 3  # spatial dimension
    st_anis = 0.4
    st_model = gs.Exponential(temporal=True, spatial_dim=dim, anis=st_anis)

Since it is given in the name "spatio-temporal", time is always treated as last dimension.
You could also use ``dim`` to specify the dimension but note that it needs to include
the temporal dimension.

There are now three different dimension attributes giving information about (i) the
model dimension (``dim``), (ii) the field dimension (``field_dim``, including time) and
(iii) the spatial dimension (``spatial_dim`` always 1 less than ``field_dim`` for temporal models).
Model and field dimension can differ in case of geographic coordinates where the model dimension is 3,
but the field or parametric dimension is 2.
If the model is spatio-temporal with geographic coordinates, the model dimension is 4,
the field dimension is 3 and the spatial dimension is 2.

In the case above we get:

.. code-block:: python

    st_model.dim == 4
    st_model.field_dim == 4
    st_model.spatial_dim == 3

This formulation enables us to have spatial anisotropy and rotation defined as in
non-temporal models, without altering the behavior in the time dimension:

.. code-block:: python

    anis = [0.4, 0.2]  # spatial anisotropy in 3D
    angles = [0.5, 0.4, 0.3]  # spatial rotation in 3D
    st_model = gs.Exponential(temporal=True, spatial_dim=dim, anis=anis+[st_anis], angles=angles)

In order to generate spatio-temporal position tuples, GSTools provides a
convenient function :any:`generate_st_grid`. The output can be used for
spatio-temporal random field generation (or kriging resp. conditioned fields):

.. code-block:: python

    pos = dim * [1, 2, 3]  # 3 points in space (1,1,1), (2,2,2) and (3,3,3)
    time = range(10)  # 10 time steps
    st_grid = gs.generate_st_grid(pos, time)
    st_rf = gs.SRF(st_model)
    st_field = st_rf(st_grid).reshape(-1, len(time))

Then we can access the different time-steps by the last array index.

Examples
--------



.. raw:: html

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

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example we will create a time series of a 1D synthetic precipitation field.">

.. only:: html

  .. image:: /examples/09_spatio_temporal/images/thumb/sphx_glr_01_precip_1d_thumb.png
    :alt:

  :ref:`sphx_glr_examples_09_spatio_temporal_01_precip_1d.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Creating a 1D Synthetic Precipitation Field</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example we&#x27;ll create a time series of a 2D synthetic precipitation field.">

.. only:: html

  .. image:: /examples/09_spatio_temporal/images/thumb/sphx_glr_02_precip_2d_thumb.gif
    :alt:

  :ref:`sphx_glr_examples_09_spatio_temporal_02_precip_2d.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Creating a 2D Synthetic Precipitation Field</div>
    </div>


.. raw:: html

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

.. only:: html

  .. image:: /examples/09_spatio_temporal/images/thumb/sphx_glr_03_geographic_coordinates_thumb.png
    :alt:

  :ref:`sphx_glr_examples_09_spatio_temporal_03_geographic_coordinates.py`

.. raw:: html

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


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:

   /examples/09_spatio_temporal/01_precip_1d
   /examples/09_spatio_temporal/02_precip_2d
   /examples/09_spatio_temporal/03_geographic_coordinates



.. only:: html

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

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