.. _polpicker: Polarity Picker =============== This :term:`plugin` provides the polarity pickers :ref:`P-AIC ` and :ref:`P-FX ` which are capable of determining the first motion direction of the onset. Overview -------- The plugin |appname| provides two ways to determine the first motion of a P pick. The :ref:`P-AIC ` utilizes the picker interface and the :ref:`P-FX ` the feature-extraction interface FX. Both work almost identical as they use the same internal algorithms to determine the pick polarity. The only difference is the interface and therefore when the polarity picker is started. In general, the polarity is either set to *positive* or *negative* if the polarity was determined successfully, or to *undecidable* if the intern algorithms cannot determine it uniquely. The polarity is left *unset* if any intern algorithms fail or if configuration criteria, like :confval:`minSNR`, are not fulfilled. .. _polpicker-paic: P-AIC ~~~~~ The **P-AIC** is built on top of the default AIC algorithm used to refine the P pick. In addition to the standard AIC behavior, the **P-AIC** tries to identify the first motion direction by applying one or multiple algorithms. Picks made by the **P-AIC** plugin can be identified: * In the method column of the arrival table in the Location tab of :cite:t:`scolv`, * In the picker window from the letter within brackets following a phase type (*

*), * In the picker window from the method hint which appears when hovering over a pick. .. _paic-fig-picker-method: .. figure:: /base/media/polpicker/paic-scolv.png :align: center :width: 16cm Read the pick method (:program:`scolv` picker window) to check the applied method which was used to create a pick polarity. .. _polpicker-pfx: P-FX ~~~~ The **P-FX** is using the FX interface to determine the pick polarity after a pick is made. Picks made by the **P-FX** plugin can only be identified in the picker window from the comment which appears when hovering over a pick. .. _paic-fig-picker-method: .. figure:: /base/media/polpicker/pfx-scolv.png :align: center :width: 16cm Read the pick comment (:program:`scolv` picker window) to check the applied method which was used to create a pick polarity. Picker configuration -------------------- #. **Plugin loading:** Add the plugin *polpicker* to the configuration of :program:`scautopick` or the global module configuration for making use of **P-AIC** or **P-FX**: .. code-block:: sh plugins = ${plugins}, polpicker #. **Module parameters:** Activate the **P-AIC** by changing the name of the :confval:`picker` in the module configuration of :program:`scautopick`: .. code-block:: sh picker = "P-AIC" or to use the **P-FX** set the :confval:`fx` value in the :program:`scautopick` configuration: .. code-block:: sh fx = "P-FX" #. **Bindings parameters:** Configure the **P-AIC** parameters under *picker* in global section of the bindings of :program:`scautopick`. An example: .. code-block:: picker.PAIC.minSNR = 20 picker.PAIC.algorithms = extremaComparer_envtrace,thresholdIncreaser picker.PAIC.decider = polarity picker.PAIC.noiseBegin = -1.0 picker.PAIC.signalBegin = -0.67 picker.PAIC.signalEnd = 0.5 picker.PAIC.filter = "RMHP(0.1)" picker.PAIC.useTime = true picker.PAIC.enableLinearDetrend = false picker.PAIC.disableAIC = false or for **P-FX** under *fx*: .. code-block:: fx.PFX.minSNR = 20 fx.PFX.algorithms = extremaComparer_envtrace,thresholdIncreaser fx.PFX.decider = polarity fx.PFX.noiseBegin = -1.0 fx.PFX.signalBegin = -0.67 fx.PFX.signalEnd = 0.5 fx.PFX.filter = "RMHP(0.1)" fx.PFX.useTime = true fx.PFX.enableLinearDetrend = false Parameter explanation: .. _paic-table-parameter: .. csv-table:: :header: "Parameter", "Description", "Values (defaults in bold)" :widths: 15,40,20 ":confval:`minSNR`","Minimum SNR in order to start the polarity picker.","" ":confval:`algorithms`","Defines the polarity algorithm(s) to use.", "**thresholdIncreaser**, **extremaComparer**, extremaComparer_dominantperiod, extremaComparer_dominantperiod_noend, extremaComparer_dominantperiod_envtrace, extremaComparer_noend, extremaComparer_envtrace, extremaComparer_envtrace_noend, dominantPeriodFixed, dominantPeriod" ":confval:`decider`","Defines how the individual results of multiple algorithms are combined.","**polarity**, sample, majority" ":confval:`noiseBegin`","Begin of the noise window in relation to the initial pick time.","" ":confval:`signalBegin`","End of the noise and begin of the signal window in relation to the initial pick time.","" ":confval:`signalEnd`","End of the signal window in relation to the initial pick time.","" ":confval:`filter`","Configures the first motion filter. Usually first motions are determined on **unfiltered** traces.","" ":confval:`period`","Period of the dominant waves in the first motion. Only valid for algorithm *dominantPeriodFixed*.","" ":confval:`useTime`","Whether to use the pick time refinement produced by the polarity picker.","true, **false**" ":confval:`enableLinearDetrend`","If true, uses the linearly detrended the trace if its SNR increases.","true, **false**" ":confval:`disableAIC`","If true disables the second-stage AIC picker beforehand (only used by P-AIC).","true, **false**" #. **Repicker in scolv**: In addition, the **P-AIC** is available as a repicker in the :program:`scolv` picker window. In the repicker drop-down menu of the scolv picker, the entry *P-AIC* should appear. Enable 'P picking' and press 'R' to automatically repick with *P-AIC*. .. With SeisComP versions >7, the repicker shows the predicted polarity besides .. the SNR. Make sure the plugin in loaded either in the global module or scolv configuration: .. code-block:: sh plugins = ${plugins}, polpicker Configuration hints ~~~~~~~~~~~~~~~~~~~ Although polarities should be picked on **unfiltered** waveforms, the algorithms might benefit from applying filters that remove noise or precursor artifacts. Depending on the presumed dominant frequency of the signal, low-frequent noise (e.g. microseism) might be filtered out by using a high-pass filter. For example, the filter **RMHP(0.1)** might not significantly distort the phase of the incoming P phase. For picking polarities on phases that have similar frequencies compared to the sensor sample-rate, precursor artifacts might be visible. To remove their influence, a low-pass filter, e.g. **BW_LP(3,-0.4)**, might be useful. For more robust polarities :confval:`minSNR` values of at least 10-20 are recommended. The noise window should not be too small (and not zero!) as the algorithms need some data to calibrate. The initial testing suggested a reasonable :confval:`signalBegin` value is 66\% of the :confval:`noiseBegin` value. Algorithms ---------- Determining the first motion correctly can become a challenging task and may result in non-unique solutions. Therefore the plugin provides a set of algorithms that try to determine the first motion based on different approaches. The simplest approach is measuring the gradient between the pick and its next sample. As the **P-AIC** and **P-FX** are embedded in an automatic processing chain and each automatic pick usually has an uncertainty that is higher than a few samples, the reference pick might not be accurate enough to reliably apply the simple gradient method. Further, the waveform may be affected by high noise levels (either low- or high-frequent), which may make the absolute measurement of the gradient incorrect for such cases. Instead, more robust algorithms were implemented. Those assume an uncertainty of the initial triggering pick and, thus, consider a larger time window around the pick. Still each algorithm has its drawbacks and might only be useful for certain types of waveform data. Besides determining the first motion, most of the available algorithms are capable of refining the pick time by determining the sample that *most-likely* corresponds to the polarity onset. Configure the parameter :confval:`useTime` to enable/disable the pick time refinement. thresholdIncreaser: ~~~~~~~~~~~~~~~~~~~ The idea of this algorithm is that the polarity is the first *stable* amplitude that exceeds the noise. The polarity amplitude is determined by the amplitude that crosses two consecutively increased thresholds. Advantages: - simplicity of the algorithm - reliable for strong amplitude first motions Disadvantages: - does not work with large low-frequent noise - might miss weak first motions .. figure:: /base/media/polpicker/thresholdIncreaser-example1.png :align: center :width: 16cm .. figure:: /base/media/polpicker/thresholdIncreaser-example2.png :align: center :width: 16cm Two examples showing the basic idea of the algorithm. Dashed, horizontal lines represent the increasing thresholds. The yellow pick represents the amplitude that is responsible for the polarity decision, while the red pick is the position of the final pick if :confval:`useTime` is true. For data where the signal is large compared to the background noise (top), the algorithm performs well. For example, if the waveform is highly influenced by low-frequent noise (bottom), the threshold approach is not suitable anymore and might produce erroneous polarities. extremaComparer: ~~~~~~~~~~~~~~~~ The idea of this algorithm is that the polarity defining extremum is significantly larger than the previous extremum. The contrast between each pair of consecutive extrema is calculated. The extremum with the largest contrast to its previous extremum defines the polarity. To stabilize the results, the algorithm considers only extrema within a *most-likely* time window around the P onset and calculates for each extrema pair a *local* mean level before determining the amplitude contrast. The latter results in a more robust determination of the polarity, especially in low-frequent noise environments. Advantages: - more robust in noisy environments - reliable for strong amplitude first motions - has derivatives tackling certain use cases Disadvantages: - complex algorithm - might miss weak first motions .. figure:: /base/media/polpicker/extremaComparer-example1.png :align: center :width: 16cm .. figure:: /base/media/polpicker/extremaComparer-example2.png :align: center :width: 16cm Two examples showing the basic idea of the algorithm. Green dots mark all extrema, whereas red dots mark only the relevant extrema, which lie in the predicted *most-likely* arrival time window (vertical, dotted lines). Next to each red dot is the confidence value, the extremum with the highest value determines the polarity. The yellow pick represents the amplitude that is responsible for the polarity decision, whereas the red pick is the position of the final pick if :confval:`useTime` is true. The approach is capable of finding the correct polarities for data with large SNR (top) as well as for data significantly influenced by low-frequent noise (bottom). To tackle some of its limitations, the algorithm has some extensions. For example, add the *envtrace* extension by replacing :confval:`extremaComparer` with :confval:`extremaComparer_envtrace`. Available extensions: - :confval:`extremaComparer_envtrace`: combines amplitude ratios for an envelope trace with the original trace ratios - enhances the detection quality of first motions with small amplitudes - :confval:`extremaComparer_dominantperiod`: applies a weighting based on a period depending time difference to the pick - prefers polarities close to the initial pick - :confval:`extremaComparer_noend`: there is no end time window restriction by the internal algorithm - helps if the initial pick is too early and combinations: :confval:`extremaComparer_envtrace_noend`, :confval:`extremaComparer_dominantperiod_envtrace` and :confval:`extremaComparer_dominantperiod_noend` dominantPeriod: ~~~~~~~~~~~~~~~ In the first step, the dominant period is determined or, for the *fixed* mode, read from the configuration (:confval:`picker.PAIC.period` or :confval:`fx.PFX.period`). Based on the period value, a time window around the pick is calculated. The final polarity is defined by the average slope of the time window. Decider ------- It is possible to use multiple algorithms simultaneously on the same pick by providing multiple entries in :confval:`picker.PAIC.algorithms` or :confval:`fx.PFX.algorithms`. Each algorithm determines polarity and sample individually. The *final* polarity that will be associated to the pick needs to be determined based on the outcome of all algorithms. For that reason several :confval:`decider` algorithms are available: - :confval:`polarity`: sets the polarity only if **all** algorithms predict the same polarity - :confval:`sample`: sets the polarity only if **all** algorithms predict the same sample as phase onset, as most algorithms are capable of refining the pick time - :confval:`majority`: sets the polarity to the value of the **majority** of the results, the polarity is set to *undecidable* if it is a draw .. note:: If only one single algorithm is used, the *decider* is skipped and the polarity is directly determined by the algorithm. Validation on test sets ----------------------- The performance of the algorithms have been validated by using publicly available first motion datasets. Hereby, the theoretical polarities (P-AIC/P-FX) were compared against the manual picks from the datasets. .. _paic-fig-picker-comparison: .. figure:: /base/media/polpicker/evaluation_instance.png :align: center :width: 16cm .. figure:: /base/media/polpicker/evaluation_scsn.png :align: center :width: 16cm Evaluation of the different polarity picker algorithms against the Instance dataset by :cite:t:`INSTANCE` (top) and the SCSN dataset by :cite:t:`ross-2018` (bottom). The plots show the matching percentage for all data points with at least at certain SNR value.