Usage Examples
--------------
This section shows some more extensive examples demonstrating that
``SEIS-PROV`` can be used to capture provenance for a wide range of
seismological relevant applications. Keep in mind that these diagrams describe
the history of some piece of data, not a workflow. The **arrows point towards
the past**, e.g. to the origin/history of any piece of data.
.. note::
`Right click -> View Image` to see the graphs in more detail.
.. contents::
:local:
:depth: 1
Detailed Processing Chain
^^^^^^^^^^^^^^^^^^^^^^^^^^
This example demonstrates how a linear chain of signal processing routines can
be described. The data has been detrended with a linear fit, then a
Butterworth lowpass filter has been applied and finally some integer decimation
has been performed. All of these operations where performed by a certain
version of ObsPy. Toolboxes can be adapted to provide this kind of provenance
information fully automatic.
.. raw:: html
.. graphviz:: _generated/dot/examples/example_detailed_processing_chain.dot
.. raw:: html
Python code utilizing the `prov `_ package.
.. literalinclude:: _generated/py/examples/example_detailed_processing_chain.py
:language: python
.. raw:: html
In the `PROV-XML `_ serialization.
.. literalinclude:: _generated/xml/examples/example_detailed_processing_chain.xml
:language: xml
.. raw:: html
In the
`PROV-JSON `_
serialization.
.. literalinclude:: _generated/json/examples/example_detailed_processing_chain.json
:language: json
.. raw:: html
In `PROV-N `_ notation.
.. literalinclude:: _generated/provn/examples/example_detailed_processing_chain.provn
.. raw:: html
Schematic Processing Chain
^^^^^^^^^^^^^^^^^^^^^^^^^^
Sometimes not all information needs to be captured for a given application and
SEIS PROV is flexible enough to also allow a qualitative description of a
workflow. This is the same example as above but with less information. This
could be treated as a schema on how to process a large amount of data
independent of the used software and actual data.
.. raw:: html
.. graphviz:: _generated/dot/examples/example_schematic_processing_chain.dot
.. raw:: html
Python code utilizing the `prov `_ package.
.. literalinclude:: _generated/py/examples/example_schematic_processing_chain.py
:language: python
.. raw:: html
In the `PROV-XML `_ serialization.
.. literalinclude:: _generated/xml/examples/example_schematic_processing_chain.xml
:language: xml
.. raw:: html
In the
`PROV-JSON `_
serialization.
.. literalinclude:: _generated/json/examples/example_schematic_processing_chain.json
:language: json
.. raw:: html
In `PROV-N `_ notation.
.. literalinclude:: _generated/provn/examples/example_schematic_processing_chain.provn
.. raw:: html
Waveform Simulation
^^^^^^^^^^^^^^^^^^^
This fairly realistic example demonstrates how the waveform files resulting
from a numerical simulation can be described. This example does use some of the
more advanced features of the W3C PROV data model which are useful in many
contexts. Note that the waveform simulation activity has start and end times
and that SPECFEM in this example actually has been steered by a certain person.
The amount of information to store has to be decided by the given application.
The general idea is to store those input file parameters that actually have an
effect on the output. It might also be useful to store information about the
machine it was run on in the provenance information but that is not shown here.
Additionally in this case the provenance also contains a reference to a source
code file which might often be user defined and thus influences the final
result of the simulation.
One can also see which parameter file the input parameters have been
extracted from. In the provenance data model this is done by specifying the
source of some information.
The implementation of this in a waveform solver is fairly simple by just using
an existing SEIS PROV XML file as a template and adjusting the information
dynamically. No need to incorporate an actual XML library.
.. raw:: html
.. graphviz:: _generated/dot/examples/example_waveform_simulation.dot
.. raw:: html
Python code utilizing the `prov `_ package.
.. literalinclude:: _generated/py/examples/example_waveform_simulation.py
:language: python
.. raw:: html
In the `PROV-XML `_ serialization.
.. literalinclude:: _generated/xml/examples/example_waveform_simulation.xml
:language: xml
.. raw:: html
In the
`PROV-JSON `_
serialization.
.. literalinclude:: _generated/json/examples/example_waveform_simulation.json
:language: json
.. raw:: html
In `PROV-N `_ notation.
.. literalinclude:: _generated/provn/examples/example_waveform_simulation.provn
.. raw:: html
Cross Correlation
^^^^^^^^^^^^^^^^^
This is a simplistic example of two waveforms that are cross correlated to
produce a cross correlation. It is of course also possible to store the
processing steps that have been applied to the waveforms prior to the
correlation.
.. raw:: html
.. graphviz:: _generated/dot/examples/example_cross_correlation.dot
.. raw:: html
Python code utilizing the `prov `_ package.
.. literalinclude:: _generated/py/examples/example_cross_correlation.py
:language: python
.. raw:: html
In the `PROV-XML `_ serialization.
.. literalinclude:: _generated/xml/examples/example_cross_correlation.xml
:language: xml
.. raw:: html
In the
`PROV-JSON `_
serialization.
.. literalinclude:: _generated/json/examples/example_cross_correlation.json
:language: json
.. raw:: html
In `PROV-N `_ notation.
.. literalinclude:: _generated/provn/examples/example_cross_correlation.provn
.. raw:: html
Adjoint Source Calculation
^^^^^^^^^^^^^^^^^^^^^^^^^^
Last but not least is a fairly extreme example describing the provenance
history of a more complex operation - the calculation of an adjoint source
for transverse component seismograms. Nobody will create such a graph by
hand so this is only feasible if is happens automatically but it
demonstrates the power and scope of the concepts behind W3C PROV and
``SEIS-PROV``. In practice most programs and tools will likely choose to
create simpler descriptions.
This ``SEIS-PROV`` document here describes:
1. The generation of north and east component synthetic seismograms with
SPECFEM3D GLOBE.
2. These seismograms are detrended, demeaned, tapered, bandpass filtered,
detrended, demeaned, tapered, interpolated to new sampling rates, and
finally rotated to a transverse component seismogram.
3. The same is done to the observed waveforms and additionally their
instrument response is deconvolved at a certain point in the chain.
4. The difference between these two processed transverse component
seismograms is then encoded in an adjoint source.
In this particular example the graph generating code already has a hard to
time to produce a nice and clean graph and it is kind of hard to interpret
visually. Different ways to visualize such complex provenance descriptions
might have to be devised in the future.
.. raw:: html
.. graphviz:: _generated/dot/examples/example_adjoint_source.dot
.. raw:: html
Python code utilizing the `prov `_ package.
.. literalinclude:: _generated/py/examples/example_adjoint_source.py
:language: python
.. raw:: html
In the `PROV-XML `_ serialization.
.. literalinclude:: _generated/xml/examples/example_adjoint_source.xml
:language: xml
.. raw:: html
In the
`PROV-JSON `_
serialization.
.. literalinclude:: _generated/json/examples/example_adjoint_source.json
:language: json
.. raw:: html
In `PROV-N `_ notation.
.. literalinclude:: _generated/provn/examples/example_adjoint_source.provn
.. raw:: html