.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "basic_examples/plot_infer_heterosc.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_basic_examples_plot_infer_heterosc.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_basic_examples_plot_infer_heterosc.py:


Elevation error map
===================

Digital elevation models have a precision that can vary with terrain and instrument-related variables. Here, we
rely on a non-stationary spatial statistics framework to estimate and model this variability in elevation error,
using terrain slope and maximum curvature as explanatory variables, with stable terrain as an error proxy for moving
terrain.

**Reference:** `Hugonnet et al. (2022) <https://doi.org/10.1109/jstars.2022.3188922>`_.

.. GENERATED FROM PYTHON SOURCE LINES 12-17

.. code-block:: Python


    import geoutils as gu

    import xdem








.. GENERATED FROM PYTHON SOURCE LINES 19-22

We load a difference of DEMs at Longyearbyen, already coregistered using :ref:`nuthkaab` as shown in
the :ref:`sphx_glr_basic_examples_plot_nuth_kaab.py` example. We also load the reference DEM to derive terrain
attributes and the glacier outlines here corresponding to moving terrain.

.. GENERATED FROM PYTHON SOURCE LINES 22-26

.. code-block:: Python

    dh = xdem.DEM(xdem.examples.get_path("longyearbyen_ddem"))
    ref_dem = xdem.DEM(xdem.examples.get_path("longyearbyen_ref_dem"))
    glacier_outlines = gu.Vector(xdem.examples.get_path("longyearbyen_glacier_outlines"))








.. GENERATED FROM PYTHON SOURCE LINES 27-28

We derive the terrain slope and max curvature from the reference DEM.

.. GENERATED FROM PYTHON SOURCE LINES 28-30

.. code-block:: Python

    slope, max_curvature = xdem.terrain.get_terrain_attribute(ref_dem, attribute=["slope", "max_curvature"])








.. GENERATED FROM PYTHON SOURCE LINES 31-32

Then, we run the pipeline for inference of elevation heteroscedasticity from stable terrain:

.. GENERATED FROM PYTHON SOURCE LINES 32-36

.. code-block:: Python

    errors, df_binning, error_function = xdem.spatialstats.infer_heteroscedasticity_from_stable(
        dvalues=dh, list_var=[slope, max_curvature], list_var_names=["slope", "maxc"], unstable_mask=glacier_outlines
    )








.. GENERATED FROM PYTHON SOURCE LINES 37-38

The first output corresponds to the error map for the DEM (:math:`\pm` 1\ :math:`\sigma` level):

.. GENERATED FROM PYTHON SOURCE LINES 38-40

.. code-block:: Python

    errors.plot(vmin=2, vmax=7, cmap="Reds", cbar_title=r"Elevation error (1$\sigma$, m)")




.. image-sg:: /basic_examples/images/sphx_glr_plot_infer_heterosc_001.png
   :alt: plot infer heterosc
   :srcset: /basic_examples/images/sphx_glr_plot_infer_heterosc_001.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 41-42

The second output is the dataframe of 2D binning with slope and max curvature:

.. GENERATED FROM PYTHON SOURCE LINES 42-44

.. code-block:: Python

    df_binning






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>nd</th>
          <th>count</th>
          <th>nmad</th>
          <th>slope</th>
          <th>maxc</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>1</td>
          <td>280392.0</td>
          <td>2.189184</td>
          <td>[3.1805545068312735e-14, 5.9084978103637695)</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>1</th>
          <td>1</td>
          <td>192490.0</td>
          <td>2.218063</td>
          <td>[5.9084978103637695, 11.816995620727539)</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>2</th>
          <td>1</td>
          <td>144898.0</td>
          <td>2.325252</td>
          <td>[11.816995620727539, 17.725494384765625)</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>3</th>
          <td>1</td>
          <td>150927.0</td>
          <td>2.565186</td>
          <td>[17.725494384765625, 23.633991241455078)</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>4</th>
          <td>1</td>
          <td>171491.0</td>
          <td>2.759741</td>
          <td>[23.633991241455078, 29.542490005493164)</td>
          <td>NaN</td>
        </tr>
        <tr>
          <th>...</th>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
        </tr>
        <tr>
          <th>95</th>
          <td>2</td>
          <td>0.0</td>
          <td>NaN</td>
          <td>[53.176483154296875, 59.08498001098633)</td>
          <td>[1.8829385042190552, 2.409055471420288)</td>
        </tr>
        <tr>
          <th>96</th>
          <td>2</td>
          <td>0.0</td>
          <td>NaN</td>
          <td>[53.176483154296875, 59.08498001098633)</td>
          <td>[2.409055471420288, 2.9351725578308105)</td>
        </tr>
        <tr>
          <th>97</th>
          <td>2</td>
          <td>0.0</td>
          <td>NaN</td>
          <td>[53.176483154296875, 59.08498001098633)</td>
          <td>[2.9351725578308105, 3.461289644241333)</td>
        </tr>
        <tr>
          <th>98</th>
          <td>2</td>
          <td>0.0</td>
          <td>NaN</td>
          <td>[53.176483154296875, 59.08498001098633)</td>
          <td>[3.461289644241333, 3.9874064922332764)</td>
        </tr>
        <tr>
          <th>99</th>
          <td>2</td>
          <td>0.0</td>
          <td>NaN</td>
          <td>[53.176483154296875, 59.08498001098633)</td>
          <td>[3.9874064922332764, 4.513523578643799)</td>
        </tr>
      </tbody>
    </table>
    <p>120 rows × 5 columns</p>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 45-47

The third output is the 2D binning interpolant, i.e. an error function with the slope and max curvature
(*Note: below we divide the max curvature by 100 to convert it in* m\ :sup:`-1` ):

.. GENERATED FROM PYTHON SOURCE LINES 47-53

.. code-block:: Python

    for slope, maxc in [(0, 0), (40, 0), (0, 5), (40, 5)]:
        print(
            "Error for a slope of {:.0f} degrees and"
            " {:.2f} m-1 max. curvature: {:.1f} m".format(slope, maxc / 100, error_function((slope, maxc)))
        )





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Error for a slope of 0 degrees and 0.00 m-1 max. curvature: 2.2 m
    Error for a slope of 40 degrees and 0.00 m-1 max. curvature: 4.1 m
    Error for a slope of 0 degrees and 0.05 m-1 max. curvature: 2.4 m
    Error for a slope of 40 degrees and 0.05 m-1 max. curvature: 5.1 m




.. GENERATED FROM PYTHON SOURCE LINES 54-58

This pipeline will not always work optimally with default parameters: spread estimates can be affected by skewed
distributions, the binning by extreme range of values, some DEMs do not have any error variability with terrain (e.g.,
terrestrial photogrammetry). **To learn how to tune more parameters and use the subfunctions, see the gallery example:**
:ref:`sphx_glr_advanced_examples_plot_heterosc_estimation_modelling.py`!


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 2.269 seconds)


.. _sphx_glr_download_basic_examples_plot_infer_heterosc.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_infer_heterosc.ipynb <plot_infer_heterosc.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_infer_heterosc.py <plot_infer_heterosc.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_infer_heterosc.zip <plot_infer_heterosc.zip>`


.. only:: html

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

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