obspy.signal.trigger.coincidence_trigger

coincidence_trigger(trigger_type, thr_on, thr_off, stream, thr_coincidence_sum, trace_ids=None, max_trigger_length=1000000.0, delete_long_trigger=False, trigger_off_extension=0, details=False, event_templates={}, similarity_threshold=0.7, **options)[source]

Perform a network coincidence trigger.

The routine works in the following steps:

  • take every single trace in the stream

  • apply specified triggering routine (can be skipped to work on precomputed custom characteristic functions)

  • evaluate all single station triggering results

  • compile chronological overall list of all single station triggers

  • find overlapping single station triggers

  • calculate coincidence sum of every individual overlapping trigger

  • add to coincidence trigger list if it exceeds the given threshold

  • optional: if master event templates are provided, also check single station triggers individually and include any single station trigger if it exceeds the specified similarity threshold even if no other stations coincide with the trigger

  • return list of network coincidence triggers

Note

An example can be found in the Trigger/Picker Tutorial.

Note

Setting trigger_type=None precomputed characteristic functions can be provided.

See also

[Withers1998] (p. 98) and [Trnkoczy2012]

Parameters

  • trigger_type (str or None) – String that specifies which trigger is applied (e.g. 'recstalta'). See e.g. obspy.core.trace.Trace.trigger() for further details. If set to None no triggering routine is applied, i.e. data in traces is supposed to be a precomputed characteristic function on which the trigger thresholds are evaluated.

  • thr_on (float) – threshold for switching single station trigger on

  • thr_off (float) – threshold for switching single station trigger off

  • stream (Stream) – Stream containing waveform data for all stations. These data are changed inplace, make a copy to keep the raw waveform data.

  • thr_coincidence_sum (int or float) – Threshold for coincidence sum. The network coincidence sum has to be at least equal to this value for a trigger to be included in the returned trigger list.

  • trace_ids (list or dict, optional) – Trace IDs to be used in the network coincidence sum. A dictionary with trace IDs as keys and weights as values can be provided. If a list of trace IDs is provided, all weights are set to 1. The default of None uses all traces present in the provided stream. Waveform data with trace IDs not present in this list/dict are disregarded in the analysis.

  • max_trigger_length (int or float) – Maximum single station trigger length (in seconds). delete_long_trigger controls what happens to single station triggers longer than this value.

  • delete_long_trigger (bool, optional) – If False (default), single station triggers are manually released at max_trigger_length, although the characteristic function has not dropped below thr_off. If set to True, all single station triggers longer than max_trigger_length will be removed and are excluded from coincidence sum computation.

  • trigger_off_extension (int or float, optional) – Extends search window for next trigger on-time after last trigger off-time in coincidence sum computation.

  • details (bool, optional) – If set to True the output coincidence triggers contain more detailed information: A list with the trace IDs (in addition to only the station names), as well as lists with single station characteristic function peak values and standard deviations in the triggering interval and mean values of both, relatively weighted like in the coincidence sum. These values can help to judge the reliability of the trigger.

  • options – Necessary keyword arguments for the respective trigger that will be passed on. For example sta and lta for any STA/LTA variant (e.g. sta=3, lta=10). Arguments sta and lta (seconds) will be mapped to nsta and nlta (samples) by multiplying with sampling rate of trace. (e.g. sta=3, lta=10 would call the trigger with 3 and 10 seconds average, respectively)

  • event_templates (dict) – Event templates to use in checking similarity of single station triggers against known events. Expected are streams with three traces for Z, N, E component. A dictionary is expected where for each station used in the trigger, a list of streams can be provided as the value to the network/station key (e.g. {“GR.FUR”: [stream1, stream2]}). Templates are compared against the provided stream without the specified triggering routine (trigger_type) applied.

  • similarity_threshold (float or dict) – similarity threshold (0.0-1.0) at which a single station trigger gets included in the output network event trigger list. A common threshold can be set for all stations (float) or a dictionary mapping station names to float values for each station.

Return type

list

Returns

List of event triggers sorted chronologically.