Triggers¶

The trigger turns the detection function, the maximum semblance over all nodes, into detections. A peak of the detection function is a detection when its height and its prominence exceed the thresholds of the trigger. Peaks closer than the blinding, 1 s by default, count as one detection. See detection.

Qseek computes the thresholds of the adaptive triggers in every processed window of window_length, 5 minutes by default.

The default ThresholdTrigger has a single parameter: the minimum semblance of a detection, 0.3 by default. The semblance of your events depends on the network, the phase weights and the distance weighting, so treat 0.3 as a starting point and set the threshold from the semblance column of csv/detections.csv of a first run. The adaptive triggers find more small events, at the cost of more parameters and more weak detections. On one day of the 2024 Campi Flegrei swarm (18 INGV stations, 287 windows), the adaptive thresholds range from 0.03 in quiet windows to 0.25 in the busiest windows:

Both adaptive triggers find all detections of the fixed threshold, at the same locations. They add about 200 detections with at least 8 picks, smaller events in the same cluster (median ML 0.19 against 0.48), and about 200 poorly constrained detections with a median of 4 picks. The fixed threshold of 0.3 misses weak events in quiet windows, where the adaptive thresholds are six to ten times lower. On this data set, z_score 6 gives nearly the same detections as mad_factor 10: the noise floor of the detection function is low, about 0.01. The default z_score 7 is slightly stricter, with 642 detections.

Fixed threshold¶

ThresholdTrigger applies the same minimum semblance to all windows, for height and prominence. Set it from the semblance of the events you want to detect: the semblance column of csv/detections.csv of a first run shows it.

{
  "trigger": "ThresholdTrigger",
  "blinding": "PT1S",
  "threshold": 0.3
}

threshold: PositiveFloat = 0.3

blinding: timedelta = timedelta(seconds=1.0)

get_threshold(detection_function: ndarray) -> tuple[float, float]

get_subclasses() -> tuple[type[Trigger], ...]

detect(detection_function: ndarray, sampling_rate: float, padding: int = 0) -> tuple[ndarray, ndarray]

MAD trigger¶

The threshold is mad_factor times the median absolute deviation (MAD) of the detection function in each window, 10 by default. It is the minimum height and the minimum prominence of a detection.

{
  "trigger": "MADTrigger",
  "blinding": "PT1S",
  "mad_factor": 10.0,
  "threshold_range": null
}

mad_factor: PositiveFloat = 10.0

blinding: timedelta = timedelta(seconds=1.0)

get_threshold(detection_function: ndarray) -> tuple[float, float]

get_subclasses() -> tuple[type[Trigger], ...]

detect(detection_function: ndarray, sampling_rate: float, padding: int = 0) -> tuple[ndarray, ndarray]

Modified z-score trigger¶

The modified z-score of Iglewicz and Hoaglin (1993) measures how far a peak stands above the median \(\tilde{x}\) of the detection function, in units of the MAD scaled to a standard deviation:

A detection needs a height of at least the median plus z_score scaled MADs, and a prominence of at least z_score scaled MADs, 7 by default. Unlike the MADTrigger, the threshold rises with the noise floor of the detection function.

{
  "trigger": "ModZScoreTrigger",
  "blinding": "PT1S",
  "z_score": 7.0,
  "threshold_range": null
}

z_score: PositiveFloat = 7.0

blinding: timedelta = timedelta(seconds=1.0)

get_threshold(detection_function: ndarray) -> tuple[float, float]

get_subclasses() -> tuple[type[Trigger], ...]

detect(detection_function: ndarray, sampling_rate: float, padding: int = 0) -> tuple[ndarray, ndarray]

Limit the adaptive threshold¶

threshold_range clips the thresholds of the adaptive triggers to [min, max] semblance in every window. The minimum keeps noise peaks out of quiet windows, and windows where the detection function is flat: there the MAD is close to zero, and so is the threshold. The maximum keeps a busy window from raising its own threshold during a swarm.

"trigger": {
  "trigger": "MADTrigger",
  "mad_factor": 10.0,
  "threshold_range": [0.05, 0.12]
}

On the Campi Flegrei day, with mad_factor 10:

Lost and new count the detections with at least 8 picks, against no range. The maximum adds well-constrained detections in busy windows without losing any. The minimum of 0.05 removes 27 detections, all with fewer than 8 picks.