Recipe · change detection

Directional trend

A sensor signal doesn't fail in one instant. It slips — a tenth of a dB, a millivolt, a milliwatt — too little per sample to trigger a magnitude alarm, too steady across samples to read as noise. By the time the magnitude crosses threshold, the rate has already told you where the signal was going.

This recipe converts the signal into its instantaneous slope with a Savitzky-Golay derivative kernel, then thresholds the slope in both directions and requires a short persistence window. Declines and rises become visible samples before the magnitude does.


flow('directional-trend')
    .sanitize('sane', 'x', { failureReason: 'failReason' },
        { ranges: { x: { min: -10, max: 10 } } })
    .median3('clean', 'x', { median3: 'xClean' })
    .kernel('slope', 'xClean', { filtered: 'slope' }, { preset: 'trend5' })
    .threshold('fallGate', 'slope', { active: 'trendingDown' },
        { mode: 'below', threshold: -0.07 })
    .threshold('riseGate', 'slope', { active: 'trendingUp' },
        { mode: 'above', threshold: 0.07 })
    .persistenceCheck('confirmFall',
        msg => msg.trendingDown === true,
        { persistenceConfirmed: 'confirmedDown' },
        { minVotes: 2, outOfTotal: 3 })
    .persistenceCheck('confirmRise',
        msg => msg.trendingUp === true,
        { persistenceConfirmed: 'confirmedUp' },
        { minVotes: 2, outOfTotal: 3 })
    .run()

Drag the slider through the signal and watch the slope catch both the decline and the recovery while the magnitude is still moving. Toggle the data source to compare the technique on a synthetic trace and on a real WiFi RSSI stream from Velocis Systems.

Loading directional trend recipe...

What You’re Seeing

The slate line is the raw signal. In the synthetic mode it drops from 5.0 down to 1.0 over 25 samples, holds low for a short plateau, then climbs back over 15 samples. In the real-data mode, an enterprise client’s RSSI falls sharply as it roams onto a distant AP, stays poor for about 35 samples, and snaps back when it roams home.

The cyan line on the right axis is the slope from the trend kernel — the weighted local gradient of the signal. During steady operation it fluctuates around zero. It settles at a sustained negative value during declines and a sustained positive value during rises.

The orange bands mark where the slope has crossed below the cutoff — a decline in progress. The green bands mark where the slope has crossed above the cutoff — a rise in progress. These are the raw outputs of the two threshold nodes and show the full duration of each directional window.

The rose verticals are the confirmation events — where persistenceCheck has seen two of the last three trending ticks and fires its confirmed state. The small gap between the first orange (or green) band and the first rose vertical is the persistence delay — the price paid for noise rejection.

Switch the kernel between trend5, trend7, and trend11 to see the latency-smoothness tradeoff: shorter windows catch the transition earlier but react to more noise.

Where This Pattern Fits

Domain	What drifts	Why the rate matters
WiFi client	RSSI as a client moves or an AP loads	Act before quality crosses the glitch threshold
Battery-powered device	Voltage or state of charge	Rate distinguishes normal draw from fault
Server fleet	Memory consumption before OOM	Rate sets the time-to-remediation window
Fuel or fluid systems	Tank level	An unexpected rate is a leak
Process plant	Temperature before equipment failure	Rate signals bearing or insulation wear

How It Works

The kernel node applies a weighted sum over a sliding window. Loaded with the Savitzky-Golay 1st-derivative coefficients [−2, −1, 0, 1, 2] / 10 (the trend5 preset), it performs a polynomial linear regression over five points and returns the slope. The output is the local rate of change in the same units as the signal per sample.

Wider kernels trade latency for smoothness. trend5 reacts within a few samples but carries the most noise. trend11 produces a smoother slope at the cost of a later response. For the 5-minute polling cadence used in the real-data toggle, trend5 is the sweet spot.

Two threshold nodes fan out from the slope — one fires when the slope drops below −cutoff (a decline), the other when it rises above +cutoff (a rise). Each gate feeds its own persistence check. The cutoff is domain-chosen: ±0.07 /sample on the synthetic signal, ±0.5 dBm/sample on the real WiFi trace. Each persistence check requires at least two firings within a three-sample window, suppressing single-tick noise without adding much latency.

Validation on real data

On an anonymized client health export from Velocis Systems — five clients, four days at 5-minute polling — this detector caught 71% of the drops later confirmed by an extremaRank persistence check, with 84% precision and a median 20-minute lead. The slope fires on the downswing; extremaRank validates at the recovery peak. The two are complementary, not redundant. See the WiFi AP Health use case for the applied narrative.

Choosing Between This and the `trend` Node

Both expose a numeric slope, built on different models.

The trend node takes the first difference x[n] − x[n−1] and applies exponential smoothing. It emits a state label (learning / stable / rising / falling), a confidence score, the smoothed slope (rocMean), and an optional acceleration hint — one primitive, bundled outputs.

The kernel path fits a line over a fixed window (trend5 / trend7 / trend11) and returns its slope as a raw number. Threshold and persistence nodes decide what to do with it downstream.

Reach for the kernel path when the cutoff must be readable in the signal’s own units (−0.5 dBm/sample), when you need independent fall and rise booleans, or when the slope feeds downstream math. Reach for the trend node when the bundled state, confidence, or acceleration hint are what you want to consume.

The kernel path is a measurement instrument. The trend node is a prepared verdict.

References

Savitzky, A. & Golay, M.J.E. (1964). Smoothing and differentiation of data by simplified least squares procedures. Analytical Chemistry, 36(8), 1627–1639. doi:10.1021/ac60214a047
Data for the Real WiFi toggle: anonymized Cisco DNA Center client health export from Velocis Systems , used with permission. One client, 350 samples at 5-minute polling. PII removed upstream: MAC addresses, usernames, IP addresses, and location identifiers replaced with anonymized labels.

Next Steps

Gradual Drift — the complementary recipe using Page-Hinkley change-point detection. Slope answers how fast and which way; Page-Hinkley answers did it change.
Sudden Shifts — for abrupt step changes using Kalman innovation gating.
Under the Hood — how messages, state, and specs compose inside the pipeline.