This example will demonstrate a joint inversion of a finite rectangular fault plane for the 2019 Ridgecrest Earthquake. We will jointly invert InSAR and GNSS data using Grond. Unwrapped InSAR surface displacement data from the `Advanced Rapid Imaging and Analysis (ARIA) Project for Natural Hazards <https://aria.jpl.nasa.gov/>`_ by JPL/NASA. The coseismic GNSS displacements are delivered by `Nevada Geodetic Laboratory <http://geodesy.unr.edu/index.php>`_.

This example will demonstrate a non-linear optimisation of a finite rectangular fault plane using Grond based on static displacement data. Here we use coseismic InSAR and GNSS displacements measured for the 2019 Ridgecrest Earthquake. The InSAR surface displacement data are taken from the `Advanced Rapid Imaging and Analysis (ARIA) Project for Natural Hazards <https://aria.jpl.nasa.gov/>`_ by JPL/NASA. The coseismic GNSS displacements were delivered by `Nevada Geodetic Laboratory <http://geodesy.unr.edu/index.php>`_.

This tutorial will guide through the preparation of the unwrapped InSAR surface displacements in Kite. The GNSS displacement data will be imported into Pyrocko and significant stations are pre-selected.

This tutorial will guide through the preparation of the InSAR surface displacements (unwrapped interferograms)in `Kite`_. The GNSS displacement data will be imported into Pyrocko and stations with significant coseismic displacment have been pre-selected.

This is an advanced example to demonstrate a geodetic joint inversion. If you haven't worked with Grond earthquake inversions before, we recommend to exercise a single dataset example first.

This is an advanced example to demonstrate a geodetic joined-datanon-linear optimisation. If you haven't worked with Grond earthquake optimisations before, we recommend to exercise a single dataset example first (e.g. see `Rectangular source plane from InSAR observations <https://pyrocko.org/docs/grond/docs/current/examples/satellite_insar/>`_).

Setup

-----

To repeat this exercise on your machine, you should first `install Pyrocko

<https://pyrocko.org/docs/current/install/>`_ and Grond (see :doc:`/install/index`), if you have not already done so. Then create the example project with:

To do this exercise on your machine, you should first install Grond (see :doc:`/install/index`), which needs `Pyrocko <https://pyrocko.org/docs/current/install/>`__ and `Kite`_, if you have not already done so. Now create the example project with:

@ -34,48 +33,48 @@ The project folder now contains a configuration file for Grond and some utility

Green's function download

-------------------------

To download the pre-calculated Green's functions needed in this exercise, run

To download the pre-calculated Green's functions needed in this exercise, go into you new grond project folder :file:`grond-joint-geodetic` and run

.. code-block :: sh

bin/download_gf_stores.sh

./bin/download_gf_stores.sh

When the command succeeds, you should have a new subdirectory :file:`gf_stores` in your project folder:

When the command succeeds, you will have a new subdirectory :file:`gf_stores` in your project folder:

.. code-block :: sh

gf_stores

└── crust2_ib_static/... # Green's function store

It contains a Pyrocko Green's function store, named ``crust2_ib_static``, which has been created using the `Fomosto <https://pyrocko.org/docs/current/apps/fomosto/index.html>`_ tool of `Pyrocko <http://pyrocko.org/>`_ and the static modelling code `PSGRN/PSCMP <https://pyrocko.org/docs/current/apps/fomosto/backends.html#the-psgrn-pscmp-backend>`_. The Green's functions in this store have been calculated for a regional `CRUST2 <https://igppweb.ucsd.edu/~gabi/crust2.html>`_ earth model for source depths between 0 and 30 km in 500 m steps, and horizontal extent from 0 - 300 km in 500 m steps.

It contains a Pyrocko Green's function store, named ``crust2_ib_static``, which has been created using the `Fomosto <https://pyrocko.org/docs/current/apps/fomosto/index.html>`_ tool of `Pyrocko <http://pyrocko.org/>`_ and the static modelling code `PSGRN/PSCMP <https://pyrocko.org/docs/current/apps/fomosto/backends.html#the-psgrn-pscmp-backend>`_. The Green's functions in this store have been calculated for a regional `CRUST2 <https://igppweb.ucsd.edu/~gabi/crust2.html>`_ earth model for source depths between 0 and 30 km in 500 m steps, and horizontal extent from 0 - 300 km in 500 m steps. Find more information on the Green's function and their use in the `Pyrocko-GF section <https://pyrocko.org/docs/current/topics/pyrocko-gf.html>`_.

