estimate_period()

PeriodEstimate MayaFlux::Kinesis::estimate_period ( std::span< const double >  values, double  dt, double  min_period, double  max_period  )

inlinenoexcept

Estimate a repetition period by direct autocorrelation over a bounded lag range.

Parameters

values	Chronological span
dt	Seconds per sample
min_period	Shortest period to consider, in seconds
max_period	Longest period to consider, in seconds

Returns

The lag in the range with the highest normalized correlation, with that correlation as strength

Direct rather than FFT-backed, and bounded rather than full-lag. The caller stating the period range they care about is not a limitation to work around: a meaning about turning every few seconds is not interested in a correlation peak at forty milliseconds, and searching for one invites the estimate to lock onto sensor noise or onto a harmonic of the real period.

Correlation is normalized by the window's own variance (Estimate::variance), so strength is scale-free and comparable across channels carrying different units. A window whose variance is negligible has nothing to correlate and returns zero strength rather than a ratio of two small numbers.

Requires the window to be at least twice the longest period searched, since a lag longer than half the window correlates too few pairs to mean anything. Lags failing that are skipped rather than reported with low confidence.

Distinct from Discrete::auto_correlate, which is FFT-backed, computes every lag up to the buffer length, and allocates a full output vector each call; the right shape for characterizing a recording once, the wrong shape for a bounded search run on every channel update.

Definition at line 203 of file TemporalMeasures.hpp.

{
    const size_t n = values.size();
    if (n < 4 || dt <= 0.0 || max_period <= min_period)
        return {};
 
    double mean = 0.0;
    for (const double v : values)
        mean += v;
    mean /= static_cast<double>(n);
 
    const double denom = Stochastic::Estimate::variance(values) * static_cast<double>(n - 1);
    if (denom < 1e-12)
        return {};
 
    const auto min_lag = std::max<size_t>(1, static_cast<size_t>(min_period / dt));
    const auto max_lag = std::min(n / 2, static_cast<size_t>(max_period / dt));
    if (min_lag > max_lag)
        return {};
 
    PeriodEstimate best;
    for (size_t lag = min_lag; lag <= max_lag; ++lag) {
        double acc = 0.0;
        for (size_t i = 0; i + lag < n; ++i)
            acc += (values[i] - mean) * (values[i + lag] - mean);
 
        const double correlation = acc / denom;
        if (correlation > best.strength) {
            best.strength = correlation;
            best.period = static_cast<double>(lag) * dt;
        }
    }
 
    return best;
}

References correlation(), MayaFlux::mean(), MayaFlux::Kinesis::PeriodEstimate::period, MayaFlux::Kinesis::PeriodEstimate::strength, values, and MayaFlux::Kinesis::Stochastic::Estimate::variance().

Here is the call graph for this function: