relation_lag()

LagRelation MayaFlux::Kinesis::relation_lag ( std::span< const double >  a, std::span< const double >  b, long  max_lag  )

inlinenoexcept

Search a bounded lag range for the offset at which two streams correlate most strongly.

Parameters

a	First span
b	Second span
max_lag	Furthest offset to test in either direction, in samples

Returns

The lag in [-max_lag, max_lag] with the highest absolute correlation, and that correlation as strength

Answers which of two streams leads and by how much, without the caller specifying the offset in advance. Searches both directions since neither stream is privileged: a positive result lag means b lags a, a negative one means a lags b.

Signed strength is kept rather than always reporting the magnitude, so a caller distinguishes streams moving together (positive) from streams moving in exact opposition at the same offset (negative); the best lag is chosen by absolute value since a strong inverse relationship is as informative as a strong direct one.

Bounded rather than full-length for the same reason estimate_period in TemporalMeasures.hpp bounds its period search: the caller stating the range of offsets that could plausibly matter keeps the search from locking onto a coincidental alignment far outside any physically meaningful lag between two related streams.

Definition at line 155 of file Relation.hpp.

{
    LagRelation best;
    for (long lag = -max_lag; lag <= max_lag; ++lag) {
        const double r = relation_at_lag(a, b, lag);
        if (std::abs(r) > std::abs(best.strength)) {
            best.strength = r;
            best.lag = lag;
        }
    }
    return best;
}

References a, b, MayaFlux::Kinesis::LagRelation::lag, relation_at_lag(), and MayaFlux::Kinesis::LagRelation::strength.

Here is the call graph for this function: