Adaptive normalizer: normalizes values on-the-run using exponential moving averages over mean and standard deviation. More...

#include <Normalizer.h>

Inheritance diagram for pq::Normalizer:

[legend]

Collaboration diagram for pq::Normalizer:

[legend]

Public Member Functions
	Normalizer (Engine &engine=Engine::primary())
	Default constructor.

	Normalizer (float timeWindow, Engine &engine=Engine::primary())
	Constructor with time window.

	Normalizer (float mean, float stdDev, Engine &engine=Engine::primary())
	Constructor with infinite time window.

	Normalizer (float mean, float stdDev, float timeWindow, Engine &engine=Engine::primary())
	Constructor with time window.

void	targetMean (float mean)
	Sets target mean of normalized values.

float	targetMean () const
	Returns target mean.

void	targetStdDev (float stdDev)
	Sets target standard deviation of normalized values.

float	targetStdDev () const
	Returns target standard deviation.

virtual void	reset ()
	Resets the statistics.

virtual void	reset (float estimatedMeanValue)
	Resets the filter with a prior estimate of the mean value.

virtual void	reset (float estimatedMinValue, float estimatedMaxValue)
	Resets the moving filter with a prior estimate of the min and max values.

virtual float	put (float value)
	Pushes value into the unit.

virtual float	filter (float value)
	Returns the filtered value (without calibrating).

virtual float	lowOutlierThreshold (float nStdDev=1.5f) const
	Returns value above which value is considered to be a low outler (below average).

virtual float	highOutlierThreshold (float nStdDev=1.5f) const
	Returns value above which value is considered to be a high outler (above average).

bool	isClamped () const
	Return true iff the normalized value is clamped within reasonable range.

void	clamp (float nStdDev=NORMALIZER_DEFAULT_CLAMP_STDDEV)
	Assign clamping value.

void	noClamp ()
	Remove clamping.

virtual float	mapTo (float toLow, float toHigh)
	Maps value to new range.

virtual void	resumeCalibrating ()
	Switches to calibration mode (default).

virtual void	pauseCalibrating ()
	Switches to non-calibration mode: calls to put(value) will return filtered value without updating the normalization statistics.

virtual void	toggleCalibrating ()
	Toggles calibration mode.

virtual bool	isCalibrating () const
	Returns true iff the moving filter is in calibration mode.

unsigned int	nSamples () const
	Returns the number of samples that have been processed thus far.

virtual bool	isPreInitialized () const
	Returns true if the moving filter has been initialized with a starting range at reset.

virtual float	get ()
	Returns value in [0, 1].

virtual void	clearEvents ()

float	seconds () const
	Returns engine time in seconds.

uint32_t	milliSeconds () const
	Returns engine time in milliseconds.

uint64_t	microSeconds () const
	Returns engine time in microseconds.

unsigned long	nSteps () const
	Returns number of engine steps.

float	sampleRate () const
	Returns engine sample rate.

float	samplePeriod () const
	Returns enginesample period.

	operator float ()
	Object can be used directly to access its value.

	operator bool ()
	Operator that allows usage in conditional expressions.

virtual void	infiniteTimeWindow ()
	Sets time window to infinite.

virtual void	noTimeWindow ()
	Sets time window to no time window.

virtual void	timeWindow (float seconds)
	Changes the time window (expressed in seconds).

virtual float	timeWindow () const
	Returns the time window (expressed in seconds).

virtual bool	timeWindowIsInfinite () const
	Returns true if time window is infinite.

virtual void	cutoff (float hz)
	Changes the time window cutoff frequency (expressed in Hz).

virtual float	cutoff () const
	Returns the time window cutoff frequency (expressed in Hz).

virtual float	update (float value, float alpha)
	Adds a value to the statistics (returns the mean).

virtual float	mean () const
	Returns an exponential moving average of the samples.

virtual float	meanSquared () const
	Return an exponential moving variance of the squared samples.

virtual float	var () const
	Returns an exponential moving variance of the samples.

virtual float	stdDev () const
	Returns the standard deviation of the samples.

virtual float	normalize (float value) const
	Returns the normalized value according N(0, 1).

virtual float	normalize (float value, float mean, float stdDev) const
	Returns the normalized value according to the computed statistics (mean and variance).

virtual bool	isOutlier (float value, float nStdDev=1.5f) const
	Returns true if the value is considered an outlier.

