forked from pyrocko/grond
1
0
Fork 0

docs: polish, added reports

whitelist
miili 5 years ago
parent 78e1700bdb
commit d487862d3a

3
.gitignore vendored

@ -102,3 +102,6 @@ venv.bak/
# mypy
.mypy_cache/
# sphinx
docs/source/cli/

@ -37,6 +37,7 @@ import sphinx_sleekcat_theme
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.imgconverter',
'sphinx.ext.todo',
'sphinx.ext.mathjax',
'sphinx.ext.viewcode',
@ -147,7 +148,7 @@ htmlhelp_basename = 'gronddoc'
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
'papersize': 'a4paper',
# The font size ('10pt', '11pt' or '12pt').
#
@ -155,13 +156,15 @@ latex_elements = {
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
'preamble': r'\setcounter{tocdepth}{2}',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
'figure_align': 'H',
}
latex_engine = 'xelatex'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).

@ -1,10 +1,10 @@
Rectangular source plane from InSAR observations
------------------------------------------------
================================================
This step-by-step recipe will guide you to through an earthquake source inversion for a finite rectangular fault plane from InSAR data using Grond. We will excercise the inversion for the 2009 L'Aquila earthquake - A shallow normal faulting Mw 6.3 earthquake - and use unwrapped surface displacement data derived from the Envisat mission.
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, copy the
@ -18,7 +18,7 @@ exercise project directory from Grond's git repos to a place of your choice.
The project folder
..................
------------------
The project folder now contains a configuration file for Grond, some utility scripts to download precalculated Green's functions and InSAR data
@ -33,7 +33,7 @@ The project folder now contains a configuration file for Grond, some utility scr
Green's function download
.........................
-------------------------
To download the precalculated Green's functions needed in this exercise, run
@ -44,7 +44,7 @@ To download the precalculated Green's functions needed in this exercise, run
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 modelling code `QSSP <https://pyrocko.org/docs/current/apps/fomosto/backends.html#the-qssp-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 a source depths between 0 and 30 km in 500 m steps, and horizontal extent from 0 - 300 km in 500 m steps.
InSAR displacement download
...........................
---------------------------
The example includes a script to download unwrapped InSAR data from Pyrocko's servers. The sufrface displacement data has been derived from the Envisat satellite mission.
@ -55,7 +55,7 @@ The example includes a script to download unwrapped InSAR data from Pyrocko's se
This will download (1) an ascending and (2) descending scene to :file:`data/events/2009laquila/insar/`. Data is held in ``kite`` container format.
InSAR data preparation with ``kite``
....................................
------------------------------------
The downloaded data has to be prepared for the inversion using the ``kite`` tool. To install the software, follow the `install instructions <https://pyrocko.org/docs/kite/current/installation.html>`_.
@ -77,9 +77,9 @@ Start kite's :program:`spool` GUI with:
.. code-block :: sh
spool data/events/2009LAquila/insar/asc_insar
spool data/events/2009laquila/insar/asc_insar
# descending scene:
spool data/events/2009LAquila/insar/dsc_insar
spool data/events/2009laquila/insar/dsc_insar
Now we can parametrize the quadtree visually:
@ -115,7 +115,7 @@ Once we finished parametrisation of the quadtree and covariance, we have to calc
Grond configuration
...................
-------------------
The project folder already contains a configuration file for rectangular source optimisation with Grond, so let's have a look at it.
@ -128,7 +128,7 @@ It's a `YAML`_ file: This file format has been choosen for the Grond configurati
Checking the optimisation setup
...............................
-------------------------------
Before running the actual optimisation, we can now use the command
@ -139,7 +139,7 @@ Before running the actual optimisation, we can now use the command
to run some sanity checks. In particular, Grond will try to run a few forward models to see if the modelling works and if it can read the input data. If only one event is available, we can also neglect the event name argument in this and other Grond commands.
Starting the optimisation
.........................
-------------------------
Now we are set to start the optimisation with:
@ -160,7 +160,7 @@ Depending on the configured number of iterations and the computer's hardware the
Optimisation report
...................
-------------------
Once the optimisation is finished we can generate and open the final report with:
@ -168,7 +168,11 @@ Once the optimisation is finished we can generate and open the final report with
grond report -so rundir/rect_source.grun
See the `example report <https://localhost>`_.
Example report
~~~~~~~~~~~~~~
Explore the `online example reports <https://pyrocko.org/grond/reports>`_ to see what information the inversion reveals.
.. _Kite: https://pyrocko.org/docs/kite/current/

@ -57,7 +57,7 @@ Now run:
.. code-block :: sh
bin/grondown_regional.sh gfz2015pmjk
bin/grondown_regional.sh gfz2018pmjk
This shell script calls the data downloader :file:`bin/grondown` with parameters appropriate to get a dataset of broadband seismometer recordings, sufficient for a surface wave CMT optimisation. It performs the following steps for us:
@ -75,7 +75,7 @@ After running the download script, the playground directory should contain a new
data
└── events
└── gfz2015pmjk
└── gfz2018pmjk
├── event.txt # catalog information about the event
└── waveforms
├── grondown.command
@ -97,7 +97,7 @@ For a quick visual inspection of the dataset, we can use the `Snuffler <https://
.. code-block :: sh
cd data/events/gfz2015pmjk/waveforms
cd data/events/gfz2018pmjk/waveforms
snuffler --event=../event.txt --stations=stations.prepared.txt prepared
cd - # change to previous folder
@ -109,7 +109,7 @@ Figure 1 shows our view after some interactive adjustments in Snuffler. In parti
* add markers for expected P and S phase arrivals, (Menu → *Panels* → *Cake Phase (builtin)*).
* show only vertical components: Command ‣ :command:`c *z`.
.. figure:: ../../images/example_snuffler-gfz2015pmjk.svg
.. figure:: ../../images/example_snuffler-gfz2018pmjk.svg
:name: Fig. 1 Example surface wave CMT inversion
:width: 100%
:align: center
@ -136,7 +136,7 @@ Before running the actual optimisation, we can now use the command
.. code-block :: sh
grond check config/regional_cmt.gronf gfz2015pmjk
grond check config/regional_cmt.gronf gfz2018pmjk
to run some sanity checks. In particular, Grond will try to run a few forward models to see if the modelling works and if it can read the input data. If only one event is available, we can also neglect the event name argument in this and other Grond commands.
@ -144,7 +144,7 @@ To get some more insight into the setup, we can now run
.. code-block :: sh
grond report -so config/regional_cmt.gronf gfz2015pmjk
grond report -so config/regional_cmt.gronf gfz2018pmjk
This will plot some diagnostic figures, create web pages in a new directory :file:`reports`, and finally open these in a web browser.
@ -177,3 +177,9 @@ Once the optimisation is finished we can generate and open the final report with
.. code-block :: sh
grond report -so config/regional_cmt.gronf
Example report
~~~~~~~~~~~~~~
Explore the `online example reports <https://pyrocko.org/grond/reports>`_ to see what information the inversion reveals.

@ -181,6 +181,7 @@ Once the optimisation is finished we can generate and open the final report with
grond report -so config/wphase_cmt.gronf
Example report
~~~~~~~~~~~~~~
Explore the `online example reports <https://pyrocko.org/grond/reports>`_ to see what information the inversion reveals.

