Stateful statistical characterization of an evolving scalar stream. More...

#include <Estimate.hpp>

Collaboration diagram for MayaFlux::Kinesis::Stochastic::Estimate:

Public Member Functions
double	confidence (double step) const
	Confidence that a step is signal, not floor.

double	confidence_of_rate (double rate, double dt) const
	Confidence that a Differential-derived rate reflects signal, not floor.

	Estimate (EstimateModel model=EstimateModel::EWM_VARIANCE, double adapt_rate=0.05, size_t window=32)
	Constructs an estimator with the specified model.

double	floor () const
	Current learned floor.

double	get_adapt_rate () const
	Gets the current adapt rate.

EstimateModel	get_model () const
	Gets current model.

size_t	get_window () const
	Gets the current window size.

void	reset ()
	Resets internal state.

void	set_adapt_rate (double rate)
	Sets the adapt rate used by EWM_VARIANCE.

void	set_model (EstimateModel model)
	Changes active model.

void	set_window (size_t window)
	Sets the window size used by windowed models.

const EstimateState &	state () const
	Gets current internal state.

EstimateState &	state_mutable ()
	Gets mutable internal state.

double	update (double sample)
	Feed one new sample, updating the running estimate.

void	update_into (double sample, Memory::HistoryBuffer< double > &out)
	Feed one sample and push the filtered result into a HistoryBuffer.

double	value () const
	Current filtered value, the cleaned counterpart to the raw sample.

Static Public Member Functions
static std::vector< size_t >	flag_outliers (std::span< const double > samples, double threshold_mad=3.0) noexcept
	Flags samples whose deviation from the median exceeds a threshold.

static double	median_absolute_deviation (std::span< const double > samples) noexcept
	Median absolute deviation of a span.

static double	stddev (std::span< const double > samples) noexcept
	Standard deviation of a span.

static double	trend_explained_ratio (std::span< const double > samples) noexcept
	Fraction of a span's variance attributable to its linear trend.

static double	trend_slope (std::span< const double > samples) noexcept
	Linear trend slope across a span.

static double	variance (std::span< const double > samples) noexcept
	Sample variance of a span.

Private Member Functions
double	update_ewm_variance (double sample)

double	update_mad (double sample)

double	update_quiet_period (double sample)

double	update_rolling_variance (double sample)

double	update_trend (double sample)

Private Attributes
double	m_adapt_rate

Memory::HistoryBuffer< double >	m_history

EstimateModel	m_model

EstimateState	m_state

size_t	m_window

Detailed Description

Stateful statistical characterization of an evolving scalar stream.

Provides mathematical primitives for characterizing controlled uncertainty in an arriving signal, across all computational domains. This is the read direction of what Stochastic is for the write direction: Stochastic produces a signal with chosen statistical character, Estimate consumes a signal and characterizes its statistical character, updating that characterization as the stream's behavior itself changes.

Architectural Philosophy

Treats stream characterization as fundamental mathematical infrastructure rather than domain-specific processing. The same primitives that learn a tablet's pressure noise floor can learn a camera-derived tracking point's jitter, an analysis feature's drift, or any other per-frame scalar's evolving statistical behavior. The numbers themselves are discipline-agnostic.

Model Categories

Windowed (bounded recent memory):

ROLLING_VARIANCE: mean and variance over the last N samples
MEDIAN_ABSOLUTE_DEVIATION: median-based floor, robust to spikes
QUIET_PERIOD_FLOOR: floor only updates when the window looks calm by its own recent standard
TREND: linear trend and residual variance over the last N samples

Unbounded (exponentially weighted memory):

EWM_VARIANCE: mean and variance tracked with no fixed window depth, older samples fade rather than drop off a cliff

Usage Patterns

Learning a noise floor:

Estimate est(EstimateModel::EWM_VARIANCE);
for (auto sample : incoming_stream) {
    double floor = est.update(sample);
    double conf = est.confidence(sample - est.state().last_raw_sample);
}

Feeding Differential with cleaned values:

Estimate est(EstimateModel::EWM_VARIANCE);
Memory::HistoryBuffer<double> position_history(3);
for (auto raw_sample : incoming_stream) {
    est.update_into(raw_sample, position_history);
    double vel = Differential::velocity(position_history, dt);
    double acc = Differential::acceleration(position_history, dt);
}