.. _deepc-workflow:

Workflow
========

The plugin is loaded by :cite:t:`scautopick` as well as :cite:t:`screpick` or :cite:t:`scolv`.


.. _fig-deepc-workflow-scautopick:

.. figure:: media/deepc-scautopick-full-ex.svg
   :align: center
   :width: 16cm

   Example workflow with |deepc| as a plugin for scautopick


Depending on the type of model and application, |deepc|'s output differs:

#. An *event classification* model used with `scautopick` or `screpick` adds a **comment with the event type**
   to the resulting pick object. It shouldn't be loaded with `scolv`.
#. Models providing *phase classification* used with `scautopick` or `screpick` potentially change
   the **phase hint** of the resulting pick object, and they shouldn't be loaded with `scolv` either.
#. Models providing *onset time prediction* used with `scautopick` or `screpick` will **refine the pick time**
   as any other picker plugin.
   They can also be loaded by `scolv` and used as repicker. Further, if activated, the **confidence** of the model's pick
   can be shown in the SNR field of the info box.

To load one of these models, you need to define the appropriate "sub-picker".

.. _deepc-config-subpickers:

.. csv-table::
   :header: task, kind, config name, global binding parameter group
   :widths: 25, 15, 15, 25

   Event classifier, primary, deepc-ec, picker.deepc.deepcEC
   Phase classifier, primary, deepc-pc, picker.deepc.deepcPC
   Phase classifier and refiner, primary, deepc-pr, picker.deepc.deepcPR
   Phase classifier and refiner, secondary, deepc-sr, spicker.deepcSR

.. note::

   Currently, gempa doesn't provide a model for the task *event classification*.


3-Component Data Processing
---------------------------

Most :ref:`DL models<deepc-available-models>` require 3-component waveform data
to work with. In case only single-component data exits, the missing data
.. channels may be generated
from the existing ones by duplication and renaming of streams using
:cite:t:`scart`.

Example duplicating and renaming streams from a file :file:`data.mseed`:

.. code-block:: sh

   dataFile=data.mseed
   # extract data to be duplicated:
   echo "
   2000-01-01 00:00;2024-01-01 00:00;AB.*.00.HHZ > /tmp/filter.list

   scart -I $dataFile -l /tmp/filter.list --stdout > /tmp/filter.mseed

   # rename:
   scart --rename AB.TEST1.00.HHZ:AB.TEST1.00.HHN,AB.TEST1.00.HHZ:AB.TEST1.00.HHN -I /tmp/filter.mseed --stdout > /tmp/hhn.mseed
   scart --rename AB.TEST1.00.HHZ:AB.TEST1.00.HHE,AB.TEST1.00.HHZ:AB.TEST1.00.HHE -I /tmp/filter.mseed --stdout > /tmp/hhe.mseed

   # merge:
   cat /tmp/hhn.mseed /tmp/hhe.mseed $dataFile | scmssort -Eui > /tmp/duplicated.mseed

Note that a :ref:`DL model<deepc-available-models>` won't work as reliably with
artificial components as with true 3-component data.


Phase reclassification
----------------------

For phase refinement and classification, *deepcp* and *deepcsr*
can be used as primary and as secondary picker, respectively.
Depending on whether :confval:`picker.deepc.deepcPR.reclassify` is set and how
confidence thresholds are defined, *deepcp* follows a decision tree to classify
a pick:


.. _fig-deepc-decisiontree-p:

.. figure:: media/decisiontree-p.svg
   :align: center
   :width: 16cm

   Pick decision tree for DeepC primary picker

In principle, *deepcsr* could be run with reclassification as well, but it is currently not recommended as it
would undermine the sense of the secondary picker. Therefore, *deepcsr* has only two possibilities: send or not-send
an S pick which is implemented by the very basic check if the first S pick after the trigger has a confidence
above the given threshold.

A reclassification could take into account if the confidence for a P pick close to the potential S pick is higher.
As a consequence, *deepcsr* could then reject the pick.
But, currently, its pick decision tree is not implemented this way,
so reclassification should be turned off for *deepcsr*.