virtual bool	isLowOutlier (float value, float nStdDev=1.5f) const
	Returns true if the value is considered a low outlier (below average).

virtual bool	isHighOutlier (float value, float nStdDev=1.5f) const
	Returns true if the value is considered a high outlier (above average).

virtual float	stddev () const

Static Public Member Functions
static bool	analogToDigital (float f)
	Converts analog (float) value to digital (bool) value.

static float	digitalToAnalog (bool b)
	Converts digital (bool) value to analog (float) value.

Public Attributes
MovingAverage	_mean

MovingAverage	_mean2

Protected Member Functions
virtual void	step ()

void	_init (float mean, float stdDev)

float	_clamp (float value) const

virtual void	begin ()

virtual float	alpha () const

virtual bool	eventTriggered (EventType eventType)
	Returns true iff an event of a certain type has been triggered.

virtual void	onEvent (EventCallback callback, EventType eventType)
	Registers event callback.

Engine *	engine () const
	Returns the engine that owns this unit.

Protected Attributes
float	_targetMean

float	_targetStdDev

float	_clampStdDev

float	_currentMeanStep

float	_currentMean2Step

bool	_isCalibrating: 1

bool	_isPreInitialized: 1

uint8_t	_nValuesStep: 6

unsigned int	_nSamples

float	_value

float	_timeWindow

Detailed Description

Adaptive normalizer: normalizes values on-the-run using exponential moving averages over mean and standard deviation.

Constructor & Destructor Documentation

◆ Normalizer() [1/4]

pq::Normalizer::Normalizer ( Engine & engine = Engine::primary() )

Default constructor.

Assigns infinite time window. Will renormalize data around a mean of 0.5 and a standard deviation of 0.15.

Parameters

engine the engine running this unit

◆ Normalizer() [2/4]

pq::Normalizer::Normalizer	(	float	timeWindow,
		Engine &	engine = `Engine::primary()`
	)

Constructor with time window.

Will renormalize data around a mean of 0.5 and a standard deviation of 0.15.

Parameters

timeWindow	the time window over which the normalization applies (in seconds)
engine	the engine running this unit

◆ Normalizer() [3/4]

pq::Normalizer::Normalizer	(	float	mean,
		float	stdDev,
		Engine &	engine = `Engine::primary()`
	)

Constructor with infinite time window.

Parameters

mean	the target mean
stdDev	the target standard deviation

◆ Normalizer() [4/4]

pq::Normalizer::Normalizer	(	float	mean,
		float	stdDev,
		float	timeWindow,
		Engine &	engine = `Engine::primary()`
	)

Constructor with time window.

Parameters

mean	the target mean
stdDev	the target standard deviation
timeWindow	the time window over which the normalization applies (in seconds)

Member Function Documentation

◆ begin()

void pq::MovingFilter::begin ( )

protectedvirtualinherited

Reimplemented from pq::Unit.

◆ clamp()

void pq::Normalizer::clamp ( float nStdDev = NORMALIZER_DEFAULT_CLAMP_STDDEV )

Assign clamping value.

Values will then be clamped between reasonable range (targetMean() +/- nStdDev * targetStdDev()).

Parameters

nStdDev the number of standard deviations (default: 3.333333333)

◆ eventTriggered()

virtual bool pq::Unit::eventTriggered ( EventType eventType )

inlineprotectedvirtualinherited

Returns true iff an event of a certain type has been triggered.

Reimplemented in pq::AbstractWave, pq::Alarm, pq::Metronome, pq::PeakDetector, pq::DigitalSource, pq::Ramp, pq::StreamIn, and pq::TimeSliceField< COUNT >.

◆ filter()

float pq::Normalizer::filter ( float value )

virtual

Returns the filtered value (without calibrating).

Implements pq::MovingFilter.

◆ get()

virtual float pq::AnalogSource::get ( )

inlinevirtualinherited

Returns value in [0, 1].

Reimplemented from pq::Flowable.

Reimplemented in pq::AbstractWave, and pq::RobustScaler.

◆ highOutlierThreshold()

float pq::Normalizer::highOutlierThreshold ( float nStdDev = 1.5f ) const

virtual

Returns value above which value is considered to be a high outler (above average).

Parameters

nStdDev the number of standard deviations (typically between 1 and 3); low values = more sensitive

