ml-time-graph 1.0.0 → 1.0.2

package/dist/analyze/index.d.ts

@@ -1,5 +1,81 @@
-import { l as DataPoint, A as AggregatedPoint, d as AggregationThresholds, J as Gap, ae as TimeScale, W as LinearScale, _ as Point, p as DrawCommand } from '../scale-Cbr0KpPz.js';
-import { S as StatsAggregatedPoint } from '../aggregated_subtypes-DZNZyFTX.js';
+/*!
+ * ml-time-analyze — Copyright (c) 2026 Michael Lechner
+ * MIT with Attribution: free use incl. commercial requires visible credit to
+ * "Michael Lechner". Commercial license (no attribution) on request. See LICENSE.
+ */
+/** A single measurement. `value: null` = gap (no reading at this time). */
+interface DataPoint {
+    /** Wall-clock time as a millisecond epoch. */
+    time: number;
+    /** Numeric reading, or `null` to mark a gap (no measurement). */
+    value: number | null;
+    /** Optional free-text annotation attached to the point. */
+    annotation?: string;
+    /**
+     * Synthetic point — not a real measurement. Set by `SeriesProcessor`
+     * on interpolated points (threshold crossings, gap edges) or by users
+     * who want their own computed waypoints to be ignored for tooltip
+     * snapping and statistics.
+     */
+    synthetic?: boolean;
+}
+/** A bucketed aggregate (one slot of `aggregateBySlot`). */
+interface AggregatedPoint {
+    time: number;
+    min: number | null;
+    max: number | null;
+    avg: number | null;
+    /** Number of raw samples that fell into this slot. */
+    count: number;
+}
+/** Aggregation grouping. */
+type AggregationMode = "none" | "hourly" | "daily" | "custom";
+interface AggregationConfig {
+    mode: AggregationMode;
+    /** Slot length in ms — required when `mode === 'custom'`. */
+    interval?: number;
+}
+/**
+ * A time-range gap detected by `detectGaps`. Minimal shape — start, end
+ * and an optional label. The chart package extends this with its own
+ * presentation fields (fill, hatch, style) for rendering.
+ */
+interface DetectedGap {
+    startTime: number;
+    endTime: number;
+    label?: string;
+}
+/**
+ * Optional limits passed to `aggregateBySlot`. When set, the returned
+ * slots widen to {@link StatsAggregatedPoint} (MKT + σ + minutes-above /
+ * minutes-below).
+ */
+interface AggregationThresholds {
+    limitLow: number;
+    limitHigh: number;
+    /** Activation energy for the Arrhenius MKT formula. Default 83 144 J/mol (USP <1079.2>). */
+    activationEnergy?: number;
+}
+/** Slot carrying a rolling Mean Kinetic Temperature value (USP <1079.2>). */
+interface MktPoint extends AggregatedPoint {
+    mkt: number | null;
+    /** Delta vs the previous slot's MKT (optional). */
+    deltaMkt?: number | null;
+}
+/** Slot carrying the standard deviation of the samples in the window. */
+interface StdDevPoint extends AggregatedPoint {
+    stdDev: number | null;
+}
+/** Slot carrying minutes-above-/below-limit statistics. */
+interface LimitStatsPoint extends AggregatedPoint {
+    minutesAboveHigh?: number | null;
+    minutesBelowLow?: number | null;
+}
+/**
+ * Full-stats slot — what `aggregateBySlot(data, mode, thresholds)` returns
+ * when thresholds are provided. Carries MKT, σ, and minutes-out-of-bounds.
+ */
+type StatsAggregatedPoint = MktPoint & StdDevPoint & LimitStatsPoint;
 
 /*!
  * MLTimeGraph — Copyright (c) 2026 Michael Lechner
@@ -73,7 +149,7 @@ declare function createAggr(time: number, values: number[]): AggregatedPoint;
  * Detect gaps in time-series data (autoDetect).
  * Gibt alle Zeitenrücken zurück wo das Zeitintervall > minGapMs ist.
  */