@ -55,7 +55,7 @@ The objective function defines what a `model fit` is and how `good` or `poor` mo
.. figure:: ../images/illu_combi_weights.svg
:name: Fig. 1
:height: 500px
:width: 80%
:align: center
:alt: alternate text
@ -90,13 +90,12 @@ The misfit is based on the configurable :math:`L^x`-norm with :math:`x \,\, \eps
\lVert e \rVert_x = \lVert {\bf{d}}_{obs} - {{\bf d}}_{synth} \rVert_x = \
\left(\sum{|{ d}_{i, obs} - {d}_{i, synth}|^x}\right)^{\frac{1}{x}}
Further the misfit normalisation factor :math:`norm` is associated with each target. This measure will be used to normalise the misfit values for relative weighing:
Further the misfit normalisation factor :math:`norm` is associated with each target. This measure will be used to normalise the misfit values for relative weighting:
.. math::
:label: ns
\lVert e_{\mathrm{0}} \rVert_x = \lVert {\bf{d}}_{obs} \rVert_x = \
left(\sum{|{d}_{i, obs}|^x} \right) ^{\frac{1}{x}}.
\lVert e_{\mathrm{0}} \rVert_x = \lVert {\bf{d}}_{obs} \rVert_x = \left(\sum{|{d}_{i, obs}|^x} \right)^{\frac{1}{x}}.
The resulting normalised misfit
@ -178,6 +177,15 @@ Target balancing weights
With these weights waveform targets are `balanced` with respect to the expected earthquake signal amplitude.
.. figure:: ../images/illu_target_balancing.svg
:name: Fig. 2
:width: 50%
:align: left
:alt: alternate text
:figclass: align-center
**Figure 2**: Qualitative sketch how target balancing weight increases with source-receiver distance to balance amplitude inferred by geometrical spreading.
Signal amplitudes in a trace :math:`|{\bf{d}}_{synth}|` depend on the (1) source-receiver distance, (2) on the phase type and (3) signal procesing applied (taper or bandpass). The problem tackled with this particular weight is that large signal amplitude have higher contributions to the misfit than smaller signals, without providing more information about the source machanism. From synthetic waveforms of `N` forward models that have been randomly drawn from the defined model space the mean signal amplitude of the traces is derived. The weight for each trace is then the inverse of these mean signal amplitudes:
.. math::
@ -188,15 +196,6 @@ Signal amplitudes in a trace :math:`|{\bf{d}}_{synth}|` depend on the (1) source
These balancing weights will enhanced small signals and supress large signals in the objective function. This is described as `adaptive station weighting` in the PhD `thesis by Heimann`_ (2011) (page 23). In Grond they are defined as ``balancing weights`` and are received from the :class:`~grond.analysers.target_balancing.TargetBalancingAnalyser` module before the optimisation.
.. figure:: ../images/illu_target_balancing.svg
:name: Fig. 2
:width: 300px
:align: left
:alt: alternate text
:figclass: align-center
**Figure 2**: Qualitative sketch how target balancing weight increases with source-receiver distance to balance amplitude inferred by geometrical spreading.
Data weights based on data error statistics
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -331,7 +330,7 @@ To generate random noise we use functions of the `Kite`_ module. From the noise
.. figure:: ../images/illu_residual_bootstrap_realisation.svg
:name: Fig. 5
:width: 1400px
:width: 100%
:align: center
:alt: alternate text
:figclass: align-center
@ -375,7 +374,7 @@ the model space:
.. figure:: ../images/illu_sampling_phases.svg
:name: Fig. 6
:height: 300px
:width: 100%
:align: center
:alt: alternate text
:figclass: align-center
@ -427,7 +426,7 @@ The highscore list member models in each bootstrap chain (Fig. 7B) will differ t
.. figure:: ../images/illu_bootstrap_weights.svg
:name: Fig. 7
:height: 400px
:width: 80%
:align: center
:alt: alternate text
:figclass: align-center
@ -439,8 +438,8 @@ The convergence of model parameters for the models within each bootstrap chain i
.. figure:: ../images/illu_babo_chains.svg
:name: Fig. 8
:height: 300px
:align: left
:width: 50%
:align: center
:alt: alternate text
:figclass: align-left

@ -34,7 +34,7 @@ To use Grond with your own dataset, we suggest the following folder structure.
Single files and data formats listed here are explained below. The folders ``runs`` and ``reports`` are generated during and after the optimisation, respectively.
.. code-block :: sh
.. code-block :: none
├── config
│ ├── laquila2009_joint.gronf

@ -1,15 +1,11 @@
Report
======
TODO: describe how to create and configure Grond's reports. Describe what
output plots are available.
Grond's reports are presented in interactive HTML webpages where you can browse and compare different events and inversion runs.
.. figure :: ../images/report_webpage.png
:name: Grond Webpage
:width: 100%
:align: left
:width: 80%
:alt: Grond report webpage
:figclass: align-center
@ -18,13 +14,13 @@ Grond's reports are presented in interactive HTML webpages where you can browse
Generate reports
----------------
When an inversion is finished you can create and open the report with:
When an inversion is finished and with a set-up project structure you can create and open the report with:
.. code-block:: sh
grond report -so <rundir>
You can look up the meaning of ``-so`` with ``grond report --help``
The flags ``-s`` will spin up a webserver and ``-o`` will open the browser; more information is given from ``grond report --help``.
Plot types

@ -1,11 +1,15 @@
#!/bin/bash
set -e
DATA_PATH="data/events/2009laquila/insar/"
mkdir -p $DATA_PATH
EVENT_PATH="data/events/2009laquila"
INSAR_PATH="$EVENT_PATH/insar/"
mkdir -p $EVENT_PATH
mkdir -p $INSAR_PATH
wget http://data.pyrocko.org/examples/2009-LAquila-InSAR/README -P $DATA_PATH
wget http://data.pyrocko.org/examples/2009-LAquila-InSAR/asc_insar.npz -P $DATA_PATH
wget http://data.pyrocko.org/examples/2009-LAquila-InSAR/asc_insar.yml -P $DATA_PATH
wget http://data.pyrocko.org/examples/2009-LAquila-InSAR/dsc_insar.npz -P $DATA_PATH
wget http://data.pyrocko.org/examples/2009-LAquila-InSAR/dsc_insar.yml -P $DATA_PATH
wget http://data.pyrocko.org/examples/2009-LAquila-InSAR/README -P $INSAR_PATH
wget http://data.pyrocko.org/examples/2009-LAquila-InSAR/asc_insar.npz -P $INSAR_PATH
wget http://data.pyrocko.org/examples/2009-LAquila-InSAR/asc_insar.yml -P $INSAR_PATH
wget http://data.pyrocko.org/examples/2009-LAquila-InSAR/dsc_insar.npz -P $INSAR_PATH
wget http://data.pyrocko.org/examples/2009-LAquila-InSAR/dsc_insar.yml -P $INSAR_PATH
wget http://data.pyrocko.org/examples/2009-LAquila-InSAR/dsc_insar.yml -P $INSAR_PATH
wget http://data.pyrocko.org/examples/2009-LAquila-InSAR/event.txt -P $EVENT_PATH

@ -1,62 +1,197 @@
--- !grond.Config
path_prefix: ..
rundir_template: rundir/${problem_name}.grun
# All file paths referenced below are treated relative to the location of this
# configuration file, here we may give a common prefix. E.g. setting it to '..'
# if the configuration file is in the sub-directory '${project_root}/config'
# allows us to give the paths below relative to '${project_root}'.
path_prefix: '..'
# Path, where to store output (run directories). The placeholder
# '${problem_name}' will be expanded to a name configured below in
# problem_config.name_template and will typically include a config identifier
# and the event name.
rundir_template: runs/${problem_name}.grun
# If given, restrict to processing of listed events
#event_names:
#- 'gfz2018pmjk'
# -----------------------------------------------------------------------------
# Configuration section for dataset (input data)
#
# The placeholder '${event_name}' will be expanded to the current event. This
# enables us to use the same configuration for multiple events. The available
# events are detected by looking into possible expansions of
# dataset_config.events_path
# -----------------------------------------------------------------------------
dataset_config: !grond.DatasetConfig
events_path: event.txt
extend_incomplete: false
picks_paths: []
blacklist_paths: []
blacklist: []
whitelist_paths: []
kite_scene_paths: [insar]
# File with hypocenter information and possibly reference solution
events_path: 'data/events/${event_name}/event.txt'
# List of directories for the InSAR scenes
kite_scene_paths: ['data/events/${event_name}/insar']
# -----------------------------------------------------------------------------
# Configuration section for the observational data fitting
#
# This defines the objective function to be minimized in the optimisation. It
# can be composed of one or more contributions, each represented by a
# !grond.*TargetGroup section.
# -----------------------------------------------------------------------------
target_groups:
- !grond.SatelliteTargetGroup
normalisation_family: static
path: all
# Normalisation family (see the Grond documentation for how it works).
# Use distinct normalisation families when mixing misfit contributors with
# different magnitude scaling, like e.g. cross-correlation based misfit and
# time-domain Lx norm.
normalisation_family: 'static'
# Just a name used to identify targets from this group. Use dot-separated path
# notation to group related contributors
path: 'insar'
# How to weight contributions from this group in the global misfit
weight: 1.0
# Selector for kite scene ids, '*all' is a wildcard and load all scenes present
kite_scenes: ['*all']
# Subsection on how to fit the traces
misfit_config: !grond.SatelliteMisfitConfig
# Optimise a planar orbital ramp
optimise_orbital_ramp: false
# Parameters for the orbital ramp
ranges:
# Vertical offset in [m]
offset: -0.5 .. 0.5
# Ranges for the East-West and North-South inclination of the ramp
ramp_east: -1e-4 .. 1e-4
ramp_north: -1e-4 .. 1e-4
# How to interpolate the Green's functions (available choices:
# 'nearest_neighbor', 'multilinear'). Choices other than 'nearest_neighbor'
# may require dense GF stores to avoid aliasing artifacts in the forward
# modelling.
interpolation: multilinear
# Name of the GF Store to use
store_id: crust2_ib_static
# -----------------------------------------------------------------------------
# Definition of the problem to be solved
#
# In this section the source model to be fitted is chosen, the parameter space
# defined, and how to combine the misfit contributions defined in the
# target_groups section above.
#
# The marker !grond.RectangularProblemConfig selects a finite rectancular
# source model.
# -----------------------------------------------------------------------------
problem_config: !grond.RectangularProblemConfig
name_template: rect_source
# Name used to identify the output
name_template: rect_2009LaAquila
# How to combine the target misfits. For L1 norm: 1, L2 norm: 2, etc.
norm_exponent: 2
# Definition of model parameter space to be searched in the optimisation
ranges:
# Scaling ranges in [m]
depth: 2500 .. 7000
dip: 10 .. 50
east_shift: 0 .. 20000
length: 5000 .. 10000
north_shift: 0 .. 20000
rake: 120 .. 360
length: 5000 .. 10000
width: 2000 .. 10000
slip: .2 .. 2
# Orientation ranges in [deg]
dip: 10 .. 50
rake: 120 .. 360
strike: 220 .. 360
width: 2000 .. 10000
# We are using a dense GF store and will reduce the number of discrete
# subsources by this factor. Decrease the decimation for a finer sub-source
# resolution, and increased computational time
decimation_factor: 12
# Clearance distance around stations (no models with origin closer than this
# distance to any station are produced by the sampler)
distance_min: 0.0
# -----------------------------------------------------------------------------
# Configuration of pre-optimisation analysis phases.
# determined during this phase.
# -----------------------------------------------------------------------------
#
analyser_configs:
# DOES NOT APPLY FOR INSAR! Balancing weights are determined with this analyser
- !grond.TargetBalancingAnalyserConfig
niterations: 1000
# -----------------------------------------------------------------------------
# Configuration of the optimisation procedure
# -----------------------------------------------------------------------------
optimiser_config: !grond.HighScoreOptimiserConfig
# Number of bootstrap realisations to be tracked simultaneously in the
# optimisation
nbootstrap: 25
# Stages of the sampler then narrow down to the interesting regions
# (!grond.DirectedSamplerPhase).
sampler_phases:
# Start with uniform sampling of the model space
- !grond.UniformSamplerPhase
# Number of iterations
niterations: 10000
# How often we shall try to find a valid sample
ntries_preconstrain_limit: 1000
# Narrow down to the interesting regions
- !grond.DirectedSamplerPhase
# Number of iterations
niterations: 40000
# How often we shall try to find a valid sample
ntries_preconstrain_limit: 1000
# Multiplicator for width of sampler distribution at start of this phase
scatter_scale_begin: 2.0
# Multiplicator for width of sampler distribution at end of this phase
scatter_scale_end: 0.5
starting_point: excentricity_compensated
sampler_distribution: normal
standard_deviation_estimator: median_density_single_chain
ntries_sample_limit: 2000
# This parameter determines the length of the chains
chain_length_factor: 8.0
nbootstrap: 25
# -----------------------------------------------------------------------------
# Configuration section for synthetic seismogram engine
#
# Configures where to look for GF stores.
# -----------------------------------------------------------------------------
engine_config: !grond.EngineConfig
# Whether to use GF store directories listed in ~/.pyrocko/config.pf
gf_stores_from_pyrocko_config: true
gf_store_superdirs: [.]
gf_store_dirs: []
event_names: []
# List of directories with GF stores
gf_store_superdirs: ['gf_stores']

@ -32,7 +32,6 @@ tfade_factor = 1.0
ffade_factors = 0.5, 1.5
ws.g_timeout = 60.
logging.basicConfig(level=logging.DEBUG)
class starfill(object):

@ -73,7 +73,7 @@ target_groups:
# time-domain Lx norm.
normalisation_family: 'td'
# Just a name used to identfy targets from this group. Use dot-separated path
# Just a name used to identify targets from this group. Use dot-separated path
# notation to group related contributors
path: 'td.love'
@ -197,7 +197,6 @@ target_groups:
# The marker !grond.CMTProblemConfig selects a centroid moment tensor source
# model.
# -----------------------------------------------------------------------------
problem_config: !grond.CMTProblemConfig
# Name used to identify the output
@ -255,7 +254,6 @@ analyser_configs:
# -----------------------------------------------------------------------------
# Configuration of the optimisation procedure
# -----------------------------------------------------------------------------
optimiser_config: !grond.HighScoreOptimiserConfig
# Number of bootstrap realisations to be tracked simultaneously in the
@ -268,12 +266,10 @@ optimiser_config: !grond.HighScoreOptimiserConfig
sampler_phases:
- !grond.UniformSamplerPhase
# Number of iterations
niterations: 1000
- !grond.DirectedSamplerPhase
# Number of iterations
niterations: 20000

Loading…
Cancel
Save