Package org.chsrobotics.lib.math.filters

Class PeakDetectionFilter

java.lang.Object

org.chsrobotics.lib.math.filters.PeakDetectionFilter

All Implemented Interfaces:

Filter

public class PeakDetectionFilter
extends java.lang.Object
implements Filter

A filter to isolate peaks in a stream of data.

Returns 1 if a given value is greater than a rolling average of standard deviations away from the median, -1 if it's smaller by that amount or more.

Returns 0 for the first window - 1 inputs.

Concept from the Stack Overflow answer cited below.

Generally when tuning, there's a balance to be made between window (number of past data points to consider) and stddev and mean (influence a value considered a peak will have on the total mean and standard deviation of the data) influences. A large window will result in more phase lag, but can allow for influences of 1.0 for stddev and mean, as signals will be surrounded by much more data. However, a small window has little phase lag, but can be susceptible to high influences from peaks (they are, after all, outliers by definition). Larger windows are almost always recommended if you can ignore the slight phase lag issue.

Special care should be taken when the series exhibits trends over time to balance influences so as not to completely erase or amplify said trend.

Brakel, J.P.G. van (2014). "Robust peak detection algorithm using z-scores". Stack Overflow. Available at: https://stackoverflow.com/questions/22583391/peak-signal-detection-in-realtime-timeseries-data/22640362#22640362 (version: 2020-11-08).

Constructor Summary

Constructors

Constructor	Description
PeakDetectionFilter(int window, double threshold, double standardDeviationInfluence, double meanInfluence)	Constructs a PeakDetection filter.
PeakDetectionFilter(int window, double threshold, double standardDeviationInfluence, double meanInfluence, double minimumDelta)	Constructs a PeakDetection filter with a minimum delta from the mean to be considered a signal.

Method Summary

Modifier and Type	Method	Description
double	calculate(double value)	Returns whether a value is considered a peak, a valley, or neither within the combined input data.
double	getCurrentOutput()	Returns the current output of the filter without updating with a new value.
void	reset()	Resets the history of the filter.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PeakDetectionFilter

public PeakDetectionFilter(int window,
                           double threshold,
                           double standardDeviationInfluence,
                           double meanInfluence,
                           double minimumDelta)

Constructs a PeakDetection filter with a minimum delta from the mean to be considered a signal.

Parameters:

window - The number of past data points to consider for mean and stddev calculations.

threshold - The number of standard deviations above or below the mean needed to be considered a signal.

standardDeviationInfluence - The effect a signal will have on the standard deviation, in [0,1].

meanInfluence - The effect a signal will have on the mean, in [0,1].

minimumDelta - The minimum distance from the mean requrired to be considered significant. An input of zero means that any variance above threshold standard deviations will be counted, no matter how small.

Throws:

java.security.InvalidParameterException - If the window is less than 2.

PeakDetectionFilter

public PeakDetectionFilter(int window,
                           double threshold,
                           double standardDeviationInfluence,
                           double meanInfluence)

Constructs a PeakDetection filter.

Parameters:

window - The number of past data points to consider for mean and stddev calculations.

threshold - The number of standard deviations above or below the mean needed to be considered a signal.

standardDeviationInfluence - The effect a signal will have on the standard deviation, in [0,1].

meanInfluence - The effect a signal will have on the mean, in [0,1].

Throws:

java.security.InvalidParameterException - If the window is less than 2.

Method Detail

calculate

public double calculate(double value)

Returns whether a value is considered a peak, a valley, or neither within the combined input data.

Returns 0 for the first window-1 inputs.

Specified by:

calculate in interface Filter

Parameters:

value - The value to input to the filter.

Returns:

1 if the input value represents a peak, -1 if it represents a valley, 0 if it represents neither.

reset

public void reset()

Resets the history of the filter.

Specified by:

reset in interface Filter

getCurrentOutput

public double getCurrentOutput()

Returns the current output of the filter without updating with a new value.

Specified by:

getCurrentOutput in interface Filter

Returns:

The current output of the filter (0 if no values have been given to calculate()).