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