|
| 1 | +export interface TideSample { |
| 2 | + time: string; |
| 3 | + value: number; |
| 4 | +} |
| 5 | + |
| 6 | +export interface TideExtreme { |
| 7 | + time: string; |
| 8 | + value: number; |
| 9 | + type: "H" | "L"; |
| 10 | +} |
| 11 | + |
| 12 | +export interface TideExtremaOptions { |
| 13 | + /** Minimum swing (in the samples' own units) below which a reversal is noise. */ |
| 14 | + minDelta: number; |
| 15 | + /** Extra threshold as a fraction of the series range, added via `max`. Default 0. */ |
| 16 | + relativeDelta?: number; |
| 17 | +} |
| 18 | + |
| 19 | +/** |
| 20 | + * Derive tide highs/lows from a noisy observation series using hysteresis |
| 21 | + * (a "zigzag" peak detector). A reversal is only registered once the series |
| 22 | + * has moved at least `delta = max(minDelta, range * relativeDelta)` away from |
| 23 | + * the running peak/trough. |
| 24 | + * |
| 25 | + * This replaces a naive ±N-sample local-extremum scan, which on raw gauge data |
| 26 | + * reports dozens of spurious highs/lows — and, because it compared |
| 27 | + * non-strictly, flagged flat plateaus as both a high AND a low at the same |
| 28 | + * time. The hysteresis output is noise-free and strictly alternates H/L. |
| 29 | + */ |
| 30 | +function median(values: number[]): number { |
| 31 | + const sorted = [...values].sort((a, b) => a - b); |
| 32 | + const mid = sorted.length >> 1; |
| 33 | + return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2; |
| 34 | +} |
| 35 | + |
| 36 | +/** |
| 37 | + * Drop spike/sentinel outliers from a gauge series: a sample is removed when it |
| 38 | + * deviates from the median of a centred ±`window` neighbourhood by more than |
| 39 | + * `maxDeviation` (in the samples' own units). Tide levels change slowly, so a |
| 40 | + * large jump over a few seconds is a sensor glitch (e.g. IOC's `-1.0` sentinel) |
| 41 | + * — and one such outlier wrecks both the range/threshold and the extrema. Run |
| 42 | + * this before {@link findTideExtrema} and before plotting the curve. |
| 43 | + */ |
| 44 | +export function despikeSeries( |
| 45 | + samples: TideSample[], |
| 46 | + maxDeviation: number, |
| 47 | + window = 5, |
| 48 | +): TideSample[] { |
| 49 | + if (samples.length <= window * 2) return samples; |
| 50 | + const values = samples.map((s) => s.value); |
| 51 | + const kept: TideSample[] = []; |
| 52 | + for (let i = 0; i < samples.length; i++) { |
| 53 | + const lo = Math.max(0, i - window); |
| 54 | + const hi = Math.min(values.length, i + window + 1); |
| 55 | + if (Math.abs(values[i] - median(values.slice(lo, hi))) <= maxDeviation) kept.push(samples[i]); |
| 56 | + } |
| 57 | + return kept; |
| 58 | +} |
| 59 | + |
| 60 | +export function findTideExtrema(samples: TideSample[], opts: TideExtremaOptions): TideExtreme[] { |
| 61 | + if (samples.length < 5) return []; |
| 62 | + |
| 63 | + let lo = Number.POSITIVE_INFINITY; |
| 64 | + let hi = Number.NEGATIVE_INFINITY; |
| 65 | + for (const s of samples) { |
| 66 | + if (s.value < lo) lo = s.value; |
| 67 | + if (s.value > hi) hi = s.value; |
| 68 | + } |
| 69 | + const delta = Math.max(opts.minDelta, (hi - lo) * (opts.relativeDelta ?? 0)); |
| 70 | + if (!(delta > 0)) return []; |
| 71 | + |
| 72 | + const extrema: TideExtreme[] = []; |
| 73 | + let mn = Number.POSITIVE_INFINITY; |
| 74 | + let mx = Number.NEGATIVE_INFINITY; |
| 75 | + let mnIdx = 0; |
| 76 | + let mxIdx = 0; |
| 77 | + // null until the first significant move decides whether to open on a high or low. |
| 78 | + let lookForMax: boolean | null = null; |
| 79 | + // Value of the last confirmed extreme, to gauge whether the trailing swing is real. |
| 80 | + let pivot: number | null = null; |
| 81 | + |
| 82 | + for (let i = 0; i < samples.length; i++) { |
| 83 | + const v = samples[i].value; |
| 84 | + if (v > mx) { |
| 85 | + mx = v; |
| 86 | + mxIdx = i; |
| 87 | + } |
| 88 | + if (v < mn) { |
| 89 | + mn = v; |
| 90 | + mnIdx = i; |
| 91 | + } |
| 92 | + |
| 93 | + if (lookForMax !== false && v < mx - delta) { |
| 94 | + // Skip index 0: a drop from the first sample means the window opened past |
| 95 | + // a peak — a window edge, not a real turning point. Still transition. |
| 96 | + if (mxIdx > 0) { |
| 97 | + extrema.push({ time: samples[mxIdx].time, value: samples[mxIdx].value, type: "H" }); |
| 98 | + } |
| 99 | + pivot = samples[mxIdx].value; |
| 100 | + mn = v; |
| 101 | + mnIdx = i; |
| 102 | + lookForMax = false; |
| 103 | + } else if (lookForMax !== true && v > mn + delta) { |
| 104 | + if (mnIdx > 0) { |
| 105 | + extrema.push({ time: samples[mnIdx].time, value: samples[mnIdx].value, type: "L" }); |
| 106 | + } |
| 107 | + pivot = samples[mnIdx].value; |
| 108 | + mx = v; |
| 109 | + mxIdx = i; |
| 110 | + lookForMax = true; |
| 111 | + } |
| 112 | + } |
| 113 | + |
| 114 | + // Emit the final turning point. Hysteresis only confirms an extreme once the |
| 115 | + // series reverses past `delta`, so a peak/trough sitting at the very end of |
| 116 | + // the window (e.g. a recent high near "now") would otherwise be dropped. |
| 117 | + // Require it to be an actual turn (not the last sample) and ≥ delta from the |
| 118 | + // last pivot, so a still-rising/falling tail isn't reported as an extreme. |
| 119 | + const lastIdx = samples.length - 1; |
| 120 | + if (pivot !== null) { |
| 121 | + if (lookForMax && mxIdx < lastIdx && samples[mxIdx].value - pivot >= delta) { |
| 122 | + extrema.push({ time: samples[mxIdx].time, value: samples[mxIdx].value, type: "H" }); |
| 123 | + } else if (lookForMax === false && mnIdx < lastIdx && pivot - samples[mnIdx].value >= delta) { |
| 124 | + extrema.push({ time: samples[mnIdx].time, value: samples[mnIdx].value, type: "L" }); |
| 125 | + } |
| 126 | + } |
| 127 | + |
| 128 | + return extrema; |
| 129 | +} |
0 commit comments