diff --git a/lib/aggregate.dart b/lib/aggregate.dart index 65a803d..ad2d63d 100644 --- a/lib/aggregate.dart +++ b/lib/aggregate.dart @@ -6,12 +6,12 @@ export 'src/aggregate/checkpoint.dart'; export 'src/aggregate/laws.dart'; export 'src/aggregate/primitives.dart'; export 'src/onehz/clinical/hrv_time_aggregator.dart' hide hrvTimeOneSlice; - - +export 'src/onehz/clinical/load_trimp_aggregator.dart'; +export 'src/onehz/clinical/cosinor_aggregator.dart'; export 'src/onehz/sleep/hypnogram_aggregator.dart'; - +export 'src/onehz/sleep/circadian_np_aggregator.dart'; export 'src/onehz/clinical/prsa_aggregator.dart'; export 'src/onehz/foundations/rr_sandwich.dart'; - - - +export 'src/onehz/clinical/readiness_lnrmssd_aggregator.dart'; +export 'src/onehz/sleep/sri_aggregator.dart'; +export 'src/onehz/workout/time_in_zone_aggregator.dart'; diff --git a/lib/onehz.dart b/lib/onehz.dart index 845b7ca..973f785 100644 --- a/lib/onehz.dart +++ b/lib/onehz.dart @@ -29,7 +29,8 @@ export 'src/onehz/clinical/hrv_freq.dart'; export 'src/onehz/clinical/prsa.dart'; export 'src/onehz/clinical/nocturnal.dart'; export 'src/onehz/clinical/illness_cusum.dart'; -export 'src/onehz/clinical/readiness_lnrmssd.dart'; +export 'src/onehz/clinical/readiness_lnrmssd.dart' + hide readinessLnRmssdFromSuffix; export 'src/onehz/clinical/cosinor.dart'; export 'src/onehz/clinical/load_trimp.dart'; export 'src/onehz/clinical/stress_si.dart'; diff --git a/lib/src/onehz/clinical/cosinor.dart b/lib/src/onehz/clinical/cosinor.dart index eaa8f5b..f4a56ca 100644 --- a/lib/src/onehz/clinical/cosinor.dart +++ b/lib/src/onehz/clinical/cosinor.dart @@ -10,9 +10,11 @@ // the daytime peak — callers choose the period and supply trough-anchored // times; this engine just fits. R² is reported so a poor fit is visible. -import 'dart:math' as math; +import 'dart:typed_data'; +import '../../aggregate/aggregator.dart'; import '../types.dart'; import '../util.dart'; +import 'cosinor_aggregator.dart'; class CosinorFit { final double mesor; // rhythm-adjusted mean @@ -60,7 +62,6 @@ class CosinorFit { /// reported. const double cosinorAcrophaseAlpha = 0.05; - /// Minimum samples for a cosinor fit. The model has 3 free parameters /// (M, β, γ); with n = 4 there is a single residual degree of freedom, so R² /// is essentially an interpolation score (4 RANDOM points routinely fit at @@ -86,154 +87,17 @@ Metric cosinor( note: 'invalid cosinor period', ); } + // Runs [cosinorAggregator] over the whole series in one slice. Mismatched + // lengths cannot be a [TimedValues] batch; they are the same "too few + // points" refusal as before. if (tHours.length != y.length) { - return const Metric.absent(tier: Tier.high, - inputs_used: ['signal_timeseries'], note: 'too few points for cosinor'); - } - final state = _CosinorState(); - final w = 2 * math.pi / periodHours; - for (var i = 0; i < y.length; i++) { - state.addCentered(math.cos(w * tHours[i]), math.sin(w * tHours[i]), y[i]); - } - return _finishCosinor(state, periodHours: periodHours, minPoints: minPoints); -} - -// Nelson et al. (1979), Methods for cosinor-rhythmometry. -// Centered least squares changes rounding. Relative 1e-12 gate is a -// numerical identifiability policy, not a physiological cutoff. -class _CosinorState { - var n = 0; - var meanC = 0.0; - var meanS = 0.0; - var meanY = 0.0; - var mCC = 0.0; - var mSS = 0.0; - var mYY = 0.0; - var mCS = 0.0; - var mCY = 0.0; - var mSY = 0.0; - - void addCentered(double c, double s, double y) { - final nextN = n + 1; - final dc = c - meanC; - final ds = s - meanS; - final dy = y - meanY; - final nextMeanC = meanC + dc / nextN; - final nextMeanS = meanS + ds / nextN; - final nextMeanY = meanY + dy / nextN; - mCC += dc * (c - nextMeanC); - mSS += ds * (s - nextMeanS); - mYY += dy * (y - nextMeanY); - mCS += dc * (s - nextMeanS); - mCY += dc * (y - nextMeanY); - mSY += ds * (y - nextMeanY); - meanC = nextMeanC; - meanS = nextMeanS; - meanY = nextMeanY; - n = nextN; - } - -} - -Metric _finishCosinor( - _CosinorState state, { - required double periodHours, - required int minPoints, -}) { - const inputs = ['signal_timeseries']; - final n = state.n; - if (n < math.max(4, minPoints) || periodHours <= 0) { return const Metric.absent( tier: Tier.high, - inputs_used: inputs, + inputs_used: ['signal_timeseries'], note: 'too few points for cosinor', ); } - // A finite period or response can still overflow the design arithmetic. - // Reject invalid moments before NaN can bypass the identifiability gate. - if (![state.meanC, state.meanS, state.meanY, state.mCC, state.mSS, - state.mYY, state.mCS, state.mCY, state.mSY].every((v) => v.isFinite)) { - return const Metric.absent( - tier: Tier.high, - inputs_used: inputs, - note: 'non-finite cosinor design', - ); - } - final determinant = state.mCC * state.mSS - state.mCS * state.mCS; - // The determinant is relative to the diagonal co-moments. A design needs - // at least 1e-12 of that scale after removing its means to identify both - // cosine coefficients; below that, numerical noise decides the fit. - if (determinant <= 1e-12 * state.mCC * state.mSS) { - return const Metric.absent( - tier: Tier.high, - inputs_used: inputs, - note: 'singular cosinor design (insufficient phase coverage)', - ); - } - final beta = - (state.mCY * state.mSS - state.mSY * state.mCS) / determinant; - final gamma = - (state.mSY * state.mCC - state.mCY * state.mCS) / determinant; - final mesor = state.meanY - beta * state.meanC - gamma * state.meanS; - final amplitude = math.sqrt(beta * beta + gamma * gamma); - final acro = math.atan2(-gamma, beta); - final w = 2 * math.pi / periodHours; - var phaseHours = -acro / w; - phaseHours = phaseHours % periodHours; - if (phaseHours < 0) phaseHours += periodHours; - - final ssTot = state.mYY; - final ssRes = state.mYY - - 2 * beta * state.mCY - - 2 * gamma * state.mSY + - beta * beta * state.mCC + - gamma * gamma * state.mSS + - 2 * beta * gamma * state.mCS; - final double r2 = ssTot == 0 ? 0.0 : (1 - ssRes / ssTot).clamp(0, 1); - final double r2Adj = (1 - (1 - r2) * (n - 1) / (n - 3)).clamp(0, 1); - // Zero-amplitude F-test (Nelson 1979): the acrophase is only defined once - // the test rejects. A flat or rhythm-free series still yields some - // atan2(−γ, β) from residual noise or float rounding. - final dof = n - 3; - final double ampP; - if (ssTot <= 0) { - ampP = 1.0; - } else if (ssRes <= 0) { - ampP = 0.0; - } else { - final f = ((ssTot - ssRes) / 2) / (ssRes / dof); - ampP = _f2Survival(f, dof); - } - final phaseDefined = ampP < cosinorAcrophaseAlpha; - - return Metric( - value: CosinorFit( - mesor: mesor, - amplitude: amplitude, - acrophaseRad: phaseDefined ? acro : null, - acrophaseHours: phaseDefined ? phaseHours : null, - periodHours: periodHours, - r2: r2, - r2Adj: r2Adj, - amplitudeP: ampP, - ), - confidence: r2Adj.clamp(0.1, 0.95), - tier: Tier.high, - inputs_used: inputs, - note: phaseDefined - ? 'single-component cosinor; anchor circadian phase on the nocturnal ' - 'trough, not the daytime peak' - : 'single-component cosinor; no resolvable rhythm ' - '(zero-amplitude test not rejected), acrophase undefined', - ); -} - - -/// Upper tail of F(2, d): P(F > f) = (1 + 2f/d)^(−d/2), exact for 2 numerator -/// degrees of freedom. -double _f2Survival(double f, int d) { - if (f.isNaN) return 1.0; - if (f.isInfinite) return 0.0; - if (f <= 0) return 1.0; - return math.pow(1 + 2 * f / d, -d / 2).toDouble(); + return cosinorAggregator(periodHours: periodHours, minPoints: minPoints) + .run(TimedValues( + Float64List.fromList(tHours), Float64List.fromList(y))); } diff --git a/lib/src/onehz/clinical/cosinor_aggregator.dart b/lib/src/onehz/clinical/cosinor_aggregator.dart new file mode 100644 index 0000000..1c0bd2c --- /dev/null +++ b/lib/src/onehz/clinical/cosinor_aggregator.dart @@ -0,0 +1,365 @@ +import 'dart:math' as math; +import 'dart:typed_data'; + +import '../../aggregate/aggregator.dart'; +import '../../aggregate/json_support.dart'; +import '../types.dart'; +import 'cosinor.dart'; + +/// Sample times and values for a cosinor fit. +class TimedValues extends Batch { + TimedValues(this.tHours, this.y) : assert(tHours.length == y.length); + + factory TimedValues.fromJson(Object? json) { + final map = decodeMap(json); + final times = decodeDoubles(field(map, 'tHours')); + final values = decodeDoubles(field(map, 'y')); + if (times.length != values.length) { + throw const FormatException('TimedValues columns differ in length'); + } + return TimedValues(times, values); + } + + final Float64List tHours; + final Float64List y; + + @override + Object? toJson() => {'tHours': encodeDoubles(tHours), 'y': encodeDoubles(y)}; + + @override + int get length => y.length; + + @override + TimedValues copyRange(int start, int end) => TimedValues( + Float64List(end - start)..setRange(0, end - start, tHours, start), + Float64List(end - start)..setRange(0, end - start, y, start), + ); + + @override + TimedValues join(TimedValues other) { + final times = Float64List(length + other.length); + final values = Float64List(length + other.length); + times + ..setRange(0, length, tHours) + ..setRange(length, times.length, other.tHours); + values + ..setRange(0, length, y) + ..setRange(length, values.length, other.y); + return TimedValues(times, values); + } +} + +class _CosinorState { + var n = 0; + var meanC = 0.0; + var meanS = 0.0; + var meanY = 0.0; + var mCC = 0.0; + var mSS = 0.0; + var mYY = 0.0; + var mCS = 0.0; + var mCY = 0.0; + var mSY = 0.0; + + /// The largest |2 pi t / period| seen: the scale of the argument the cosine + /// and sine columns were evaluated at, which bounds their rounding error. + /// Once non-finite it stays so, and the design is refused as non-finite. + var maxArg = 0.0; + + void addCentered(double c, double s, double y, [double arg = 0.0]) { + final nextN = n + 1; + final dc = c - meanC; + final ds = s - meanS; + final dy = y - meanY; + final nextMeanC = meanC + dc / nextN; + final nextMeanS = meanS + ds / nextN; + final nextMeanY = meanY + dy / nextN; + mCC += dc * (c - nextMeanC); + mSS += ds * (s - nextMeanS); + mYY += dy * (y - nextMeanY); + mCS += dc * (s - nextMeanS); + mCY += dc * (y - nextMeanY); + mSY += ds * (y - nextMeanY); + meanC = nextMeanC; + meanS = nextMeanS; + meanY = nextMeanY; + maxArg = _maxAbs(maxArg, arg); + n = nextN; + } + + void mergeCentered(_CosinorState other) { + if (other.n == 0) return; + if (n == 0) { + meanC = other.meanC; + meanS = other.meanS; + meanY = other.meanY; + mCC = other.mCC; + mSS = other.mSS; + mYY = other.mYY; + mCS = other.mCS; + mCY = other.mCY; + mSY = other.mSY; + maxArg = other.maxArg; + n = other.n; + return; + } + final total = n + other.n; + final factor = n * other.n / total; + final dc = other.meanC - meanC; + final ds = other.meanS - meanS; + final dy = other.meanY - meanY; + mCC += other.mCC + dc * dc * factor; + mSS += other.mSS + ds * ds * factor; + mYY += other.mYY + dy * dy * factor; + mCS += other.mCS + dc * ds * factor; + mCY += other.mCY + dc * dy * factor; + mSY += other.mSY + ds * dy * factor; + meanC += dc * other.n / total; + meanS += ds * other.n / total; + meanY += dy * other.n / total; + maxArg = _maxAbs(maxArg, other.maxArg); + n = total; + } +} + +/// A stored argument scale is an absolute value: negative is not a state this +/// aggregator can have built (NaN and infinity are, and are refused at finish). +double _decodeMaxArg(Object? json) { + final v = decodeDouble(json); + if (v < 0) throw const FormatException('Negative cosinor argument scale'); + return v; +} + +/// max(|current|, |value|) that keeps a non-finite result: a NaN or infinite +/// argument must reach the finiteness check, not be dropped by a comparison. +double _maxAbs(double current, double value) { + final a = value.abs(); + if (!current.isFinite) return current; + if (!a.isFinite) return a; + return a > current ? a : current; +} + +/// Double machine epsilon, 2^-52. +const double _machineEps = 2.220446049250313e-16; + +class _CosinorStats + extends Aggregator<_CosinorState, TimedValues, _CosinorState> { + const _CosinorStats(this.periodHours); + + final double periodHours; + + @override + _CosinorState empty() => _CosinorState(); + + @override + _CosinorState addSlice( + _CosinorState state, TimedValues batch, int start, int end) { + if (!periodHours.isFinite || periodHours <= 0) return state; + final w = 2 * math.pi / periodHours; + for (var i = start; i < end; i++) { + final c = math.cos(w * batch.tHours[i]); + final s = math.sin(w * batch.tHours[i]); + final y = batch.y[i]; + state.addCentered(c, s, y, w * batch.tHours[i]); + } + return state; + } + + @override + _CosinorState combine(_CosinorState left, _CosinorState right) { + left.mergeCentered(right); + return left; + } + + @override + _CosinorState finish(_CosinorState state) => state; + + @override + bool get persistable => true; + + @override + Object? encodeState(_CosinorState state) => { + 'n': state.n, + 'meanC': encodeDouble(state.meanC), + 'meanS': encodeDouble(state.meanS), + 'meanY': encodeDouble(state.meanY), + 'mCC': encodeDouble(state.mCC), + 'mSS': encodeDouble(state.mSS), + 'mYY': encodeDouble(state.mYY), + 'mCS': encodeDouble(state.mCS), + 'mCY': encodeDouble(state.mCY), + 'mSY': encodeDouble(state.mSY), + 'maxArg': encodeDouble(state.maxArg), + }; + + @override + _CosinorState decodeState(Object? json) { + final map = decodeMap(json); + return _CosinorState() + ..n = decodeCount(field(map, 'n')) + ..meanC = decodeDouble(field(map, 'meanC')) + ..meanS = decodeDouble(field(map, 'meanS')) + ..meanY = decodeDouble(field(map, 'meanY')) + ..mCC = decodeDouble(field(map, 'mCC')) + ..mSS = decodeDouble(field(map, 'mSS')) + ..mYY = decodeDouble(field(map, 'mYY')) + ..mCS = decodeDouble(field(map, 'mCS')) + ..mCY = decodeDouble(field(map, 'mCY')) + ..mSY = decodeDouble(field(map, 'mSY')) + ..maxArg = _decodeMaxArg(field(map, 'maxArg')); + } +} + +// Halberg & Nelson 1979 single-component cosinor. Centered co-moments solve the +// same least-squares model. cosinor() now runs this aggregator in one slice. +// Floating-point order differs from the former batch solver; the relative +// determinant gate replaces its absolute 1e-12 pivot gate. See +// test/aggregate/cosinor_aggregator_test.dart for numerical tolerances and phase +// degeneracies. +/// Builds a mergeable single-component cosinor fit over [TimedValues]. +Aggregator<_CosinorState, TimedValues, Metric> cosinorAggregator({ + double periodHours = 24, + int minPoints = cosinorMinPoints, +}) => + _CosinorStats(periodHours).map((state) => + _finishCosinor(state, periodHours: periodHours, minPoints: minPoints)); + +Metric _finishCosinor( + _CosinorState state, { + required double periodHours, + required int minPoints, +}) { + const inputs = ['signal_timeseries']; + if (!periodHours.isFinite || periodHours <= 0) { + return const Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'invalid cosinor period', + ); + } + final n = state.n; + if (n < math.max(4, minPoints)) { + return const Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'too few points for cosinor', + ); + } + // A finite period or response can still overflow the design arithmetic. + // Reject invalid moments before NaN can bypass the identifiability gate. + // CLAIM(review-input-refusals): applies to slices, merges and restores too. + if (![ + state.meanC, + state.meanS, + state.meanY, + state.mCC, + state.mSS, + state.mYY, + state.mCS, + state.mCY, + state.mSY, + state.maxArg + ].every((v) => v.isFinite)) { + return const Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'non-finite cosinor design', + ); + } + // A column whose centered energy is only what rounding can produce carries no + // phase information. Each cosine or sine is evaluated at fl(fl(2 pi / period) + // * t): that argument has a relative error of about 1.5 eps (the rounded + // period constant and the rounded product), so an absolute error of at most + // 1.5 eps A for A = max |argument|, and the library function adds at most one + // ulp (about eps). Every computed value is within 2 eps (A + 1) of the exact + // one, so two of them differ by at most 4 eps (A + 1), and a column whose true + // values are all equal (a sine at t = 12 i with a 24 h period is exactly zero + // at every sample) has a centered sum of squares of at most n * that bound + // squared. At or under it the column is indistinguishable from constant and + // its coefficient would be read from rounding residue, not data. The bound + // follows from eps and the argument scale, not from a tuned constant, and a + // real column (variation of even 1e-9 rad) is far above it. + final noise = 4 * _machineEps * (state.maxArg + 1); + final noiseFloor = n * noise * noise; + if (state.mCC <= noiseFloor || state.mSS <= noiseFloor) { + return const Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'singular cosinor design (insufficient phase coverage)', + ); + } + final determinant = state.mCC * state.mSS - state.mCS * state.mCS; + // The determinant is relative to the diagonal co-moments. A design needs + // at least 1e-12 of that scale after removing its means to identify both + // cosine coefficients; below that, numerical noise decides the fit. + if (determinant <= 1e-12 * state.mCC * state.mSS) { + return const Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'singular cosinor design (insufficient phase coverage)', + ); + } + final beta = (state.mCY * state.mSS - state.mSY * state.mCS) / determinant; + final gamma = (state.mSY * state.mCC - state.mCY * state.mCS) / determinant; + final mesor = state.meanY - beta * state.meanC - gamma * state.meanS; + final amplitude = math.sqrt(beta * beta + gamma * gamma); + final acro = math.atan2(-gamma, beta); + final w = 2 * math.pi / periodHours; + var phaseHours = -acro / w; + phaseHours = phaseHours % periodHours; + if (phaseHours < 0) phaseHours += periodHours; + + final ssTot = state.mYY; + final ssRes = state.mYY - + 2 * beta * state.mCY - + 2 * gamma * state.mSY + + beta * beta * state.mCC + + gamma * gamma * state.mSS + + 2 * beta * gamma * state.mCS; + final double r2 = ssTot == 0 ? 0.0 : (1 - ssRes / ssTot).clamp(0, 1); + final double r2Adj = (1 - (1 - r2) * (n - 1) / (n - 3)).clamp(0, 1); + // Zero-amplitude F-test (Nelson 1979): the acrophase is only defined once + // the test rejects. A flat or rhythm-free series still yields some + // atan2(−γ, β) from residual noise or float rounding. + final dof = n - 3; + final double ampP; + if (ssTot <= 0) { + ampP = 1.0; + } else if (ssRes <= 0) { + ampP = 0.0; + } else { + final f = ((ssTot - ssRes) / 2) / (ssRes / dof); + ampP = _f2Survival(f, dof); + } + final phaseDefined = ampP < cosinorAcrophaseAlpha; + + return Metric( + value: CosinorFit( + mesor: mesor, + amplitude: amplitude, + acrophaseRad: phaseDefined ? acro : null, + acrophaseHours: phaseDefined ? phaseHours : null, + periodHours: periodHours, + r2: r2, + r2Adj: r2Adj, + amplitudeP: ampP, + ), + confidence: r2Adj.clamp(0.1, 0.95), + tier: Tier.high, + inputs_used: inputs, + note: phaseDefined + ? 'single-component cosinor; anchor circadian phase on the nocturnal ' + 'trough, not the daytime peak' + : 'single-component cosinor; no resolvable rhythm ' + '(zero-amplitude test not rejected), acrophase undefined', + ); +} + +/// Upper tail of F(2, d): P(F > f) = (1 + 2f/d)^(−d/2), exact for 2 numerator +/// degrees of freedom. +double _f2Survival(double f, int d) { + if (f.isNaN) return 1.0; + if (f.isInfinite) return 0.0; + if (f <= 0) return 1.0; + return math.pow(1 + 2 * f / d, -d / 2).toDouble(); +} diff --git a/lib/src/onehz/clinical/load_trimp.dart b/lib/src/onehz/clinical/load_trimp.dart index 53187ef..6b8b583 100644 --- a/lib/src/onehz/clinical/load_trimp.dart +++ b/lib/src/onehz/clinical/load_trimp.dart @@ -23,8 +23,11 @@ // prediction. import 'dart:math' as math; +import 'dart:typed_data'; +import '../../aggregate/aggregator.dart'; import '../types.dart'; import '../util.dart'; +import 'load_trimp_aggregator.dart'; /// Banister TRIMP over a series of per-minute mean HRs. /// @@ -45,48 +48,11 @@ Metric banisterTrimp( required double? maxHr, required Sex sex, }) { - const inputs = ['hr_per_min', 'resting_hr', 'max_hr']; - // `maxHr <= restingHr` is FALSE when either is NaN, so the finiteness checks - // are load-bearing: a NaN anchor otherwise makes a NaN reserve, and every - // clamp below (`hrr < 0`, `hrr > 1`) is false for NaN too, so the sum comes - // out NaN inside a PRESENT metric. - if (restingHr == null || - maxHr == null || - !restingHr.isFinite || - !maxHr.isFinite || - maxHr <= restingHr || - hrPerMin.isEmpty) { - return const Metric.absent( - tier: Tier.estimate, - inputs_used: inputs, - note: 'Banister TRIMP needs finite measured RHR and HRmax (HRmax>RHR)', - ); - } - final reserve = maxHr - restingHr; - // Neumaier (1974), Rundungsfehleranalyse einiger Verfahren zur Summation. - var trimp = 0.0, correction = 0.0; - for (final hr in hrPerMin) { - if (!hr.isFinite || hr <= 0) continue; // off-skin + non-finite guard - var hrr = (hr - restingHr) / reserve; - if (hrr < 0) hrr = 0; - if (hrr > 1) hrr = 1; - // ONE Banister implementation for the whole package: the sex-specific - // weighting factor y lives in [StrainScorer.banisterY]. 1 minute each. - final value = hrr * StrainScorer.banisterY(hrr, female: sex == Sex.female); - final next = trimp + value; - if (next.isFinite) { - correction += trimp.abs() >= value.abs() - ? (trimp - next) + value : (value - next) + trimp; - } - trimp = next; - } - return Metric( - value: trimp + correction, - confidence: 0.6, - tier: Tier.estimate, - inputs_used: inputs, - note: 'Banister exponential TRIMP (wrist HR estimate)', - ); + // Runs [banisterTrimpAggregator] over the whole column in one slice, so the + // batch and chunked paths share one implementation. The aggregator carries + // the finiteness guards on the anchors and the off-skin / non-finite filter. + return banisterTrimpAggregator(restingHr: restingHr, maxHr: maxHr, sex: sex) + .run(DoubleColumn(Float64List.fromList(hrPerMin))); } /// Fraction of heart-rate reserve that simply BEING AWAKE costs — THE REFERENCE @@ -853,57 +819,13 @@ Metric ctlAtlTsb(List dailyTrimp, double atlDays = 7, int minDays = ctlAtlMinDays, int primeDays = 7}) { - const inputs = ['daily_trimp']; - if (dailyTrimp.any((value) => !value.isFinite)) { - return const Metric.absent( - tier: Tier.estimate, - inputs_used: inputs, - note: 'non-finite daily TRIMP', - ); - } - if (dailyTrimp.length < minDays) { - return Metric.absent( - tier: Tier.estimate, - inputs_used: inputs, - note: needBaselineNote(have: dailyTrimp.length, need: minDays), - ); - } - final lc = 1 - math.exp(-1 / ctlDays); - final la = 1 - math.exp(-1 / atlDays); - final prime = math.min(math.max(primeDays, 1), dailyTrimp.length); - // Neumaier (1974) compensation for the bounded-prefix mean. - var sum = 0.0, correction = 0.0; - for (final value in dailyTrimp.take(prime)) { - final next = sum + value; - if (next.isFinite) { - correction += sum.abs() >= value.abs() - ? (sum - next) + value : (value - next) + sum; - } - sum = next; - } - final seed = (sum + correction) / prime; - // Banister et al. (1975) recurrence evaluated as an affine map. - // f(x) = scale*x + offset, with keep = 1-lambda. - double evaluate(double lambda) { - var scale = 1.0, offset = 0.0; - final keep = 1 - lambda; - for (var i = prime; i < dailyTrimp.length; i++) { - final value = dailyTrimp[i]; - scale *= keep; - offset = keep * offset + lambda * value; - } - return scale * seed + offset; - } - final ctl = evaluate(lc); - final atl = evaluate(la); - final conf = (dailyTrimp.length / 42.0).clamp(0.3, 0.85); - return Metric( - value: LoadState(ctl, atl, ctl - atl), - confidence: conf, - tier: Tier.estimate, - inputs_used: inputs, - note: - 'Banister CTL(42d)/ATL(7d)/TSB, primed from the first $prime observed ' - 'days; descriptive load, not injury risk', - ); + // Runs [ctlAtlTsbAggregator] over the whole series in one slice. The + // aggregator holds the abstain rule (below [minDays]), the prime mean of the + // first [primeDays] days and the EWMA over the remainder. + return ctlAtlTsbAggregator( + ctlDays: ctlDays, + atlDays: atlDays, + minDays: minDays, + primeDays: primeDays) + .run(DoubleColumn(Float64List.fromList(dailyTrimp))); } diff --git a/lib/src/onehz/clinical/load_trimp_aggregator.dart b/lib/src/onehz/clinical/load_trimp_aggregator.dart new file mode 100644 index 0000000..9c4040a --- /dev/null +++ b/lib/src/onehz/clinical/load_trimp_aggregator.dart @@ -0,0 +1,162 @@ +import 'dart:math' as math; + +import '../../aggregate/aggregator.dart'; +import '../../aggregate/json_support.dart'; +import '../../aggregate/primitives.dart'; +import '../types.dart'; +import 'load_trimp.dart'; + +const _trimpInputs = ['hr_per_min', 'resting_hr', 'max_hr']; +const _trimpNote = + 'Banister TRIMP needs finite measured RHR and HRmax (HRmax>RHR)'; + +// Morton, R. H., Fitz-Clarke, J. R., Banister, E. W. (1990). Modeling human +// performance in running. Journal of Applied Physiology 69(3):1171-1177. +// Supports HR-reserve exponential TRIMP weighting and the impulse-response +// model; the sex-specific coefficients are retained from Banister 1991. +// banisterTrimp() runs this per-minute HR- +// reserve sum in one slice. Merge order changes rounding; checked relative +// tolerance is 1e-12. Retains ESTIMATE tier and confidence 0.6. +/// Builds a mergeable Banister TRIMP summary over per-minute mean HR values. +/// +/// The resulting metric has the same missing-input and empty-input behaviour as +/// [banisterTrimp]. +Aggregator> banisterTrimpAggregator({ + required double? restingHr, + required double? maxHr, + required Sex sex, +}) { + // `maxHr <= restingHr` is FALSE when either is NaN, so the finiteness checks + // are load-bearing: a NaN anchor otherwise makes a NaN reserve, and every + // clamp below (`hrr < 0`, `hrr > 1`) is false for NaN too, so the sum comes + // out NaN inside a PRESENT metric. + final anchorsValid = restingHr != null && + maxHr != null && + restingHr.isFinite && + maxHr.isFinite && + maxHr > restingHr; + final reserve = anchorsValid ? maxHr - restingHr : 0.0; + final core = both( + Count(), + SumOf((batch) => batch.values, (hr) { + if (!anchorsValid || !hr.isFinite || hr <= 0) return double.nan; + // ONE Banister implementation for the whole package: the sex-specific + // weighting factor y lives in [StrainScorer.banisterY]. 1 minute each. + var hrr = (hr - restingHr) / reserve; + if (hrr < 0) hrr = 0.0; + if (hrr > 1) hrr = 1.0; + return hrr * StrainScorer.banisterY(hrr, female: sex == Sex.female); + }), + ); + return core.map((result) { + if (!anchorsValid || result.$1 == 0) { + return const Metric.absent( + tier: Tier.estimate, + inputs_used: _trimpInputs, + note: _trimpNote, + ); + } + return Metric( + value: result.$2, + confidence: 0.6, + tier: Tier.estimate, + inputs_used: _trimpInputs, + note: 'Banister exponential TRIMP (wrist HR estimate)', + ); + }); +} + +// Banister, E. W., Calvert, T. W., Savage, M. V., Bach, T. (1975). A systems +// model of training for athletic performance. Australian Journal of Sports +// Medicine 7:57-61. See also Morton, Fitz-Clarke & Banister 1990 above. +// CTL/ATL are a discrete EWMA fitness/fatigue adaptation, TSB = CTL - ATL; +// 42/7-day defaults and bounded-prefix priming are implementation choices. +// With a=1-lambda, f_y(f_x(c))=a*a*c+a*lambda*x+lambda*y, algebraically +// equal to two EWMA recurrence steps. +// Banister impulse-response model, now also the ctlAtlTsb() one-slice path. The +// identical bounded-prefix prime seeds affine compositions of the same EWMA +// recurrence. Composition is algebraically equal; checked absolute and relative +// tolerances are 1e-9. +/// Builds a mergeable CTL/ATL/TSB summary over a daily-TRIMP column (oldest +/// first), matching [ctlAtlTsb]. +/// +/// Both accumulators are primed with the mean of the first [primeDays] rows +/// (a bounded prefix), then each later row is one EWMA step, kept as an affine +/// map so chunks merge. With fewer rows than [primeDays] the prime is the row +/// count, as in the reference. +Aggregator> ctlAtlTsbAggregator({ + double ctlDays = 42, + double atlDays = 7, + int minDays = ctlAtlMinDays, + int primeDays = 7, +}) { + const inputs = ['daily_trimp']; + final lc = 1 - math.exp(-1 / ctlDays); + final la = 1 - math.exp(-1 / atlDays); + // CLAIM(review-input-refusals): Sum/Ewma skip NaN by design. Keep a + // separate finite-row count so unknown load survives every streaming path. + final core = both( + both(const Count(), + CountWhere((batch) => batch.values, (v) => v.isFinite)), + Prefix( + math.max(primeDays, 1), + both( + const Count(), + Sum((batch) => batch.values), + ), + both( + Ewma((batch) => batch.values, lc), + Ewma((batch) => batch.values, la), + ), + batchFromJson: DoubleColumn.fromJson, + ), + ); + final prime = math.max(primeDays, 1); + return validateCheckpoint(core, (json) { + final state = decodeList(json); + if (state.length != 2) throw const FormatException('Expected two states'); + final counts = decodeList(state[0]); + if (counts.length != 2) throw const FormatException('Expected two counts'); + final days = decodeCount(counts[0]); + if (decodeCount(counts[1]) > days) { + throw const FormatException('Finite TRIMP count exceeds day count'); + } + final rows = field(decodeMap(state[1]), 'rows'); + if (days == 0) { + if (rows != null) throw const FormatException('Prefix rows without days'); + return; + } + if (rows == null || + decodeList(rows).length != (days < prime ? days : prime)) { + throw const FormatException('Prefix rows disagree with days'); + } + }).map((result) { + final (days, finiteDays) = result.$1; + if (finiteDays != days) { + return const Metric.absent( + tier: Tier.estimate, + inputs_used: inputs, + note: 'non-finite daily TRIMP', + ); + } + if (days < minDays) { + return Metric.absent( + tier: Tier.estimate, + inputs_used: inputs, + note: needBaselineNote(have: days, need: minDays), + ); + } + final ((primed, primeSum), (ctlMap, atlMap)) = result.$2; + final seed = primeSum / primed; + final ctl = ctlMap.apply(seed); + final atl = atlMap.apply(seed); + return Metric( + value: LoadState(ctl, atl, ctl - atl), + confidence: (days / 42.0).clamp(0.3, 0.85), + tier: Tier.estimate, + inputs_used: inputs, + note: 'Banister CTL(42d)/ATL(7d)/TSB, primed from the first $primed ' + 'observed days; descriptive load, not injury risk', + ); + }); +} diff --git a/lib/src/onehz/clinical/readiness_lnrmssd.dart b/lib/src/onehz/clinical/readiness_lnrmssd.dart index 9326651..9dd858a 100644 --- a/lib/src/onehz/clinical/readiness_lnrmssd.dart +++ b/lib/src/onehz/clinical/readiness_lnrmssd.dart @@ -68,37 +68,84 @@ Metric readinessLnRmssd( int windowDays = 7, int minNights = readinessLnRmssdMinNights, }) { - const inputs = ['ln_rmssd_history']; if (historyLnRmssd.length < minNights) { - return Metric.absent( - tier: Tier.high, - inputs_used: inputs, - note: needBaselineNote(have: historyLnRmssd.length, need: minNights), - ); + return _tooShort(historyLnRmssd.length, minNights); } - final today = historyLnRmssd.last; final n = historyLnRmssd.length; final start = n - 1 - windowDays < 0 ? 0 : n - 1 - windowDays; - // this used to be historyLnRmssd.sublist(start), which runs to the END of - // the list - including tonight's own value in its own baseline. that - // pulls the mean/sd toward tonight, understating how far off a genuinely - // suppressed/elevated night actually is, worst right when the window is - // smallest (minNights). the baseline has to be strictly prior nights. - final List priorWindow; // all-or-nothing: calendarDays falls back to the row index for a label it // can't parse, and an index compared against epoch days is meaningless. if (dates != null && dates.length == n && dates.every((d) => DateTime.tryParse(d) != null)) { final day = calendarDays(dates); - priorWindow = [ - for (var i = 0; i < n - 1; i++) - if (day[i] < day[n - 1] && day[n - 1] - day[i] <= windowDays) - historyLnRmssd[i] - ]; - } else { - priorWindow = historyLnRmssd.sublist(start, n - 1); + return readinessLnRmssdFromSuffix( + n, + [ + for (var i = 0; i < n - 1; i++) + if (day[i] < day[n - 1] && day[n - 1] - day[i] <= windowDays) + historyLnRmssd[i], + historyLnRmssd.last, + ], + meanNnTodayMs: meanNnTodayMs, + windowDays: windowDays, + minNights: minNights, + ); } + if (windowDays >= 0) { + return readinessLnRmssdFromSuffix( + n, + historyLnRmssd.sublist(start, n), + meanNnTodayMs: meanNnTodayMs, + windowDays: windowDays, + minNights: minNights, + ); + } + // A negative window cannot be built as a suffix block, so it keeps the old + // path: otherwise sublist(start, n - 1) with start > n - 1 throws RangeError, + // as it always did. + final priorWindow = historyLnRmssd.sublist(start, n - 1); + return readinessLnRmssdFromSuffix( + n, + [...priorWindow, historyLnRmssd.last], + meanNnTodayMs: meanNnTodayMs, + windowDays: windowDays, + minNights: minNights, + ); +} + +const _inputs = ['ln_rmssd_history']; + +/// The absent result for a history shorter than [minNights]. +Metric _tooShort(int n, int minNights) => + Metric.absent( + tier: Tier.high, + inputs_used: _inputs, + note: needBaselineNote(have: n, need: minNights), + ); + +/// Shared by [readinessLnRmssd] and the aggregator (not public API): the +/// arithmetic after the length check, given the history length [n] and its +/// last min(windowDays + 1, n) values [suffix] (tonight last). +// Plews et al. 2013, as implemented by readinessLnRmssd(). Retains the history +// count and relevant prior-night suffix, then calls identical scoring +// arithmetic. The aggregator uses positional history; calendar-date filtering +// remains in the batch wrapper. +Metric readinessLnRmssdFromSuffix( + int n, + List suffix, { + double? meanNnTodayMs, + required int windowDays, + required int minNights, +}) { + const inputs = _inputs; + final today = suffix.last; + // this used to be historyLnRmssd.sublist(start), which runs to the END of + // the list - including tonight's own value in its own baseline. that + // pulls the mean/sd toward tonight, understating how far off a genuinely + // suppressed/elevated night actually is, worst right when the window is + // smallest (minNights). the baseline has to be strictly prior nights. + final priorWindow = suffix.sublist(0, suffix.length - 1); if (priorWindow.isEmpty || priorWindow.length < minNights - 1) { // empty only if minNights got set to 1 somewhere; short when a wear gap // left too few nights inside the calendar window. either way there's no diff --git a/lib/src/onehz/clinical/readiness_lnrmssd_aggregator.dart b/lib/src/onehz/clinical/readiness_lnrmssd_aggregator.dart new file mode 100644 index 0000000..5ad666f --- /dev/null +++ b/lib/src/onehz/clinical/readiness_lnrmssd_aggregator.dart @@ -0,0 +1,59 @@ +import '../../aggregate/aggregator.dart'; +import '../../aggregate/json_support.dart'; +import '../../aggregate/primitives.dart'; +import '../types.dart'; +import 'readiness_lnrmssd.dart'; + +// Plews et al. 2013, as implemented by readinessLnRmssd(). Retains the history +// count and relevant prior-night suffix, then calls identical scoring +// arithmetic. The aggregator uses positional history; calendar-date filtering +// remains in the batch wrapper. +/// Builds a mergeable lnRMSSD readiness summary over a nightly history column +/// (oldest first, tonight last), matching [readinessLnRmssd] exactly. +/// +/// Only the history length and the last [windowDays] + 1 nights matter, so the +/// state is a count and a bounded suffix. [windowDays] must be at least 0. +Aggregator> + readinessLnRmssdAggregator({ + double? meanNnTodayMs, + int windowDays = 7, + int minNights = readinessLnRmssdMinNights, +}) { + assert(windowDays >= 0); + const maxLastRows = 1 << 62; + final keptRows = windowDays >= maxLastRows ? maxLastRows : windowDays + 1; + final core = both( + const Count(), + LastRows(keptRows, + batchFromJson: DoubleColumn.fromJson), + ); + return validateCheckpoint(core, (json) { + final state = decodeList(json); + if (state.length != 2) throw const FormatException('Expected two states'); + final count = decodeCount(state[0]); + final rows = field(decodeMap(state[1]), 'rows'); + if (count == 0) { + if (rows != null) throw const FormatException('Rows without history'); + return; + } + if (rows == null || decodeList(rows).length != (count < keptRows ? count : keptRows)) { + throw const FormatException('History rows disagree with count'); + } + }).map((result) { + final n = result.$1; + if (n < minNights) { + return Metric.absent( + tier: Tier.high, + inputs_used: const ['ln_rmssd_history'], + note: needBaselineNote(have: n, need: minNights), + ); + } + return readinessLnRmssdFromSuffix( + n, + result.$2!.values.toList(), + meanNnTodayMs: meanNnTodayMs, + windowDays: windowDays, + minNights: minNights, + ); + }); +} diff --git a/lib/src/onehz/sleep/circadian_np.dart b/lib/src/onehz/sleep/circadian_np.dart index e37de96..ce0bfb1 100644 --- a/lib/src/onehz/sleep/circadian_np.dart +++ b/lib/src/onehz/sleep/circadian_np.dart @@ -17,9 +17,11 @@ // HONESTY: anchor circadian phase on the nocturnal trough (L5), never the // daytime peak — L5 is the trough-anchored marker the catalog requires. -import 'dart:math' as math; +import 'dart:typed_data'; +import '../../aggregate/aggregator.dart'; import '../types.dart'; import '../util.dart'; +import 'circadian_np_aggregator.dart'; class CircadianNp { final double interdailyStability; // IS @@ -60,122 +62,11 @@ Metric circadianNonparametric( int? m10Epochs, int? l5Epochs, }) { - const inputs = ['activity_or_hr_epochs']; - final n = x.length; - if (epochsPerDay <= 0 || n < epochsPerDay) { - return const Metric.absent( - tier: Tier.high, - inputs_used: inputs, - note: 'need ≥1 full day of epochs for circadian metrics', - ); - } - // M10 = 10 h, L5 = 5 h scaled to the epoch resolution. - final mEp = m10Epochs ?? (epochsPerDay * 10 ~/ 24); - final lEp = l5Epochs ?? (epochsPerDay * 5 ~/ 24); - - final grand = mean(x)!; - // Welford (1962) centered variance; Witting (1990), van Someren (1999) - // indices retain their formulas. Circular profile sums keep input order. - var ssTot = 0.0, center = 0.0, count = 0; - for (final value in x) { - count++; - if (!value.isFinite) { - // NaN is absorbing: every later update keeps ssTot NaN, so the running - // centre is not needed again and the rest of the series is not walked. - ssTot = double.nan; - break; - } - final delta = value - center; - center += delta / count; - ssTot += delta * (value - center); - } - if (ssTot == 0) { - return const Metric.absent( - tier: Tier.high, - inputs_used: inputs, - note: 'no variance in activity series', - ); - } - - // IS: between-epoch-of-day variance vs total variance. - final p = epochsPerDay; - final hourMeans = List.filled(p, 0); - final hourCounts = List.filled(p, 0); - for (var i = 0; i < n; i++) { - final h = i % p; - hourMeans[h] += x[i]; - hourCounts[h]++; - } - for (var h = 0; h < p; h++) { - if (hourCounts[h] > 0) hourMeans[h] /= hourCounts[h]; - } - var ssHour = 0.0; - for (var h = 0; h < p; h++) { - final d = hourMeans[h] - grand; - ssHour += d * d; - } - final is_ = (n * ssHour) / (p * ssTot); - - // IV: mean-squared successive difference vs variance. - var ssDiff = 0.0; - for (var i = 1; i < n; i++) { - final d = x[i] - x[i - 1]; - ssDiff += d * d; - } - final iv = (n * ssDiff) / ((n - 1) * ssTot); - - // M10 / L5: best contiguous window over the AVERAGE day profile (hourMeans), - // circularly, so a window straddling midnight is allowed. - final m10 = _bestWindow(hourMeans, mEp, maximize: true); - final l5 = _bestWindow(hourMeans, lEp, maximize: false); - final ra = (m10.value + l5.value) > 0 - ? (m10.value - l5.value) / (m10.value + l5.value) - : 0.0; - - final days = n / epochsPerDay; - final conf = (days / 7.0).clamp(0.3, 0.95); - return Metric( - value: CircadianNp( - interdailyStability: is_.clamp(0, 1), - intradailyVariability: math.max(0, iv), - m10: m10.value, - l5: l5.value, - relativeAmplitude: ra.clamp(0, 1), - m10StartEpoch: m10.start, - l5StartEpoch: l5.start, - ), - confidence: conf, - tier: Tier.high, - inputs_used: inputs, - note: 'IS/IV/RA/L5/M10 (van Someren 1999); circadian phase anchored on the ' - 'L5 nocturnal trough, not the daytime peak', - ); -} - -class _Window { - final double value; - final int start; - const _Window(this.value, this.start); -} - -/// Best (max or min) mean over a contiguous circular window of length [w]. -_Window _bestWindow(List profile, int w, {required bool maximize}) { - final p = profile.length; - if (w >= p) { - return _Window(mean(profile) ?? 0, 0); - } - double? best; - var bestStart = 0; - for (var s = 0; s < p; s++) { - var sum = 0.0; - for (var k = 0; k < w; k++) { - sum += profile[(s + k) % p]; - } - final m = sum / w; - if (best == null || (maximize ? m > best : m < best)) { - best = m; - bestStart = s; - } - } - return _Window(best ?? 0, bestStart); + // Runs [circadianNpAggregator] over the whole series in one slice. IS is the + // between-epoch-of-day variance over the total variance, IV the mean-squared + // successive difference over the variance, and M10 / L5 the best circular + // window over the average day profile (so a window may straddle midnight). + return circadianNpAggregator(epochsPerDay, + m10Epochs: m10Epochs, l5Epochs: l5Epochs) + .run(EpochSeries(Float64List.fromList(x))); } diff --git a/lib/src/onehz/sleep/circadian_np_aggregator.dart b/lib/src/onehz/sleep/circadian_np_aggregator.dart new file mode 100644 index 0000000..cd99a90 --- /dev/null +++ b/lib/src/onehz/sleep/circadian_np_aggregator.dart @@ -0,0 +1,392 @@ +import 'dart:typed_data'; + +import '../../aggregate/aggregator.dart'; +import '../../aggregate/json_support.dart'; +import '../../aggregate/primitives.dart'; +import '../types.dart'; +import 'circadian_np.dart'; +import 'circadian_window.dart'; + +/// Epoch-binned activity (or HR) values. +/// +/// [firstIndex] is the absolute index of row zero, so the epoch of day of a +/// row survives slicing and joining. +class EpochSeries extends Batch { + EpochSeries(this.x, {this.firstIndex = 0}); + + factory EpochSeries.fromJson(Object? json) { + final map = decodeMap(json); + return EpochSeries(decodeDoubles(field(map, 'x')), + firstIndex: decodeCount(field(map, 'firstIndex'))); + } + + final Float64List x; + final int firstIndex; + + @override + Object? toJson() => {'x': encodeDoubles(x), 'firstIndex': firstIndex}; + + @override + int get length => x.length; + + @override + EpochSeries copyRange(int start, int end) => EpochSeries( + Float64List(end - start)..setRange(0, end - start, x, start), + firstIndex: firstIndex + start); + + @override + EpochSeries join(EpochSeries other) { + assert(other.firstIndex == firstIndex + length); + return EpochSeries( + Float64List(length + other.length) + ..setRange(0, length, x) + ..setRange(length, length + other.length, other.x), + firstIndex: firstIndex); + } +} + +/// Sum of squared successive differences. Run under `Lookback(2)`, which +/// feeds the pair across each chunk seam. +class _SquaredDiffs extends Aggregator { + const _SquaredDiffs(); + @override + double empty() => 0.0; + @override + double addSlice(double state, EpochSeries batch, int start, int end) { + for (var i = start + 1; i < end; i++) { + final d = batch.x[i] - batch.x[i - 1]; + state += d * d; + } + return state; + } + + @override + double combine(double left, double right) => left + right; + @override + double finish(double state) => state; + @override + bool get persistable => true; + @override + Object? encodeState(double state) => encodeDouble(state); + @override + double decodeState(Object? json) => decodeDouble(json); +} + +/// A direct, non-skipping sum. Circadian's reference calculation deliberately +/// lets NaN and infinities propagate through every sum they touch. +class _RawSum extends Aggregator { + const _RawSum(this.column); + + final Float64List Function(EpochSeries batch) column; + + @override + double empty() => 0.0; + + @override + double addSlice(double state, EpochSeries batch, int start, int end) { + final values = column(batch); + for (var i = start; i < end; i++) { + state += values[i]; + } + return state; + } + + @override + double combine(double left, double right) => left + right; + + @override + double finish(double state) => state; + + @override + bool get persistable => true; + + // This retains the Sum checkpoint shape, so pre-existing finite checkpoints + // remain readable. + @override + Object? encodeState(double state) => + {'sum': encodeDouble(state), 'correction': 0.0}; + + @override + double decodeState(Object? json) { + final map = decodeMap(json); + return decodeDouble(field(map, 'sum')) + + decodeDouble(field(map, 'correction')); + } +} + +class _CircadianStats { + int count = 0; + double sum = 0.0; + double mean = 0.0; + double m2 = 0.0; +} + +/// Raw total plus mergeable centred squares for circadian variance. +/// +/// The raw total reproduces the reference grand mean. Centred squares retain +/// the finite-input stability of the former Moments block, while an individual +/// non-finite row immediately poisons them just as the reference's second +/// pass does. +class _CircadianStatsAggregator + extends Aggregator<_CircadianStats, EpochSeries, _CircadianStats> { + const _CircadianStatsAggregator(this.column); + + final Float64List Function(EpochSeries batch) column; + + @override + _CircadianStats empty() => _CircadianStats(); + + @override + _CircadianStats addSlice( + _CircadianStats state, EpochSeries batch, int start, int end) { + final values = column(batch); + for (var i = start; i < end; i++) { + final value = values[i]; + state.sum += value; + state.count++; + // Match the batch centered-variance pass: NaN is absorbing. Counts and + // the raw sum still need every row for the other circadian indices. + if (state.m2.isNaN) continue; + if (!value.isFinite) { + state.m2 = double.nan; + continue; + } + final delta = value - state.mean; + state.mean += delta / state.count; + state.m2 += delta * (value - state.mean); + } + return state; + } + + @override + _CircadianStats combine(_CircadianStats left, _CircadianStats right) { + if (right.count == 0) return left; + if (left.count == 0) { + left + ..count = right.count + ..sum = right.sum + ..mean = right.mean + ..m2 = right.m2; + return left; + } + final leftCount = left.count; + final count = leftCount + right.count; + final delta = right.mean - left.mean; + left + ..sum += right.sum + ..mean += delta * right.count / count + // The pair weight leftCount * right.count / count comes first: scaling + // delta * delta by the two counts before dividing by their sum can pass + // the double range (1e306 * 51 * 50) when the combined value, with the + // division applied, is finite (about 2.5e307). + ..m2 += right.m2 + delta * delta * (leftCount * right.count / count) + ..count = count; + return left; + } + + @override + _CircadianStats finish(_CircadianStats state) => state; + + @override + bool get persistable => true; + + @override + Object? encodeState(_CircadianStats state) => { + 'version': 1, + 'type': 'CircadianStats', + 'count': state.count, + 'sum': encodeDouble(state.sum), + 'mean': encodeDouble(state.mean), + 'm2': encodeDouble(state.m2), + }; + + @override + _CircadianStats decodeState(Object? json) { + final map = decodeMap(json); + final type = field(map, 'type'); + if (field(map, 'version') != 1 || type is! String) { + throw const FormatException('Unsupported circadian statistics checkpoint'); + } + final result = _CircadianStats()..count = decodeCount(field(map, 'count')); + if (type == 'CircadianStats') { + result + ..sum = decodeDouble(field(map, 'sum')) + ..mean = decodeDouble(field(map, 'mean')) + ..m2 = decodeDouble(field(map, 'm2')); + if ((result.m2.isFinite && result.m2 < 0) || + (result.count == 0 && + (result.sum != 0 || result.mean != 0 || result.m2 != 0))) { + throw const FormatException('Invalid circadian statistics'); + } + return result; + } + if (type != 'RunningMoments') { + throw const FormatException('Unsupported circadian statistics checkpoint'); + } + // Older checkpoints used RunningMoments. Their finite mean is sufficient + // to resume, even though it did not preserve the reference's raw sum. + final origin = decodeDouble(field(map, 'origin')); + final meanOffset = decodeDouble(field(map, 'meanOffset')); + result + ..mean = origin + meanOffset + ..sum = result.mean * result.count + ..m2 = decodeDouble(field(map, 'm2')); + if (!origin.isFinite || + !meanOffset.isFinite || + (result.m2.isFinite && result.m2 < 0) || + (result.count == 0 && + (origin != 0 || meanOffset != 0 || result.m2 != 0))) { + throw const FormatException('Invalid circadian statistics'); + } + return result; + } +} + +/// Mergeable nonparametric circadian metrics, matching +/// [circadianNonparametric]. +// Witting 1990 / van Someren 1999 nonparametric circadian indices, now also the +// circadianNonparametric() one-slice path. Phase sums/counts, centered variance +// and successive squared differences reproduce the formulas. Checked relative +// tolerances are 1e-12 for integer fixtures and 1e-9 for real fixtures; real- +// valued near-ties can select different L5/M10 start epochs. +Aggregator> circadianNpAggregator( + int epochsPerDay, { + int? m10Epochs, + int? l5Epochs, +}) { + const inputs = ['activity_or_hr_epochs']; + const tooShort = Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'need ≥1 full day of epochs for circadian metrics', + ); + if (epochsPerDay <= 0) { + return Count().map((_) => tooShort); + } + final p = epochsPerDay; + final mEp = m10Epochs ?? (p * 10 ~/ 24); + final lEp = l5Epochs ?? (p * 5 ~/ 24); + Float64List column(EpochSeries b) => b.x; + final core = both( + both(Count(), _CircadianStatsAggregator(column)), + both( + GroupBy( + (EpochSeries batch, int row) => (batch.firstIndex + row) % p, + both(Count(), _RawSum(column)), + ), + Lookback(2, const _SquaredDiffs(), + batchFromJson: EpochSeries.fromJson), + ), + ); + return validateCheckpoint(core, (json) { + final state = decodeList(json); + if (state.length != 2) throw const FormatException('Expected two states'); + final totals = decodeList(state[0]); + final grouped = decodeList(state[1]); + if (totals.length != 2 || grouped.length != 2) { + throw const FormatException('Unexpected circadian checkpoint state'); + } + final count = decodeCount(totals[0]); + final statistics = decodeMap(totals[1]); + if (decodeCount(field(statistics, 'count')) != count) { + throw const FormatException('Circadian statistics disagree with total'); + } + final groups = decodeMap(grouped[0]); + final lookback = decodeMap(grouped[1]); + if (decodeCount(field(lookback, 'length')) != count) { + throw const FormatException('Lookback length disagrees with epoch count'); + } + final first = field(lookback, 'first'); + if (count == 0) { + if (first != null || groups.isNotEmpty) { + throw const FormatException('Circadian groups without epochs'); + } + return; + } + if (first == null) throw const FormatException('Missing first circadian epoch'); + final firstEpoch = EpochSeries.fromJson(first); + if (firstEpoch.length != 1) { + throw const FormatException('Expected one first circadian epoch'); + } + // The last edge row sits at an absolute index the epoch count fixes. A + // wrong one decodes (the lookback checks only the length) and then fails + // when the next batch is joined to it, so it is refused here. + final lastRaw = field(lookback, 'last'); + if (lastRaw == null) throw const FormatException('Missing last circadian epoch'); + final lastEpoch = EpochSeries.fromJson(lastRaw); + if (lastEpoch.length != 1 || + lastEpoch.firstIndex != firstEpoch.firstIndex + count - 1) { + throw const FormatException('Last circadian epoch is out of position'); + } + final start = firstEpoch.firstIndex % p; + final expectedGroups = count < p ? count : p; + if (groups.length != expectedGroups) { + throw const FormatException('Unexpected epoch-of-day groups'); + } + final fullDays = count ~/ p; + final remainder = count % p; + var groupTotal = 0; + for (final entry in groups.entries) { + final bin = int.tryParse(entry.key); + if (bin == null || bin < 0 || bin >= p) { + throw const FormatException('Epoch-of-day group is outside the record'); + } + final offset = (bin - start + p) % p; + final expected = fullDays + (offset < remainder ? 1 : 0); + final groupState = decodeList(entry.value); + if (groupState.length != 2 || + decodeCount(groupState[0]) != expected || + expected == 0 || + groupTotal > count - expected) { + throw const FormatException('Epoch-of-day group count disagrees'); + } + groupTotal += expected; + } + if (groupTotal != count) { + throw const FormatException('Epoch-of-day groups disagree with total'); + } + }).map((result) { + final ((n, stats), (byEpoch, ssDiff)) = result; + if (n < p) return tooShort; + final grand = stats.sum / n; + final ssTot = stats.m2; + if (ssTot == 0) { + return const Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'no variance in activity series', + ); + } + final profile = List.filled(p, 0); + var ssHour = 0.0; + for (var h = 0; h < p; h++) { + final (count, sum) = byEpoch[h]!; + profile[h] = sum / count; + final d = profile[h] - grand; + ssHour += d * d; + } + final is_ = (n * ssHour) / (p * ssTot); + final iv = (n * ssDiff) / ((n - 1) * ssTot); + final m10 = bestCircularWindow(profile, mEp, maximize: true); + final l5 = bestCircularWindow(profile, lEp, maximize: false); + final ra = (m10.value + l5.value) > 0 + ? (m10.value - l5.value) / (m10.value + l5.value) + : 0.0; + return Metric( + value: CircadianNp( + interdailyStability: is_.clamp(0, 1), + intradailyVariability: iv < 0 ? 0 : iv, + m10: m10.value, + l5: l5.value, + relativeAmplitude: ra.clamp(0, 1), + m10StartEpoch: m10.start, + l5StartEpoch: l5.start, + ), + confidence: (n / p / 7.0).clamp(0.3, 0.95), + tier: Tier.high, + inputs_used: inputs, + note: 'IS/IV/RA/L5/M10 (van Someren 1999); circadian phase anchored on ' + 'the L5 nocturnal trough, not the daytime peak', + ); + }); +} diff --git a/lib/src/onehz/sleep/circadian_window.dart b/lib/src/onehz/sleep/circadian_window.dart new file mode 100644 index 0000000..221d59d --- /dev/null +++ b/lib/src/onehz/sleep/circadian_window.dart @@ -0,0 +1,34 @@ +import '../util.dart'; + +/// Mean and start epoch of a circular profile window. +class CircularWindow { + final double value; + final int start; + const CircularWindow(this.value, this.start); +} + +/// Best (max or min) mean over a contiguous circular window of length [w]. +// Unchanged extraction of circadianNonparametric() circular L5/M10 search, +// Witting 1990 / van Someren 1999. Traversal, arithmetic and first-winner tie +// handling are unchanged. +CircularWindow bestCircularWindow(List profile, int w, + {required bool maximize}) { + final p = profile.length; + if (w >= p) { + return CircularWindow(mean(profile) ?? 0, 0); + } + double? best; + var bestStart = 0; + for (var s = 0; s < p; s++) { + var sum = 0.0; + for (var k = 0; k < w; k++) { + sum += profile[(s + k) % p]; + } + final m = sum / w; + if (best == null || (maximize ? m > best : m < best)) { + best = m; + bestStart = s; + } + } + return CircularWindow(best ?? 0, bestStart); +} diff --git a/lib/src/onehz/sleep/sri.dart b/lib/src/onehz/sleep/sri.dart index a59c90d..3fccf17 100644 --- a/lib/src/onehz/sleep/sri.dart +++ b/lib/src/onehz/sleep/sri.dart @@ -16,8 +16,12 @@ // fixed number of epochs per day (e.g. 1440 one-minute epochs, or 86400 one- // second epochs). The vector spans ≥2 days. +import 'dart:typed_data'; + +import '../../aggregate/aggregator.dart'; import '../types.dart'; import '../util.dart'; +import 'sri_aggregator.dart'; /// One adjacent-day comparison, broken out of the total. /// @@ -112,6 +116,57 @@ Metric phillipsSri( ); } + final completeDaySpan = days * epochsPerDay; + // The former direct loop reads a short mask only while its entries are true. + // Preserve that historical short-circuit behaviour, including its RangeError. + if (valid != null && valid.length < completeDaySpan) { + return _legacyPhillipsSri( + sleepWake, + epochsPerDay, + valid: valid, + minPairCases: minPairCases, + ); + } + + return sriAggregator(epochsPerDay, minPairCases: minPairCases).run(Epochs( + Uint8List.fromList([ + for (var i = 0; i < completeDaySpan; i++) + sleepWake[i] ? 1 : 0, + ]), + valid: valid == null + ? null + : Uint8List.fromList([ + for (var i = 0; i < completeDaySpan; i++) + valid[i] ? 1 : 0, + ]), + )); +} + +/// The direct-loop implementation retained for malformed, short validity masks. +Metric _legacyPhillipsSri( + List sleepWake, + int epochsPerDay, { + List? valid, + int? minPairCases, +}) { + const inputs = ['sleep_wake_epochs']; + final n = sleepWake.length; + if (epochsPerDay <= 0 || n < 2 * epochsPerDay) { + return const Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'need ≥2 full days of clock-aligned sleep/wake epochs for SRI', + ); + } + final days = n ~/ epochsPerDay; + if (days < 2) { + return const Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'need ≥2 full days for SRI', + ); + } + final pairFloor = minPairCases ?? (epochsPerDay ~/ 2); var agreement = 0; var cases = 0; @@ -129,8 +184,6 @@ Metric phillipsSri( } agreement += pairAgreement; cases += pairCases; - // `> 0` is not redundant with the floor: a caller may pass - // `minPairCases: 0`, and a zero-case pair would make SriPair.sri NaN. if (pairCases > 0 && pairCases >= pairFloor) { pairs.add(SriPair(d, pairAgreement, pairCases)); } diff --git a/lib/src/onehz/sleep/sri_aggregator.dart b/lib/src/onehz/sleep/sri_aggregator.dart new file mode 100644 index 0000000..107da07 --- /dev/null +++ b/lib/src/onehz/sleep/sri_aggregator.dart @@ -0,0 +1,341 @@ +import 'dart:typed_data'; + +import '../../aggregate/aggregator.dart'; +import '../../aggregate/json_support.dart'; +import '../../aggregate/primitives.dart'; +import '../types.dart'; +import 'sri.dart'; + +/// Clock-aligned sleep/wake epochs, optionally accompanied by a validity mask. +/// +/// [firstIndex] is the absolute index of row zero. It lets [Lookback] preserve +/// the day a comparison belongs to when it joins copied chunks at a seam. +class Epochs extends Batch { + Epochs(this.asleep, {this.valid, this.firstIndex = 0}); + + factory Epochs.fromJson(Object? json) { + final map = decodeMap(json); + final asleep = _readBytes(field(map, 'asleep')); + final rawValid = field(map, 'valid'); + final valid = rawValid == null ? null : _readBytes(rawValid); + if (valid != null && valid.length != asleep.length) { + throw const FormatException('Epochs columns differ in length'); + } + return Epochs(asleep, + valid: valid, firstIndex: decodeCount(field(map, 'firstIndex'))); + } + + final Uint8List asleep; + final Uint8List? valid; + final int firstIndex; + + @override + Object? toJson() => { + 'asleep': asleep.toList(), + 'valid': valid?.toList(), + 'firstIndex': firstIndex, + }; + + @override + int get length => asleep.length; + + @override + Epochs copyRange(int start, int end) { + final copiedLength = end - start; + final copiedAsleep = Uint8List(copiedLength) + ..setRange(0, copiedLength, asleep, start); + final sourceValid = valid; + final copiedValid = sourceValid == null + ? null + : (Uint8List(copiedLength) + ..setRange(0, copiedLength, sourceValid, start)); + return Epochs(copiedAsleep, + valid: copiedValid, firstIndex: firstIndex + start); + } + + @override + Epochs join(Epochs other) { + assert(other.firstIndex == firstIndex + length); + final joinedAsleep = Uint8List(length + other.length) + ..setRange(0, length, asleep) + ..setRange(length, length + other.length, other.asleep); + Uint8List? joinedValid; + if (valid != null || other.valid != null) { + joinedValid = Uint8List(length + other.length); + for (var i = 0; i < length; i++) { + joinedValid[i] = valid == null ? 1 : valid![i]; + } + for (var i = 0; i < other.length; i++) { + joinedValid[length + i] = other.valid == null ? 1 : other.valid![i]; + } + } + return Epochs(joinedAsleep, valid: joinedValid, firstIndex: firstIndex); + } +} + +Uint8List _readBytes(Object? json) { + final list = decodeList(json); + final bytes = Uint8List(list.length); + for (var i = 0; i < list.length; i++) { + final value = list[i]; + if (value is! int || value < 0 || value > 255) { + throw const FormatException('Expected a byte'); + } + bytes[i] = value; + } + return bytes; +} + +class _PairCounts { + var agreement = 0; + var cases = 0; +} + +class _PairCountsAggregator + extends Aggregator<_PairCounts, Epochs, _PairCounts> { + const _PairCountsAggregator(this.epochsPerDay); + + final int epochsPerDay; + + @override + _PairCounts empty() => _PairCounts(); + + @override + _PairCounts addSlice(_PairCounts state, Epochs batch, int start, int end) { + final valid = batch.valid; + for (var i = start; i < end; i++) { + final previous = i - epochsPerDay; + if (valid == null || (valid[previous] != 0 && valid[i] != 0)) { + state.cases++; + if (batch.asleep[previous] == batch.asleep[i]) state.agreement++; + } + } + return state; + } + + @override + _PairCounts combine(_PairCounts left, _PairCounts right) { + left + ..agreement += right.agreement + ..cases += right.cases; + return left; + } + + @override + bool get persistable => true; + + @override + Object? encodeState(_PairCounts state) => + {'agreement': state.agreement, 'cases': state.cases}; + + @override + _PairCounts decodeState(Object? json) { + final map = decodeMap(json); + final agreement = decodeCount(field(map, 'agreement')); + final cases = decodeCount(field(map, 'cases')); + if (agreement > cases) { + throw const FormatException('agreement exceeds cases'); + } + return _PairCounts() + ..agreement = agreement + ..cases = cases; + } + + @override + _PairCounts finish(_PairCounts state) => state; +} + +/// Applies [GroupBy] only to windows that [Lookback] says are complete. +/// +/// A Lookback inner sees a length-k window ending at `start + k - 1` through +/// `end - 1`. GroupBy would otherwise reset that origin for each day run, so +/// this small adapter advances to the first complete window before grouping. +class _GroupedPairWindows + extends Aggregator, Epochs, Map> { + _GroupedPairWindows(this.epochsPerDay) + : _groups = GroupBy( + (batch, row) => (batch.firstIndex + row) ~/ epochsPerDay, + _PairCountsAggregator(epochsPerDay), + ); + + final int epochsPerDay; + final GroupBy _groups; + + @override + Map empty() => _groups.empty(); + + @override + Map addSlice( + Map state, Epochs batch, int start, int end) { + final firstWindowEnd = start + epochsPerDay; + if (firstWindowEnd < end) { + return _groups.addSlice(state, batch, firstWindowEnd, end); + } + return state; + } + + @override + Map combine( + Map left, Map right) => + _groups.combine(left, right); + + @override + Map finish(Map state) => + _groups.finish(state); + + @override + bool get persistable => _groups.persistable; + + @override + Object? encodeState(Map state) => + _groups.encodeState(state); + + @override + Map decodeState(Object? json) => + _groups.decodeState(json); +} + +/// Mergeable Phillips SRI over [Epochs]. +/// +/// The complete record must start at [Epochs.firstIndex] zero. Nonzero indices +/// are for contiguous chunks of that record; combine them in order with the +/// zero-origin prefix before finishing. To evaluate a separate record, reindex +/// it from zero rather than finishing a nonzero-origin chunk on its own. +/// +/// The Lookback window has one row from each of two adjacent clock days. Its +/// last row determines the later-day key used by GroupBy. +// Phillips et al. 2017 SRI, as in phillipsSri(). Lookback pairs epochs exactly +// one day apart; integer agreement/case counts preserve the formula, validity +// mask, pair eligibility and complete-day truncation. +Aggregator> sriAggregator( + int epochsPerDay, { + int? minPairCases, +}) { + if (epochsPerDay <= 0) { + return Count().map((_) => const Metric.absent( + tier: Tier.high, + inputs_used: ['sleep_wake_epochs'], + note: 'need ≥2 full days of clock-aligned sleep/wake epochs for SRI', + )); + } + final pairs = Lookback, Map>( + epochsPerDay + 1, + _GroupedPairWindows(epochsPerDay), + batchFromJson: Epochs.fromJson, + ); + final core = both(Count(), pairs); + return validateCheckpoint(core, (json) { + final state = decodeList(json); + if (state.length != 2) throw const FormatException('Expected two states'); + final count = decodeCount(state[0]); + final lookback = decodeMap(state[1]); + if (decodeCount(field(lookback, 'length')) != count) { + throw const FormatException('Lookback length disagrees with epoch count'); + } + final groups = decodeMap(field(lookback, 'inner')); + if (count > 0) { + // The last edge's absolute index is fixed by the first and the count. A + // wrong one decodes and then breaks the join with the next batch (or, + // without assertions, compares against the wrong day). + final firstEdge = decodeMap(field(lookback, 'first')); + final lastEdge = decodeMap(field(lookback, 'last')); + final firstAt = decodeCount(field(firstEdge, 'firstIndex')); + final lastAt = decodeCount(field(lastEdge, 'firstIndex')); + final lastLen = Epochs.fromJson(lastEdge).length; + if (lastLen < 1 || lastAt != firstAt + count - lastLen) { + throw const FormatException('Last SRI epoch is out of position'); + } + } + if (count <= epochsPerDay) { + if (groups.isNotEmpty) { + throw const FormatException('Pair days without complete comparisons'); + } + return; + } + final first = decodeMap(field(lookback, 'first')); + final firstIndex = decodeCount(field(first, 'firstIndex')); + final firstDay = (firstIndex + epochsPerDay) ~/ epochsPerDay; + final lastDay = (firstIndex + count - 1) ~/ epochsPerDay; + if (groups.length != lastDay - firstDay + 1) { + throw const FormatException('Unexpected number of pair days'); + } + var totalCases = 0; + final pairLimit = count - epochsPerDay; + for (final entry in groups.entries) { + final day = int.tryParse(entry.key); + if (day == null || day < firstDay || day > lastDay) { + throw const FormatException('Pair day is outside the record'); + } + final pair = decodeMap(entry.value); + final cases = decodeCount(field(pair, 'cases')); + final dayStart = day * epochsPerDay - firstIndex; + final dayEnd = dayStart + epochsPerDay; + final lower = dayStart > epochsPerDay ? dayStart : epochsPerDay; + final upper = dayEnd < count ? dayEnd : count; + final slots = upper > lower ? upper - lower : 0; + if (cases > slots || totalCases > pairLimit - cases) { + throw const FormatException('Pair cases exceed available epochs'); + } + totalCases += cases; + } + }).map((result) { + const inputs = ['sleep_wake_epochs']; + final n = result.$1; + if (n < 2 * epochsPerDay) { + return const Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'need ≥2 full days of clock-aligned sleep/wake epochs for SRI', + ); + } + final days = n ~/ epochsPerDay; + if (days < 2) { + return const Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'need ≥2 full days for SRI', + ); + } + + final pairFloor = minPairCases ?? (epochsPerDay ~/ 2); + var agreement = 0; + var cases = 0; + final sriPairs = []; + for (var day = 1; day < days; day++) { + final pair = result.$2[day]; + if (pair == null) continue; + agreement += pair.agreement; + cases += pair.cases; + if (pair.cases > 0 && pair.cases >= pairFloor) { + sriPairs.add(SriPair(day, pair.agreement, pair.cases)); + } + } + if (cases == 0) { + return const Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'no valid epoch pairs for SRI', + ); + } + + if (sriPairs.isEmpty) { + return Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'no adjacent-day pair has ≥$pairFloor epochs observed on both ' + 'days (have=$cases epochs in total)', + ); + } + + final sri = 200.0 * agreement / cases - 100.0; + final confidence = (sriPairs.length / 7.0).clamp(0.3, 0.95); + return Metric( + value: SriResult(sri, days, cases, sriPairs), + confidence: confidence, + tier: Tier.high, + inputs_used: inputs, + note: 'epoch-by-epoch 24-h concordance (Phillips 2017), ' + 'SRI=200·agreement/cases−100; NOT SD-of-midsleep', + ); + }); +} diff --git a/lib/src/onehz/workout/hr_zones.dart b/lib/src/onehz/workout/hr_zones.dart index d2efec6..b063160 100644 --- a/lib/src/onehz/workout/hr_zones.dart +++ b/lib/src/onehz/workout/hr_zones.dart @@ -1,7 +1,9 @@ -import 'dart:math' as math; +import 'dart:typed_data'; +import '../../aggregate/aggregator.dart'; import '../types.dart'; import '../util.dart'; +import 'time_in_zone_aggregator.dart'; /// One display heart-rate zone defined by a bpm interval. class HeartRateZone { @@ -166,6 +168,9 @@ class HeartRateZones { return HeartRateZoneSet(zones: built, maxHr: maxHr, source: source); } + // Cadence validation, median-capped interval credit and tail credit are an + // internal rule, ESTIMATE with low confidence. Karvonen 1957 supports the + // HR-reserve zone option, not this duration-credit policy. /// Time-in-zone from a time-ordered HR stream. /// /// Each sample is credited with the duration until the next sample. The tail @@ -181,30 +186,25 @@ class HeartRateZones { List hr, HeartRateZoneSet zoneSet, ) { - final sorted = [...hr]..sort((a, b) => a.tsMs.compareTo(b.tsMs)); - // Karvonen (1957) supports reserve zones only. Duration credit is an - // internal ESTIMATE rule. Count equal gaps before summing their credit. - final cadence = sampleCadenceSeconds([for (final s in sorted) s.tsMs / 1000.0]); - if (cadence == null) return null; - final credits = List.generate(6, (_) => {}); - for (var i = 1; i < sorted.length; i++) { - final previous = sorted[i - 1]; - if (!previous.valid) continue; - final gap = (sorted[i].tsMs - previous.tsMs) / 1000.0; - final histogram = credits[zoneSet.zoneNumber(previous.hr)]; - histogram[gap] = (histogram[gap] ?? 0) + 1; - } - final seconds = List.filled(6, 0); - for (var zone = 0; zone < credits.length; zone++) { - for (final entry in credits[zone].entries) { - final gap = entry.key; - seconds[zone] += entry.value * (gap > 0 ? math.min(gap, cadence) : cadence); - } - } - if (sorted.isNotEmpty && sorted.last.valid) { - seconds[zoneSet.zoneNumber(sorted.last.hr)] += cadence; - } - return TimeInHeartRateZone(seconds: seconds.sublist(1), belowZone1: seconds[0]); + // A timestamp that is not a finite number has no place on the clock, so + // there is no time-in-zone to report (the aggregator refuses such a slice). + if (hr.any((s) => !s.tsMs.isFinite)) return null; + // Runs [timeInZoneAggregator] over the sorted stream in one slice: the + // aggregator holds the cadence rule, the credit bounding and the tail. + // Ordered by (timestamp, input position). Dart's List.sort is not stable + // above a few dozen elements, so equal timestamps could reorder, and the + // order decides which reading is credited for a repeated instant. The + // aggregator credits rows in the order it is given, so this puts both on the + // same deterministic one. + final order = List.generate(hr.length, (i) => i) + ..sort((a, b) { + final c = hr[a].tsMs.compareTo(hr[b].tsMs); + return c != 0 ? c : a.compareTo(b); + }); + final sorted = [for (final i in order) hr[i]]; + return timeInZoneAggregator(zoneSet).run(HrStream( + Float64List.fromList([for (final s in sorted) s.tsMs]), + Float64List.fromList([for (final s in sorted) s.hr]), + )); } - } diff --git a/lib/src/onehz/workout/time_in_zone_aggregator.dart b/lib/src/onehz/workout/time_in_zone_aggregator.dart new file mode 100644 index 0000000..6630e29 --- /dev/null +++ b/lib/src/onehz/workout/time_in_zone_aggregator.dart @@ -0,0 +1,437 @@ +import 'dart:math' as math; +import 'dart:typed_data'; + +import '../../aggregate/aggregator.dart'; +import '../../aggregate/json_support.dart'; +import '../../aggregate/primitives.dart'; +import '../util.dart'; +import 'hr_zones.dart'; + +/// Time-ordered heart-rate samples held in timestamp and heart-rate columns. +class HrStream extends Batch { + HrStream(this.tsMs, this.hr) : assert(tsMs.length == hr.length); + + factory HrStream.fromJson(Object? json) { + final map = decodeMap(json); + final timestamps = decodeDoubles(field(map, 'tsMs')); + final heartRates = decodeDoubles(field(map, 'hr')); + if (timestamps.length != heartRates.length) { + throw const FormatException('HrStream columns differ in length'); + } + return HrStream(timestamps, heartRates); + } + + final Float64List tsMs; + final Float64List hr; + + @override + Object? toJson() => + {'tsMs': encodeDoubles(tsMs), 'hr': encodeDoubles(hr)}; + + @override + int get length => tsMs.length; + + @override + HrStream copyRange(int start, int end) => HrStream( + Float64List(end - start)..setRange(0, end - start, tsMs, start), + Float64List(end - start)..setRange(0, end - start, hr, start), + ); + + @override + HrStream join(HrStream other) { + final timestamps = Float64List(length + other.length); + final heartRates = Float64List(length + other.length); + timestamps + ..setRange(0, length, tsMs) + ..setRange(length, timestamps.length, other.tsMs); + heartRates + ..setRange(0, length, hr) + ..setRange(length, heartRates.length, other.hr); + return HrStream(timestamps, heartRates); + } +} + +/// Builds a mergeable time-in-heart-rate-zone summary over [HrStream]. +/// +/// It has the same cadence validation and duration crediting as +/// [HeartRateZones.timeInZone]. The exact gap histograms let it defer the +/// global cadence median until [Aggregator.finish]. +// Cadence validation, median-capped interval credit and tail credit are an +// internal rule, ESTIMATE with low confidence. Karvonen 1957 supports the +// HR-reserve zone option, not this duration-credit policy. +// Histogram reformulation of HeartRateZones.timeInZone(), now its one-slice +// path. Exact cadence-gap counts and zone-credit gaps retain the same global +// median, cadence validation and duration-credit rule. Grouped sums change +// rounding; checked tolerances are 1e-12 relative and 1e-9 absolute. +Aggregator timeInZoneAggregator( + HeartRateZoneSet zoneSet, +) => + _TimeInZoneAggregator(zoneSet); + +/// Number of distinct histogram values retained by a time-in-zone state. +/// +/// This accepts [Object] so callers can inspect an empty state without knowing +/// the private state type used by the aggregator. +int timeInZoneStateEntries(Object? state) { + if (state is! _TimeInZoneState) return 0; + return state.histograms().entryCount; +} + +class _TimeInZoneAggregator + extends Aggregator<_TimeInZoneState, HrStream, TimeInHeartRateZone?> { + _TimeInZoneAggregator(this.zoneSet) + : _windows = Lookback( + 2, _PairHistograms(zoneSet), + batchFromJson: HrStream.fromJson); + + final HeartRateZoneSet zoneSet; + final Lookback _windows; + + @override + _TimeInZoneState empty() => + _TimeInZoneState(_windows.empty(), (windows) => _windows.finish(windows)); + + @override + _TimeInZoneState addSlice( + _TimeInZoneState state, HrStream batch, int start, int end) { + // Checked before anything changes. A non-finite timestamp would store an + // infinite or NaN gap in the histograms, a state that restore refuses + // (finite keys are its contract), so an accepted state could not round-trip. + for (var i = start; i < end; i++) { + if (!batch.tsMs[i].isFinite) { + throw ArgumentError('heart-rate timestamps must be finite'); + } + } + state.windows = _windows.addSlice(state.windows, batch, start, end); + if (start < end) { + state.hasTail = true; + state.tailTimestampMs = batch.tsMs[end - 1]; + state.tailHr = batch.hr[end - 1]; + } + return state; + } + + @override + _TimeInZoneState combine( + _TimeInZoneState left, _TimeInZoneState right) { + left.windows = _windows.combine(left.windows, right.windows); + if (right.hasTail) { + left.hasTail = true; + left.tailTimestampMs = right.tailTimestampMs; + left.tailHr = right.tailHr; + } + return left; + } + + @override + bool get persistable => _windows.persistable; + + @override + Object? encodeState(_TimeInZoneState state) => { + 'zoneSet': _zoneIdentity(), + 'windows': _windows.encodeState(state.windows), + 'hasTail': state.hasTail, + 'tailTimestampMs': encodeDouble(state.tailTimestampMs), + 'tailHr': encodeDouble(state.tailHr), + }; + + // Ordered definition, including custom bounds: maxHr/source alone do not + // identify the zone indices already assigned to histogram credits. + List _zoneIdentity() => [ + zoneSet.source, + encodeDouble(zoneSet.maxHr), + for (final zone in zoneSet.zones) ...[ + zone.number, + encodeDouble(zone.lower), + encodeDouble(zone.upper), + encodeDouble(zone.lowerPct), + encodeDouble(zone.upperPct), + ], + ]; + + @override + _TimeInZoneState decodeState(Object? json) { + final map = decodeMap(json); + final storedZones = decodeList(field(map, 'zoneSet')); + final currentZones = _zoneIdentity(); + if (storedZones.length != currentZones.length) { + throw const FormatException('Different heart-rate zone set'); + } + for (var i = 0; i < currentZones.length; i++) { + if (storedZones[i] != currentZones[i]) { + throw const FormatException('Different heart-rate zone set'); + } + } + final windows = decodeMap(field(map, 'windows')); + final length = decodeCount(field(windows, 'length')); + final hasTail = field(map, 'hasTail'); + if (hasTail is! bool) throw const FormatException('Expected a bool'); + // Every timestamp the state retains must be finite. The stream decoder only + // checks column lengths, so an infinite edge timestamp would decode and + // later turn into an infinite credit gap, a histogram key that restore then + // refuses. Ingestion refuses non-finite timestamps, so no state it built + // holds one. + for (final edge in ['first', 'last']) { + final raw = windows[edge]; + if (raw == null) continue; + for (final t in HrStream.fromJson(raw).tsMs) { + if (!t.isFinite) { + throw const FormatException('Non-finite retained timestamp'); + } + } + } + final result = empty() + ..windows = _windows.decodeState(windows) + ..hasTail = hasTail + ..tailTimestampMs = decodeDouble(field(map, 'tailTimestampMs')) + ..tailHr = decodeDouble(field(map, 'tailHr')); + if (hasTail != (length > 0)) { + throw const FormatException('Invalid tail'); + } + if (hasTail && !result.tailTimestampMs.isFinite) { + throw const FormatException('Non-finite tail timestamp'); + } + if (hasTail) { + final last = HrStream.fromJson(field(windows, 'last')); + // The lookback decoder has checked that this edge holds exactly one row. + // Encoded comparison preserves accepted NaN HR, which is invalid input + // for crediting but must still survive a checkpoint round trip. + if (result.tailTimestampMs != last.tsMs.single || + encodeDouble(result.tailHr) != encodeDouble(last.hr.single)) { + throw const FormatException('Tail disagrees with retained last row'); + } + } + _validateHistogramCounts(result.histograms(), length); + return result; + } + + @override + TimeInHeartRateZone? finish(_TimeInZoneState state) { + final histograms = state.histograms(); + final cadence = _cadence(histograms.cadence); + if (cadence == null) return null; + + final seconds = List.filled(5, 0.0); + var belowZone1 = 0.0; + for (var zone = 0; zone < histograms.credits.length; zone++) { + var total = 0.0; + for (final entry in histograms.credits[zone].entries) { + final gap = entry.key; + final credited = gap > 0 ? math.min(gap, cadence) : cadence; + total += entry.value * credited; + } + if (zone == 0) { + belowZone1 += total; + } else { + seconds[zone - 1] += total; + } + } + if (state.hasTail && state.tailHr > 0) { + final zone = zoneSet.zoneNumber(state.tailHr); + if (zone == 0) { + belowZone1 += cadence; + } else { + seconds[zone - 1] += cadence; + } + } + return TimeInHeartRateZone(seconds: seconds, belowZone1: belowZone1); + } +} + +class _TimeInZoneState { + _TimeInZoneState(this.windows, this._finishWindows); + + dynamic windows; + final _ZoneHistograms Function(dynamic) _finishWindows; + bool hasTail = false; + double tailTimestampMs = 0.0; + double tailHr = 0.0; + + _ZoneHistograms histograms() => _finishWindows(windows); +} + +/// Processes every complete two-row window supplied by [Lookback]. +class _PairHistograms + extends Aggregator<_ZoneHistograms, HrStream, _ZoneHistograms> { + const _PairHistograms(this.zoneSet); + + final HeartRateZoneSet zoneSet; + + @override + _ZoneHistograms empty() => _ZoneHistograms(); + + @override + _ZoneHistograms addSlice( + _ZoneHistograms state, HrStream batch, int start, int end) { + for (var i = start + 1; i < end; i++) { + final previous = i - 1; + final cadenceGap = batch.tsMs[i] / 1000.0 - + batch.tsMs[previous] / 1000.0; + if (cadenceGap > 0) state.addCadence(cadenceGap); + + final previousHr = batch.hr[previous]; + if (previousHr > 0) { + final creditGap = + (batch.tsMs[i] - batch.tsMs[previous]) / 1000.0; + state.addCredit(zoneSet.zoneNumber(previousHr), creditGap); + } + } + return state; + } + + @override + _ZoneHistograms combine(_ZoneHistograms left, _ZoneHistograms right) { + left.merge(right); + return left; + } + + @override + _ZoneHistograms finish(_ZoneHistograms state) => state; + + @override + bool get persistable => true; + + @override + Object? encodeState(_ZoneHistograms state) => { + 'cadence': _encodeHistogram(state.cadence), + 'credits': [ + for (final histogram in state.credits) _encodeHistogram(histogram) + ], + }; + + @override + _ZoneHistograms decodeState(Object? json) { + final map = decodeMap(json); + final state = _ZoneHistograms(); + _decodeHistogram(field(map, 'cadence'), state.cadence, + requirePositive: true); + final credits = decodeList(field(map, 'credits')); + if (credits.length != state.credits.length) { + throw const FormatException('Expected six credit histograms'); + } + for (var zone = 0; zone < credits.length; zone++) { + _decodeHistogram(credits[zone], state.credits[zone]); + } + return state; + } +} + +class _ZoneHistograms { + final Map cadence = {}; + final List> credits = + List>.generate(6, (_) => {}); + + int get entryCount => cadence.length + + credits.fold(0, (count, histogram) => count + histogram.length); + + void addCadence(double gap) => _increment(cadence, gap); + + void addCredit(int zone, double gap) => _increment(credits[zone], gap); + + void merge(_ZoneHistograms other) { + _merge(cadence, other.cadence); + for (var zone = 0; zone < credits.length; zone++) { + _merge(credits[zone], other.credits[zone]); + } + } +} + +/// A double-keyed histogram as `[[gap, count], ...]`; keys stay lossless. +List _encodeHistogram(Map histogram) => [ + for (final entry in histogram.entries) + [encodeDouble(entry.key), entry.value] + ]; + +void _decodeHistogram(Object? json, Map into, + {bool requirePositive = false}) { + for (final item in decodeList(json)) { + final pair = decodeList(item); + if (pair.length != 2) throw const FormatException('Expected [gap, count]'); + final gap = decodeDouble(pair[0]); + if (!gap.isFinite || (requirePositive && gap <= 0)) { + throw const FormatException('Invalid histogram gap'); + } + final count = decodeCount(pair[1]); + if (count == 0 || into.containsKey(gap)) { + throw const FormatException('Invalid histogram entry'); + } + into[gap] = count; + } +} + +void _validateHistogramCounts(_ZoneHistograms histograms, int length) { + final pairCount = length == 0 ? 0 : length - 1; + _validateHistogramCount(histograms.cadence.values, pairCount); + var credits = 0; + for (final histogram in histograms.credits) { + for (final count in histogram.values) { + if (count > pairCount - credits) { + throw const FormatException('Too many credit histogram entries'); + } + credits += count; + } + } +} + +void _validateHistogramCount(Iterable counts, int maximum) { + var total = 0; + for (final count in counts) { + if (count > maximum - total) { + throw const FormatException('Too many cadence histogram entries'); + } + total += count; + } +} + +void _increment(Map histogram, double value) { + histogram[value] = (histogram[value] ?? 0) + 1; +} + +void _merge(Map left, Map right) { + for (final entry in right.entries) { + left[entry.key] = (left[entry.key] ?? 0) + entry.value; + } +} + +double? _cadence(Map histogram) { + var gapCount = 0; + for (final count in histogram.values) { + gapCount += count; + } + final median = _median(histogram, gapCount); + if (median == null || median > maxSupportedCadenceSec) return null; + + var inMode = 0; + for (final entry in histogram.entries) { + final gap = entry.key; + if (gap <= median * 2.0 && gap * 2.0 >= median) { + inMode += entry.value; + } + } + return inMode < gapCount * 0.5 ? null : median; +} + +/// Equivalent to `percentileSorted(expandedHistogram, 50)` without expansion. +double? _median(Map histogram, int count) { + if (count == 0) return null; + final sorted = histogram.keys.toList()..sort(); + if (count == 1) return sorted.single; + final rank = (50 / 100) * (count - 1); + final lo = rank.floor(); + final hi = rank.ceil(); + final loValue = _valueAt(sorted, histogram, lo); + if (lo == hi) return loValue; + final hiValue = _valueAt(sorted, histogram, hi); + final fraction = rank - lo; + return loValue + (hiValue - loValue) * fraction; +} + +double _valueAt(List sorted, Map histogram, int index) { + var remaining = index; + for (final value in sorted) { + final count = histogram[value]!; + if (remaining < count) return value; + remaining -= count; + } + throw StateError('histogram index out of range'); +} diff --git a/test/aggregate/circadian_np_aggregator_test.dart b/test/aggregate/circadian_np_aggregator_test.dart new file mode 100644 index 0000000..0c7259e --- /dev/null +++ b/test/aggregate/circadian_np_aggregator_test.dart @@ -0,0 +1,511 @@ +// EpochSeries + circadianNpAggregator must reproduce the batch calculation +// under every slicing / chunking, and obey the laws. The batch calculation is +// `_referenceCircadianNp` below, the pre-aggregator implementation kept in this +// file: `circadianNonparametric` now delegates to the aggregator, so comparing +// against it would let a shared mistake pass. +// +// Contract: EpochSeries(Float64List x, {firstIndex = 0}); copyRange copies and +// shifts firstIndex; join asserts other.firstIndex == firstIndex + length. +// circadianNpAggregator(epochsPerDay, {m10Epochs, l5Epochs}) never throws; +// epochsPerDay <= 0 is the reference's absent Metric. +// +// Parity: integer data -> IS/IV/M10/L5/RA within relTol 1e-12 and start epochs +// EXACT. Real data -> values within relTol 1e-9, start epochs NOT compared (the +// window margin is not available to the equality, so only integer cases check +// starts). + +import 'dart:math' as math; +import 'dart:typed_data'; + +import 'package:openstrap_analytics/aggregate.dart'; +import 'package:openstrap_analytics/onehz.dart'; +import 'package:test/test.dart'; + +import '../support/checkpoint_support.dart'; +import '../support/aggregator_laws.dart'; +import '../support/property.dart' show Rng; + +List _meta(Metric m) => + [m.present, m.confidence, m.tier, m.inputs_used.join(','), m.note]; + +List _vals(Metric m) { + final v = m.value; + return [ + ..._meta(m), + v?.interdailyStability, v?.intradailyVariability, v?.m10, v?.l5, + v?.relativeAmplitude, + ]; +} + +List _withStarts(Metric m) => + [..._vals(m), m.value?.m10StartEpoch, m.value?.l5StartEpoch]; + +final _exact = fieldsEqual>(_withStarts, relTol: 1e-12); +final _real = fieldsEqual>(_vals, relTol: 1e-9); + +EpochSeries _es(List x, {int first = 0}) => EpochSeries( + Float64List.fromList([for (final v in x) v.toDouble()]), + firstIndex: first); + +double _mean(List v) { + var s = 0.0; + for (final x in v) { + s += x; + } + return s / v.length; +} + +/// The batch rule as it was before `circadianNonparametric` delegated to the +/// aggregator (Witting 1990, van Someren 1999), written out again here: Welford +/// total variance, the epoch-of-day profile, IS, IV and the circular M10/L5 +/// windows. Nothing below calls the code under test. +Metric _referenceCircadianNp(List x, int epochsPerDay, + {int? m10Epochs, int? l5Epochs}) { + const inputs = ['activity_or_hr_epochs']; + final n = x.length; + if (epochsPerDay <= 0 || n < epochsPerDay) { + return const Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'need ≥1 full day of epochs for circadian metrics', + ); + } + final mEp = m10Epochs ?? (epochsPerDay * 10 ~/ 24); + final lEp = l5Epochs ?? (epochsPerDay * 5 ~/ 24); + final grand = _mean(x); + var ssTot = 0.0, center = 0.0, count = 0; + for (final value in x) { + count++; + if (!value.isFinite) { + ssTot = double.nan; + break; + } + final delta = value - center; + center += delta / count; + ssTot += delta * (value - center); + } + if (ssTot == 0) { + return const Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'no variance in activity series', + ); + } + final p = epochsPerDay; + final hourMeans = List.filled(p, 0); + final hourCounts = List.filled(p, 0); + for (var i = 0; i < n; i++) { + hourMeans[i % p] += x[i]; + hourCounts[i % p]++; + } + for (var h = 0; h < p; h++) { + if (hourCounts[h] > 0) hourMeans[h] /= hourCounts[h]; + } + var ssHour = 0.0; + for (var h = 0; h < p; h++) { + final d = hourMeans[h] - grand; + ssHour += d * d; + } + final isValue = (n * ssHour) / (p * ssTot); + var ssDiff = 0.0; + for (var i = 1; i < n; i++) { + final d = x[i] - x[i - 1]; + ssDiff += d * d; + } + final iv = (n * ssDiff) / ((n - 1) * ssTot); + + (double, int) best(int w, {required bool maximize}) { + if (w >= p) return (_mean(hourMeans), 0); + double? bestValue; + var bestStart = 0; + for (var s = 0; s < p; s++) { + var sum = 0.0; + for (var k = 0; k < w; k++) { + sum += hourMeans[(s + k) % p]; + } + final m = sum / w; + if (bestValue == null || (maximize ? m > bestValue : m < bestValue)) { + bestValue = m; + bestStart = s; + } + } + return (bestValue ?? 0, bestStart); + } + + final m10 = best(mEp, maximize: true); + final l5 = best(lEp, maximize: false); + final ra = (m10.$1 + l5.$1) > 0 ? (m10.$1 - l5.$1) / (m10.$1 + l5.$1) : 0.0; + final days = n / epochsPerDay; + final conf = (days / 7.0).clamp(0.3, 0.95); + return Metric( + value: CircadianNp( + interdailyStability: isValue.clamp(0, 1), + intradailyVariability: math.max(0, iv), + m10: m10.$1, + l5: l5.$1, + relativeAmplitude: ra.clamp(0, 1), + m10StartEpoch: m10.$2, + l5StartEpoch: l5.$2, + ), + confidence: conf, + tier: Tier.high, + inputs_used: inputs, + note: 'IS/IV/RA/L5/M10 (van Someren 1999); circadian phase anchored on the ' + 'L5 nocturnal trough, not the daytime peak', + ); +} + +/// Seeded series: [count] lengths in 0..10 days plus a partial day. +List _cases(int seed, int p, double Function(Rng) draw, + {int count = 10}) { + final r = Rng(seed); + return [ + _es([]), + _es([draw(r)]), + for (var i = 0; i < count; i++) + _es([ + for (var k = r.intIn(0, 10 * p + p - 1); k > 0; k--) draw(r) + ]), + _es([for (var k = 0; k < 3 * p; k++) draw(r)]), + ]; +} + +void _parity(String name, int p, {int? m10, int? l5, bool ints = true}) { + test(name, () { + final draw = ints + ? (Rng r) => r.intIn(0, 500).toDouble() + : (Rng r) => r.nextDouble() * 300 - 20; + expectConversion>( + (_) => circadianNpAggregator(p, m10Epochs: m10, l5Epochs: l5), + _cases(p * 31 + (ints ? 1 : 0), p, draw), + (b) => _referenceCircadianNp(b.x, p, m10Epochs: m10, l5Epochs: l5), + equals: ints ? _exact : _real, + seed: p, + ); + }); +} + +void main() { + group('EpochSeries batch', () { + final e = _es([for (var i = 0; i < 10; i++) i * 1.5]); + + test('copyRange shifts firstIndex and copies', () { + final c = e.copyRange(3, 8); + expect(c.length, 5); + expect(c.firstIndex, 3); + expect(c.x, e.x.sublist(3, 8)); + expect(c.copyRange(2, 4).firstIndex, 5); + expect(_es([1, 2, 3], first: 100).copyRange(1, 3).firstIndex, 101); + expect(e.copyRange(4, 4).length, 0); + e.x[4] = -1; + expect(c.x[1], 6.0); + e.x[4] = 6.0; + }); + + test('join of adjacent batches', () { + final j = e.copyRange(2, 5).join(e.copyRange(5, 5)).join(e.copyRange(5, 9)); + expect(j.firstIndex, 2); + expect(j.x, e.x.sublist(2, 9)); + final l = e.copyRange(0, 3); + final k = l.join(e.copyRange(3, 10)); + l.x[0] = 99; + expect(k.x[0], 0.0); + }); + + test('non-adjacent join asserts', () { + expect(() => e.copyRange(0, 3).join(e.copyRange(4, 10)), + throwsA(isA())); + expect(() => e.copyRange(3, 6).join(e.copyRange(0, 3)), + throwsA(isA())); + }); + }); + + group('parity with circadianNonparametric', () { + for (final p in [6, 7, 12, 24]) { + _parity('integer data, p=$p', p); + _parity('real data, p=$p', p, ints: false); + } + _parity('custom windows, integers', 12, m10: 5, l5: 3); + _parity('custom windows, real', 12, m10: 5, l5: 3, ints: false); + _parity('windows w >= p', 8, m10: 8, l5: 20); + _parity('window w == 1', 8, m10: 1, l5: 1); + + test('3 days of 1440 epochs, integers', () { + final r = Rng(1440); + final x = _es([for (var i = 0; i < 3 * 1440; i++) r.intIn(0, 900)]); + expectConversion>( + (_) => circadianNpAggregator(1440), [x], + (b) => _referenceCircadianNp(b.x, 1440), + // Laws are covered by the small-p cases above; here each finish runs + // the O(p·w) window search, so the law sweep alone took ~9 s. + equals: _exact, chunkings: 4, laws: false); + }); + }); + + test('persistable: a mid-stream checkpoint resumes to the one-pass result', () { + final x = _cases(0xC0DE, 12, (r) => r.intIn(0, 500).toDouble()).last; + expectCheckpointResumes(circadianNpAggregator(12), x, equals: _exact); + }); + + group('absent cases and extremes', () { + void same(String name, EpochSeries s, int p, {int? m10, int? l5}) => + test(name, () { + final want = _referenceCircadianNp(s.x, p, m10Epochs: m10, l5Epochs: l5); + final got = circadianNpAggregator(p, m10Epochs: m10, l5Epochs: l5) + .run(s); + expect(_exact(got, want), isTrue, reason: '$got vs $want'); + expect(got.present, want.present); + }); + + same('empty', _es([]), 4); + same('shorter than a day', _es([1, 2, 3]), 4); + same('constant series (no variance)', _es(List.filled(12, 7)), 4); + same('constant zero series', _es(List.filled(8, 0)), 4); + same('exactly one day', _es([1, 5, 2, 8]), 4); + same('partial trailing day uses n', _es([1, 5, 2, 8, 3, 9, 1]), 4); + for (final p in [0, -1, -24]) { + same('epochsPerDay $p', _es([1, 5, 2, 8, 3, 9, 1, 4]), p); + same('epochsPerDay $p, empty', _es([]), p); + } + + test('absent reasons differ', () { + expect(circadianNpAggregator(4).run(_es([1, 2])).note, + contains('≥1 full day')); + expect(circadianNpAggregator(4).run(_es(List.filled(8, 3))).note, + 'no variance in activity series'); + }); + + test('epochsPerDay <= 0 never throws on any path', () { + final s = _es([for (var i = 0; i < 9; i++) i * 1.0]); + final a = circadianNpAggregator(0); + expect(a.finish(a.empty()).present, isFalse); + expect(runChunked(a, s, [0, 4, 9]).present, isFalse); + expect(runSliced(a, s, [0, 0, 5, 9]).present, isFalse); + }); + }); + + group('missing and non-finite values follow the reference policy', () { + const nan = double.nan; + const inf = double.infinity; + + void same(String name, List x, int p, {int? m10, int? l5}) => + test(name, () { + final s = _es(x); + final want = _referenceCircadianNp(s.x, p, m10Epochs: m10, l5Epochs: l5); + final agg = circadianNpAggregator(p, m10Epochs: m10, l5Epochs: l5); + final got = agg.run(s); + expect(_exact(got, want), isTrue, reason: 'whole: $got vs $want'); + // Every path, not only the whole fold. + final n = x.length; + for (final bounds in [ + [0, n ~/ 2, n], + [0, 1, n], + [0, n - 1, n], + [for (var i = 0; i <= n; i++) i], + ]) { + expect(_exact(runChunked(agg, s, bounds), want), isTrue, + reason: 'chunked $bounds'); + expect(_exact(runSliced(agg, s, bounds), want), isTrue, + reason: 'sliced $bounds'); + } + }); + + same('review: six NaNs, epochsPerDay 6 (used to throw)', + [nan, nan, nan, nan, nan, nan], 6); + same('review: [1,2,3,4,5,NaN], epochsPerDay 6 (L5 and RA were wrong)', + [1, 2, 3, 4, 5, nan], 6); + same('NaN in the second day', [1, 2, 3, 4, 5, 6, 7, nan, 9, 1, 2, 3], 6); + same('a NaN in every epoch-of-day bin', [nan, 1, 2, 3, 4, 5, 6, nan, 8], 4); + same('a whole bin missing', [1, nan, 3, 4, 5, nan, 7, 8, 9, nan, 2, 3], 4); + same('NaN with custom windows', [3, 1, nan, 9, 2, 8, 7, nan, 5, 4], 5, + m10: 2, l5: 3); + same('one +Infinity', [1, 2, inf, 4, 5, 6, 7, 8], 4); + same('one -Infinity', [1, 2, -inf, 4, 5, 6, 7, 8], 4); + same('+Infinity and -Infinity', [1, inf, 3, -inf, 5, 6, 7, 8], 4); + same('NaN and Infinity together', [nan, inf, 3, 4, 5, 6, 7, 8], 4); + + test('series with sprinkled NaN agree with the reference', () { + for (final p in [4, 6, 12]) { + final r = Rng(0xA11 + p); + expectConversion>( + (_) => circadianNpAggregator(p), + [ + for (var c = 0; c < 14; c++) + _es([ + for (var k = r.intIn(p, 6 * p); k > 0; k--) + r.nextBool(c.isEven ? .08 : .3) + ? nan + : r.intIn(0, 500).toDouble() + ]), + ], + (b) => _referenceCircadianNp(b.x, p), + equals: _exact, + seed: p, + ); + } + }); + }); + + group('checkpoint relationships (counts and bins agree across children)', () { + // p = 6, 9 epochs: bins 0..5 all present, bins 0..2 hold two epochs. + final agg = circadianNpAggregator(6); + final x = _es([4, 8, 1, 9, 2, 7, 5, 3, 6]); + + // State: [[n, moments], [groups, lookback]]; a group is [count, sum]. + Map groups(Object? s) => ((s as List)[1] as List)[0] as Map; + Map lookback(Object? s) => ((s as List)[1] as List)[1] as Map; + + test('review case: group "0" removed is refused', () { + // Used to decode, then finish threw on the missing bin. + expectDamagedCheckpointRefused(agg, x, (s) { + groups(s).remove('0'); + return s; + }); + }); + test('another bin removed, or an extra bin added, is refused', () { + expectDamagedCheckpointRefused(agg, x, (s) { + groups(s).remove('5'); + return s; + }); + expectDamagedCheckpointRefused(agg, x, (s) { + groups(s)['6'] = groups(s)['0']; + return s; + }); + expectDamagedCheckpointRefused(agg, x, (s) { + groups(s)['-1'] = groups(s)['0']; + return s; + }); + }); + test('group counts that do not sum to the total are refused', () { + expectDamagedCheckpointRefused(agg, x, (s) { + final g = groups(s)['3'] as List; + g[0] = (g[0] as int) + 1; + return s; + }); + expectDamagedCheckpointRefused(agg, x, (s) { + ((s as List)[0] as List)[0] = 10; + return s; + }); + }); + test('a count that puts the epochs in the wrong bins is refused', () { + // Same total, but bins 0 and 3 swap their counts: 0 should hold two. + expectDamagedCheckpointRefused(agg, x, (s) { + final g0 = groups(s)['0'] as List, g5 = groups(s)['5'] as List; + g0[0] = 1; + g5[0] = 2; + return s; + }); + }); + test('a lookback row count that differs from the total is refused', () { + expectDamagedCheckpointRefused(agg, x, (s) { + lookback(s)['length'] = 12; + return s; + }); + }); + test('the bins required follow firstIndex, not just the count', () { + // Rows 4..8 only: epochs of day 4,5,0,1,2, so bin 3 must be absent. + final tail = EpochSeries(Float64List.fromList([1, 2, 3, 4, 5]), + firstIndex: 4); + final a = circadianNpAggregator(6); + final good = checkpointOf(a, tail); + expect(((good['state'] as List)[1] as List)[0] as Map, + hasLength(5)); // sanity: bins 0,1,2,4,5 + expect(decodeCheckpoint(a, good, kind: 'test', version: 1), + isNotNull); + expectDamagedCheckpointRefused(a, tail, (s) { + groups(s)['3'] = groups(s)['0']; + return s; + }); + expectDamagedCheckpointRefused(a, tail, (s) { + final g = groups(s); + g['3'] = g.remove('4'); // right number of bins, wrong ones + return s; + }); + }); + // # catches: only the first edge's index was checked, so a last edge at the + // wrong index decoded and then failed when the next batch was joined to it. + test('the last edge must sit at firstIndex + count - 1', () { + for (final bad in [7, 9, 0, 100]) { + expectDamagedCheckpointRefused(agg, x, (s) { + (lookback(s)['last'] as Map)['firstIndex'] = bad; + return s; + }, reason: 'last.firstIndex $bad'); + } + // The right value (9 epochs from index 0: last at 8) is accepted. + expect( + decodeCheckpoint(agg, checkpointOf(agg, x), + kind: 'test', version: 1), + isNotNull); + // A checkpoint that starts later moves the expected index with it. + final tail = EpochSeries(Float64List.fromList([1, 2, 3, 4, 5]), + firstIndex: 4); + final a = circadianNpAggregator(6); + expectDamagedCheckpointRefused(a, tail, (s) { + (lookback(s)['last'] as Map)['firstIndex'] = 4; + return s; + }); + }); + test('a consistent checkpoint resumes after the checks', () { + expectCheckpointResumes(agg, x, equals: _exact); + }); + }); + + // The public batch function now runs the aggregator; it must still equal the + // independent reference, including the awkward series. + group('circadianNonparametric agrees with the frozen reference', () { + final p = 6; + final series = >{ + 'ordinary': [for (var i = 0; i < 4 * p; i++) (i * 7 % 11).toDouble()], + 'partial day': [for (var i = 0; i < 2 * p + 3; i++) (i * 5 % 9).toDouble()], + 'constant': List.filled(3 * p, 4.0), + 'one value off': [for (var i = 0; i < 3 * p; i++) i == 7 ? 100.0 : 3.0], + 'huge values': [for (var i = 0; i < 3 * p; i++) (i.isEven ? 1e300 : 1e-300)], + 'a NaN': [for (var i = 0; i < 3 * p; i++) i == 5 ? double.nan : i.toDouble()], + 'an Infinity': [for (var i = 0; i < 3 * p; i++) i == 9 ? double.infinity : i.toDouble()], + 'too short': [1.0, 2.0, 3.0], + 'empty': [], + }; + for (final e in series.entries) { + test(e.key, () { + final got = circadianNonparametric(e.value, p); + final want = _referenceCircadianNp(e.value, p); + expect(_withStarts(got).map((v) => v is double && v.isNaN ? 'NaN' : v), + _withStarts(want).map((v) => v is double && v.isNaN ? 'NaN' : v)); + }); + } + test('epochsPerDay <= 0 is the absent metric', () { + for (final bad in [0, -3]) { + expect(_vals(circadianNonparametric([1, 2, 3], bad)), + _vals(_referenceCircadianNp([1, 2, 3], bad))); + } + }); + }); + + // # catches: merging two halves scaled delta * delta by both counts before + // dividing by their sum, so 1e306 * 51 * 50 overflowed to Infinity while the + // one-pass total (about 2.5e307) is finite. IS then came out 0 instead of the + // one-pass value. + test('merging halves of a huge-valued series equals one pass', () { + const p = 6; + final x = _es([ + for (var i = 0; i < 101; i++) i < 51 ? 0.0 : 1e153, + ]); + final agg = circadianNpAggregator(p); + final want = _referenceCircadianNp(x.x, p); + expect(want.present, isTrue); + final one = agg.run(x); + final left = agg.addSlice(agg.empty(), x, 0, 51); + final right = agg.addSlice(agg.empty(), x, 51, 101); + final merged = agg.finish(agg.combine(left, right)); + expect(_real(one, want), isTrue, reason: 'one pass vs reference'); + expect(_real(merged, want), isTrue, reason: 'merged halves vs reference'); + expect(merged.value!.interdailyStability, greaterThan(0)); + // Merged the other way round (left half is the larger value block). + final big = _es([for (var i = 0; i < 101; i++) i < 50 ? 1e153 : 0.0]); + final bigWant = _referenceCircadianNp(big.x, p); + final bl = agg.addSlice(agg.empty(), big, 0, 50); + final br = agg.addSlice(agg.empty(), big, 50, 101); + expect(_real(agg.finish(agg.combine(bl, br)), bigWant), isTrue, + reason: 'merged, big block first'); + }); +} diff --git a/test/aggregate/cosinor_aggregator_test.dart b/test/aggregate/cosinor_aggregator_test.dart new file mode 100644 index 0000000..5f4272d --- /dev/null +++ b/test/aggregate/cosinor_aggregator_test.dart @@ -0,0 +1,728 @@ +// cosinorAggregator (sufficient statistics) must agree with cosinor() for any +// series and any chunking or slicing, and obey the aggregator laws. +// +// Contract used here: +// * TimedValues(tHours, y): equal-length Float64Lists (assert). Row r is the +// sample (tHours[r], y[r]). copyRange returns copies; join concatenates. +// TimedValues and cosinorAggregator are exported from +// package:openstrap_analytics/aggregate.dart. Non-finite moments abstain; +// a tHours/y length mismatch cannot occur. +// * cosinorAggregator({periodHours = 24, minPoints = cosinorMinPoints}) is an +// Aggregator<_, TimedValues, Metric>. Constructing it never +// throws, also for periodHours <= 0 (then every run is absent). +// * Absent exactly when cosinor() is absent: n < max(4, minPoints), +// invalid/non-finite period ('invalid cosinor period'), non-finite moments, +// or a singular design +// (relative centered determinant <= 1e-12 of the diagonal product; +// 'singular cosinor design (insufficient phase coverage)'). +// Absent metrics carry the same tier, inputs_used and note. +// * Present: mesor, amplitude, acrophaseRad within relTol 1e-9 (acrophaseRad +// compared modulo 2 pi and with an absolute floor of 1e-9, because a phase +// near 0 or +-pi has no meaningful relative error; for an amplitude that is +// only rounding noise, below 1e-9 * max(1, |mesor|), the amplitude gets an +// absolute floor of 1e-12 * max(1, |mesor|) and the phases are not compared); +// acrophaseHours within +// relTol 1e-9 of the period, modulo periodHours; periodHours equal; r2, +// r2Adj, confidence absTol 1e-7; tier, inputs_used, note equal. +// * Batch now runs the same aggregator. The near-singular fixture below +// pins its relative gate; ordinary parity fixtures avoid that threshold. + +import 'dart:convert'; +import 'dart:math' as math; +import 'dart:typed_data'; + +import 'package:openstrap_analytics/aggregate.dart'; +import 'package:openstrap_analytics/onehz.dart'; +import 'package:test/test.dart'; + +import 'support/upstream_cosinor.dart'; +import '../support/checkpoint_support.dart'; +import '../support/aggregator_laws.dart'; +import '../support/property.dart' show Rng; + +const _twoPi = 2 * math.pi; + +typedef _Agg = Aggregator>; + +TimedValues _tv(List t, List y) => + TimedValues(Float64List.fromList(t), Float64List.fromList(y)); + +/// Distance of [a] and [b] on a circle of circumference [period]. +double _circ(double a, double b, double period) { + var d = (a - b) % period; + if (d < 0) d += period; + return math.min(d, period - d); +} + +/// True when a finite/non-finite mismatch (or two different non-finite values) +/// makes a tolerance comparison meaningless: NaN fails every `>` check, so +/// without this guard a NaN field would slip through as "equal". +bool _nonFiniteMismatch(double a, double b) { + if (a.isFinite && b.isFinite) return false; + if (a.isNaN && b.isNaN) return false; + return a != b; +} + +/// Null when [got] matches [want] per the spec tolerances, else why not. +String? _diff(Metric got, Metric want) { + if (got.present != want.present) { + return 'present ${got.present} vs ${want.present}'; + } + if (got.tier != want.tier || + got.inputs_used.join(',') != want.inputs_used.join(',') || + got.note != want.note) { + return 'metadata ${got.tier}/${got.inputs_used}/${got.note} vs ' + '${want.tier}/${want.inputs_used}/${want.note}'; + } + if (_nonFiniteMismatch(got.confidence, want.confidence) || + (got.confidence - want.confidence).abs() > 1e-7) { + return 'confidence ${got.confidence} vs ${want.confidence}'; + } + final g = got.value, w = want.value; + if (g == null || w == null) return null; + for (final (name, a, b) in [ + ('mesor', g.mesor, w.mesor), + ('amplitude', g.amplitude, w.amplitude), + ('r2', g.r2, w.r2), + ('r2Adj', g.r2Adj, w.r2Adj), + ]) { + if (_nonFiniteMismatch(a, b)) return '$name non-finite mismatch $a vs $b'; + } + bool rel(double a, double b, [double floor = 0]) => + (a - b).abs() <= math.max(floor, 1e-9 * math.max(a.abs(), b.abs())); + // A mesor near zero (data centred on 0) has no relative accuracy either: + // its rounding scales with the amplitude, so it gets the same data-scale + // floor. + final scale = math.max(1.0, math.max(w.mesor.abs(), w.amplitude)); + if (!rel(g.mesor, w.mesor, 1e-12 * scale)) { + return 'mesor ${g.mesor} vs ${w.mesor}'; + } + // An amplitude that is pure rounding noise (constant data) has no relative + // accuracy and no phase: compare it against a floor and skip the phases. + final floor = 1e-12 * math.max(1, w.mesor.abs()); + if (!rel(g.amplitude, w.amplitude, floor)) { + return 'amplitude ${g.amplitude} vs ${w.amplitude}'; + } + for (final (name, a, b) in [ + ('acrophaseRad', g.acrophaseRad, w.acrophaseRad), + ('acrophaseHours', g.acrophaseHours, w.acrophaseHours), + ]) { + if ((a == null) != (b == null)) return '$name presence $a vs $b'; + if (a != null && b != null && _nonFiniteMismatch(a, b)) { + return '$name non-finite mismatch $a vs $b'; + } + } + if (g.acrophaseRad != null && w.acrophaseRad != null && + _circ(g.acrophaseRad!, w.acrophaseRad!, _twoPi) > + 1e-9 * math.max(1, w.acrophaseRad!.abs())) { + return 'acrophaseRad ${g.acrophaseRad} vs ${w.acrophaseRad}'; + } + if (g.periodHours != w.periodHours) return 'periodHours'; + if (g.acrophaseHours != null && w.acrophaseHours != null && + _circ(g.acrophaseHours!, w.acrophaseHours!, w.periodHours) > + 1e-9 * w.periodHours) { + return 'acrophaseHours ${g.acrophaseHours} vs ${w.acrophaseHours}'; + } + if (_nonFiniteMismatch(g.amplitudeP, w.amplitudeP) || + (g.amplitudeP - w.amplitudeP).abs() > 1e-7) return 'amplitudeP'; + if ((g.r2 - w.r2).abs() > 1e-7) return 'r2 ${g.r2} vs ${w.r2}'; + if ((g.r2Adj - w.r2Adj).abs() > 1e-7) { + return 'r2Adj ${g.r2Adj} vs ${w.r2Adj}'; + } + return null; +} + +bool _eq(Metric a, Metric b) => _diff(a, b) == null; + +void _same(Metric got, Metric want, String tag) { + expect(_diff(got, want), isNull, reason: tag); +} + +Metric _want(TimedValues d, double period, int minPoints) { + // Review 3c21387 changed the invalid-period note and its precedence. Keep + // the frozen independent solver for finite-input numerical comparisons. + if (!period.isFinite || period <= 0) { + return const Metric.absent( + tier: Tier.high, + inputs_used: ['signal_timeseries'], + note: 'invalid cosinor period', + ); + } + return upstreamCosinor(d.tHours, d.y, + periodHours: period, minPoints: minPoints); +} + +void _allPaths(_Agg a, TimedValues d, List b, Metric want, + String tag) { + _same(runChunked(a, d, b), want, '$tag chunks $b'); + _same(runChunked(a, d, b, copy: true), want, '$tag copies $b'); + _same(runChunkedRight(a, d, b), want, '$tag right $b'); + _same(runSliced(a, d, b), want, '$tag sliced $b'); +} + +/// [n] samples: y = mesor + amp cos(w (t - peak)) + noise. Times are a regular +/// grid of [step] hours from [t0] with jitter [jitter] (hours). +TimedValues _series(Rng r, int n, + {double period = 24, + double mesor = 33, + double amp = .3, + double noise = 0, + double peak = 15.5, + double t0 = 0, + double step = .25, + double jitter = 0}) { + final w = _twoPi / period; + final t = [], y = []; + for (var i = 0; i < n; i++) { + final ti = t0 + i * step + (jitter == 0 ? 0 : (r.nextDouble() - .5) * jitter); + t.add(ti); + y.add(mesor + + amp * math.cos(w * (ti - peak)) + + (noise == 0 ? 0 : (r.nextDouble() - .5) * 2 * noise)); + } + return _tv(t, y); +} + +void _parity(String tag, TimedValues d, + {double period = 24, int minPoints = cosinorMinPoints, int seed = 1}) { + final want = _want(d, period, minPoints); + final a = cosinorAggregator(periodHours: period, minPoints: minPoints); + _same(a.run(d), want, '$tag whole'); + final r = Rng(seed); + for (var k = 0; k < 3; k++) { + _allPaths(a, d, randomBounds(r, d.length), want, tag); + } + _allPaths(a, d, singletonBounds(d.length), want, '$tag singletons'); +} + +TimedValues _lawSeries(Rng r, int i) { + final n = r.intIn(0, 40); + return _series(r, n, + amp: [.3, 2.0][i % 2], + noise: [.02, .3, 1e-6][i % 3], + // Cover about one to two periods so the design is well conditioned. + step: 24 * (1 + r.nextDouble()) / math.max(n, 1), + jitter: .3, + peak: r.nextDouble() * 24); +} + +void main() { + // The singular case is built to be EXACT, not near the gate. Every sample sits + // at the same time, so cos and sin receive bit-identical inputs and every + // sample has the same c and s. The running means then equal c and s exactly, + // so each later deviation is exactly 0 and mCC, mSS and mCS stay exactly 0 (in + // one slice and across merges, where the mean difference is exactly 0 too). + // The determinant is 0 and the gate `0 <= 1e-12 * 0 * 0` holds whatever libm + // returns for cos and sin. Nothing here sits near the 1e-12 threshold, so no + // platform's rounding can move it. + test('tiny phase coverage returns an absent metric, not a fabricated fit', () { + final t = List.filled(16, 3.0); + final y = [for (var i = 0; i < t.length; i++) 60.0 + i * 0.01]; + final batch = _tv(t, y); + final agg = cosinorAggregator(); + final left = agg.addSlice(agg.empty(), batch, 0, 8); + final right = agg.addSlice(agg.empty(), batch, 8, batch.length); + for (final result in [agg.run(batch), + agg.finish(agg.combine(left, right)), cosinor(t, y)]) { + expect(result.value, isNull); + expect(result.present, isFalse); + expect(result.confidence, 0); + expect(result.tier, Tier.high); + expect(result.inputs_used, ['signal_timeseries']); + expect(result.note, + 'singular cosinor design (insufficient phase coverage)'); + } + }); + + // Control: a narrow phase window that is still sufficient. The times span + // 0.015 h (about 54 s) in 1e-3 h steps. The relative determinant of that + // design is about 1.15e-6, over a million times the 1e-12 gate, and the + // cancellation in the determinant costs about 1e-10 relative, so the verdict + // does not depend on how a platform rounds cos and sin. + test('a narrow but sufficient phase window still fits', () { + final t = [for (var i = 0; i < 16; i++) 3.0 + i * 1e-3]; + final y = [for (var i = 0; i < t.length; i++) 60.0 + i * 0.01]; + final batch = _tv(t, y); + final agg = cosinorAggregator(); + final left = agg.addSlice(agg.empty(), batch, 0, 8); + final right = agg.addSlice(agg.empty(), batch, 8, batch.length); + for (final result in [agg.run(batch), + agg.finish(agg.combine(left, right)), cosinor(t, y)]) { + expect(result.present, isTrue); + expect(result.value, isNotNull); + expect(result.value!.amplitude.isFinite, isTrue); + } + }); + + group('TimedValues batch', () { + // A fresh batch for every test: one of them writes into it, so a shared one + // would hand the others different data depending on the run order. + TimedValues fresh() => _tv([0, 1, 2, 3, 4], [10, 11, 12, 13, 14]); + test('length, copyRange, join', () { + final d = fresh(); + expect(d.length, 5); + final c = d.copyRange(1, 4); + expect(c.tHours, [1.0, 2.0, 3.0]); + expect(c.y, [11.0, 12.0, 13.0]); + final j = d.copyRange(0, 2).join(d.copyRange(2, 5)); + expect(j.tHours, d.tHours); + expect(j.y, d.y); + expect(d.copyRange(2, 2).length, 0); + }); + test('copies are independent of the source and of the join inputs', () { + final d = fresh(); + final c = d.copyRange(0, 3); + d.y[0] = -1; + d.tHours[1] = -1; + expect(c.y[0], 10.0); + expect(c.tHours[1], 1.0); + final left = _tv([0, 1], [1, 2]), right = _tv([2], [3]); + final j = left.join(right); + left.y[0] = 99; + right.tHours[0] = 99; + expect(j.y, [1.0, 2.0, 3.0]); + expect(j.tHours, [0.0, 1.0, 2.0]); + }); + }); + + group('absent cases', () { + final good = _series(Rng(1), 48); + + test('too few points, default minPoints 8', () { + for (var n = 0; n <= 10; n++) { + final d = _series(Rng(n), n, noise: .1, step: .7); + final want = _want(d, 24, cosinorMinPoints); + expect(want.present, n >= 8, reason: 'n=$n'); + _parity('n=$n', d, seed: n); + } + final m = cosinorAggregator().run(_series(Rng(1), 7, noise: .1)); + expect(m.present, isFalse); + expect(m.note, 'too few points for cosinor'); + expect(m.confidence, 0); + }); + test('minPoints is honoured: larger, and smaller than 4 is floored to 4', + () { + for (final mp in [2, 4, 5, 12, 40]) { + for (var n = 0; n <= 14; n++) { + final d = _series(Rng(n), n, noise: .1, step: .7); + _parity('mp=$mp n=$n', d, minPoints: mp, seed: n + mp); + } + } + expect(cosinorAggregator(minPoints: 12) + .run(_series(Rng(1), 11, noise: .1, step: .7)).present, isFalse); + expect(cosinorAggregator(minPoints: 2) + .run(_series(Rng(1), 3, noise: .1, step: 5)).present, isFalse); + expect(cosinorAggregator(minPoints: 2) + .run(_series(Rng(1), 4, noise: .1, step: 5)).present, isTrue); + }); + test('periodHours <= 0 is absent, and building the aggregator is fine', () { + for (final p in [0.0, -24.0, -1e-9]) { + final want = _want(good, p, cosinorMinPoints); + expect(want.present, isFalse); + final a = cosinorAggregator(periodHours: p); + _same(a.run(good), want, 'period $p'); + _same(a.run(good.copyRange(0, 3)), _want(good.copyRange(0, 3), p, 8), + 'period $p short'); + _allPaths(a, good, [0, 10, 10, 30, 48], want, 'period $p'); + } + }); + test('empty batch and empty state are absent', () { + final a = cosinorAggregator(); + final want = _want(_tv([], []), 24, cosinorMinPoints); + _same(a.run(_tv([], [])), want, 'empty'); + _same(a.finish(a.empty()), want, 'empty state'); + }); + test('singular design: every sample at the same phase', () { + // Whole periods apart, so cos/sin are the same at every row. + final d = _tv([for (var i = 0; i < 20; i++) 24.0 * i], + [for (var i = 0; i < 20; i++) 33 + .1 * (i % 3)]); + final want = _want(d, 24, 8); + expect(want.present, isFalse); + expect(want.note, contains('singular')); + _parity('same phase (multiples of the period)', d); + final same = _tv(List.filled(12, 7.5), [for (var i = 0; i < 12; i++) 30.0 + i]); + expect(_want(same, 24, 8).present, isFalse); + _parity('all at one time', same); + }); + test('singular note and metadata match', () { + final d = _tv(List.filled(10, 3.0), [for (var i = 0; i < 10; i++) i * 1.0]); + final m = cosinorAggregator().run(d); + expect(m.present, isFalse); + expect(m.note, 'singular cosinor design (insufficient phase coverage)'); + expect(m.confidence, 0); + }); + }); + + group('values', () { + test('noise-free 33 +- 0.3 recovers the parameters', () { + final d = _series(Rng(1), 96, peak: 15.5); + final m = cosinorAggregator().run(d); + final v = m.value!; + expect(v.mesor, closeTo(33, 1e-9)); + expect(v.amplitude, closeTo(.3, 1e-9)); + expect(v.acrophaseHours, closeTo(15.5, 1e-7)); + expect(v.r2, closeTo(1, 1e-7)); + expect(v.r2Adj, closeTo(1, 1e-7)); + expect(v.periodHours, 24.0); + expect(m.confidence, closeTo(.95, 1e-7)); + }); + test('hand-worked: y = 10 + 2 cos(2 pi t / 24) on a 3-hour grid', () { + final t = [for (var i = 0; i < 16; i++) 3.0 * i]; + final y = [for (final x in t) 10 + 2 * math.cos(_twoPi * x / 24)]; + final v = cosinorAggregator().run(_tv(t, y)).value!; + expect(v.mesor, closeTo(10, 1e-9)); + expect(v.amplitude, closeTo(2, 1e-9)); + expect(v.acrophaseRad, closeTo(0, 1e-9)); + expect(_circ(v.acrophaseHours!, 0, 24), lessThan(1e-7)); + }); + test('period 12 and a custom period are carried through', () { + final d = _series(Rng(2), 80, period: 12, peak: 4, step: .3); + final v = cosinorAggregator(periodHours: 12).run(d).value!; + expect(v.periodHours, 12.0); + expect(v.acrophaseHours, closeTo(4, 1e-6)); + expect(v.amplitude, closeTo(.3, 1e-9)); + }); + }); + + group('parity on named series', () { + final named = { + 'mesor 33 amp 0.3 exact, 24 h': (_series(Rng(1), 96), 24), + 'mesor 33 amp 0.3 exact, 12 h': (_series(Rng(2), 96, period: 12), 12), + 'mesor 33 amp 0.3, noise 0.01': ( + _series(Rng(3), 200, noise: .01, jitter: .1), + 24 + ), + 'mesor 33 amp 0.3, noise 0.3 (noisy)': ( + _series(Rng(4), 200, noise: .3, jitter: .1), + 24 + ), + 'mesor 33 amp 0.3, noise 2 (almost nothing)': ( + _series(Rng(5), 120, noise: 2), + 24 + ), + 'mesor 200 amp 0.01 exact': ( + _series(Rng(6), 150, mesor: 200, amp: .01), + 24 + ), + 'mesor 1000 amp 0.5 noisy': ( + _series(Rng(7), 150, mesor: 1000, amp: .5, noise: .2, jitter: .2), + 24 + ), + 'zero amplitude, tiny noise': ( + _series(Rng(8), 100, amp: 0, noise: .05), + 24 + ), + 'near-perfect, amp 20': (_series(Rng(9), 100, mesor: 60, amp: 20), 24), + 'near-perfect with 1e-6 noise': ( + _series(Rng(10), 100, noise: 1e-6, jitter: .05), + 24 + ), + 'hours since epoch (large t)': ( + _series(Rng(11), 100, t0: 480000, noise: .02), + 24 + ), + 'negative t': (_series(Rng(12), 100, t0: -500, noise: .02), 24), + 'exactly 8 points': (_series(Rng(13), 8, step: 3, noise: .1), 24), + 'peak at 0 h': (_series(Rng(14), 96, peak: 0, noise: .02), 24), + 'peak at 23.9 h': (_series(Rng(15), 96, peak: 23.9, noise: .02), 24), + 'period 12, noisy': ( + _series(Rng(16), 120, period: 12, noise: .2, amp: .6), + 12 + ), + 'period 24 data fitted at 12': ( + _series(Rng(17), 120, noise: .05, amp: 1), + 12 + ), + 'period 8': (_series(Rng(18), 90, period: 8, noise: .05, step: .5), 8), + 'irregular times over 3 days': ( + _series(Rng(19), 60, step: 1.2, jitter: 1, noise: .05, amp: 1), + 24 + ), + }; + var seed = 0; + named.forEach((name, c) { + final s = ++seed; + test(name, () { + final want = _want(c.$1, c.$2, cosinorMinPoints); + expect(want.present, isTrue, reason: 'fixture should be fittable'); + _parity(name, c.$1, period: c.$2, seed: s); + }); + }); + + test('the clamps agree: ssRes rounding must not leave r2 outside 0..1', () { + final d = _series(Rng(30), 200, mesor: 500, amp: .05); + _parity('r2 clamp', d); + final v = cosinorAggregator().run(d).value!; + expect(v.r2, inInclusiveRange(0, 1)); + expect(v.r2Adj, inInclusiveRange(0, 1)); + }); + test('constant y: ssTot is 0, r2 is 0 as in cosinor()', () { + final d = _series(Rng(31), 40, amp: 0, noise: 0); + final want = _want(d, 24, 8); + expect(want.present, isTrue); + expect(want.value!.r2, 0.0); + _parity('constant', d); + }); + }); + + group('random parity (seeded)', () { + test('random shape, period, size; whole, chunked, sliced', () { + final r = Rng(0xC051); + var checked = 0; + for (var t = 0; t < 60; t++) { + final period = [24.0, 12.0, 24.0, 8.0, 36.0][r.intIn(0, 4)]; + final n = r.nextBool(.15) ? r.intIn(0, 9) : r.intIn(10, 220); + final mesor = [0.0, 33.0, 33.0, 120.0, -15.0][r.intIn(0, 4)]; + final amp = r.nextBool(.15) ? 0.0 : [.3, 1.0, 12.0][r.intIn(0, 2)]; + // Noise-free flat data and 1e-6 noise on a flat series have no + // meaningful phase; keep them for series that have an amplitude. + final noise = amp == 0 + ? [.02, .3, 1.5][r.intIn(0, 2)] + : [0.0, 1e-6, .02, .3, 1.5][r.intIn(0, 4)]; + final d = _series(r, n, + period: period, + mesor: mesor, + amp: amp, + noise: noise, + peak: r.nextDouble() * period, + t0: r.nextBool(.2) ? 1e5 * r.nextDouble() : 0, + // 0.6 to 3 periods of coverage, so the design is well conditioned. + step: period * (.6 + r.nextDouble() * 2.4) / math.max(n, 1), + jitter: r.nextBool() ? 0 : .5); + final mp = r.nextBool(.7) ? cosinorMinPoints : r.intIn(2, 30); + _parity('t$t n=$n P=$period mesor=$mesor amp=$amp noise=$noise', d, + period: period, minPoints: mp, seed: t); + checked++; + } + expect(checked, 60); + }); + }); + + test('persistable: a mid-stream checkpoint resumes to the one-pass result', () { + final b = _lawSeries(Rng(0xC0DE), 3); + expectCheckpointResumes(cosinorAggregator(), b, equals: _eq); + }); + + group('lawful', () { + final r = Rng(0xC052); + final cases = [ + _tv([], []), + _tv([1], [2]), + _tv([1, 2], [2, 3]), + for (var i = 0; i < 12; i++) + _lawSeries(r, i), + ]; + test('default period', () { + expectLawful(cosinorAggregator(), cases, equals: _eq); + }); + test('period 12, minPoints 5', () { + expectLawful(cosinorAggregator(periodHours: 12, minPoints: 5), cases, + equals: _eq); + }); + test('periodHours 0 (always absent)', () { + expectLawful(cosinorAggregator(periodHours: 0), cases, equals: _eq); + }); + }); + + group('_diff comparator', () { + final base = cosinor(_series(Rng(1), 48, noise: .05).tHours, + _series(Rng(1), 48, noise: .05).y); + Metric with_( + {double? mesor, + double? amplitude, + double? rad, + double? hours, + double? r2, + double? r2Adj, + double? amplitudeP, + double? confidence}) => + Metric( + value: CosinorFit( + mesor: mesor ?? base.value!.mesor, + amplitude: amplitude ?? base.value!.amplitude, + acrophaseRad: rad ?? base.value!.acrophaseRad, + acrophaseHours: hours ?? base.value!.acrophaseHours, + periodHours: base.value!.periodHours, + r2: r2 ?? base.value!.r2, + r2Adj: r2Adj ?? base.value!.r2Adj, + amplitudeP: amplitudeP ?? base.value!.amplitudeP, + ), + confidence: confidence ?? base.confidence, + tier: base.tier, + inputs_used: base.inputs_used, + note: base.note, + ); + + test('identical metrics are equal', () { + expect(_diff(with_(), base), isNull); + }); + test('r2 replaced by NaN is reported', () { + expect(_diff(with_(r2: double.nan), base), isNotNull); + expect(_diff(base, with_(r2: double.nan)), isNotNull); + }); + test('every field turned NaN or infinite is reported', () { + for (final bad in [double.nan, double.infinity]) { + expect(_diff(with_(r2Adj: bad), base), isNotNull, reason: 'r2Adj $bad'); + expect(_diff(with_(amplitudeP: bad), base), isNotNull, reason: 'amplitudeP $bad'); + expect(_diff(with_(confidence: bad), base), isNotNull, + reason: 'confidence $bad'); + expect(_diff(with_(rad: bad), base), isNotNull, reason: 'rad $bad'); + expect(_diff(with_(hours: bad), base), isNotNull, reason: 'hours $bad'); + expect(_diff(with_(mesor: bad), base), isNotNull, reason: 'mesor $bad'); + expect(_diff(with_(amplitude: bad), base), isNotNull, + reason: 'amplitude $bad'); + } + }); + }); + + group('narrow phase coverage', () { + // 16 samples in 0.15 h of a 24 h period: the (c, s) design is almost + // collinear. cosinor()'s own 3x3 solve is not trustworthy here, so these + // tests make NO parity claim against cosinor(); they only demand that the + // aggregator agrees with itself across chunking. + TimedValues narrow(int n, {double step = .01}) { + final w = _twoPi / 24; + final t = [for (var i = 0; i < n; i++) step * i]; + return _tv(t, [ + for (final ti in t) 33 + .3 * math.cos(w * ti) + .1 * math.sin(w * ti) + ]); + } + + bool relClose(double a, double b, double tol) => + (a - b).abs() <= tol * math.max(a.abs(), b.abs()); + + test('whole vs split at 8 agree to 1e-9 relative (review case)', () { + final d = narrow(16); + final a = cosinorAggregator(); + final whole = a.run(d); + for (final split in [ + runChunked(a, d, [0, 8, 16]), + runChunked(a, d, [0, 8, 16], copy: true), + runChunkedRight(a, d, [0, 8, 16]), + ]) { + expect(split.present, whole.present, + reason: 'present ${split.present} vs ${whole.present}'); + if (!whole.present) continue; + final g = split.value!, w = whole.value!; + expect(relClose(g.amplitude, w.amplitude, 1e-9), isTrue, + reason: 'amplitude ${g.amplitude} vs ${w.amplitude}'); + expect(relClose(g.mesor, w.mesor, 1e-9), isTrue, + reason: 'mesor ${g.mesor} vs ${w.mesor}'); + } + }); + + test('every single split point of the review case agrees', () { + final d = narrow(16); + final a = cosinorAggregator(); + final whole = a.run(d); + for (var k = 1; k < 16; k++) { + final split = runChunked(a, d, [0, k, 16]); + expect(split.present, whole.present, reason: 'split $k presence'); + if (!whole.present) continue; + expect( + relClose(split.value!.amplitude, whole.value!.amplitude, 1e-9), + isTrue, + reason: 'split $k amplitude ' + '${split.value!.amplitude} vs ${whole.value!.amplitude}'); + expect(relClose(split.value!.mesor, whole.value!.mesor, 1e-9), isTrue, + reason: 'split $k mesor'); + } + }); + + test('narrow-coverage cases are lawful', () { + expectLawful(cosinorAggregator(), [ + _tv([], []), + narrow(16), + narrow(24), + narrow(16, step: .02), + narrow(20, step: .005), + ], equals: _eq); + }); + }); + + // A column of pure rounding residue is not data. With a 24 h period and + // t = 12 i the phase is exactly pi i, so the true sine is 0 at every sample; + // the computed values are tiny, nonzero and arbitrary (sin of fl(pi) * i). The + // cosine column is +-1 and well conditioned, so the design is not collinear in + // the relative sense and used to pass the gate and report an amplitude read + // from that residue. The guard compares the column's centered energy with the + // most rounding can produce at that argument scale (see the aggregator), which + // follows from machine epsilon and the largest argument, not a tuned constant: + // here the residue is about 1e-14 against a floor near 1e-13, and any real + // sine column is many orders above it, so no platform's libm can move this. + group('a column of rounding residue makes the metric absent', () { + const note = 'singular cosinor design (insufficient phase coverage)'; + void expectAbsent(List t, String why) { + final y = [for (var i = 0; i < t.length; i++) 60.0 + 3 * (i % 5)]; + final batch = _tv(t, y); + final agg = cosinorAggregator(); + final half = t.length ~/ 2; + final left = agg.addSlice(agg.empty(), batch, 0, half); + final right = agg.addSlice(agg.empty(), batch, half, batch.length); + for (final (name, result) in [ + ('run', agg.run(batch)), + ('merged', agg.finish(agg.combine(left, right))), + ('batch', cosinor(t, y)), + ]) { + expect(result.present, isFalse, reason: '$why $name'); + expect(result.value, isNull, reason: '$why $name'); + expect(result.note, note, reason: '$why $name'); + } + } + + test('sine column: t = 12 i, period 24 (the true sine is 0)', () { + expectAbsent([for (var i = 0; i < 48; i++) 12.0 * i], 'sine'); + }); + test('cosine column: t = 6 + 12 i (the true cosine is 0)', () { + expectAbsent([for (var i = 0; i < 48; i++) 6.0 + 12.0 * i], 'cosine'); + }); + test('the same holds for a long record, where the argument is large', () { + expectAbsent([for (var i = 0; i < 2000; i++) 12.0 * i], 'long sine'); + }); + test('the guard survives a checkpoint', () { + final t = [for (var i = 0; i < 48; i++) 12.0 * i]; + final y = [for (var i = 0; i < 48; i++) 60.0 + 3 * (i % 5)]; + final batch = _tv(t, y); + final agg = cosinorAggregator(); + final json = jsonDecode(jsonEncode( + agg.encodeState(agg.addSlice(agg.empty(), batch, 0, 24)))); + final back = agg.decodeState(json); + final done = agg.finish(agg.addSlice(back, batch, 24, 48)); + expect(done.present, isFalse); + expect(done.note, note); + }); + test('a negative stored argument scale is refused', () { + final batch = _tv([0, 1, 2, 3], [1, 2, 3, 4]); + final agg = cosinorAggregator(); + final json = jsonDecode(jsonEncode( + agg.encodeState(agg.addSlice(agg.empty(), batch, 0, 4)))) as Map; + expect(() => agg.decodeState(json), returnsNormally); + json['maxArg'] = -1.0; + expect(() => agg.decodeState(json), throwsFormatException); + }); + }); + + // The relative-determinant gate still does its own job: two distinct phases + // only (t = 0 and t = 6, a quarter period apart) make every centered column a + // multiple of the same two-valued indicator, so the design has rank one while + // both columns carry real energy. Each column takes exactly two values (equal + // inputs give equal outputs), so the only noise is the accumulation, about + // 1e-16 relative, four orders under the 1e-12 gate. + test('two phases only: rank one, caught by the determinant gate', () { + final t = [for (var i = 0; i < 16; i++) i.isEven ? 0.0 : 6.0]; + final y = [for (var i = 0; i < 16; i++) 60.0 + (i.isEven ? 0.0 : 5.0) + i * 0.01]; + final batch = _tv(t, y); + final agg = cosinorAggregator(); + final left = agg.addSlice(agg.empty(), batch, 0, 8); + final right = agg.addSlice(agg.empty(), batch, 8, 16); + for (final result in [ + agg.run(batch), + agg.finish(agg.combine(left, right)), + cosinor(t, y) + ]) { + expect(result.present, isFalse); + expect(result.note, + 'singular cosinor design (insufficient phase coverage)'); + } + }); +} diff --git a/test/aggregate/ctl_atl_aggregator_test.dart b/test/aggregate/ctl_atl_aggregator_test.dart new file mode 100644 index 0000000..ff540a3 --- /dev/null +++ b/test/aggregate/ctl_atl_aggregator_test.dart @@ -0,0 +1,383 @@ +// ctlAtlTsbAggregator must agree with ctlAtlTsb for the same daily series under +// any slicing or chunking, and obey the aggregator laws. +// +// Contract used here: +// * ctlAtlTsbAggregator({ctlDays = 42, atlDays = 7, minDays = ctlAtlMinDays, +// primeDays = 7}) is an Aggregator<_, DoubleColumn, Metric>; +// the column is daily TRIMP, oldest first. Exported from +// package:openstrap_analytics/aggregate.dart. +// * Fewer rows than minDays: absent, with the reference's note (the +// needBaselineNote), tier and inputs_used. +// * Otherwise ctl / atl / tsb within relTol 1e-9 (absTol 1e-9); confidence, +// tier, inputs_used and note (which interpolates the prime count +// min(max(primeDays, 1), rows)) are exactly equal. +// * Unknown/non-finite daily loads abstain; an observed rest day is zero. +// minDays < 1 is out of scope (the reference throws on an empty +// series with minDays 0). +// * primeDays 0 behaves as 1 (reference clamps), primeDays > rows as rows. +// * Constructing the aggregator never throws for the parameters below. + +import 'dart:math' as math; +import 'dart:typed_data'; + +import 'package:openstrap_analytics/aggregate.dart'; +import 'package:openstrap_analytics/onehz.dart'; +import 'package:test/test.dart'; + +import '../support/checkpoint_support.dart'; +import '../support/aggregator_laws.dart'; +import '../support/property.dart' show Rng; + +typedef _Agg = Aggregator>; + +List _fields(Metric m) => [ + m.present, + m.value?.ctl, + m.value?.atl, + m.value?.tsb, + m.tier, + m.inputs_used.join(','), + m.note, + ]; + +final _eq = fieldsEqual>(_fields, relTol: 1e-9, absTol: 1e-9); + +/// _same, as a predicate: the fields within tolerance, confidence exact. +bool _eqExact(Metric got, Metric want) => + _eq(got, want) && got.confidence == want.confidence; + +void _same(Metric got, Metric want, String tag) { + expect(_eq(got, want), isTrue, + reason: '$tag\n got ${_fields(got)}\nwant ${_fields(want)}'); + expect(got.confidence, want.confidence, reason: '$tag confidence'); + expect(got.note, want.note, reason: '$tag note'); +} + +/// The reference: CTL / ATL / TSB written out one day at a time, not through +/// `ctlAtlTsb`, which now runs the aggregator (and whose recurrence the +/// aggregator evaluates as an affine map, a different computation). +/// +/// Banister et al. 1975: an exponentially weighted moving average, +/// x[t] = x[t-1] + lambda * (v[t] - x[t-1]), lambda = 1 - exp(-1 / days), +/// 42 days for chronic load, 7 for acute. Both start at the plain mean of the +/// first `primeDays` observed days (never one day, never later days) and then +/// take each remaining day in turn; TSB = CTL - ATL. Below `minDays`, or for any +/// non-finite load, it abstains. +Metric _referenceCtlAtl(List daily, + {double ctlDays = 42, + double atlDays = 7, + int minDays = ctlAtlMinDays, + int primeDays = 7}) { + const inputs = ['daily_trimp']; + if (daily.any((v) => !v.isFinite)) { + return const Metric.absent( + tier: Tier.estimate, + inputs_used: inputs, + note: 'non-finite daily TRIMP', + ); + } + if (daily.length < minDays) { + return Metric.absent( + tier: Tier.estimate, + inputs_used: inputs, + note: 'need_baseline:have=${daily.length},need=$minDays', + ); + } + final prime = math.min(math.max(primeDays, 1), daily.length); + var seed = 0.0; + for (var i = 0; i < prime; i++) { + seed += daily[i]; + } + seed /= prime; + final lambdaCtl = 1 - math.exp(-1 / ctlDays); + final lambdaAtl = 1 - math.exp(-1 / atlDays); + var ctl = seed, atl = seed; + for (var i = prime; i < daily.length; i++) { + ctl += lambdaCtl * (daily[i] - ctl); + atl += lambdaAtl * (daily[i] - atl); + } + return Metric( + value: LoadState(ctl, atl, ctl - atl), + confidence: (daily.length / 42.0).clamp(0.3, 0.85), + tier: Tier.estimate, + inputs_used: inputs, + note: 'Banister CTL(42d)/ATL(7d)/TSB, primed from the first $prime observed ' + 'days; descriptive load, not injury risk', + ); +} + +class _P { + const _P(this.name, {this.ctl = 42, this.atl = 7, this.min = ctlAtlMinDays, this.prime = 7}); + final String name; + final double ctl, atl; + final int min, prime; + _Agg get agg => ctlAtlTsbAggregator( + ctlDays: ctl, atlDays: atl, minDays: min, primeDays: prime); + Metric want(DoubleColumn c) => _referenceCtlAtl(c.values.toList(), + ctlDays: ctl, atlDays: atl, minDays: min, primeDays: prime); +} + +const _params = [ + _P('default'), + _P('custom time constants', ctl: 30, atl: 5, min: 10, prime: 5), + _P('minDays < primeDays', min: 3, prime: 10), + _P('minDays 1, primeDays 7', min: 1), + _P('primeDays 1', prime: 1), + _P('primeDays 0 acts as 1', prime: 0), + _P('primeDays 14 = minDays', prime: 14), + _P('primeDays > minDays', min: 5, prime: 30), +]; + +void _allPaths(_Agg a, DoubleColumn c, List b, Metric want, + String tag) { + _same(runChunked(a, c, b), want, '$tag chunks $b'); + _same(runChunked(a, c, b, copy: true), want, '$tag copies $b'); + _same(runChunkedRight(a, c, b), want, '$tag right $b'); + _same(runSliced(a, c, b), want, '$tag sliced $b'); +} + +/// A daily-TRIMP-like series: rest days (0), spikes, ordinary workouts. +DoubleColumn _series(Rng r, int n) => DoubleColumn(Float64List.fromList([ + for (var i = 0; i < n; i++) + r.nextBool(.25) + ? 0.0 + : r.nextBool(.05) + ? 300 + r.nextDouble() * 9000 + : r.nextDouble() * 250 + ])); + +void main() { + _referenceChecks(); + group('absent below minDays', () { + test('identical to the reference for every short length', () { + for (final p in _params) { + final cols = [ + for (var n = 0; n < p.min && n < 16; n++) + col([for (var i = 0; i < n; i++) 10.0 + i]) + ]; + for (final c in cols) { + expect(p.want(c).present, isFalse, reason: '${p.name} n=${c.length}'); + } + expectConversion>( + (_) => p.agg, cols, p.want, + equals: _eqExact); + } + }); + + test('empty state is absent for minDays >= 1', () { + final a = ctlAtlTsbAggregator(); + _same(a.finish(a.empty()), _referenceCtlAtl([]), 'empty state'); + _same(a.run(col([])), _referenceCtlAtl([]), 'empty column'); + }); + + test('length minDays - 1 absent, minDays present (default)', () { + final a = ctlAtlTsbAggregator(); + expect(a.run(_iotaCol(13)).present, isFalse); + expect(a.run(_iotaCol(14)).present, isTrue); + expect(a.run(_iotaCol(14)).note, + contains('primed from the first 7 observed days')); + }); + }); + + group('values', () { + test('constant series: ctl = atl = the constant, tsb 0', () { + final c = col(List.filled(60, 120.0)); + final got = ctlAtlTsbAggregator().run(c); + expect(got.value!.ctl, closeTo(120, 1e-9)); + expect(got.value!.atl, closeTo(120, 1e-9)); + expect(got.value!.tsb, closeTo(0, 1e-9)); + _same(got, _referenceCtlAtl(c.values.toList()), 'constant'); + }); + + test('exactly primeDays == rows: the value is the mean', () { + final p = const _P('p', min: 3, prime: 4); + final c = col([10, 20, 30, 40]); + final got = p.agg.run(c); + expect(got.value!.ctl, closeTo(25, 1e-12)); + expect(got.value!.atl, closeTo(25, 1e-12)); + _same(got, p.want(c), 'mean'); + }); + + test('fewer rows than primeDays: prime is the row count', () { + final p = const _P('p', min: 3, prime: 10); + final c = col([4, 8, 12, 16, 20]); + final got = p.agg.run(c); + expect(got.note, contains('first 5 observed days')); + _same(got, p.want(c), 'short prime'); + }); + + test('primeDays 0 and 1 seed from the first day', () { + for (final prime in [0, 1]) { + final p = _P('p', min: 2, prime: prime); + final c = col([100, 0, 0, 0, 50, 0, 0, 0, 0, 0]); + _same(p.agg.run(c), p.want(c), 'prime $prime'); + expect(p.agg.run(c).note, contains('first 1 observed days')); + } + }); + + test('rest days decay the load: all-zero tail', () { + final c = col([200, 200, 200, 200, 200, 200, 200, ...List.filled(40, 0.0)]); + final got = ctlAtlTsbAggregator().run(c); + _same(got, _referenceCtlAtl(c.values.toList()), 'decay'); + expect(got.value!.atl, lessThan(got.value!.ctl)); + expect(got.value!.tsb, greaterThan(0)); + }); + + test('a single spike on the last day', () { + final xs = [...List.filled(30, 50.0), 5000.0]; + final c = col(xs); + _same(ctlAtlTsbAggregator().run(c), _referenceCtlAtl(xs), 'spike'); + }); + + test('confidence is exact: rows/42 clamped to 0.3..0.85', () { + final a = ctlAtlTsbAggregator(); + expect(a.run(_iotaCol(14)).confidence, _referenceCtlAtl(_iotaCol(14).values.toList()).confidence); + expect(a.run(_iotaCol(30)).confidence, 30 / 42.0); + expect(a.run(_iotaCol(300)).confidence, 0.85); + }); + }); + + group('random parity (seeded)', () { + for (final p in _params) { + test(p.name, () { + final r = Rng(0xC71 + p.name.length * 31 + p.min * 7 + p.prime); + final cols = []; + for (var t = 0; t < 30; t++) { + final n = r.nextBool(.2) ? r.intIn(0, 20) : r.intIn(0, 200); + cols.add(_series(r, n)); + } + expectConversion>( + (_) => p.agg, cols, p.want, + equals: _eqExact); + }); + } + + test('constant series of random lengths and values', () { + final r = Rng(0xC72); + final cols = []; + for (var t = 0; t < 30; t++) { + final n = r.intIn(0, 120); + final v = r.nextBool(.3) ? 0.0 : r.nextDouble() * 400; + cols.add(col(List.filled(n, v))); + } + expectConversion>( + (_) => ctlAtlTsbAggregator(), cols, (c) => _referenceCtlAtl(c.values.toList()), + equals: _eqExact); + }); + + test('chunks straddle the prime boundary (primeDays 7)', () { + final r = Rng(0xC73); + final a = ctlAtlTsbAggregator(); + final c = _series(r, 40); + final want = _referenceCtlAtl(c.values.toList()); + for (final cut in [1, 2, 6, 7, 8, 13, 14, 15]) { + _allPaths(a, c, [0, cut, 40], want, 'cut $cut'); + _allPaths(a, c, [0, 3, cut > 3 ? cut : 3, 40], want, 'cuts 3,$cut'); + } + }); + }); + + test('persistable: a mid-stream checkpoint resumes to the one-pass result', () { + final c = _series(Rng(0xC0DE), 60); + for (final p in [_params[0], _params[2]]) { + expectCheckpointResumes(p.agg, c, equals: _eq); + } + }); + + group('lawful', () { + final cols = [ + ...randomColumns(0xC74, nanP: 0, maxLen: 60, value: (r) => r.nextDouble() * 300), + for (final n in [13, 14, 15, 21, 22]) _iotaCol(n), + ]; + for (final p in [_params[0], _params[2], _params[5]]) { + test(p.name, () => expectLawful(p.agg, cols, equals: _eq)); + } + }); + + group('composition', () { + test('both(...) and map still work around it', () { + final a = both(ctlAtlTsbAggregator(), Count()) + .map((r) => (r.$1.present, r.$2)); + expect(a.run(_iotaCol(20)), (true, 20)); + expect(a.run(_iotaCol(5)), (false, 5)); + }); + }); + + group('checkpoint relationships (day count against the primed prefix)', () { + final agg = ctlAtlTsbAggregator(); // primeDays 7 + // State: [[days, finiteDays], {rows: , tail: [..]}]. + Object? set(Object? s, int days) { + (s as List)[0] = [days, days]; + return s; + } + + test('a day count below the prefix rows held is refused', () { + expectDamagedCheckpointRefused(agg, _iotaCol(10), (s) => set(s, 5)); + expectDamagedCheckpointRefused(agg, _iotaCol(10), (s) => set(s, 0)); + }); + test('a day count above what the prefix rows allow is refused', () { + expectDamagedCheckpointRefused(agg, _iotaCol(3), (s) => set(s, 9)); + expectDamagedCheckpointRefused(agg, _iotaCol(3), (s) => set(s, 4)); + }); + test('days with no prefix rows are refused', () { + expectDamagedCheckpointRefused(agg, _iotaCol(10), (s) { + (((s as List)[1]) as Map)['rows'] = null; + return s; + }); + }); + test('prefix rows with no days are refused', () { + expectDamagedCheckpointRefused(agg, _iotaCol(3), (s) => set(s, 0)); + }); + test('consistent checkpoints still restore', () { + for (final n in [0, 1, 6, 7, 8, 20]) { + final b = _iotaCol(n); + expect( + decodeCheckpoint(agg, checkpointOf(agg, b), + kind: 'test', version: 1), + isNotNull, + reason: 'n=$n'); + } + }); + }); +} + +DoubleColumn _iotaCol(int n) => col([for (var i = 0; i < n; i++) 5.0 + i * 3]); + +/// The reference itself, and the public batch function against it. +void _referenceChecks() { + // Seven days at 10 prime both loads at 10; seven days at 20 then move each by + // x = 10 + (1 - exp(-7 / days)) * 10 + // because (1 - lambda)^7 = exp(-7 / days). So CTL (42 d) and ATL (7 d) are + // 10 + 10 * (1 - exp(-1/6)) and 10 + 10 * (1 - exp(-1)). + test('the reference gives the hand-computed step response', () { + final day = [...List.filled(7, 10.0), ...List.filled(7, 20.0)]; + final m = _referenceCtlAtl(day); + expect(m.present, isTrue); + expect(m.value!.ctl, closeTo(10 + 10 * (1 - math.exp(-1 / 6)), 1e-12)); + expect(m.value!.atl, closeTo(10 + 10 * (1 - math.exp(-1)), 1e-12)); + expect(m.value!.tsb, closeTo(m.value!.ctl - m.value!.atl, 1e-15)); + }); + + // The public batch function now runs the aggregator; it must still equal the + // independent reference, for every parameter set and random series. + test('ctlAtlTsb agrees with the day-by-day reference', () { + final r = Rng(0xC71); + for (final p in _params) { + for (var k = 0; k < 15; k++) { + final v = _series(r, r.intIn(0, 120)).values.toList(); + _same( + ctlAtlTsb(v, + ctlDays: p.ctl, + atlDays: p.atl, + minDays: p.min, + primeDays: p.prime), + _referenceCtlAtl(v, + ctlDays: p.ctl, + atlDays: p.atl, + minDays: p.min, + primeDays: p.prime), + '${p.name} $k'); + } + } + }); +} diff --git a/test/aggregate/readiness_lnrmssd_aggregator_test.dart b/test/aggregate/readiness_lnrmssd_aggregator_test.dart new file mode 100644 index 0000000..4296571 --- /dev/null +++ b/test/aggregate/readiness_lnrmssd_aggregator_test.dart @@ -0,0 +1,407 @@ +// readinessLnRmssdAggregator (Count + LastRows(windowDays + 1)) must reproduce +// the reference EXACTLY (every field, bit for bit), and the public +// readinessLnRmssd, which delegates to it, must too. `_reference` is a frozen +// copy of upstream main 9db83ce, including small-window band calibration. +// +// windowDays <= 0 decision. The reference with windowDays 0 keeps an empty +// prior window, so it returns the absent metric (need minNights + 1) and +// LastRows(1) can express that: windowDays 0 is checked on the aggregator +// like any other. With windowDays -1 the reference computes start = n, then +// sublist(n, n - 1) throws RangeError (once n >= minNights; shorter +// histories are absent first). LastRows(0) cannot be built, so the aggregator +// is NOT required to exist for windowDays < 0: the public function keeps the +// reference path there and must behave identically, throw included. + + +import 'dart:math' as math; + +import 'package:openstrap_analytics/aggregate.dart'; +import 'package:openstrap_analytics/onehz.dart'; +import 'package:test/test.dart'; + +import '../support/aggregator_laws.dart'; +import '../support/checkpoint_support.dart'; +import '../support/property.dart' show Rng; + +Metric _reference( + List historyLnRmssd, { + List? dates, + double? meanNnTodayMs, + int windowDays = 7, + int minNights = readinessLnRmssdMinNights, +}) { + const inputs = ['ln_rmssd_history']; + if (historyLnRmssd.length < minNights) { + return Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: needBaselineNote(have: historyLnRmssd.length, need: minNights), + ); + } + final today = historyLnRmssd.last; + final n = historyLnRmssd.length; + final start = n - 1 - windowDays < 0 ? 0 : n - 1 - windowDays; + // this used to be historyLnRmssd.sublist(start), which runs to the END of + // the list - including tonight's own value in its own baseline. that + // pulls the mean/sd toward tonight, understating how far off a genuinely + // suppressed/elevated night actually is, worst right when the window is + // smallest (minNights). the baseline has to be strictly prior nights. + final List priorWindow; + // all-or-nothing: calendarDays falls back to the row index for a label it + // can't parse, and an index compared against epoch days is meaningless. + if (dates != null && + dates.length == n && + dates.every((d) => DateTime.tryParse(d) != null)) { + final day = calendarDays(dates); + priorWindow = [ + for (var i = 0; i < n - 1; i++) + if (day[i] < day[n - 1] && day[n - 1] - day[i] <= windowDays) + historyLnRmssd[i] + ]; + } else { + priorWindow = historyLnRmssd.sublist(start, n - 1); + } + if (priorWindow.isEmpty || priorWindow.length < minNights - 1) { + // empty only if minNights got set to 1 somewhere; short when a wear gap + // left too few nights inside the calendar window. either way there's no + // baseline yet, same as not enough history. + return Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: needBaselineNote( + have: priorWindow.length + 1, need: minNights < 2 ? 2 : minNights), + ); + } + final m = mean(priorWindow)!; + final sd = stddev(priorWindow); + if (sd == null || m == 0) { + // The published outputs of this stack (CV, SWC, band) are all defined + // RELATIVE to the baseline's dispersion. With a single prior night the SD + // is UNDEFINED — and the metric used to fill in cvPct 0.0 and band + // 'normal', asserting "tonight is typical" on the strength of nothing at + // all. Abstain instead (a zero-but-DEFINED SD is a different case: CV is + // genuinely 0 and SWC is genuinely 0, so that still computes below). + return Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'lnRMSSD baseline dispersion undefined (needs ≥2 prior nights) — ' + 'CV/z/SWC/band are undefined', + ); + } + final cv = (sd / m).abs() * 100; + // ROBUST CENTRE AND SPREAD for the decision band. One illness night in a + // seven-night window both drags the mean down and inflates the SD, so a + // genuinely low night reads "normal": on a real window holding a 35.5 ms + // night, mean 4.465 / SD 0.405 put a 4.478 night (88 ms) inside the band, + // while the other six nights sat at 4.40–4.79. Median + MAD (×1.4826) are + // what the window looks like without that one night. MAD collapses only when + // more than half the window is identical; the SD stands in then. The CV + // above stays the classic SD/mean (Plews' published CV). + final centre = median(priorWindow)!; + final robustSd = mad(priorWindow)!; + final spread = robustSd > 0 ? robustSd : sd; + final z = spread > 0 ? (today - centre) / spread : null; + // Plews SWC ≈ 0.5 × within-window SD (a small worthwhile change in lnRMSSD). + final swc = 0.5 * spread; + + // The band is a SINGLE-NIGHT decision, so its threshold has to be a + // single-night one: tonight outside centre ± 1 × spread, Kiviniemi 2007's + // daily reference value (baseline mean ± SD). The SWC above (0.5 × spread) + // is Plews' threshold for a 7-day ROLLING mean, where averaging has already + // cut night-to-night noise by ~1/sqrt(7); applied to one night it sits inside + // ordinary noise and a user whose HRV never changed read 'suppressed' or + // 'elevated' on ~70% of nights. Comparing a rolling mean instead does not + // work against this baseline: the week being tested is six-sevenths the same + // nights the centre comes from, so a real multi-night drop drags the centre + // with it and goes unflagged, and one old bad night keeps an ordinary + // tonight 'suppressed' for the rest of the week. At zero spread any + // departure from the centre is outside the band. + // + // "± 1 SD" only means a ~32% flag rate when the centre and spread are known. + // Here they come from 3-7 prior nights: the median misses the true level and + // the MAD of so few points is biased low and noisy, so a user whose HRV + // never changed still read 'suppressed'/'elevated' on 62% of nights with 3 + // prior nights and 45% with 7. [_lnRmssdBandWidening] restores the intended + // single-night rate for the window size actually used. + final halfWidth = spread * _lnRmssdBandWidening(priorWindow.length); + final String band; + if (today < centre - halfWidth) { + band = 'suppressed'; + } else if (today > centre + halfWidth) { + band = 'elevated'; + } else { + band = 'normal'; + } + + // LnRMSSD:RR saturation guard: when mean NN is long (low HR, high vagal tone) + // and lnRMSSD is at the top of the personal range, the metric saturates. + final saturation = + meanNnTodayMs != null && meanNnTodayMs > 1100 && z != null && z > 1.0; + + final conf = (priorWindow.length / windowDays.toDouble()).clamp(0.3, 0.9); + return Metric( + value: ReadinessLnRmssd( + lnRmssdToday: today, + rolling7Mean: m, + rolling7Median: centre, + cvPct: cv, + z: z, + swc: swc, + band: band, + saturationFlag: saturation, + ), + confidence: conf, + tier: Tier.high, + inputs_used: inputs, + note: saturation + ? 'lnRMSSD:RR saturation — high-HRV interpretation caution' + : 'Plews/Kiviniemi whole-night lnRMSSD readiness; PRV', + ); +} + +/// Half-width of the single-night band in units of the baseline's robust SD +/// (MAD × 1.4826), by number of prior nights. Each entry is the empirical +/// 68.27th percentile of |tonight − median| / (MAD × 1.4826) when tonight and +/// the prior nights are drawn from one fixed normal distribution (400k trials +/// per n), so a stable user lands outside the band on ~31.7% of nights, +/// Kiviniemi's mean ± SD rate with known parameters. It folds in both the +/// prediction-interval term for a new observation (√(1 + 1/n)) and the small-n +/// bias and noise of the MAD; 3 is above 2 because the MAD of three points is +/// 1.4826 × the smaller non-median deviation and runs especially small. +/// Interpolated log-linearly in n; past the last anchor it decays toward 1 as +/// 1/n, since the MAD then converges to σ. +const List<(int, double)> _lnRmssdBandWideningTable = [ + (2, 2.144), + (3, 2.851), + (4, 1.884), + (5, 1.687), + (6, 1.487), + (7, 1.418), + (8, 1.334), + (10, 1.257), + (14, 1.172), + (20, 1.119), + (28, 1.085), + (45, 1.051), + (90, 1.025), +]; + +double _lnRmssdBandWidening(int n) { + final first = _lnRmssdBandWideningTable.first; + final last = _lnRmssdBandWideningTable.last; + if (n <= first.$1) return first.$2; + if (n >= last.$1) return 1 + (last.$2 - 1) * last.$1 / n; + for (var i = 1; i < _lnRmssdBandWideningTable.length; i++) { + final (n1, f1) = _lnRmssdBandWideningTable[i]; + if (n > n1) continue; + final (n0, f0) = _lnRmssdBandWideningTable[i - 1]; + final t = (math.log(n) - math.log(n0)) / (math.log(n1) - math.log(n0)); + return math.exp(math.log(f0) + t * (math.log(f1) - math.log(f0))); + } + return 1.0; +} + +List _fields(Metric m) { + final v = m.value; + return [ + m.present, m.confidence, m.tier, m.inputs_used.join(','), m.note, + m.drivers, v?.lnRmssdToday, v?.rolling7Mean, v?.rolling7Median, v?.cvPct, v?.z, v?.swc, + v?.band, v?.saturationFlag, + ]; +} + +final _same = fieldsEqual>(_fields); + +DoubleColumn _hist(Rng r, int n, int style) => col([ + for (var i = 0; i < n; i++) + switch (style) { + 0 => 3.0 + r.nextDouble() * 2.0, + 1 => 4.2, // constant: sd == 0 + 2 => 0.0, // zeros: m == 0 + _ => r.nextBool(.3) ? 0.0 : 3.0 + r.nextDouble() * 2.0, + } + ]); + +List _cases(int seed) { + final r = Rng(seed); + return [ + for (var n = 0; n <= 40; n++) _hist(r, n, n % 4), + for (var n = 1; n <= 12; n++) _hist(r, n, 0), + for (var n = 3; n <= 20; n += 4) _hist(r, n, 1), + for (var n = 3; n <= 20; n += 4) _hist(r, n, 2), + ]; +} + +void main() { + group('parity with the reference', () { + for (final w in [0, 1, 3, 7, 14]) { + for (final nn in [null, 900.0, 1200.0]) { + test('windowDays=$w meanNn=$nn, minNights 1/2/4/6', () { + for (final mn in [1, 2, 4, 6]) { + expectConversion>( + (_) => readinessLnRmssdAggregator( + meanNnTodayMs: nn, windowDays: w, minNights: mn), + _cases(w * 31 + mn), + (b) => _reference(b.values.toList(), + meanNnTodayMs: nn, windowDays: w, minNights: mn), + equals: _same, + chunkings: 3, + seed: w + mn, + ); + } + }); + } + } + }); + + group('public readinessLnRmssd equals the reference', () { + for (final w in [0, 1, 3, 7, 14]) { + test('windowDays=$w', () { + for (final nn in [null, 900.0, 1200.0]) { + for (final mn in [1, 2, 4, 6]) { + for (final b in _cases(w + 500)) { + final h = b.values.toList(); + final got = readinessLnRmssd(h, + meanNnTodayMs: nn, windowDays: w, minNights: mn); + final want = _reference(h, + meanNnTodayMs: nn, windowDays: w, minNights: mn); + expect(_same(got, want), isTrue, + reason: 'n=${h.length} mn=$mn: $got vs $want'); + } + } + } + }); + } + test('default arguments', () { + for (final b in _cases(9)) { + final h = b.values.toList(); + expect(_same(readinessLnRmssd(h), _reference(h)), isTrue); + } + }); + test('windowDays=-1: absent when short, RangeError otherwise, as before', + () { + for (final b in _cases(3)) { + final h = b.values.toList(); + Object? run(Metric Function() f) { + try { + return f(); + } on RangeError { + return 'RangeError'; + } + } + + final got = run(() => readinessLnRmssd(h, windowDays: -1)); + final want = run(() => _reference(h, windowDays: -1)); + if (want is String) { + expect(got, want, reason: 'n=${h.length}'); + expect(h.length >= readinessLnRmssdMinNights, isTrue); + } else { + expect(got, isA>()); + expect( + _same(got as Metric, + want as Metric), + isTrue); + } + } + }); + }); + + test('persistable: a mid-stream checkpoint resumes to the one-pass result', + () { + final agg = readinessLnRmssdAggregator(meanNnTodayMs: 1200); + expect(agg.persistable, isTrue); + expectCheckpointResumes(agg, _hist(Rng(0x12), 30, 0), equals: _same); + }); + + group('checkpoint relationships (count against the kept rows)', () { + final agg = readinessLnRmssdAggregator(windowDays: 7); // keeps 8 rows + Metric? restore(Object? state) { + final got = decodeCheckpoint( + agg, {'kind': 'k', 'version': 1, 'state': state}, + kind: 'k', version: 1); + return got == null ? null : agg.finish(got); + } + + test('review case: count 4 with no rows is refused', () { + // Used to decode, then finish threw on the missing rows. + expect( + decodeCheckpoint( + agg, + { + 'kind': 'k', + 'version': 1, + 'state': [4, {'rows': null}] + }, + kind: 'k', + version: 1), + isNull); + }); + test('count 0 with rows present is refused', () { + final rows = ((checkpointOf(agg, _hist(Rng(1), 3, 0))['state'] as List)[1] + as Map)['rows']; + expect(restore([0, {'rows': rows}]), isNull); + }); + test('count that disagrees with the number of kept rows is refused', () { + final long = _hist(Rng(2), 30, 0); + // 30 nights keep 8 rows; claiming 5 (or 3 nights holding 8) is damage. + expectDamagedCheckpointRefused(agg, long, (s) { + (s as List)[0] = 5; + return s; + }); + expectDamagedCheckpointRefused(agg, long, (s) { + (s as List)[0] = 0; + return s; + }); + final short = _hist(Rng(3), 5, 0); // keeps all 5 + expectDamagedCheckpointRefused(agg, short, (s) { + (s as List)[0] = 9; + return s; + }); + expectDamagedCheckpointRefused(agg, short, (s) { + (s as List)[0] = 4; + return s; + }); + }); + test('a consistent checkpoint still restores', () { + for (final n in [0, 1, 5, 8, 9, 30]) { + final b = _hist(Rng(n), n, 0); + final got = decodeCheckpoint(agg, checkpointOf(agg, b), + kind: 'test', version: 1); + expect(got, isNotNull, reason: 'n=$n'); + expect(_same(agg.finish(got), agg.run(b)), isTrue); + } + }); + }); + + group('reads only the suffix of the history', () { + test('an unused prefix element is never read', () { + // Element 0 is not a double; only the last windowDays + 1 are read. + final h = ['unused', 3.0, 4.0, 5.0, 6.0].cast(); + final got = readinessLnRmssd(h, windowDays: 3); + final want = _reference(h, windowDays: 3); + expect(want.present, isTrue); + expect(_same(got, want), isTrue, reason: '$got vs $want'); + }); + test('a too-short history is refused without reading any element', () { + final h = ['a', 'b'].cast(); + final got = readinessLnRmssd(h); + expect(got.present, isFalse); + expect(got.note, needBaselineNote(have: 2, need: readinessLnRmssdMinNights)); + }); + }); + + group('windowDays at the int limit', () { + const huge = 0x7fffffffffffffff; + final h = [3.0, 4.0, 5.0, 6.0]; + test('the public function matches the reference', () { + final got = readinessLnRmssd(h, windowDays: huge); + expect(_same(got, _reference(h, windowDays: huge)), isTrue); + expect(got.present, isTrue); + }); + test('the aggregator matches the reference and resumes', () { + final agg = readinessLnRmssdAggregator(windowDays: huge); + expect(_same(agg.run(col(h)), _reference(h, windowDays: huge)), isTrue); + expectCheckpointResumes(agg, col(h), equals: _same); + }); + }); +} diff --git a/test/aggregate/review_input_refusals_test.dart b/test/aggregate/review_input_refusals_test.dart new file mode 100644 index 0000000..e2f3752 --- /dev/null +++ b/test/aggregate/review_input_refusals_test.dart @@ -0,0 +1,140 @@ +import 'dart:convert'; +import 'dart:math' as math; +import 'dart:typed_data'; + +import 'package:openstrap_analytics/aggregate.dart'; +import 'package:openstrap_analytics/onehz.dart'; +import 'package:test/test.dart'; + +// why: batch guards alone leave chunked, combined and restored states unsafe. +// proves: CLAIM(review-input-refusals) +// catches: keeping the old aggregator finalizers while fixing only batch APIs. +Map _paths, R>( + Aggregator agg, B batch) { + final split = batch.length ~/ 2; + final saved = + jsonDecode(jsonEncode(agg.encodeState(agg.fold(batch, 0, split)))); + return { + 'one slice': agg.run(batch), + 'successive slices': agg.finish( + agg.addSlice(agg.fold(batch, 0, split), batch, split, batch.length)), + 'combined': agg.finish(agg.combine( + agg.fold(batch, 0, split), agg.fold(batch, split, batch.length))), + 'restored': agg.finish( + agg.addSlice(agg.decodeState(saved), batch, split, batch.length)), + }; +} + +void _refuses(Map> results, String note) { + for (final entry in results.entries) { + expect(entry.value.value, isNull, reason: entry.key); + expect(entry.value.present, isFalse, reason: entry.key); + expect(entry.value.note, note, reason: entry.key); + } +} + +TimedValues _signal() => TimedValues( + Float64List.fromList([for (var i = 0; i < 48; i++) i.toDouble()]), + Float64List.fromList([ + for (var i = 0; i < 48; i++) 60 + 4 * math.cos(2 * math.pi * i / 24), + ])); + +void main() { + test('finite cosinor remains measurable through every streaming path', () { + // Independent oracle: y = 60 + 4*cos(2*pi*t/24) has MESOR 60, amplitude 4. + for (final result in _paths(cosinorAggregator(), _signal()).values) { + expect(result.value!.mesor, closeTo(60, 1e-12)); + expect(result.value!.amplitude, closeTo(4, 1e-12)); + } + }); + + test('invalid cosinor periods refuse even with insufficient observations', + () { + for (final period in [ + 0.0, + -24.0, + double.nan, + double.infinity, + double.negativeInfinity + ]) { + final agg = cosinorAggregator(periodHours: period); + for (final batch in [_signal(), _signal().copyRange(0, 3)]) { + _refuses(_paths(agg, batch), 'invalid cosinor period'); + } + _refuses({'empty': agg.finish(agg.empty())}, 'invalid cosinor period'); + } + }); + + test('subnormal cosinor period refuses its overflowing design', () { + _refuses(_paths(cosinorAggregator(periodHours: 1e-320), _signal()), + 'non-finite cosinor design'); + }); + + test('non-finite time and response poison either side of a cosinor merge', + () { + for (final bad in [double.nan, double.infinity, double.negativeInfinity]) { + for (final index in [0, 12, 47]) { + for (final axis in ['time', 'response']) { + final batch = _signal(); + (axis == 'time' ? batch.tHours : batch.y)[index] = bad; + _refuses( + _paths(cosinorAggregator(), batch), 'non-finite cosinor design'); + } + } + } + }); + + test('finite response overflow refuses non-finite cosinor moments', () { + final batch = _signal(); + for (var i = 0; i < batch.length; i++) { + batch.y[i] = i.isEven ? 1e308 : -1e308; + } + _refuses(_paths(cosinorAggregator(), batch), 'non-finite cosinor design'); + }); + + test('unknown daily TRIMP refuses in prime, tail and short history', () { + // NaN is unknown, never an observed rest day. Infinities are invalid load. + for (final bad in [double.nan, double.infinity, double.negativeInfinity]) { + for (final index in [0, 6, 7, 13]) { + final batch = DoubleColumn( + Float64List.fromList(List.filled(14, 50)..[index] = bad)); + _refuses( + _paths(ctlAtlTsbAggregator(), batch), 'non-finite daily TRIMP'); + } + final short = DoubleColumn(Float64List.fromList([50, bad, 50])); + _refuses(_paths(ctlAtlTsbAggregator(), short), 'non-finite daily TRIMP'); + } + }); + + test('load checkpoints without validity evidence are refused', () { + // Old checkpoints may already have skipped unknown load. Refusing them + // forces a replay instead of asserting that all prior days were observed. + final agg = ctlAtlTsbAggregator(); + final batch = DoubleColumn(Float64List.fromList(List.filled(14, 50.0))); + final state = + jsonDecode(jsonEncode(agg.encodeState(agg.fold(batch)))) as List; + state[0] = 14; + expect(() => agg.decodeState(state), throwsFormatException); + }); + + test('load checkpoints cannot claim more finite days than observed days', () { + final agg = ctlAtlTsbAggregator(); + final batch = DoubleColumn(Float64List.fromList(List.filled(14, 50.0))); + final state = + jsonDecode(jsonEncode(agg.encodeState(agg.fold(batch)))) as List; + state[0] = [14, 15]; + expect(() => agg.decodeState(state), throwsFormatException); + }); + + test('observed zero-load days decay through every streaming path', () { + // Seven 50-load days prime at 50; seven zero-load days give 50*exp(-7/tau). + final batch = DoubleColumn(Float64List.fromList([ + ...List.filled(7, 50), + ...List.filled(7, 0), + ])); + for (final result in _paths(ctlAtlTsbAggregator(), batch).values) { + expect(result.value!.ctl, closeTo(42.3240862445307, 1e-12)); + expect(result.value!.atl, closeTo(18.3939720585721, 1e-12)); + } + }); +} diff --git a/test/aggregate/sri_aggregator_test.dart b/test/aggregate/sri_aggregator_test.dart new file mode 100644 index 0000000..bffc41d --- /dev/null +++ b/test/aggregate/sri_aggregator_test.dart @@ -0,0 +1,684 @@ +// Epochs + sriAggregator, and the public phillipsSri rewired onto them, must +// reproduce upstream main 9db83ce phillipsSri exactly. `_referenceSri` below is a frozen +// copy of that target body, including its pair-coverage publication gate. +// +// Contract used here: +// * Epochs(asleep, {valid, firstIndex = 0}): asleep is 0/1 per epoch, valid +// (optional, 0/1) the mask. The absolute epoch index of row r is +// firstIndex + r. valid == null means every epoch is valid. Exported from +// package:openstrap_analytics/aggregate.dart, with public fields asleep, +// valid (Uint8List?) and firstIndex. +// * copyRange(a, b) returns COPIES (the source can change afterwards) with +// firstIndex shifted by a; a null valid stays null. +// * join(other) requires other.firstIndex == firstIndex + length (assert; an +// AssertionError in debug mode). When exactly one side has a mask, the +// missing side counts as all-valid; the joined batch has a mask then, and +// none when neither side has one. The joined batch is a new, independent +// copy and keeps this.firstIndex. +// * sriAggregator(epochsPerDay, {minPairCases}) is built for epochsPerDay >= 1 +// and run on batches with firstIndex 0 (the whole record, or its chunks cut +// with copyRange / ranges of that one batch). Its result equals +// phillipsSri on the same record (sri bit-identical, days, cases, every +// pair, confidence, tier, inputs_used, note). +// * phillipsSri(sleepWake, epochsPerDay, valid:, minPairCases:) keeps its +// signature and behaviour, including epochsPerDay <= 0 (absent) and a +// trailing partial day (ignored). + +import 'dart:typed_data'; + +import 'package:openstrap_analytics/aggregate.dart'; +import 'package:openstrap_analytics/onehz.dart'; +import 'package:test/test.dart'; + +import '../support/checkpoint_support.dart'; +import '../support/aggregator_laws.dart'; +import '../support/property.dart' show Rng; + +// --------------------------------------------------------------------------- +// FROZEN COPY of phillipsSri as it was before the rewire. +// --------------------------------------------------------------------------- +Metric _referenceSri( + List sleepWake, + int epochsPerDay, { + List? valid, + int? minPairCases, +}) { + const inputs = ['sleep_wake_epochs']; + final n = sleepWake.length; + if (epochsPerDay <= 0 || n < 2 * epochsPerDay) { + return const Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'need ≥2 full days of clock-aligned sleep/wake epochs for SRI', + ); + } + final days = n ~/ epochsPerDay; + if (days < 2) { + return const Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'need ≥2 full days for SRI', + ); + } + + final pairFloor = minPairCases ?? (epochsPerDay ~/ 2); + var agreement = 0; + var cases = 0; + final pairs = []; + for (var d = 1; d < days; d++) { + var pairAgreement = 0; + var pairCases = 0; + for (var e = 0; e < epochsPerDay; e++) { + final iPrev = (d - 1) * epochsPerDay + e; + final iCur = d * epochsPerDay + e; + if (iCur >= n) break; + if (valid != null && (!valid[iPrev] || !valid[iCur])) continue; + pairCases++; + if (sleepWake[iPrev] == sleepWake[iCur]) pairAgreement++; + } + agreement += pairAgreement; + cases += pairCases; + // `> 0` is not redundant with the floor: a caller may pass + // `minPairCases: 0`, and a zero-case pair would make SriPair.sri NaN. + if (pairCases > 0 && pairCases >= pairFloor) { + pairs.add(SriPair(d, pairAgreement, pairCases)); + } + } + if (cases == 0) { + return const Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'no valid epoch pairs for SRI', + ); + } + + if (pairs.isEmpty) { + return Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'no adjacent-day pair has ≥$pairFloor epochs observed on both ' + 'days (have=$cases epochs in total)', + ); + } + + final sri = 200.0 * agreement / cases - 100.0; + // Confidence: scales with the number of adequately-observed day-comparisons + // (more of them, more stable). Saturates around a typical 7-day record. + final conf = (pairs.length / 7.0).clamp(0.3, 0.95); + return Metric( + value: SriResult(sri, days, cases, pairs), + confidence: conf, + tier: Tier.high, + inputs_used: inputs, + note: 'epoch-by-epoch 24-h concordance (Phillips 2017), ' + 'SRI=200·agreement/cases−100; NOT SD-of-midsleep', + ); +} + +// --------------------------------------------------------------------------- + +typedef _Agg = Aggregator>; + +/// Everything observable, flattened. Compared EXACTLY (no tolerance). +List _fields(Metric m) { + final v = m.value; + return [ + m.present, + m.confidence, + m.tier, + m.inputs_used.join(','), + m.note, + v?.sri, + v?.days, + v?.cases, + v?.pairs.length, + if (v != null) + for (final p in v.pairs) ...[p.dayIndex, p.agreement, p.cases], + ]; +} + +final _eq = fieldsEqual>(_fields); + +void _same(Metric got, Metric want, String tag) { + // Bit-identical sri, not just ==. + if (want.value != null && got.value != null) { + expect(got.value!.sri.toString(), want.value!.sri.toString(), + reason: '$tag sri'); + } + expect(_fields(got), _fields(want), reason: tag); +} + +Epochs _epochs(List sw, [List? valid]) => Epochs( + Uint8List.fromList([for (final b in sw) b ? 1 : 0]), + valid: valid == null + ? null + : Uint8List.fromList([for (final b in valid) b ? 1 : 0]), + ); + +class _Rec { + _Rec(this.sw, this.valid); + final List sw; + final List? valid; + Epochs get epochs => _epochs(sw, valid); + int get n => sw.length; + @override + String toString() => + 'n=$n sw=${sw.map((b) => b ? 1 : 0).join()} ' + 'valid=${valid?.map((b) => b ? 1 : 0).join()}'; +} + +/// A record of [n] epochs: day-periodic sleep with [flipP] noise, optionally a +/// validity mask with holes (whole stretches and single epochs). +_Rec _record(Rng r, int n, int epd, {bool masked = false, double flipP = .1}) { + final base = [for (var e = 0; e < epd; e++) r.nextBool()]; + final sw = [ + for (var i = 0; i < n; i++) + r.nextBool(flipP) ? !base[i % epd] : base[i % epd] + ]; + List? valid; + if (masked) { + valid = [for (var i = 0; i < n; i++) !r.nextBool(.15)]; + if (n > 0 && r.nextBool(.4)) { + // A stretch of invalid epochs (a thin day). + final a = r.intIn(0, n - 1), len = r.intIn(1, epd + 2); + for (var i = a; i < a + len && i < n; i++) { + valid[i] = false; + } + } + } + return _Rec(sw, valid); +} + +void _allPaths( + _Agg a, Epochs e, List b, Metric want, String tag) { + _same(runChunked(a, e, b), want, '$tag chunks $b'); + _same(runChunked(a, e, b, copy: true), want, '$tag copies $b'); + _same(runChunkedRight(a, e, b), want, '$tag right $b'); + _same(runSliced(a, e, b), want, '$tag sliced $b'); +} + +void _checkRecord(Rng r, _Rec rec, int epd, int? floor, String tag, + {int slicings = 2}) { + final want = _referenceSri(rec.sw, epd, valid: rec.valid, minPairCases: floor); + // The public function (rewired) must still be the original. + _same(phillipsSri(rec.sw, epd, valid: rec.valid, minPairCases: floor), want, + '$tag phillipsSri'); + final a = sriAggregator(epd, minPairCases: floor); + final e = rec.epochs; + _same(a.run(e), want, '$tag run'); + for (var k = 0; k < slicings; k++) { + _allPaths(a, e, randomBounds(r, rec.n), want, tag); + } + // Day-aligned and one-off-day-aligned cuts exercise the day boundary. + final days = rec.n ~/ epd; + if (days >= 1) { + final aligned = [ + 0, + for (var d = 1; d <= days; d++) d * epd, + if (rec.n % epd != 0) rec.n, + ]; + _allPaths(a, e, aligned, want, '$tag aligned'); + final off = [ + 0, + for (var d = 1; d <= days; d++) + if (d * epd - 1 > 0) d * epd - 1, + rec.n, + ]; + _allPaths(a, e, off, want, '$tag off-by-one'); + } +} + +void main() { + group('Epochs batch', () { + Epochs mk(int n, {bool mask = false, int first = 0}) => Epochs( + Uint8List.fromList([for (var i = 0; i < n; i++) i % 3 == 0 ? 1 : 0]), + valid: mask + ? Uint8List.fromList([for (var i = 0; i < n; i++) i % 4 == 0 ? 0 : 1]) + : null, + firstIndex: first, + ); + + test('defaults and length', () { + final e = mk(5); + expect(e.length, 5); + expect(e.firstIndex, 0); + expect(e.valid, isNull); + expect(mk(0).length, 0); + }); + + test('copyRange cuts rows and shifts firstIndex', () { + final e = mk(10, mask: true); + final c = e.copyRange(3, 8); + expect(c.length, 5); + expect(c.firstIndex, 3); + expect(c.asleep, e.asleep.sublist(3, 8)); + expect(c.valid, e.valid!.sublist(3, 8)); + final cc = c.copyRange(2, 4); + expect(cc.firstIndex, 5); + expect(cc.asleep, e.asleep.sublist(5, 7)); + final shifted = mk(10, first: 100).copyRange(4, 10); + expect(shifted.firstIndex, 104); + }); + + test('copyRange of nothing, and of a batch without a mask', () { + final e = mk(6); + final empty = e.copyRange(4, 4); + expect(empty.length, 0); + expect(empty.firstIndex, 4); + expect(e.copyRange(0, 6).valid, isNull); + expect(e.copyRange(0, 6).length, 6); + }); + + test('copies are independent of the source, both ways', () { + final e = mk(8, mask: true); + final snapshot = Uint8List.fromList(e.asleep); + final snapshotValid = Uint8List.fromList(e.valid!); + final c = e.copyRange(2, 6); + e.asleep[3] ^= 1; + e.valid![4] ^= 1; + expect(c.asleep, snapshot.sublist(2, 6)); + expect(c.valid, snapshotValid.sublist(2, 6)); + final before = Uint8List.fromList(e.asleep); + c.asleep[0] ^= 1; + expect(e.asleep, before); + }); + + test('join of adjacent batches', () { + final e = mk(10, mask: true); + final j = e.copyRange(0, 4).join(e.copyRange(4, 10)); + expect(j.length, 10); + expect(j.firstIndex, 0); + expect(j.asleep, e.asleep); + expect(j.valid, e.valid); + final j2 = e.copyRange(2, 5).join(e.copyRange(5, 5)).join(e.copyRange(5, 9)); + expect(j2.firstIndex, 2); + expect(j2.asleep, e.asleep.sublist(2, 9)); + }); + + test('join result is independent of both inputs', () { + final e = mk(6, mask: true); + final left = e.copyRange(0, 3), right = e.copyRange(3, 6); + final j = left.join(right); + final want = Uint8List.fromList(j.asleep); + left.asleep[0] ^= 1; + right.asleep[0] ^= 1; + expect(j.asleep, want); + }); + + test('join with one side unmasked treats it as all valid', () { + final withMask = Epochs(Uint8List.fromList([1, 0]), + valid: Uint8List.fromList([0, 1])); + final plain = Epochs(Uint8List.fromList([1, 1]), firstIndex: 2); + expect(withMask.join(plain).valid, [0, 1, 1, 1]); + final plain0 = Epochs(Uint8List.fromList([1, 1])); + final maskedAfter = Epochs(Uint8List.fromList([0, 0]), + valid: Uint8List.fromList([1, 0]), firstIndex: 2); + expect(plain0.join(maskedAfter).valid, [1, 1, 1, 0]); + expect(plain0.join(Epochs(Uint8List(1), firstIndex: 2)).valid, isNull); + }); + + test('join of a non-adjacent batch asserts', () { + final e = mk(10); + expect(() => e.copyRange(0, 3).join(e.copyRange(4, 10)), + throwsA(isA())); + expect(() => e.copyRange(3, 6).join(e.copyRange(0, 3)), + throwsA(isA())); + }); + }); + + group('known results', () { + test('perfectly regular 3 days: sri 100, 2 pairs', () { + final sw = [for (var i = 0; i < 12; i++) (i % 4) < 2]; + final m = sriAggregator(4).run(_epochs(sw)); + _same(m, _referenceSri(sw, 4), 'regular'); + expect(m.value!.sri, 100.0); + expect(m.value!.days, 3); + expect(m.value!.cases, 8); + expect([for (final p in m.value!.pairs) p.dayIndex], [1, 2]); + }); + test('anti-phase 2 days: sri -100', () { + final sw = [true, true, false, false, false, false, true, true]; + final m = sriAggregator(4).run(_epochs(sw)); + expect(m.value!.sri, -100.0); + expect(m.value!.days, 2); + expect(m.confidence, 0.3); // (days-1)/7 clamped to 0.3..0.95 + }); + test('a trailing partial day is dropped at finish', () { + // 2 full days + 3 stray epochs that would disagree if they were used. + final sw = [true, false, true, false, true, false, true, false, + false, false, false]; + final m = sriAggregator(4).run(_epochs(sw)); + _same(m, _referenceSri(sw, 4), 'partial'); + expect(m.value!.days, 2); + expect(m.value!.cases, 4); + expect(m.value!.sri, 100.0); + }); + }); + + group('absent cases (notes included)', () { + final records = , List?, int, int?)>{ + 'empty': ([], null, 4, null), + 'one epoch': ([true], null, 4, null), + 'less than 2 days': ([for (var i = 0; i < 7; i++) i.isEven], null, 4, null), + 'exactly one day': ([true, false, true, false], null, 4, null), + '2 days minus one': ([for (var i = 0; i < 7; i++) true], null, 4, null), + 'no valid pair': ( + [for (var i = 0; i < 8; i++) true], + [true, true, false, false, false, false, true, true], + 4, + null + ), + 'mask all false': ( + [for (var i = 0; i < 12; i++) i.isEven], + List.filled(12, false), + 4, + 0 + ), + }; + records.forEach((name, rec) { + test(name, () { + final want = _referenceSri(rec.$1, + rec.$3, valid: rec.$2, minPairCases: rec.$4); + expect(want.present, isFalse); + final a = sriAggregator(rec.$3, minPairCases: rec.$4); + final e = _epochs(rec.$1, rec.$2); + _same(a.run(e), want, name); + _same(phillipsSri(rec.$1, rec.$3, valid: rec.$2, minPairCases: rec.$4), + want, name); + final r = Rng(name.hashCode & 0xffff); + for (var k = 0; k < 3; k++) { + _allPaths(a, e, randomBounds(r, e.length), want, name); + } + }); + }); + + test('the two notes are the two different absent reasons', () { + final short = sriAggregator(4).run(_epochs([true, false, true])); + expect(short.note, contains('≥2 full days of clock-aligned')); + final empty = sriAggregator(4).run(_epochs(List.filled(8, true), + List.filled(8, false))); + expect(empty.note, 'no valid epoch pairs for SRI'); + expect(short.confidence, 0); + expect(empty.confidence, 0); + }); + + test('phillipsSri with epochsPerDay <= 0 stays absent', () { + for (final epd in [0, -1, -1440]) { + final want = _referenceSri([true, false, true, false], epd); + _same(phillipsSri([true, false, true, false], epd), want, 'epd $epd'); + expect(want.present, isFalse); + } + }); + + test('empty batch finishes absent, also from an empty state', () { + final a = sriAggregator(4); + final want = _referenceSri([], 4); + _same(a.finish(a.empty()), want, 'empty state'); + _same(a.run(_epochs([])), want, 'empty batch'); + }); + }); + + group('minPairCases', () { + final r = Rng(0x5A1); + final rec = _record(r, 5 * 6 + 2, 6, masked: true, flipP: .3); + for (final floor in [null, 0, 1, 2, 3, 4, 6, 7, 100]) { + test('floor $floor', () { + _checkRecord(Rng(floor ?? -1), rec, 6, floor, 'floor $floor'); + }); + } + test('floor hides thin pairs but not their cases', () { + // Day 1 has 1 valid pair-case, day 2 has 4. + final sw = [for (var i = 0; i < 12; i++) i.isEven]; + final valid = [ + true, false, false, false, // day 0 + true, true, true, true, // day 1: only epoch 0 pairs with day 0 + true, true, true, true, // day 2 + ]; + final a = sriAggregator(4, minPairCases: 2).run(_epochs(sw, valid)); + _same(a, _referenceSri(sw, 4, valid: valid, minPairCases: 2), 'thin'); + expect(a.value!.cases, 5); + expect([for (final p in a.value!.pairs) p.dayIndex], [2]); + final z = sriAggregator(4, minPairCases: 0).run(_epochs(sw, valid)); + expect([for (final p in z.value!.pairs) p.dayIndex], [1, 2]); + }); + test('default floor is half the day (integer division)', () { + // epd 5 -> floor 2; a pair with 2 cases is kept, with 1 is not. + final sw = List.filled(15, true); + final valid = [ + true, true, true, true, true, + true, true, false, false, false, // 3 cases + true, false, false, false, false, // 0 cases with prev day mask... prev has 3 + ]; + final want = _referenceSri(sw, 5, valid: valid); + _same(sriAggregator(5).run(_epochs(sw, valid)), want, 'floor 2'); + }); + }); + + group('random parity (seeded)', () { + test('small epochsPerDay 4..12, lengths 0..7 days, masks, floors', () { + final r = Rng(0x5121); + for (var t = 0; t < 120; t++) { + final epd = r.intIn(4, 12); + final n = switch (r.intIn(0, 5)) { + 0 => r.intIn(0, 2 * epd + 1), // around the 2-day threshold + 1 => 2 * epd + r.intIn(0, epd - 1), // 2 days + partial + 2 => r.intIn(1, 7) * epd, // whole days + _ => r.intIn(0, 7 * epd + epd - 1), // anything, partial trailing day + }; + final rec = _record(r, n, epd, + masked: r.nextBool(.5), flipP: r.nextBool() ? .05 : .45); + final floor = switch (r.intIn(0, 3)) { + 0 => null, + 1 => 0, + 2 => r.intIn(1, epd), + _ => r.intIn(1, epd + 2), + }; + _checkRecord(r, rec, epd, floor, 't$t epd=$epd floor=$floor $rec'); + } + }); + + test('one 1440-epoch record of 3 days plus a partial fourth', () { + final r = Rng(0x1440); + for (final (n, masked) in [(3 * 1440, true), (3 * 1440 + 700, false)]) { + final rec = _record(r, n, 1440, masked: masked, flipP: .08); + _checkRecord(r, rec, 1440, null, 'n=$n', slicings: 2); + _checkRecord(r, rec, 1440, 100, 'n=$n floor 100', slicings: 1); + } + }); + + test('singleton chunks (state per epoch)', () { + final r = Rng(0x5106); + final rec = _record(r, 3 * 5 + 2, 5, masked: true); + final want = _referenceSri(rec.sw, 5, valid: rec.valid); + final a = sriAggregator(5); + _allPaths(a, rec.epochs, singletonBounds(rec.n), want, 'singletons'); + }); + }); + + test('persistable: a mid-stream checkpoint resumes to the one-pass result', () { + final b = _record(Rng(0xC0DE), 53, 4, masked: true, flipP: .3).epochs; + expectCheckpointResumes(sriAggregator(4), b, equals: _eq); + }); + + group('lawful (exact equality)', () { + final r = Rng(0x1A25); + List cases(int epd, {int count = 14}) => [ + _epochs([]), + _epochs([true]), + _epochs([true, false]), + for (var i = 0; i < count; i++) + _record(r, r.intIn(0, 4 * epd + epd ~/ 2), epd, + masked: r.nextBool(), flipP: .3) + .epochs, + ]; + for (final floor in [null, 0, 2]) { + test('epochsPerDay 4, floor $floor', + () => expectLawful(sriAggregator(4, minPairCases: floor), cases(4), + equals: _eq)); + } + test('epochsPerDay 7', + () => expectLawful(sriAggregator(7), cases(7, count: 10), equals: _eq)); + test('epochsPerDay 1', () { + // Degenerate day length: every epoch is its own day. + expectLawful(sriAggregator(1), cases(1, count: 10), equals: _eq); + }); + }); + + group('malformed input', () { + // Runs the frozen reference and the rewired phillipsSri on the same input: + // equal results, or the same exception type when the reference throws. + void sameAsReference( + String name, List sw, int epd, List? valid) { + test(name, () { + Metric? want; + Object? wantError; + try { + want = _referenceSri(sw, epd, valid: valid); + } catch (e) { + wantError = e; + } + if (wantError != null) { + expect(() => phillipsSri(sw, epd, valid: valid), + throwsA(predicate((e) => e.runtimeType == wantError.runtimeType)), + reason: 'reference threw $wantError'); + } else { + _same(phillipsSri(sw, epd, valid: valid), want!, name); + } + }); + } + + List pattern(int n) => [for (var i = 0; i < n; i++) i % 3 == 0]; + + sameAsReference('trailing partial day, mask one short of n (spec case)', + List.filled(9, true), 4, List.filled(8, true)); + sameAsReference('mask longer than n', pattern(8), 4, List.filled(12, true)); + sameAsReference('mask longer than n, with falses', pattern(9), 4, + [for (var i = 0; i < 20; i++) i % 5 != 0]); + sameAsReference('mask = complete span, partial day present', pattern(10), 4, + [for (var i = 0; i < 8; i++) i != 2]); + sameAsReference('mask shorter than n but covering complete days', + pattern(11), 4, [for (var i = 0; i < 9; i++) i != 5]); + sameAsReference('mask shorter than complete days, absent case', + pattern(8), 4, List.filled(4, false)); + sameAsReference('mask shorter than complete days, throwing case', + pattern(8), 4, List.filled(4, true)); + sameAsReference('mask shorter than complete days, throws later in the day', + pattern(12), 4, [for (var i = 0; i < 6; i++) i < 2 ? true : i != 4]); + sameAsReference('empty mask', pattern(8), 4, []); + + test('the shorter-mask cases really split into absent and throwing', () { + expect(_referenceSri(List.filled(8, true), 4, valid: List.filled(4, false)).present, + isFalse); + expect(() => _referenceSri(List.filled(8, true), 4, valid: List.filled(4, true)), + throwsRangeError); + }); + }); + + group('sriAggregator with epochsPerDay <= 0', () { + for (final epd in [0, -1, -5]) { + test('epochsPerDay $epd finishes as the absent phillipsSri metric', () { + final inputs = >[ + [], + [true], + List.filled(10, true), + [for (var i = 0; i < 40; i++) i % 3 == 0], + ]; + for (final sw in inputs) { + final want = _referenceSri(sw, epd); + expect(want.present, isFalse); + final got = sriAggregator(epd).run(_epochs(sw)); + _same(got, want, 'epd $epd n ${sw.length}'); + } + }); + test('epochsPerDay $epd never throws, masked or with minPairCases', () { + final sw = [for (var i = 0; i < 12; i++) i.isEven]; + final got = sriAggregator(epd, minPairCases: 2) + .run(_epochs(sw, List.filled(12, true))); + _same(got, _referenceSri(sw, epd, minPairCases: 2), 'masked'); + }); + } + }); + + group('checkpoint relationships (epoch count, window length, day pairs)', () { + // 14 epochs of 4 per day: days 1..3 hold pairs (day 3 is a partial day). + final agg = sriAggregator(4); + final b = _record(Rng(0x5A1), 14, 4, masked: false, flipP: .3).epochs; + // State: [n, lookback]; lookback inner is {dayKey: {agreement, cases}}. + Map lookback(Object? s) => (s as List)[1] as Map; + Map days(Object? s) => lookback(s)['inner'] as Map; + + test('the epoch count must equal the lookback row count', () { + expectDamagedCheckpointRefused(agg, b, (s) { + (s as List)[0] = 9; + return s; + }); + expectDamagedCheckpointRefused(agg, b, (s) { + (s as List)[0] = 20; + return s; + }); + }); + test('a day with more pair cases than epochs per day is refused', () { + expectDamagedCheckpointRefused(agg, b, (s) { + final d = days(s).values.first as Map; + d['cases'] = 5; + return s; + }); + }); + test('a day outside the later days of the record is refused', () { + // 14 epochs reach day 3; day 0 has no earlier day to compare with and + // day 9 is past the end. + for (final key in ['0', '9', '-1']) { + expectDamagedCheckpointRefused(agg, b, (s) { + final d = days(s); + d[key] = d.values.first; + return s; + }, reason: 'day $key'); + } + }); + test('pair cases beyond the epochs that can be compared are refused', () { + // 14 epochs allow at most 14 - 4 = 10 comparisons in total. + expectDamagedCheckpointRefused(agg, b, (s) { + final d = days(s); + for (final k in ['1', '2', '3']) { + (d[k] as Map) + ..['cases'] = 4 + ..['agreement'] = 4; + } + return s; + }); + }); + // # catches: only the first edge's index was checked, so a last edge at the + // wrong index decoded and then broke the join with the next batch (or, with + // assertions off, compared against the wrong day). + test('the last edge must sit at first + count - its length', () { + // 14 epochs from index 0: the last edge holds 4 rows, from index 10. + expect( + decodeCheckpoint(agg, checkpointOf(agg, b), + kind: 'test', version: 1), + isNotNull); + for (final bad in [0, 9, 11, 14, 100]) { + expectDamagedCheckpointRefused(agg, b, (s) { + (lookback(s)['last'] as Map)['firstIndex'] = bad; + return s; + }, reason: 'last.firstIndex $bad'); + } + }); + test('a short record (one day or less) checks its edges too', () { + final short = _record(Rng(0x5A2), 3, 4, masked: false, flipP: .3).epochs; + expect( + decodeCheckpoint(agg, checkpointOf(agg, short), + kind: 'test', version: 1), + isNotNull); + expectDamagedCheckpointRefused(agg, short, (s) { + (lookback(s)['last'] as Map)['firstIndex'] = 1; + return s; + }); + }); + test('a consistent checkpoint restores', () { + expect( + decodeCheckpoint(agg, checkpointOf(agg, b), + kind: 'test', version: 1), + isNotNull); + }); + }); +} diff --git a/test/aggregate/support/upstream_cosinor.dart b/test/aggregate/support/upstream_cosinor.dart new file mode 100644 index 0000000..59f8517 --- /dev/null +++ b/test/aggregate/support/upstream_cosinor.dart @@ -0,0 +1,154 @@ +// Frozen upstream main 9db83ce batch cosinor, independent of the aggregator. +// Only the entry-point name and imports change. +import 'dart:math' as math; +import 'package:openstrap_analytics/onehz.dart'; + +Metric upstreamCosinor( + List tHours, + List y, { + double periodHours = 24, + int minPoints = cosinorMinPoints, +}) { + const inputs = ['signal_timeseries']; + final n = y.length; + if (n < math.max(4, minPoints) || tHours.length != n || periodHours <= 0) { + return const Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'too few points for cosinor', + ); + } + final w = 2 * math.pi / periodHours; + final c = [for (final t in tHours) math.cos(w * t)]; + final s = [for (final t in tHours) math.sin(w * t)]; + + // Normal equations for [M, β, γ] of y = M + β·c + γ·s. + // Build 3×3 symmetric system. + var sC = 0.0, sS = 0.0, sCC = 0.0, sSS = 0.0, sCS = 0.0; + var sY = 0.0, sYC = 0.0, sYS = 0.0; + for (var i = 0; i < n; i++) { + sC += c[i]; + sS += s[i]; + sCC += c[i] * c[i]; + sSS += s[i] * s[i]; + sCS += c[i] * s[i]; + sY += y[i]; + sYC += y[i] * c[i]; + sYS += y[i] * s[i]; + } + // Matrix A = [[n, sC, sS],[sC, sCC, sCS],[sS, sCS, sSS]], b=[sY,sYC,sYS]. + final a = [ + [n.toDouble(), sC, sS], + [sC, sCC, sCS], + [sS, sCS, sSS], + ]; + final b = [sY, sYC, sYS]; + final sol = _solve3(a, b); + if (sol == null) { + return const Metric.absent( + tier: Tier.high, + inputs_used: inputs, + note: 'singular cosinor design (insufficient phase coverage)', + ); + } + final mesor = sol[0]; + final beta = sol[1]; + final gamma = sol[2]; + final amplitude = math.sqrt(beta * beta + gamma * gamma); + final acro = math.atan2(-gamma, beta); // peak phase + // Convert acrophase to clock-hours within the period (0..period). + var phaseHours = -acro / w; // time of peak relative to origin + phaseHours = phaseHours % periodHours; + if (phaseHours < 0) phaseHours += periodHours; + + // R². + final yMean = sY / n; + var ssTot = 0.0, ssRes = 0.0; + for (var i = 0; i < n; i++) { + final fit = mesor + beta * c[i] + gamma * s[i]; + ssTot += (y[i] - yMean) * (y[i] - yMean); + ssRes += (y[i] - fit) * (y[i] - fit); + } + final double r2 = ssTot == 0 ? 0.0 : (1 - ssRes / ssTot).clamp(0, 1); + // Adjusted for the 3 fitted parameters (M, β, γ). Confidence MUST come from + // the adjusted value: the raw R² of a 3-parameter fit is upward-biased + // (E[R²] = 2/(n−1) under the null), so a handful of noise points used to + // score confidence 0.95 at tier HIGH. + final double r2Adj = (1 - (1 - r2) * (n - 1) / (n - 3)).clamp(0, 1); + + // Zero-amplitude F-test (Nelson 1979): the acrophase is only defined once + // the test rejects. A flat or rhythm-free series still yields some + // atan2(−γ, β) from residual noise or float rounding. + final dof = n - 3; + final double ampP; + if (ssTot <= 0) { + ampP = 1.0; + } else if (ssRes <= 0) { + ampP = 0.0; + } else { + final f = ((ssTot - ssRes) / 2) / (ssRes / dof); + ampP = _f2Survival(f, dof); + } + final phaseDefined = ampP < cosinorAcrophaseAlpha; + + final conf = r2Adj.clamp(0.1, 0.95); + return Metric( + value: CosinorFit( + mesor: mesor, + amplitude: amplitude, + acrophaseRad: phaseDefined ? acro : null, + acrophaseHours: phaseDefined ? phaseHours : null, + periodHours: periodHours, + r2: r2, + r2Adj: r2Adj, + amplitudeP: ampP, + ), + confidence: conf, + tier: Tier.high, + inputs_used: inputs, + note: phaseDefined + ? 'single-component cosinor; anchor circadian phase on the nocturnal ' + 'trough, not the daytime peak' + : 'single-component cosinor; no resolvable rhythm ' + '(zero-amplitude test not rejected), acrophase undefined', + ); +} + +/// Solve a 3×3 linear system by Gaussian elimination with partial pivoting. +/// Returns null if singular. +List? _solve3(List> a, List b) { + final m = [ + [a[0][0], a[0][1], a[0][2], b[0]], + [a[1][0], a[1][1], a[1][2], b[1]], + [a[2][0], a[2][1], a[2][2], b[2]], + ]; + for (var col = 0; col < 3; col++) { + var piv = col; + for (var r = col + 1; r < 3; r++) { + if (m[r][col].abs() > m[piv][col].abs()) piv = r; + } + if (m[piv][col].abs() < 1e-12) return null; + final tmp = m[col]; + m[col] = m[piv]; + m[piv] = tmp; + final d = m[col][col]; + for (var j = col; j < 4; j++) { + m[col][j] /= d; + } + for (var r = 0; r < 3; r++) { + if (r == col) continue; + final f = m[r][col]; + for (var j = col; j < 4; j++) { + m[r][j] -= f * m[col][j]; + } + } + } + return [m[0][3], m[1][3], m[2][3]]; +} + +double _f2Survival(double f, int d) { + if (f.isNaN) return 1.0; + if (f.isInfinite) return 0.0; + if (f <= 0) return 1.0; + return math.pow(1 + 2 * f / d, -d / 2).toDouble(); +} diff --git a/test/aggregate/time_in_zone_aggregator_test.dart b/test/aggregate/time_in_zone_aggregator_test.dart new file mode 100644 index 0000000..011086c --- /dev/null +++ b/test/aggregate/time_in_zone_aggregator_test.dart @@ -0,0 +1,767 @@ +// timeInZoneAggregator must agree with HeartRateZones.timeInZone for the same +// (time-sorted) rows under any slicing or chunking, and obey the aggregator +// laws. +// +// Contract used here (docs: r6-time-in-zone.md): +// * HrStream(Float64List tsMs, Float64List hr) is a Batch; rows are +// sorted by tsMs; a row is valid when hr > 0 (as HrSample.valid). +// * timeInZoneAggregator(zoneSet) is an +// Aggregator<_, HrStream, TimeInHeartRateZone?>, all exported from +// package:openstrap_analytics/aggregate.dart. +// * The result is null exactly when HeartRateZones.timeInZone is null (the +// sampleCadenceSeconds rule, including fewer than 2 rows). Otherwise every +// zone's seconds and belowZone1 are within relTol 1e-12 / absTol 1e-9. +// * The median m is bit-identical to sampleCadenceSeconds'. Pinned here by +// streams whose only valid row is the LAST one: the only credit is the tail, +// so the zone total is m, compared with == (a single add to 0.0 is exact). +// * HOOK the implementer must add, exported from the same library: +// int timeInZoneStateEntries(Object? state) +// = total number of histogram entries (all histograms, all zones) held by a +// state returned by agg.fold(...). Must not throw on agg.empty() (returns 0 +// or a small number). +// * Duplicate-timestamp rows in the LARGE random streams carry the same hr as +// the row they duplicate: the reference re-sorts with an unstable sort, so +// tie order (and so which hr gets the fallback credit) is only defined for +// streams of <= 32 rows. The hand-written duplicate case uses 5 rows with +// differing hr. + +import 'dart:convert'; +import 'dart:math' as math; +import 'dart:typed_data'; + +import 'package:openstrap_analytics/aggregate.dart'; +import 'package:openstrap_analytics/onehz.dart'; +import 'package:test/test.dart'; + +import '../support/checkpoint_support.dart'; +import '../support/aggregator_laws.dart'; +import '../support/property.dart' show Rng; + +typedef _Agg = Aggregator; + +final HeartRateZoneSet _zones = HeartRateZones.zonesFromMaxHr(200); +final _Agg _agg = timeInZoneAggregator(_zones); + +List _fields(TimeInHeartRateZone? t) => + t == null ? [null] : [...t.seconds, t.belowZone1]; + +final _eq = fieldsEqual(_fields, + relTol: 1e-12, absTol: 1e-9); + +/// A raw stream: timestamps in ms and hr. +class _S { + _S(this.ts, this.hr); + final List ts; + final List hr; + int get n => ts.length; + HrStream get stream => + HrStream(Float64List.fromList(ts), Float64List.fromList(hr)); + List get samples => + [for (var i = 0; i < n; i++) HrSample(ts[i], hr[i])]; + double? get cadence => + sampleCadenceSeconds([for (final t in ts) t / 1000.0]); +} + +/// The reference: the batch rule as it was before `HeartRateZones.timeInZone` +/// delegated to the aggregator, kept here verbatim so a regression in the +/// aggregator cannot also change what it is compared with. Its only shared +/// piece is [sampleCadenceSeconds], a separate function; the credit bounding, +/// the per-gap histogram and the tail are written out again. +TimeInHeartRateZone? _referenceTimeInZone( + List hr, HeartRateZoneSet zoneSet) { + // Stable: by timestamp, then input position, so repeated timestamps keep the + // order they arrived in (Dart's List.sort is not stable for long lists). + final order = List.generate(hr.length, (i) => i) + ..sort((a, b) { + final c = hr[a].tsMs.compareTo(hr[b].tsMs); + return c != 0 ? c : a.compareTo(b); + }); + final sorted = [for (final i in order) hr[i]]; + final cadence = + sampleCadenceSeconds([for (final s in sorted) s.tsMs / 1000.0]); + if (cadence == null) return null; + final credits = List.generate(6, (_) => {}); + for (var i = 1; i < sorted.length; i++) { + final previous = sorted[i - 1]; + if (!previous.valid) continue; + final gap = (sorted[i].tsMs - previous.tsMs) / 1000.0; + final histogram = credits[zoneSet.zoneNumber(previous.hr)]; + histogram[gap] = (histogram[gap] ?? 0) + 1; + } + final seconds = List.filled(6, 0); + for (var zone = 0; zone < credits.length; zone++) { + for (final entry in credits[zone].entries) { + final gap = entry.key; + seconds[zone] += + entry.value * (gap > 0 ? math.min(gap, cadence) : cadence); + } + } + if (sorted.isNotEmpty && sorted.last.valid) { + seconds[zoneSet.zoneNumber(sorted.last.hr)] += cadence; + } + return TimeInHeartRateZone( + seconds: seconds.sublist(1), belowZone1: seconds[0]); +} + +TimeInHeartRateZone? _want(_S s) => _referenceTimeInZone(s.samples, _zones); + +void _same(TimeInHeartRateZone? got, TimeInHeartRateZone? want, String tag) { + expect(_eq(got, want), isTrue, + reason: '$tag\n got ${_fields(got)}\nwant ${_fields(want)}'); + expect(got == null, want == null, reason: '$tag null-ness'); +} + +/// Every way of evaluating the aggregator against the reference. +void _allPaths(_S s, List b, String tag) { + final want = _want(s); + final st = s.stream; + _same(_agg.run(st), want, '$tag whole'); + _same(runChunked(_agg, st, b), want, '$tag chunks $b'); + _same(runChunked(_agg, st, b, copy: true), want, '$tag copies $b'); + _same(runChunkedRight(_agg, st, b), want, '$tag right $b'); + _same(runSliced(_agg, st, b), want, '$tag sliced $b'); +} + +void _parity(_S s, String tag, Rng r) { + for (var k = 0; k < 3; k++) { + _allPaths(s, randomBounds(r, s.n), tag); + } + _allPaths(s, singletonBounds(s.n), '$tag singletons'); +} + +// ---- generators ------------------------------------------------------------ + +/// A bpm that hits every zone, the boundaries exactly, off-skin and above max. +double _bpm(Rng r) { + final k = r.nextDouble(); + if (k < .08) return 0; + if (k < .30) { + final z = _zones.zones[r.intIn(0, 4)]; + return r.nextBool() ? z.lower : z.upper; + } + if (k < .38) return 205 + r.nextDouble() * 30; // above zone 5 + if (k < .46) return 30 + r.nextDouble() * 60; // below zone 1 + return 90 + r.nextDouble() * 110; +} + +/// [n] rows at nominal [stepMs] with [jitterMs] jitter, a [dropP] chance of a +/// long [dropMs] gap, a [dupP] chance of a repeated timestamp (same hr, see +/// the header), an [offP] chance of an off-skin row. +_S _gen(Rng r, int n, + {double stepMs = 1000, + int jitterMs = 20, + double dropP = 0, + double dropMs = 600000, + double dupP = 0, + double offP = 0, + bool fractional = false}) { + final ts = []; + final hr = []; + var t = 1.7e12 + r.intIn(0, 999999); + for (var i = 0; i < n; i++) { + if (i > 0 && r.nextBool(dupP)) { + ts.add(ts.last); + hr.add(hr.last); + continue; + } + if (i > 0) { + t += r.nextBool(dropP) + ? dropMs + : stepMs + r.intIn(-jitterMs, jitterMs) + + (fractional ? r.nextDouble() : 0); + } + ts.add(t); + hr.add(r.nextBool(offP) ? 0 : _bpm(r)); + } + return _S(ts, hr); +} + +/// The input families of the spec, by name. +Map _families() => { + '1 Hz jitter': (r, n) => _gen(r, n), + '1 Hz fractional ms': (r, n) => _gen(r, n, fractional: true), + 'dropouts': (r, n) => _gen(r, n, dropP: .05), + 'duplicate timestamps': (r, n) => _gen(r, n, dupP: .15), + 'off-skin rows': (r, n) => _gen(r, n, offP: .3), + 'slow 5 s device': (r, n) => _gen(r, n, stepMs: 5000, jitterMs: 100), + 'dropouts + dups + off-skin': (r, n) => + _gen(r, n, dropP: .05, dupP: .1, offP: .15, fractional: true), + 'cadence > 300 s': (r, n) => _gen(r, n, stepMs: 400000, jitterMs: 1000), + 'fails the mode rule': (r, n) { + // Gaps cycle 1 s, 4 s, 10 s: median 4 s, only a third within 2x. + if (n == 0) return _S([], []); + final ts = [1.7e12]; + for (var i = 1; i < n; i++) { + ts.add(ts.last + const [1000.0, 4000.0, 10000.0][i % 3]); + } + return _S(ts, [for (var i = 0; i < n; i++) _bpm(r)]); + }, + }; + +void main() { + group('hand-worked', () { + test('one row, empty: null', () { + expect(_agg.run(HrStream(Float64List(0), Float64List(0))), isNull); + expect(_agg.run(_S([5000], [120]).stream), isNull); + expect(_want(_S([5000], [120])), isNull); + expect(_agg.finish(_agg.empty()), isNull); + }); + test('two rows: the tail gets m', () { + final s = _S([0, 1000], [110, 130]); + final want = _want(s)!; + final got = _agg.run(s.stream)!; + _same(got, want, 'two rows'); + expect(got.secondsInZone(1), closeTo(1, 1e-12)); + expect(got.secondsInZone(2), closeTo(1, 1e-12)); + }); + test('two rows, equal timestamps: no positive gap, null', () { + final s = _S([1000, 1000], [110, 130]); + expect(_want(s), isNull); + expect(_agg.run(s.stream), isNull); + }); + test('five regular rows, one per zone', () { + final s = _S([0, 60000, 120000, 180000, 240000], + [110, 130, 150, 170, 190]); + final got = _agg.run(s.stream)!; + for (var z = 1; z <= 5; z++) { + expect(got.secondsInZone(z), closeTo(60, 1e-9)); + } + expect(got.belowZone1, 0); + }); + test('long gap is capped at m; duplicate (gap 0) gets m', () { + final s = _S([0, 1000, 2000, 2000, 700000], [130, 150, 190, 130, 190]); + _same(_agg.run(s.stream), _want(s), 'capped'); + for (final b in [ + [0, 5], + [0, 2, 3, 5], + [0, 1, 1, 4, 5], + [0, 3, 4, 4, 5] + ]) { + _same(runChunked(_agg, s.stream, b), _want(s), 'chunks $b'); + _same(runSliced(_agg, s.stream, b), _want(s), 'sliced $b'); + } + }); + test('zone boundaries: exactly lower / upper, above zone 5, below zone 1', + () { + final hr = [ + for (final z in _zones.zones) ...[z.lower, z.upper], + _zones.maxHr + 40, + _zones.zones.first.lower - 0.5, + 0, + ]; + final s = _S([for (var i = 0; i < hr.length; i++) i * 1000.0], hr); + final want = _want(s)!; + _same(_agg.run(s.stream), want, 'boundaries'); + expect(want.belowZone1, greaterThan(0)); + expect(want.seconds[4], greaterThan(0)); + for (final b in [ + [0, hr.length], + [0, 1, 2, 5, hr.length], + [0, 4, 4, hr.length] + ]) { + _same(runChunked(_agg, s.stream, b), want, 'chunks $b'); + _same(runSliced(_agg, s.stream, b), want, 'sliced $b'); + } + }); + }); + + group('null exactly when the reference is null', () { + test('> 300 s cadence', () { + final s = _gen(Rng(1), 12, stepMs: 400000, jitterMs: 1000); + expect(_want(s), isNull); + _parity(s, '>300', Rng(2)); + expect(_agg.run(s.stream), isNull); + }); + test('stream failing the mode rule', () { + final s = _families()['fails the mode rule']!(Rng(3), 30); + expect(_want(s), isNull); + _parity(s, 'mode', Rng(4)); + expect(_agg.run(s.stream), isNull); + }); + test('exactly 300 s cadence is accepted, 301 s is not', () { + final ok = _S([for (var i = 0; i < 6; i++) i * 300000.0], + [100, 120, 140, 160, 180, 100]); + final no = _S([for (var i = 0; i < 6; i++) i * 301000.0], + [100, 120, 140, 160, 180, 100]); + expect(_want(ok), isNotNull); + expect(_want(no), isNull); + _parity(ok, '300', Rng(5)); + _parity(no, '301', Rng(6)); + }); + test('all timestamps identical: null', () { + final s = _S([5, 5, 5, 5], [100, 100, 100, 100]); + expect(_want(s), isNull); + _parity(s, 'dups', Rng(7)); + }); + }); + + group('random parity (seeded)', () { + var fam = 0; + _families().forEach((name, make) { + final seed = 0x7a11 + fam++; + test(name, () { + final r = Rng(seed); + var nonNull = 0; + for (var t = 0; t < 14; t++) { + final n = r.nextBool(.2) ? r.intIn(0, 4) : r.intIn(5, 160); + final s = make(r, n); + if (_want(s) != null) nonNull++; + _parity(s, '$name t$t n=$n', r); + } + if (!name.contains('>') && !name.contains('mode')) { + expect(nonNull, greaterThan(5), reason: 'generator too degenerate'); + } + }); + }); + + test('one-row and two-row chunks of a long stream', () { + final r = Rng(0x51); + final s = _gen(r, 90, dropP: .05, offP: .1, fractional: true); + for (final b in [ + [0, 1, 2, 90], + [0, 88, 89, 90], + [0, 45, 45, 45, 90], + [0, 0, 90, 90], + ]) { + _allPaths(s, b, 'edge $b'); + } + }); + }); + + group('cadence median is bit-identical to sampleCadenceSeconds', () { + // Only the last row is valid, so the sole credit is the tail: the zone + // total is exactly m (0.0 + m), compared with == on the double. + double total(TimeInHeartRateZone t) => + t.seconds.fold(t.belowZone1, (a, b) => a + b); + + _S tailOnly(Rng r, int n, {bool fractional = true, double step = 1000}) { + final s = _gen(r, n, + stepMs: step, jitterMs: 37, dropP: .05, fractional: fractional); + for (var i = 0; i < n - 1; i++) { + s.hr[i] = 0; + } + s.hr[n - 1] = 140; + return s; + } + + test('tail seconds == sampleCadenceSeconds, random streams and cuts', () { + final r = Rng(0xb17); + var checked = 0; + for (var t = 0; t < 40; t++) { + // Both even and odd gap counts (interpolated and exact medians). + final n = 2 + r.intIn(0, 120); + final s = tailOnly(r, n, step: r.nextBool() ? 1000 : 5000); + final m = s.cadence; + if (m == null) continue; + checked++; + final st = s.stream; + final b = randomBounds(r, n); + expect(total(_agg.run(st)!) == m, isTrue, + reason: 't$t whole ${total(_agg.run(st)!)} vs $m'); + expect(total(runChunked(_agg, st, b)!) == m, isTrue, + reason: 't$t chunks $b'); + expect(total(runChunked(_agg, st, b, copy: true)!) == m, isTrue, + reason: 't$t copies $b'); + expect(total(runChunkedRight(_agg, st, b)!) == m, isTrue, + reason: 't$t right $b'); + expect(total(runSliced(_agg, st, b)!) == m, isTrue, + reason: 't$t sliced $b'); + } + expect(checked, greaterThan(25)); + }); + + test('even gap count: the interpolated median, odd: the middle gap', () { + // gaps 1,2 -> 1.5 ; gaps 1,2,3 -> 2 (all inside the mode window). + final even = _S([0, 1000, 3000], [0, 0, 150]); + expect(total(_agg.run(even.stream)!) == 1.5, isTrue); + final odd = _S([0, 1000, 3000, 6000], [0, 0, 0, 150]); + expect(total(_agg.run(odd.stream)!) == 2.0, isTrue); + expect(even.cadence, 1.5); + expect(odd.cadence, 2.0); + }); + }); + + group('state size', () { + test('10,000 rows at 1 Hz with +-20 ms jitter: < 400 histogram entries', + () { + final r = Rng(0x5eed); + final s = _gen(r, 10000); + final entries = timeInZoneStateEntries(_agg.fold(s.stream)); + expect(entries, lessThan(400)); + expect(entries, greaterThan(0)); + _same(_agg.run(s.stream), _want(s), 'big'); + }); + test('does not grow with rows: 40,000 rows, 7 chunks combined', () { + final r = Rng(0x5eee); + final s = _gen(r, 40000); + final st = s.stream; + final b = [0, 5000, 5001, 12000, 20000, 20000, 33333, 40000]; + var acc = _agg.fold(st, b[0], b[1]); + for (var k = 1; k + 1 < b.length; k++) { + acc = _agg.combine(acc, _agg.fold(st, b[k], b[k + 1])); + } + expect(timeInZoneStateEntries(acc), lessThan(400)); + _same(_agg.finish(acc), _want(s), 'combined'); + }); + test('empty state is tiny', () { + expect(timeInZoneStateEntries(_agg.empty()), lessThan(10)); + }); + }); + + test('persistable: a mid-stream checkpoint resumes to the one-pass result', () { + expectCheckpointResumes(_agg, _gen(Rng(0xC0DE), 45, dropP: .1, offP: .2).stream, + equals: _eq); + }); + + group('checkpoint zone identity', () { + final rows = _S([0, 1000], [110, 130]).stream; + + // why: old histogram credits must never mix with a new tail/append zone + // definition (review 4573606761). Catches a restore without zone identity. + test('a different max-HR zone set is refused', () { + final other = timeInZoneAggregator(HeartRateZones.zonesFromMaxHr(180)); + expect(decodeCheckpoint(other, checkpointOf(_agg, rows), + kind: 'test', version: 1), isNull); + }); + + // why: legacy state has no evidence of which zones own its credits. + test('a checkpoint without zone identity is refused', () { + final checkpoint = checkpointOf(_agg, rows); + (checkpoint['state'] as Map).remove('zoneSet'); + expect(decodeCheckpoint(_agg, checkpoint, + kind: 'test', version: 1), isNull); + }); + + // why: maxHr/source alone cannot identify custom zone boundaries or order. + test('custom boundaries and reordered zones are refused', () { + final changed = HeartRateZone( + number: 1, + lower: 90, + upper: 120, + lowerPct: .5, + upperPct: .6, + ); + for (final zones in [ + [changed, ..._zones.zones.skip(1)], + _zones.zones.reversed.toList(), + ]) { + final other = timeInZoneAggregator(HeartRateZoneSet( + zones: zones, maxHr: _zones.maxHr, source: _zones.source)); + expect(decodeCheckpoint(other, checkpointOf(_agg, rows), + kind: 'test', version: 1), isNull); + } + }); + + // why: identity is by definition, not Dart object identity; accepted state + // must retain old credits and credit appended rows under the same zones. + test('an equivalent zone set restores and continues', () { + final other = timeInZoneAggregator(HeartRateZones.zonesFromMaxHr(200)); + final restored = decodeCheckpoint(other, checkpointOf(_agg, rows), + kind: 'test', version: 1); + expect(restored, isNotNull); + final result = other.finish(other.addSlice( + restored, _S([2000], [190]).stream, 0, 1))!; + // Three one-second credits: 110 in z1, 130 in z2, 190 in z5. + expect(result.seconds, [1, 1, 0, 0, 1]); + expect(result.belowZone1, 0); + }); + }); + + group('checkpoint tail agrees with the retained last row', () { + // why: independently restored tail fields could silently move the final + // credit or disagree with the seam timestamp (review 4573606767). + for (final field in ['tailHr', 'tailTimestampMs']) { + for (final size in [1, 2, 3]) { + test('$field mismatch is refused for $size rows', () { + final rows = _S([for (var i = 0; i < size; i++) i * 1000.0], + [110.0, 130.0, 150.0].take(size).toList()).stream; + expectDamagedCheckpointRefused(_agg, rows, (s) { + (s as Map)[field] = field == 'tailHr' ? 190.0 : 9000.0; + return s; + }); + }); + } + } + + // why: NaN HR is accepted as invalid/off-skin input; NaN != NaN must not + // make a valid checkpoint unrestoreable when the two tails agree. + test('matching non-finite heart rates restore and continue', () { + for (final hr in [double.nan, double.infinity, double.negativeInfinity]) { + final rows = _S([0, 1000], [110, hr]).stream; + final restored = decodeCheckpoint(_agg, checkpointOf(_agg, rows), + kind: 'test', version: 1); + expect(restored, isNotNull, reason: '$hr'); + final result = _agg.finish(_agg.addSlice( + restored, _S([2000], [130]).stream, 0, 1))!; + // +Infinity is zone 5; NaN/-Infinity are invalid and get no credit. + expect(result.seconds, [1, 1, 0, 0, hr == double.infinity ? 1 : 0]); + expect(result.belowZone1, 0); + } + }); + }); + + group('lawful', () { + final r = Rng(0x1a3); + final cases = [ + HrStream(Float64List(0), Float64List(0)), + _S([1000], [120]).stream, + _S([0, 1000], [120, 0]).stream, + _S([0, 1000], [0, 150]).stream, + _S([0, 0], [100, 100]).stream, + _gen(r, 30).stream, + _gen(r, 45, dropP: .1, offP: .2).stream, + _gen(r, 45, dupP: .2, fractional: true).stream, + _gen(r, 25, stepMs: 5000, jitterMs: 100).stream, + _families()['fails the mode rule']!(r, 25).stream, + for (var i = 0; i < 15; i++) _gen(r, r.intIn(0, 40), offP: .1).stream, + ]; + test('every law holds', () => expectLawful(_agg, cases, equals: _eq)); + }); + + group('checkpoint histograms are consistent with the stored rows', () { + // Three rows one second apart at 150 bpm: two pairs, one tail. + final three = _S([0, 1000, 2000], [150, 150, 150]).stream; + // One row: no pairs, only a tail. + final one = _S([5000], [150]).stream; + // Two rows: one pair. + final two = _S([0, 1000], [150, 150]).stream; + + // State: {windows: {length, first, last, inner: {cadence, credits}}, + // hasTail, tailTimestampMs, tailHr}. Histograms are [[gap, n], ..]. + Map inner(Object? s) => ((s as Map)['windows'] as Map)['inner'] as Map; + List cadence(Object? s) => inner(s)['cadence'] as List; + List credits(Object? s) => inner(s)['credits'] as List; + // The (single) non-empty credit histogram. + List credit(Object? s) => + credits(s).cast().firstWhere((h) => h.isNotEmpty); + + void refuses(HrStream batch, void Function(Object? s) damage, + [String? why]) { + expectDamagedCheckpointRefused(_agg, batch, (s) { + damage(s); + return s; + }, reason: why); + } + + test('a good checkpoint has the shape these tests damage', () { + final s = checkpointOf(_agg, three)['state']; + expect(cadence(s), [ + [1.0, 2] + ]); + expect(credit(s), [ + [1.0, 2] + ]); + }); + + test('review case: histogram multiplicities inflated past the pairs', () { + refuses(two, (s) => cadence(s)[0][1] = 300); + refuses(two, (s) => credit(s)[0][1] = 300); + refuses(three, (s) => cadence(s)[0][1] = 3); + refuses(three, (s) => credit(s)[0][1] = 3); + }); + test('credits spread over several zones still sum to at most the pairs', + () { + refuses(three, (s) { + // Two pairs exist; 1 + 2 credits across two zones is three. + final h = credit(s); + final other = credits(s).cast().firstWhere((x) => x.isEmpty); + h[0][1] = 2; + other.add([1.0, 1]); + }); + }); + test('totals at exactly the pairs are accepted', () { + for (final batch in [two, three]) { + final good = checkpointOf(_agg, batch); + expect(decodeCheckpoint(_agg, good, kind: 'test', version: 1), + isNotNull); + } + }); + test('counts whose sum overflows an int are refused', () { + refuses(three, (s) { + cadence(s) + ..[0][1] = 0x7fffffffffffffff + ..add([2.0, 5]); + }); + refuses(three, (s) { + credit(s) + ..[0][1] = 0x7fffffffffffffff + ..add([2.0, 5]); + }); + }); + test('a histogram with one row behind it must be empty (no pairs)', () { + refuses(one, (s) => cadence(s).add([1.0, 1])); + refuses(one, (s) => credits(s)[0].add([1.0, 1])); + final empty = HrStream(Float64List(0), Float64List(0)); + expect(decodeCheckpoint( + _agg, checkpointOf(_agg, empty), kind: 'test', version: 1), + isNotNull); + }); + + test('review case: cadence [["NaN", 2]] is refused', () { + refuses(three, (s) => cadence(s) + ..clear() + ..add(['NaN', 2])); + }); + test('cadence keys must be finite and positive', () { + for (final key in ['NaN', 'Infinity', '-Infinity', 0.0, -1.0, -0.5]) { + refuses(three, (s) => cadence(s)[0][0] = key, 'cadence key $key'); + } + }); + test('credit keys must be finite; zero and negative are fine', () { + for (final key in ['NaN', 'Infinity', '-Infinity']) { + refuses(three, (s) => credit(s)[0][0] = key, 'credit key $key'); + } + // A zero or negative gap credits one cadence (the fallback), so these + // are reachable from non-monotonic timestamps and must still restore. + final back = _S([2000, 1000], [150, 150]).stream; // gap -1 s + final dup = _S([1000, 1000], [150, 150]).stream; // gap 0 + for (final batch in [back, dup]) { + final good = checkpointOf(_agg, batch); + expect(decodeCheckpoint(_agg, good, kind: 'test', version: 1), + isNotNull); + } + }); + + test('the tail exists exactly when there are rows', () { + refuses(three, (s) => (s as Map)['hasTail'] = false); + refuses(two, (s) => (s as Map)['hasTail'] = false); + refuses(one, (s) => (s as Map)['hasTail'] = false); + final empty = HrStream(Float64List(0), Float64List(0)); + refuses(empty, (s) => (s as Map)['hasTail'] = true); + }); + }); + + // The batch function and the aggregator agree with the independent reference + // on the ordinary streams the parity tests build, including the public entry. + test('HeartRateZones.timeInZone agrees with the frozen reference', () { + final r = Rng(0x71A); + for (var k = 0; k < 20; k++) { + final s = _gen(r, r.intIn(2, 60)); + final want = _referenceTimeInZone(s.samples, _zones); + _same(HeartRateZones.timeInZone(s.samples, _zones), want, 'public $k'); + } + }); + + // # catches: a non-finite timestamp stored an infinite gap (cadence [1, 1, + // Infinity], 4 s credited at 150 bpm). The state encoded, but restore refuses + // infinite histogram keys, so an accepted state could not be restored. + group('a non-finite timestamp is refused before it can be stored', () { + final bad = _S([0, 1000, 2000, double.infinity], [150, 150, 150, 150]); + + test('the aggregator refuses the slice and the state is unchanged', () { + final state = _agg.fold(_S([0, 1000], [150, 150]).stream); + final before = jsonEncode(_agg.encodeState(state)); + expect(() => _agg.addSlice(state, bad.stream, 0, bad.n), + throwsArgumentError); + expect(jsonEncode(_agg.encodeState(state)), before); + expect(() => _agg.fold(bad.stream), throwsArgumentError); + }); + + test('NaN and -Infinity are refused the same way', () { + for (final t in [double.nan, double.negativeInfinity]) { + final s = _S([0, 1000, t, 3000], [150, 150, 150, 150]); + expect(() => _agg.fold(s.stream), throwsArgumentError, reason: '$t'); + } + }); + + test('the batch entry point has no time-in-zone to report', () { + expect(HeartRateZones.timeInZone(bad.samples, _zones), isNull); + }); + + test('every accepted state encodes, restores and finishes the same', () { + final r = Rng(0x71B); + for (var k = 0; k < 10; k++) { + final s = _gen(r, r.intIn(2, 80)); + final state = _agg.fold(s.stream); + final back = _agg.decodeState( + jsonDecode(jsonEncode(_agg.encodeState(state)))); + _same(_agg.finish(back), _agg.finish(_agg.fold(s.stream)), 'trip $k'); + } + }); + }); + + // # catches: HrStream.fromJson checks column lengths only, so a retained edge + // with an infinite timestamp decoded and later became an infinite credit gap, + // a histogram key that restore refuses. + group('retained timestamps must be finite at restore', () { + final three = _S([0, 1000, 2000], [150, 150, 150]).stream; + Map windows(Object? s) => (s as Map)['windows'] as Map; + for (final bad in ['Infinity', '-Infinity', 'NaN']) { + test('last edge timestamp $bad is refused', () { + expectDamagedCheckpointRefused(_agg, three, (s) { + (windows(s)['last'] as Map)['tsMs'] = [bad]; + return s; + }, reason: 'last $bad'); + }); + test('first edge timestamp $bad is refused', () { + expectDamagedCheckpointRefused(_agg, three, (s) { + (windows(s)['first'] as Map)['tsMs'] = [bad]; + return s; + }, reason: 'first $bad'); + }); + test('tail timestamp $bad is refused', () { + expectDamagedCheckpointRefused(_agg, three, (s) { + (s as Map)['tailTimestampMs'] = bad; + return s; + }, reason: 'tail $bad'); + }); + } + test('a good checkpoint still restores', () { + expect( + decodeCheckpoint(_agg, checkpointOf(_agg, three), + kind: 'test', version: 1), + isNotNull); + }); + }); + + // # catches: HeartRateZones.timeInZone re-sorted with Dart's unstable + // List.sort, so the 34 rows at one instant (more than the 32 that sort keeps + // in order) could swap places and a different reading was credited than the + // aggregator, which keeps input order, credited. + group('repeated timestamps keep their input order on every path', () { + // maxHr 200. 34 rows at t = 0: 33 at HR 110 then one at 190. Then six + // off-skin rows a second apart, from 500 ms. + final ts = [for (var i = 0; i < 34; i++) 0, for (var i = 0; i < 6; i++) 500.0 + 1000 * i]; + final hr = [for (var i = 0; i < 33; i++) 110, 190, for (var i = 0; i < 6; i++) 0]; + final s = _S(ts, hr); + + test('the aggregator and the batch function both match the reference', () { + final want = _referenceTimeInZone(s.samples, _zones); + expect(want, isNotNull); + _same(_agg.run(s.stream), want, 'aggregator'); + _same(HeartRateZones.timeInZone(s.samples, _zones), want, 'batch'); + _same(HeartRateZones.timeInZone(s.samples, _zones), _agg.run(s.stream), + 'batch vs aggregator'); + }); + + test('the order the rows arrive in decides the credit, so it is kept', () { + // The same rows with the 190 reading first: a different credit, which + // shows the ordering is real and that the stable one is what is returned. + final swapped = _S(ts, [190, for (var i = 0; i < 33; i++) 110, for (var i = 0; i < 6; i++) 0]); + final a = HeartRateZones.timeInZone(s.samples, _zones)!; + final b = HeartRateZones.timeInZone(swapped.samples, _zones)!; + expect(_eq(a, b), isFalse, + reason: 'the last reading at the repeated instant is credited'); + _same(b, _referenceTimeInZone(swapped.samples, _zones), 'swapped'); + }); + + test('many repeated instants in a longer stream stay in input order', () { + final r = Rng(0x5712); + for (var k = 0; k < 10; k++) { + final n = 40 + r.intIn(0, 60); + final t = []; + final h = []; + var at = 0.0; + for (var i = 0; i < n; i++) { + if (r.nextBool(.3)) at += 1000; + t.add(at); + h.add(r.nextBool(.1) ? 0 : 60 + r.nextDouble() * 130); + } + final x = _S(t, h); + final want = _referenceTimeInZone(x.samples, _zones); + _same(HeartRateZones.timeInZone(x.samples, _zones), want, 'batch $k'); + _same(_agg.run(x.stream), want, 'aggregator $k'); + } + }); + }); +} diff --git a/test/aggregate/trimp_aggregator_test.dart b/test/aggregate/trimp_aggregator_test.dart new file mode 100644 index 0000000..e12d485 --- /dev/null +++ b/test/aggregate/trimp_aggregator_test.dart @@ -0,0 +1,298 @@ +// banisterTrimpAggregator must agree with banisterTrimp for the same rows under +// any slicing or chunking, and obey the aggregator laws. +// +// Contract used here: +// * banisterTrimpAggregator({restingHr, maxHr, sex}) is an +// Aggregator<_, DoubleColumn, Metric>; the column is the per-minute +// HR (NaN = missing). Exported from package:openstrap_analytics/aggregate.dart. +// * Anchors null / NaN / infinite, or maxHr <= restingHr: absent, for any rows +// (the note, tier and inputs_used equal banisterTrimp's). +// * Valid anchors and ZERO rows: absent (banisterTrimp's hrPerMin.isEmpty). +// * Valid anchors and at least one row, all of them non-finite or <= 0: +// PRESENT with value 0.0 and confidence 0.6. "Zero rows" means length 0 of +// the whole batch, not "no finite row". +// * value within relTol 1e-12; present, confidence, tier, inputs_used and +// note equal. +// * Constructing the aggregator never throws, whatever the anchors are. + +import 'dart:math' as math; +import 'dart:typed_data'; + +import 'package:openstrap_analytics/aggregate.dart'; +import 'package:openstrap_analytics/onehz.dart'; +import 'package:test/test.dart'; + +import '../support/checkpoint_support.dart'; +import '../support/aggregator_laws.dart'; +import '../support/property.dart' show Rng; + +const nan = double.nan; +const inf = double.infinity; + +typedef _Agg = Aggregator>; + +List _fields(Metric m) => [ + m.present, + m.value, + m.confidence, + m.tier, + m.inputs_used.join(','), + m.note, + ]; + +final _eq = fieldsEqual>(_fields, relTol: 1e-12); + +void _same(Metric got, Metric want, String tag) { + expect(_eq(got, want), isTrue, + reason: '$tag\n got ${_fields(got)}\nwant ${_fields(want)}'); +} + +_Agg _agg(double? rest, double? max, Sex sex) => + banisterTrimpAggregator(restingHr: rest, maxHr: max, sex: sex); + +/// The reference: Banister TRIMP written out from the published formula +/// (Banister 1991, Morton 1990), not through `banisterTrimp`, which now runs the +/// aggregator, nor through the shared weighting helper: +/// TRIMP = sum over worn minutes of x * y(x), x = (HR - RHR) / (HRmax - RHR) +/// men y = 0.64 * e^(1.92 x) women y = 0.86 * e^(1.67 x) +/// Its own filtering (off-skin and non-finite minutes are skipped) and clamping +/// (x into [0, 1]). A plain sum: every term is non-negative and bounded, so it +/// agrees with the aggregator's compensated sum to far under the 1e-12 used. +Metric _referenceBanister(List hrPerMin, + {required double? restingHr, required double? maxHr, required Sex sex}) { + const inputs = ['hr_per_min', 'resting_hr', 'max_hr']; + if (restingHr == null || + maxHr == null || + !restingHr.isFinite || + !maxHr.isFinite || + maxHr <= restingHr || + hrPerMin.isEmpty) { + return const Metric.absent( + tier: Tier.estimate, + inputs_used: inputs, + note: 'Banister TRIMP needs finite measured RHR and HRmax (HRmax>RHR)', + ); + } + final reserve = maxHr - restingHr; + var total = 0.0; + for (final hr in hrPerMin) { + if (!hr.isFinite || hr <= 0) continue; + final x = math.min(1.0, math.max(0.0, (hr - restingHr) / reserve)); + final y = sex == Sex.female + ? 0.86 * math.exp(1.67 * x) + : 0.64 * math.exp(1.92 * x); + total += x * y; + } + return Metric( + value: total, + confidence: 0.6, + tier: Tier.estimate, + inputs_used: inputs, + note: 'Banister exponential TRIMP (wrist HR estimate)', + ); +} + +Metric _want(DoubleColumn c, double? rest, double? max, Sex sex) => + _referenceBanister(c.values, restingHr: rest, maxHr: max, sex: sex); + +double _hr(Rng r) { + final k = r.nextDouble(); + if (k < .04) return 0; + if (k < .08) return -r.nextDouble() * 50; + if (k < .10) return inf; + if (k < .12) return -inf; + if (k < .30) return 30 + r.nextDouble() * 30; // around / below resting + if (k < .35) return 190 + r.nextDouble() * 40; // above max + return 50 + r.nextDouble() * 140; +} + +DoubleColumn _hrColumn(Rng r, int n, {double nanP = .1}) => + DoubleColumn(Float64List.fromList( + [for (var i = 0; i < n; i++) r.nextBool(nanP) ? nan : _hr(r)])); + +void main() { + group('absent cases', () { + final rows = col([60, 100, 150, 120]); + final badAnchors = { + 'null resting': (null, 190), + 'null max': (55, null), + 'both null': (null, null), + 'NaN resting': (nan, 190), + 'NaN max': (55, nan), + 'infinite resting': (-inf, 190), + 'infinite max': (55, inf), + 'max == resting': (60, 60), + 'max < resting': (80, 70), + }; + badAnchors.forEach((name, a) { + for (final sex in Sex.values) { + test('$name (${sex.name}): absent, same note as banisterTrimp', () { + final want = _want(rows, a.$1, a.$2, sex); + expect(want.present, isFalse); + final agg = _agg(a.$1, a.$2, sex); + // Empty and non-finite-only input are absent too, anchors rule. + expectConversion>( + (_) => agg, + [rows, col([]), col([nan, 0, -5])], + (c) => _want(c, a.$1, a.$2, sex), + equals: _eq); + }); + } + }); + + test('valid anchors, zero rows: absent', () { + for (final sex in Sex.values) { + final agg = _agg(55, 190, sex); + final want = _want(col([]), 55, 190, sex); + expect(want.present, isFalse); + _same(agg.run(col([])), want, 'empty'); + _same(agg.finish(agg.empty()), want, 'empty state'); + _same( + agg.finish(agg.combine( + agg.fold(col([]), 0, 0), agg.fold(col([]), 0, 0))), + want, + 'empty combined'); + } + }); + + test('rows that all vanish in a chunk still count as rows', () { + // 3 rows, none usable: PRESENT 0.0 (not absent) however it is cut. + final c = col([nan, 0, -3]); + for (final sex in Sex.values) { + final agg = _agg(55, 190, sex); + final want = _want(c, 55, 190, sex); + expect(want.present, isTrue); + expect(want.value, 0.0); + expectConversion>( + (_) => agg, [c], (c) => _want(c, 55, 190, sex), + equals: _eq, chunkings: 24); + } + }); + }); + + group('present with 0.0 when no row counts', () { + final cases = { + 'one NaN': col([nan]), + 'one zero': col([0]), + 'one negative': col([-40]), + 'infinities': col([inf, -inf]), + 'mixed junk': col([nan, 0, -1, inf, -inf, nan]), + }; + cases.forEach((name, c) { + for (final sex in Sex.values) { + test('$name (${sex.name})', () { + final want = _want(c, 55, 190, sex); + expect(want.present, isTrue); + expect(want.value, 0.0); + expect(want.confidence, 0.6); + final got = _agg(55, 190, sex).run(c); + _same(got, want, name); + expect(got.value, 0.0); + expect(got.confidence, 0.6); + }); + } + }); + }); + + group('values', () { + test('hand-worked: resting is 0, max is 0.64 e^1.92 (male)', () { + final a = _agg(50, 190, Sex.male); + expect(a.run(col([50])).value, 0.0); + expect(a.run(col([190])).value, closeTo(0.64 * math.exp(1.92), 1e-12)); + // Clamped: below resting counts 0 (but is still a present row), above + // max counts as max. + expect(a.run(col([40, 250])).value, + closeTo(0.64 * math.exp(1.92), 1e-12)); + }); + test('hand-worked: female coefficients 0.86 and 1.67', () { + final a = _agg(50, 190, Sex.female); + expect(a.run(col([190])).value, closeTo(0.86 * math.exp(1.67), 1e-12)); + final x = (120 - 50) / 140; + expect(a.run(col([120])).value, + closeTo(x * 0.86 * math.exp(1.67 * x), 1e-12)); + }); + test('metadata equals the reference on a plain day', () { + final c = col([60, 70, 90, 120, 150, 100]); + for (final sex in Sex.values) { + final got = _agg(55, 190, sex).run(c); + final want = _want(c, 55, 190, sex); + expect(got.confidence, 0.6); + expect(got.tier, want.tier); + expect(got.inputs_used, want.inputs_used); + expect(got.note, want.note); + _same(got, want, 'plain'); + } + }); + test('sexes differ', () { + final c = col([150, 160]); + expect(_agg(55, 190, Sex.male).run(c).value, + isNot(_agg(55, 190, Sex.female).run(c).value)); + }); + }); + + group('random parity (seeded)', () { + test('random anchors, sex, rows; every evaluation path', () { + final r = Rng(0x7217); + final params = Map.identity(); + for (var t = 0; t < 120; t++) { + final n = r.nextBool(.15) ? r.intIn(0, 3) : r.intIn(0, 300); + final c = _hrColumn(r, n, nanP: r.nextBool() ? .05 : .4); + // Mostly valid anchors; sometimes degenerate. + double? rest = 40 + r.nextDouble() * 40; + double? max = rest + (r.nextBool(.1) ? -5 : 60) + r.nextDouble() * 80; + if (r.nextBool(.05)) rest = null; + if (r.nextBool(.05)) max = nan; + params[c] = (rest, max, r.nextBool() ? Sex.male : Sex.female); + } + expectConversion>( + (c) => _agg(params[c]!.$1, params[c]!.$2, params[c]!.$3), + params.keys.toList(), + (c) => _want(c, params[c]!.$1, params[c]!.$2, params[c]!.$3), + equals: _eq); + }); + }); + + test('persistable: a mid-stream checkpoint resumes to the one-pass result', () { + final a = _agg(55, 190, Sex.male); + expectCheckpointResumes(a, _hrColumn(Rng(0xC0DE), 120), equals: _eq); + }); + + group('lawful', () { + final cols = [ + ...randomColumns(31, value: _hr, nanP: .1), + col([nan, 0, -2]), + col([inf, 120]), + ]; + for (final sex in Sex.values) { + test('valid anchors (${sex.name})', + () => expectLawful(_agg(55, 190, sex), cols, equals: _eq)); + } + test('invalid anchors', + () => expectLawful(_agg(null, 190, Sex.male), cols, equals: _eq)); + }); + + // The public batch function runs the aggregator now; it must still equal the + // independent reference on ordinary, off-skin, non-finite and clamped minutes. + test('banisterTrimp agrees with the published-formula reference', () { + final r = Rng(0xB17); + for (final sex in Sex.values) { + for (var k = 0; k < 25; k++) { + final hr = [for (var i = r.intIn(0, 200); i > 0; i--) _hr(r)]; + final rest = 45 + r.nextDouble() * 25, max = 170 + r.nextDouble() * 40; + _same(banisterTrimp(hr, restingHr: rest, maxHr: max, sex: sex), + _referenceBanister(hr, restingHr: rest, maxHr: max, sex: sex), + '${sex.name} $k'); + } + } + // Known values at the endpoints and the midpoint of the reserve. + for (final (hr, male, female) in [ + (55.0, 0.0, 0.0), // at rest: no reserve used + (190.0, 0.64 * math.exp(1.92), 0.86 * math.exp(1.67)), // full reserve + ]) { + expect(_referenceBanister([hr], restingHr: 55, maxHr: 190, sex: Sex.male).value, + closeTo(male, 1e-9)); + expect(_referenceBanister([hr], restingHr: 55, maxHr: 190, sex: Sex.female).value, + closeTo(female, 1e-9)); + } + }); +}