InSAR and GNSS data download

----------------------------

The example includes a script to download unwrapped InSAR and GNSS data from Pyrocko's servers. The unwrapped InSAR Sentinel-1 surface displacement data is provided by `ARIA (NASA) <https://aria.jpl.nasa.gov/>`_. An example how to download and convert ARIA data in Kite can be followed in the `documentation <https://pyrocko.org/docs/kite/>`_.

This example includes a script to download InSAR and GNSS data from Pyrocko's servers. The InSAR data are surface displacement maps based on unwrapped Sentinel-1 interferograms provided by `ARIA (NASA) <https://aria.jpl.nasa.gov/>`_. An example how to download and convert ARIA data in `Kite`_ can be followed in the `documentation <https://pyrocko.org/docs/kite/>`_. Download the data by running:

.. code-block :: sh

bin/download_data.sh

./bin/download_data.sh

This will download the InSAR scenes and GNSS data to:file:`data/events/2019-ridgecrest`. InSAR surface displacements are held in Kite container format, GNSS data is stored in Pyrocko containers.

The InSAR and GNSS data are placed in:file:`data/events/2019-ridgecrest`. InSAR surface displacements are held in the `Kite`_ container format. GNSS data are stored in Pyrocko containers in a human-readable `YAML`_ format and we use them as they are.

Unwrapped InSAR displacement preparation with Kite

The downloaded InSAR data has to be prepared for the inversion with the `Kite tool <https://pyrocko.org/docs/kite/>`_. To install the software, follow the `install instructions <https://pyrocko.org/docs/kite/current/installation.html>`_.

The downloaded InSAR data have to be prepared for the optimisation with the `Kite tool <https://pyrocko.org/docs/kite/>`_ that you installed previously (see Setup above).

Once Kite is installed we need to parametrize the two scenes:

We prepare the two InSAR data sets as follows:

1. The data sub-sampling quadtree: This efficiently reduces the resolution of the scene, yet conserves the important data information. A reduced number of samples will benefit the forward-modelling computing cost.

1. Applying quadtree data sub-sampling: This reduces the resolution of the data in an irregular way, yet enables to conserve the information in the spatial displacement pattern. The strongly reduced number of data points will strongly reduce the forward-modelling computing costs.

2. Estimate the spatial data covariance: By looking at the spatial noise of the scene we can estimate the data covariance. Kite enables us to calculate a covariance matrix for the quadtree, which will be used as a weight matrix in our Grond inversion.

2. Estimating the spatial data error covariance: We analyse the power and spatial correlation of data noise in areas with little coseismic displacement. Kite uses the error statistics to calculate the data error variance-covariance matrix for the chosen quadtree subsamling. This matrix will be used to derive the weight matrix in our Grond optimisation.

.. note ::

The scenes come pre-configured. The following steps of defining the quadtree and calculating the covariance matrix are optional.

The scenes come pre-configured. The following steps of defining the quadtree and calculating the covariance matrix are good to exercise.

Load the InSAR data into spool:

Load the InSAR data for interactive parametrisationusing the `spool` command:

The starting window shows on the right the :guilabel:`Scene` Tab up front. You see the displacement map with some masked areas (low coherence or masked unreliable unwrapping). You can zoom, adjust the colorbar, and find values in the top right corner by pointing the mouse at them.

We need to parametrize the quadtree: find a good parameters for the sub-sampling quadtree by tuning four parameters:

**Quadtree subsampling**

To parameterise the quadtree setting we switch to the :guilabel:`Scene.quadtree` Tab and use the sliders on the left to find good parameters for the sub-sampling quadtree. We can tune the following four parameters:

1. ``epsilon``, the variance threshold in each quadtree's tile.

2. ``nan_fraction``, percentage of allowed NaN pixels per tile.

@ -96,17 +99,21 @@ We need to parametrize the quadtree: find a good parameters for the sub-sampling

:width:100%

:align:center

