Trigger#

class acoular.tprocess.Trigger

Bases: TimeOut

A signal processing class for detecting and analyzing trigger signals in time-series data.

The Trigger class identifies trigger events in a single-channel signal provided by a SamplesGenerator source. The detection process involves:

  1. Identifying peaks that exceed a specified positive or negative threshold.

  2. Estimating the approximate duration of one revolution based on the largest sample distance between consecutive peaks.

  3. Dividing the estimated revolution duration into segments called “hunks,” allowing only one peak per hunk.

  4. Selecting the most appropriate peak per hunk based on a chosen criterion (e.g., first occurrence or extremum value).

  5. Validating the consistency of the detected peaks by ensuring the revolutions have a stable duration with minimal variation.

This class is typically used for rotational speed analysis, where trigger events correspond to periodic markers in a signal (e.g., TDC signals in engine diagnostics).

source = Instance(SamplesGenerator)

The input data source. It must be an instance of a SamplesGenerator-derived class. The signal must be single-channel.

threshold = Union(None, Float)

The threshold value for detecting trigger peaks. The meaning of this threshold depends on the trigger type (:attr;`trigger_type`). The sign is relevant:

  • A positive threshold detects peaks above this value.

  • A negative threshold detects peaks below this value.

If None, an estimated threshold is used, calculated as 75% of the extreme deviation from the mean signal value. Default is None.

E.g: If the mean value is \(0\) and there are positive extrema at \(400\) and negative extrema at \(-800\). Then the estimated threshold would be \(0.75 \cdot (-800) = -600\).

max_variation_of_duration = Float(0.02)

The maximum allowable variation in duration between two trigger instances. If any revolution exceeds this variation threshold, a warning is issued. Default is 0.02.

hunk_length = Float(0.1)

Defines the length of “hunks” as a fraction of the estimated duration between two trigger instances. If multiple peaks occur within a hunk, only one is retained based on multiple_peaks_in_hunk. Default is 0.1.

trigger_type = Enum('dirac', 'rect')

Specifies the type of trigger detection:

  • 'dirac': A single impulse is considered a trigger. The sign of threshold determines whether positive or negative peaks are detected.

  • 'rect': A repeating rectangular waveform is assumed. Only every second edge is considered a trigger. The sign of threshold determines whether rising (+) or falling (-) edges are used.

Default is 'dirac'.

multiple_peaks_in_hunk = Enum('extremum', 'first')

Defines the criterion for selecting a peak when multiple occur within a hunk (see hunk_length):

  • 'extremum': Selects the most extreme peak.

  • 'first': Selects the first peak encountered.

Default is 'extremum'.

trigger_data = Property( …

A tuple containing:

  • A numpy.ndarray of sample indices corresponding to detected trigger events.

  • The maximum number of samples between consecutive trigger peaks.

  • The minimum number of samples between consecutive trigger peaks.

digest = Property( …

A unique identifier for the trigger, based on its properties. (read-only)

result(num)

Generate signal data from the source without modification.

This method acts as a pass-through, providing data blocks directly from the source generator. It is included for interface consistency but does not apply trigger-based transformations to the data.

Parameters:
numint

Number of samples per block.

Yields:
numpy.ndarray

An array containing num samples from the source signal. The last block may contain fewer samples if the total number of samples is not a multiple of num.

Warning

This method is not implemented for trigger-based transformations. A warning is issued, indicating that data is passed unprocessed.