-declare function detectGaps(data: DataPoint[], minGapMs?: number): Gap[];
+declare function detectGaps(data: DataPoint[], minGapMs?: number): DetectedGap[];
 interface LongTermInsight {
     type: "warning" | "info" | "critical";
     message: string;
@@ -132,49 +208,17 @@ declare class StatsAggregator {
     /** Compute stats for a specific time range (viewport-scoped) */
     static computeInRange(data: DataPoint[], startTime: number, endTime: number): StatsResult;
 }
-
-/*!
- * MLTimeGraph — Copyright (c) 2026 Michael Lechner
- * MIT with Attribution: free use incl. commercial requires visible credit to
- * "Michael Lechner". Commercial license (no attribution) on request. See LICENSE.
+/**
+ * Coefficient of variation (Cv = σ / μ × 100 %). Dimensionless — comparable
+ * across devices that operate at very different temperature levels
+ * (fridge at 4 °C vs incubator at 37 °C vs room at 20 °C). A ±1 °C drift
+ * is huge for the fridge but tiny for the incubator, and Cv captures that.
+ *
+ * Returns null when `mean` is zero or non-finite (the metric is undefined).
+ * The result is the absolute value, so negative means (e.g. freezer
+ * profiles like −30 °C) still give a positive percentage.
  */
-
-/** Moving average type */
-type MovingAvgType = "simple" | "exponential";
-interface MovingAvgConfig {
-    /** Data points */
-    data: DataPoint[];
-    /** Window size (number of data points) */
-    windowSize: number;
-    /** MA type */
-    type?: MovingAvgType;
-    /** Time scale for X-axis */
-    timeScale: TimeScale;
-    /** Value scale for Y-axis */
-    valueScale: LinearScale;
-    /** Stroke color */
-    stroke?: string;
-    /** Stroke width */
-    strokeWidth?: number;
-}
-declare class MovingAvg {
-    #private;
-    constructor(config: MovingAvgConfig);
-    /** Compute simple moving average points */
-    static simple(data: DataPoint[], windowSize: number): {
-        time: number;
-        value: number;
-    }[];
-    /** Compute exponential moving average (EMA) */
-    static exponential(data: DataPoint[], windowSize: number): {
-        time: number;
-        value: number;
-    }[];
-    /** Get computed moving average as pixel points */
-    points(): Point[];
-    /** Render MA as a path command */
-    render(): DrawCommand[];
-}
+declare function varianceCoefficient(meanOrStats: number | StatsResult, stdDev?: number): number | null;
 
 /*!
  * MLTimeGraph — Copyright (c) 2026 Michael Lechner
@@ -293,4 +337,186 @@ interface ComputeLimitsOpts {
  */
 declare function computeLimitExcursions(data: DataPoint[], opts: ComputeLimitsOpts): LimitStats;
 
-export { type ComputeLimitsOpts, DEFAULT_ACTIVATION_ENERGY, type LimitExcursion, type LimitStats, type LongTermInsight, MovingAvg, type MovingAvgConfig, type MovingAvgType, PRODUCT_PROFILES, type ProductConfig, type ProductType, SeriesProcessor, StatsAggregator, type StatsResult, aggregateBySlot, aggregateWithStats, analyzeLongTermTrends, computeLimitExcursions, createAggr, detectGaps, downsample, mkt, rollingMkt, rollingStdDev, sampleStdDev, stdDev };
+/*!
+ * MLTimeGraph — Copyright (c) 2026 Michael Lechner
+ * MIT with Attribution: free use incl. commercial requires visible credit to
+ * "Michael Lechner". Commercial license (no attribution) on request. See LICENSE.
+ */
+
+/** A named series for spatial analysis — a single sensor in the room. */
+interface NamedSeries {
+    /** Stable identifier (e.g. "S_FLOOR", "S_CEILING"). */
+    name: string;
+    /** Time-ordered samples. `value: null` is treated as a gap and ignored. */
+    data: DataPoint[];
+}
+/**
+ * Per-timestamp summary of a multi-sensor recording.
+ * `delta = max - min` is the room's "spatial spread" at that instant.
+ */
+interface SpatialPoint {
+    time: number;
+    /** Lowest reading across all sensors at this timestamp. */
+    min: number | null;
+    /** Highest reading across all sensors at this timestamp. */
+    max: number | null;
+    /** `max - min`; null if fewer than two valid readings at this timestamp. */
+    delta: number | null;
+    /** Name of the sensor that supplied `min`. */
+    minSensor: string | null;
+    /** Name of the sensor that supplied `max`. */
+    maxSensor: string | null;
+}
+/**
+ * Compute the spatial spread per timestamp across a set of sensor series.
+ * Returns one {@link SpatialPoint} per unique timestamp found across all
+ * inputs, in ascending time order.
+ *
+ * Sensors are matched by timestamp (no interpolation). For each timestamp
+ * we collect every non-null sample at that exact time and emit min, max
+ * and their delta — plus which sensor produced each extremum (handy for
+ * UI badges like "Hotspot: S_CEILING at 14:32").
+ *
+ * The caller is responsible for upstream alignment (same sample cadence
+ * across sensors). If a sensor has no sample at a given timestamp it is
+ * silently skipped for that point.
+ */
+declare function spatialDelta(sensors: NamedSeries[]): SpatialPoint[];
+/** Aggregate statistics for one sensor across the full observation window. */
+interface SensorStat {
+    name: string;
+    mean: number;
+    min: number;
+    max: number;
+    /** Sample count used (null values skipped). */
+    count: number;
+}
+/** Result of {@link hotColdSpots}. */
+interface HotColdSpotsResult {
+    /** Per-sensor stats in input order. Sensors with no valid samples are omitted. */
+    sensors: SensorStat[];
+    /** Sensor with the highest mean. `null` if no sensor had any samples. */
+    hottest: SensorStat | null;
+    /** Sensor with the lowest mean. */
+    coldest: SensorStat | null;
+    /** `hottest.mean - coldest.mean` — the long-term stratification of the room. */
+    meanDelta: number | null;
+}
+/**
+ * Find the hottest and coldest sensor over an extended period — the
+ * "stratification" of a room. Each sensor's mean is computed across its
+ * own samples (null values skipped); the function then picks the highest-
+ * and lowest-mean sensor.
+ *
+ * Use for long-window (days / weeks) reports to identify positions where
+ * sensitive products should NOT be stored. For short-term spread use
+ * {@link spatialDelta} instead.
+ */
+declare function hotColdSpots(sensors: NamedSeries[]): HotColdSpotsResult;
+
+/*!
+ * MLTimeGraph — Copyright (c) 2026 Michael Lechner
+ * MIT with Attribution: free use incl. commercial requires visible credit to
+ * "Michael Lechner". Commercial license (no attribution) on request. See LICENSE.
+ */
+
+/** Result of a single linear-regression fit. */
+interface TrendFit {
+    /** Slope in value-units per **millisecond** (multiply by 60000 for per-minute). */
+    slope: number;
+    /** Y-intercept of the fit line (value at time=0 epoch). */
+    intercept: number;
+    /** Number of (non-null) points used. */
+    n: number;
+}
+/** One rolling-trend output sample. */
+interface TrendPoint {
+    /** Center time of the window — the input point's own timestamp. */
+    time: number;
+    /** Trend fit for the window ending at `time`, or null if too few points. */
+    fit: TrendFit | null;
+}
+/**
+ * Linear regression (`y = m·x + b`) over an arbitrary point set.
+ * `value: null` is skipped. Returns null when fewer than 2 valid points
+ * remain or when all timestamps are identical (vertical line).
+ */
+declare function linearFit(points: DataPoint[]): TrendFit | null;
+/**
+ * Trend over the most recent `lookbackMs` of the series — useful as a
+ * "current rate of change" snapshot. Returns null when the last sample is
+ * null or fewer than 2 valid points fall inside the lookback window.
+ */
+declare function currentTrend(data: DataPoint[], lookbackMs: number): TrendFit | null;
+/**
+ * For each input point, emit a {@link TrendPoint} containing the linear fit
+ * of all points in `[time - windowMs, time]`. Useful for plotting "rate of
+ * change" as a secondary series, or for detecting when the slope itself
+ * starts to climb.
+ *
+ * `data` should be sorted by time ascending. Output length equals input
+ * length.
+ */
+declare function rollingTrend(data: DataPoint[], windowMs: number): TrendPoint[];
+/** Options for {@link predictTimeToThreshold}. */
+interface PredictOpts {
+    /** Window for the trend fit. Default 15 min. */
+    lookbackMs?: number;
+    /**
+     * Which crossing to predict:
+     *  - 'above' = predict when value will rise above `threshold`
+     *  - 'below' = predict when value will fall below `threshold`
+     *  - 'either' (default) = either direction, whichever the trend points to.
+     */
+    side?: "above" | "below" | "either";
+}
+/** Result of {@link predictTimeToThreshold}. */
+interface PredictResult {
+    /** Milliseconds from `data[last].time` until the threshold is crossed. */
+    msUntil: number;
+    /** Predicted crossing wall-clock time (ms epoch). */
+    eta: number;
+    /** Trend fit used for the extrapolation. */
+    fit: TrendFit;
+    /** Current value (the last non-null sample). */
+    currentValue: number;
+}
+/**
+ * Predict — assuming the current trend continues unchanged — how long until
+ * the series crosses `threshold`. Returns null when the trend is flat,
+ * heading the wrong way, or no usable data exists.
+ *
+ * Designed for the predictive-alarm pattern: fire a warning while the value
+ * is still in spec but trending toward a hard limit, e.g. compressor
+ * weakness on a fridge or a slow-leak excursion in a pharma room.
+ */
+declare function predictTimeToThreshold(data: DataPoint[], threshold: number, opts?: PredictOpts): PredictResult | null;
+
+/*!
+ * MLTimeGraph — Copyright (c) 2026 Michael Lechner
+ * MIT with Attribution: free use incl. commercial requires visible credit to
+ * "Michael Lechner". Commercial license (no attribution) on request. See LICENSE.
+ */
+
+/** Options for {@link f0Sterilization}. */
+interface F0Opts {
+    /** Reference temperature in °C. Default 121.11 °C (USP <1229>). */
+    refTempCelsius?: number;
+    /** z-value (resistance constant) in Kelvin. Default 10 K (B. stearothermophilus). */
+    zValueKelvin?: number;
+}
+/**
+ * Compute the F₀ value (in minutes) of a heat-treatment temperature record
+ * via trapezoidal integration of the lethality rate
+ * `L(T) = 10^((T − T_ref) / z)`.
+ *
+ * `data` must be sorted by `time` ascending. `value: null` breaks the
+ * integration — adjacent valid points around the gap are skipped (the gap
+ * contributes nothing to F₀, which is conservative).
+ *
+ * Returns 0 for empty input or a single point. Negative or non-finite
+ * temperatures produce a negligible contribution (L → 0).
+ */
+declare function f0Sterilization(data: DataPoint[], opts?: F0Opts): number;
+
+export { type AggregatedPoint, type AggregationConfig, type AggregationMode, type AggregationThresholds, type ComputeLimitsOpts, DEFAULT_ACTIVATION_ENERGY, type DataPoint, type F0Opts, type HotColdSpotsResult, type LimitExcursion, type LimitStats, type LimitStatsPoint, type LongTermInsight, type MktPoint, type NamedSeries, PRODUCT_PROFILES, type PredictOpts, type PredictResult, type ProductConfig, type ProductType, type SensorStat, SeriesProcessor, type SpatialPoint, type StatsAggregatedPoint, StatsAggregator, type StatsResult, type StdDevPoint, type TrendFit, type TrendPoint, aggregateBySlot, aggregateWithStats, analyzeLongTermTrends, computeLimitExcursions, createAggr, currentTrend, detectGaps, downsample, f0Sterilization, hotColdSpots, linearFit, mkt, predictTimeToThreshold, rollingMkt, rollingStdDev, rollingTrend, sampleStdDev, spatialDelta, stdDev, varianceCoefficient };