**Figure 1**: Parametrizing the quadtree. This efficiently sub-samples the high-resolution Sentinel-1 surface displacement data. (command :command:`spool`; `Kite<https://pyrocko.org/docs/kite/>`_ toolbox).

**Figure 1**: Parametrising the quadtree. This efficiently sub-samples the high-resolution Sentinel-1 surface displacement data. (command :command:`spool`; `Kite`_ toolbox).

.. tip ::

Delete unnecessary tiles of the quadtree by right-clicking, and delete with :kbd:`Del`.

Delete unnecessary or unwanted tiles of the quadtree by right-click dragging across these areas, and delete with :kbd:`Del`. Unnecessary could be areas far away from the action and unwanted could be quadtrees that cross the potential surface trace of the fault or that are affected by unwrapping errors.

Once you are done, click on the next tab :guilabel:`Scene.covariance`. Now we will define a window for the data's noise. The window's data will be use for calculating the spatial covariance of the scene (see `details <https://pyrocko.org/kite/docs/current/examples/covariance.html>`_).

**InSAR data error estimation**

Use a spatial window far away from the earthquake signal to capture only the noise. The bigger the window is, the better the data covariance estimation.

On the left hand side of the GUI you find parameters to tune the spatial covariance analysis. We now can fit an analytical model to the empirical covariance: :math:`\exp(d)` or :math:`\exp + \sin`. For more details on the method, see `Kite's documentation <https://pyrocko.org/docs/kite/current>`_.

For the data error estimation we switch the tab :guilabel:`Scene.covariance`. Here we define a window that ideally includes data noise. The window's data are used to calculate the variance and spatial covariance of the data noise based on variogram and covariogram (see `details <https://pyrocko.org/kite/docs/current/examples/covariance.html>`_).

Use a spatial window far away from the earthquake signal to capture only the noise. The larger the window is, the longer the analysed noise wavelengths.The variance estimation can be manually adapted by grabbing the green dashed line and move it. The variance should be as large or larger than the covariance at zero distance.

On the left hand side of the GUI you find parameters to tune the spatial covariance analysis. You can improve the data error estimation by increasing the number of spatial pairs to get smoother (co-)variograms. We now can fit an analytical model to the empirical covariance: :math:`\exp(d)` or :math:`\exp + \sin`. For more details on the method, see `Kite's documentation <https://pyrocko.org/docs/kite/current>`_.

@ -119,13 +126,13 @@ Once we finished parametrisation of the quadtree and covariance, we have to calc

1. Calculate the full covariance: :menuselection:`Tools --> Calculate Full Matrix`

Depending on the scene's resolution this process can take time.

2. Save the parametrized scene: :menuselection:`File --> Save Scene`.

2. Save the parametrised scene: :menuselection:`File --> Save Scene`.

Grond configuration

-------------------

The project folder already contains a configuration file for rectangular source optimisation with Grond, so let's have a look at it.

The project folder already contains a configuration file for a rectangular source optimisation with Grond, so let's have a look at it.

It's a `YAML`_ file: This file format has been chosen for the Grond configuration because it can represent arbitrarily nested data structures built from mappings, lists, and scalar values. It also provides an excellent balance between human and machine readability. When working with YAML files, it is good to know that the **indentation is part of the syntax** and that comments can be introduced with the ``#`` symbol. The type markers, like ``!grond.RectangularProblemConfig``, select the Grond object type of the following mapping and it's documentation can likely be found in the :doc:`/library/index`.

@ -181,14 +188,15 @@ Once the optimisation is finished we can generate and open the final report with

:width:80%

:align:center

**Figure 3**: Surface displacements from the ascending track. (Left) the observed InSAR data, (center) the modelled surface displacements, and (right) the residual displacement. More information and statistics are accessible in the complete inversion report.

**Figure 3**: Surface displacements from the ascending track. (Left) the observed InSAR data, (center) the modelled surface displacements, and (right) the residual displacement. More information, statistics and plots are accessible in the complete optimisation report.

Example report

~~~~~~~~~~~~~~

Explore the `online example reports <https://pyrocko.org/grond/reports>`_ to see what information the inversion reveals.

Explore the `online example reports <https://pyrocko.org/grond/reports>`_ to see what information the optimisation reveals.