◆ isHighOutlier()

bool pq::MovingStats::isHighOutlier	(	float	value,
		float	nStdDev = `1.5f`
	)		const

virtualinherited

Returns true if the value is considered a high outlier (above average).

Parameters

value	the raw value to be tested (non-normalized)
nStdDev	the number of standard deviations (typically between 1 and 3); low values = more sensitive

Returns: true if value is nStdDev number of standard deviations above mean

◆ isLowOutlier()

bool pq::MovingStats::isLowOutlier	(	float	value,
		float	nStdDev = `1.5f`
	)		const

virtualinherited

Returns true if the value is considered a low outlier (below average).

Parameters

value	the raw value to be tested (non-normalized)
nStdDev	the number of standard deviations (typically between 1 and 3); low values = more sensitive

Returns: true if value is nStdDev number of standard deviations below mean

◆ isOutlier()

bool pq::MovingStats::isOutlier	(	float	value,
		float	nStdDev = `1.5f`
	)		const

virtualinherited

Returns true if the value is considered an outlier.

Parameters

value	the raw value to be tested (non-normalized)
nStdDev	the number of standard deviations (typically between 1 and 3); low values = more sensitive

Returns: true if value is nStdDev number of standard deviations above or below mean

◆ lowOutlierThreshold()

float pq::Normalizer::lowOutlierThreshold ( float nStdDev = 1.5f ) const

virtual

Returns value above which value is considered to be a low outler (below average).

Parameters

nStdDev the number of standard deviations (typically between 1 and 3); low values = more sensitive

◆ mapTo()

float pq::Normalizer::mapTo	(	float	toLow,
		float	toHigh
	)

virtual

Maps value to new range.

Reimplemented from pq::AnalogSource.

◆ put()

float pq::Normalizer::put ( float value )

virtual

Pushes value into the unit.

If isRunning() is false the filter will not be updated but will just return the filtered value.

Parameters

value the value sent to the unit

Returns: the new value of the unit

Reimplemented from pq::Flowable.

◆ reset() [1/3]

void pq::Normalizer::reset ( )

virtual

Resets the statistics.

Reimplemented from pq::MovingFilter.

◆ reset() [2/3]

void pq::Normalizer::reset ( float estimatedMeanValue )

virtual

Resets the filter with a prior estimate of the mean value.

Reimplemented from pq::MovingFilter.

◆ reset() [3/3]

void pq::Normalizer::reset	(	float	estimatedMinValue,
		float	estimatedMaxValue
	)

virtual

Resets the moving filter with a prior estimate of the min and max values.

Reimplemented from pq::MovingFilter.

◆ resumeCalibrating()

void pq::MovingFilter::resumeCalibrating ( )

virtualinherited

Switches to calibration mode (default).

Calls to put(value) will return filtered value AND update the normalization statistics.

◆ stddev()

virtual float pq::MovingStats::stddev ( ) const

inlinevirtualinherited

Deprecated:: Returns the standard deviation of the samples.

◆ step()

void pq::Normalizer::step ( )

protectedvirtual

Reimplemented from pq::Unit.

◆ targetMean()

void pq::Normalizer::targetMean ( float mean )

inline

Sets target mean of normalized values.

Parameters

mean	the target mean

◆ targetStdDev()

void pq::Normalizer::targetStdDev ( float stdDev )

inline

Sets target standard deviation of normalized values.

Parameters

stdDev the target standard deviation

The documentation for this class was generated from the following files:

/home/tats/Documents/workspace/Plaquette/src/Normalizer.h
/home/tats/Documents/workspace/Plaquette/src/Normalizer.cpp

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Normalizer() [1/4]

◆ Normalizer() [2/4]

◆ Normalizer() [3/4]

◆ Normalizer() [4/4]

Member Function Documentation

◆ begin()

◆ clamp()

◆ eventTriggered()

◆ filter()

◆ get()

◆ highOutlierThreshold()

◆ isHighOutlier()

◆ isLowOutlier()

◆ isOutlier()

◆ lowOutlierThreshold()

◆ mapTo()

◆ put()

◆ reset() [1/3]

◆ reset() [2/3]

◆ reset() [3/3]

◆ resumeCalibrating()

◆ stddev()

◆ step()

◆ targetMean()

◆ targetStdDev()