Holds the last accepted value when a new sample looks like an isolated outlier relative to its recent neighbors. More...
#include <HampelFilter.hpp>
Collaboration diagram for MayaFlux::Kinesis::HampelFilter< T >:Public Member Functions | |
| T | accept (const T &candidate) |
| Test a candidate value and return the value to actually use. | |
| HampelFilter (size_t window=8, double threshold_mad=3.5, size_t max_consecutive_rejections=3) | |
| Construct a filter. | |
| bool | is_active () const |
| Whether the filter has enough history to actually screen candidates. | |
| const T & | last_good () const |
| Current last accepted value. | |
| void | reset () |
| Reset to uninitialized state. | |
Static Private Member Functions | |
| template<typename U > | |
| static double | magnitude_of (const U &v) noexcept |
| Scalar reduction used for the MAD comparison. | |
Private Attributes | |
| size_t | m_consecutive_rejections { 0 } |
| bool | m_has_history |
| Memory::HistoryBuffer< T > | m_history |
| T | m_last_good |
| size_t | m_max_consecutive_rejections |
| size_t | m_sample_count { 0 } |
| double | m_threshold_mad |
Detailed Description
class MayaFlux::Kinesis::HampelFilter< T >
Holds the last accepted value when a new sample looks like an isolated outlier relative to its recent neighbors.
Implements the Hampel identifier: a candidate is rejected when its deviation from the median of a recent window exceeds threshold_mad scaled median absolute deviations. This is the standard robust alternative to a mean/standard-deviation outlier test, chosen because a single genuine spike should not be allowed to inflate the threshold that screens for itself: one wild sample shifts a window's mean and stddev substantially, but only shifts a median by at most one rank. The hold-last-value response on rejection is the filtering variant of the Hampel identifier, as opposed to flag-only detection.
Differential's derivatives amplify noise: a single bad raw sample that survives upstream smoothing (Stochastic::Estimate) still gets multiplied by 1/dt^2 or 1/dt^3, producing one wildly spiking acceleration or jerk reading even though the underlying motion was smooth. HampelFilter screens for that specific shape of problem, an isolated one-sample spike in an already-differentiated signal, which is a different concern from Estimate's job of characterizing an evolving raw stream's noise floor. HampelFilter has no notion of a learned floor and does not filter a raw signal; it only asks whether one candidate value is consistent with its immediate recent history.
On rejection, this returns the last accepted value rather than the candidate, silently. This adds up to one sample of lag on a genuine fast transient that happens to also look statistically unusual, which is the deliberate tradeoff: a caller feeding this into a visual parameter or gesture classifier is generally better served by a held value than a single-frame glitch. A caller that needs to know a rejection happened rather than have it silently smoothed over should not use this class; it is intentionally not a flag-only tool.
- Template Parameters
-
T Sample type. Must support operator-, and the resulting difference type must be usable with scalar_t<T> reductions (a plain arithmetic value directly, a glm vector via its magnitude). See magnitude_of() below for the exact rule.
Definition at line 50 of file HampelFilter.hpp.
The documentation for this class was generated from the following file:
