ConditionalEvents

class plasmapy.analysis.time_series.conditional_averaging.ConditionalEvents( signal, time, lower_threshold, *, upper_threshold=None, reference_signal=None, length_of_return=None, distance: float = 0, remove_non_max_peaks: bool = False, )[source]

Bases: object

Calculate conditional average, conditional variance, peaks, arrival times and waiting times of events of a time series.

Parameters:

signal (1D array_like) – Signal to be analyzed.
time (1D array_like) – Corresponding time values for signal.
lower_threshold (float or Quantity) – Lower threshold for event detection.
upper_threshold (float or Quantity, default: None) – Upper threshold for event detection.
reference_signal (1D array_like, default: None) – Reference signal. If None, signal is the reference signal.
length_of_return (float, default: None) – Desired length of returned data. If None, estimated as len(signal) / len(number_of_events) * time_step.
distance (float, default: 0) – Minimum distance between peaks, in units of time.
remove_non_max_peaks (bool, default: False) – Remove events where peak is not the largest value inside window.

Raises:

ValueError – If length of signal and time are not equal. If length of reference_signal and time are not equal (when reference_signal is provided). If length_of_return is greater than the length of the time span. If length_of_return is negative. If upper_threshold is less than or equal to lower_threshold.
UnitsError – If astropy units of signal/reference_signal and either lower_threshold or upper_threshold do not match. If the units of time, length_of_return and distance do not match.

Notes

The method, in its simplest form, works by finding peaks in a signal that fulfill a certain size threshold. Equally sized excerpts of the signal around every peak are then cut out and averaged. This yields the average shape of the events that fulfill the condition.

A detailed analysis of the conditional averaging method is presented in the Master thesis by Nilsen [2023].

Examples

>>> from plasmapy.analysis.time_series.conditional_averaging import (
...     ConditionalEvents,
... )
>>> cond_events = ConditionalEvents(
...     signal=[1, 2, 1, 1, 2, 1],
...     time=[1, 2, 3, 4, 5, 6],
...     lower_threshold=1.5,
... )
>>> cond_events.time
array([-1.0, 0.0, 1.0])
>>> cond_events.average
array([1., 2., 1.])
>>> cond_events.variance
array([1., 1., 1.])
>>> cond_events.peaks
array([2, 2])
>>> cond_events.waiting_times
array([3])
>>> cond_events.arrival_times
array([2, 5])
>>> cond_events.number_of_events
2

Attributes Summary

`arrival_times`	Arrival times corresponding to the conditional events.
`average`	Conditional average over events.
`number_of_events`	Total number of conditional events.
`peaks`	Peak values of conditional events.
`time`	Time values corresponding to the analysis window.
`variance`	Conditional variance over events.
`waiting_times`	Waiting times between consecutive peaks.

Attributes Documentation

arrival_times

Arrival times corresponding to the conditional events.

Returns:: arrival_times – Arrival times the conditional events.
Return type:: 1D array_like

average

Conditional average over events.

Returns:: average – Array representing the conditional average over events.
Return type:: 1D array_like

number_of_events

Total number of conditional events.

Returns:: number_of_events – Total number of conditional events.
Return type:: int

peaks

Peak values of conditional events.

Returns:: peaks – Peak values of conditional events.
Return type:: 1D array_like

time

Time values corresponding to the analysis window.

Returns:: time – Time values representing the analysis window.
Return type:: 1D array_like

variance

Conditional variance over events.

Returns:: variance – Array representing the conditional variance over events.
Return type:: 1D array_like

waiting_times

Waiting times between consecutive peaks.

Returns:: waiting_times – Waiting times between consecutive peaks of conditional events.
Return type:: 1D array_like