dsh-plugin-show-me-data 0.1.0

package/src/core/stats/series.js

@@ -0,0 +1,465 @@
+/**
+ * Series statistics — pure functions over '{ t, v }[]' (docs/03 §2).
+ *
+ * Discipline (docs/07 M1): missing values are skipped, never interpolated and
+ * never treated as zero; small samples return 'undefined' rather than a
+ * fabricated σ or percentile; every returned number is finite or absent.
+ *
+ * @module core/stats/series
+ */
+import { daysBetween, monthsBetween } from '../time/range.js'
+
+/** Markers every upstream uses for "no observation". */
+const MISSING_MARKERS = new Set(['.', '', '-', 'null', 'none', 'n/a', 'na', 'nan', 'undefined'])
+
+/** Minimum sample size before a sample standard deviation is meaningful. */
+export const MIN_STDDEV_N = 6
+
+/** Minimum sample size before a percentile is meaningful. */
+export const MIN_PERCENTILE_N = 12
+
+/**
+ * Parse an upstream scalar into a number, honouring every documented missing
+ * marker (docs/03 §2 rule 2, docs/04 §1).
+ *
+ * @param {unknown} raw - upstream value.
+ * @returns {number|undefined} finite number or 'undefined' when missing.
+ */
+export function parseNumber(raw) {
+  if (typeof raw === 'number') return Number.isFinite(raw) ? raw : undefined
+  if (typeof raw !== 'string') return undefined
+  const trimmed = raw.trim()
+  if (MISSING_MARKERS.has(trimmed.toLowerCase())) return undefined
+  const cleaned = trimmed.replace(/,/g, '')
+  const value = Number(cleaned)
+  return Number.isFinite(value) ? value : undefined
+}
+
+/**
+ * Round to a fixed number of decimals, collapsing float noise
+ * ('115.004000000000005' → '115.004').
+ *
+ * @param {number|undefined} value - candidate value.
+ * @param {number} [decimals] - decimal places; omitted means unchanged.
+ * @returns {number|undefined} rounded value or 'undefined'.
+ */
+export function round(value, decimals) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return undefined
+  if (decimals === undefined || decimals === null) return value
+  const factor = 10 ** decimals
+  const scaled = Math.round((value + Number.EPSILON * Math.sign(value)) * factor) / factor
+  return Object.is(scaled, -0) ? 0 : scaled
+}
+
+/**
+ * Sort ascending by date, drop non-finite values, and keep the **last** entry
+ * for a repeated date (upstream revisions win, docs/03 §2 rule 1).
+ *
+ * 'v' is always the series' primary value. A price series may additionally carry
+ * an OHLC bar (`o`/`h`/`l`, with 'v' as the close), which the chart layer draws as
+ * a candle; those extras travel through every transform untouched, so a candle
+ * view never re-fetches or re-derives what the source already returned.
+ *
+ * @param {Array<{ t: string, v: number, o?: number, h?: number, l?: number }>} points - arbitrary points.
+ * @returns {Array<{ t: string, v: number, o?: number, h?: number, l?: number }>} normalized points.
+ */
+export function sortDedupe(points) {
+  const byDate = new Map()
+  for (const point of points) {
+    if (point === null || typeof point !== 'object') continue
+    if (typeof point.t !== 'string' || !Number.isFinite(point.v)) continue
+    const normalized = { t: point.t, v: point.v }
+    const bar = ohlcOf(point)
+    byDate.set(point.t, bar === undefined ? normalized : { ...normalized, ...bar })
+  }
+  return [...byDate.values()].sort((a, b) => (a.t < b.t ? -1 : a.t > b.t ? 1 : 0))
+}
+
+/**
+ * The OHLC extras of one point, when the bar is complete and coherent.
+ *
+ * A bar is only worth drawing if open, high and low are all finite and the
+ * high/low really do bound them: anything else would render an impossible
+ * candle, so the extras are dropped and the point stays a plain observation
+ * (the chart draws it as part of the line instead).
+ *
+ * @param {{ v?: number, o?: unknown, h?: unknown, l?: unknown }} [point] - candidate point.
+ * @returns {{ o: number, h: number, l: number }|undefined} the bar, or 'undefined'.
+ */
+export function ohlcOf(point) {
+  const { o, h, l } = point ?? {}
+  if (!Number.isFinite(o) || !Number.isFinite(h) || !Number.isFinite(l)) return undefined
+  const v = point.v
+  if (!Number.isFinite(v)) return undefined
+  if (h < Math.max(o, v) || l > Math.min(o, v)) return undefined
+  return { o, h, l }
+}
+
+/**
+ * Whether a series carries enough usable bars for a candlestick view.
+ *
+ * @param {Array<{ o?: number }>} [points] - points.
+ * @param {number} [minimum] - bars required before candles are offered.
+ * @returns {boolean} whether candles can be drawn.
+ */
+export function hasOhlc(points, minimum = 2) {
+  return (points ?? []).filter((point) => ohlcOf(point) !== undefined).length >= minimum
+}
+
+/**
+ * Period-over-period change against the previous existing observation
+ * (docs/03 §2 rule 4).
+ *
+ * @param {Array<{ t: string, v: number }>} points - normalized points.
+ * @returns {{ abs: number, pct: number }|undefined} change, or 'undefined' when undefined/zero-based.
+ */
+export function mom(points) {
+  if (points.length < 2) return undefined
+  const latest = points[points.length - 1]
+  const previous = points[points.length - 2]
+  if (previous.v === 0) return undefined
+  return { abs: latest.v - previous.v, pct: ((latest.v - previous.v) / Math.abs(previous.v)) * 100 }
+}
+
+/**
+ * Year-over-year change with same-calendar-period alignment (docs/03 §2 rule 3).
+ *
+ * The base is the observation one year (12 months) earlier for monthly and
+ * coarser series, or one quarter earlier for series dated on quarter ends.
+ * A ±1 month drift is tolerated and reported so downstream code can flag an
+ * approximate comparison; anything further is treated as "no base".
+ *
+ * @param {Array<{ t: string, v: number }>} points - normalized points.
+ * @param {{ toleranceMonths?: number }} [options] - alignment tolerance.
+ * @returns {{ value: number, base: number, baseAt: string, drift: number }|undefined} yoy result.
+ */
+export function yoy(points, { toleranceMonths = 1 } = {}) {
+  if (points.length < 2) return undefined
+  const latest = points[points.length - 1]
+  // Quarterly series are dated on quarter ends (03-31, 06-30, 09-30, 12-31).
+  // Their annual base is four quarters back — which is the same month one year
+  // earlier, so the target is a full 12 months for every frequency.
+  const targetMonths = 12
+
+  let best
+  for (const candidate of points) {
+    if (candidate.t >= latest.t) continue
+    const distance = monthsBetween(candidate.t, latest.t)
+    const drift = distance - targetMonths
+    if (Math.abs(drift) > toleranceMonths) continue
+    if (best === undefined || Math.abs(drift) < Math.abs(best.drift)) best = { candidate, drift }
+  }
+  if (best === undefined) return undefined
+  const base = best.candidate.v
+  if (base === 0) return undefined
+  return {
+    value: ((latest.v - base) / Math.abs(base)) * 100,
+    base,
+    baseAt: best.candidate.t,
+    drift: best.drift,
+  }
+}
+
+/**
+ * Moving average over 'window' observations. The first 'window - 1' outputs are
+ * 'undefined' — a partial mean would misrepresent the window (docs/07 T1.2).
+ *
+ * @param {Array<{ t: string, v: number }>} points - normalized points.
+ * @param {number} window - window size (>= 1).
+ * @returns {Array<{ t: string, v: number|undefined }>} moving average series.
+ */
+export function movingAverage(points, window) {
+  if (!Number.isInteger(window) || window < 1) {
+    throw new RangeError(`movingAverage: window must be a positive integer (got ${window})`)
+  }
+  return points.map((point, index) => {
+    if (index < window - 1) return { t: point.t, v: undefined }
+    let sum = 0
+    for (let i = index - window + 1; i <= index; i += 1) sum += points[i].v
+    return { t: point.t, v: sum / window }
+  })
+}
+
+/**
+ * Difference against the value 'window' observations back: 'v[i] - v[i-window]'.
+ *
+ * @param {Array<{ t: string, v: number }>} points - normalized points.
+ * @param {number} [window] - lookback in observations (default 1).
+ * @returns {Array<{ t: string, v: number|undefined }>} differenced series.
+ */
+export function diff(points, window = 1) {
+  if (!Number.isInteger(window) || window < 1) {
+    throw new RangeError(`diff: window must be a positive integer (got ${window})`)
+  }
+  return points.map((point, index) =>
+    index < window ? { t: point.t, v: undefined } : { t: point.t, v: point.v - points[index - window].v },
+  )
+}
+
+/**
+ * Sample standard deviation (n−1). Below {@link MIN_STDDEV_N} observations this
+ * is 'undefined': the panel must not present "2σ" computed from three points.
+ *
+ * @param {number[]} values - observations.
+ * @returns {number|undefined} standard deviation.
+ */
+export function stdDev(values) {
+  if (values.length < MIN_STDDEV_N) return undefined
+  const mean = values.reduce((a, b) => a + b, 0) / values.length
+  const variance = values.reduce((acc, v) => acc + (v - mean) ** 2, 0) / (values.length - 1)
+  return Math.sqrt(variance)
+}
+
+/**
+ * Linear-interpolated percentile. Below {@link MIN_PERCENTILE_N} observations
+ * this is 'undefined' (docs/07 T1.2).
+ *
+ * @param {number[]} values - observations.
+ * @param {number} p - quantile in '[0, 1]'.
+ * @returns {number|undefined} percentile value.
+ */
+export function percentile(values, p) {
+  if (values.length < MIN_PERCENTILE_N) return undefined
+  if (!(p >= 0 && p <= 1)) throw new RangeError(`percentile: p must be in [0,1] (got ${p})`)
+  const sorted = [...values].sort((a, b) => a - b)
+  const position = (sorted.length - 1) * p
+  const lower = Math.floor(position)
+  const upper = Math.ceil(position)
+  if (lower === upper) return sorted[lower]
+  return sorted[lower] + (sorted[upper] - sorted[lower]) * (position - lower)
+}
+
+/**
+ * Least-squares slope against the observation index, in units per period.
+ *
+ * @param {Array<{ t: string, v: number }>} points - normalized points.
+ * @returns {number|undefined} slope per observation.
+ */
+export function slope(points) {
+  if (points.length < 2) return undefined
+  const n = points.length
+  const meanX = (n - 1) / 2
+  const meanY = points.reduce((acc, p) => acc + p.v, 0) / n
+  let numerator = 0
+  let denominator = 0
+  for (let i = 0; i < n; i += 1) {
+    numerator += (i - meanX) * (points[i].v - meanY)
+    denominator += (i - meanX) ** 2
+  }
+  if (denominator === 0) return undefined
+  return numerator / denominator
+}
+
+/**
+ * z-score of the latest change against the history of changes
+ * (docs/03 §2 rule 8). Zero variance yields 'undefined' rather than Infinity.
+ *
+ * @param {Array<{ t: string, v: number }>} points - normalized points.
+ * @returns {number|undefined} z-score.
+ */
+export function zScoreLatestChange(points) {
+  const changes = []
+  for (let i = 1; i < points.length; i += 1) changes.push(points[i].v - points[i - 1].v)
+  if (changes.length < MIN_STDDEV_N - 1) return undefined
+  const latestChange = changes[changes.length - 1]
+  const history = changes.slice(0, -1)
+  const sigma = stdDev(history)
+  if (sigma === undefined || sigma === 0) return undefined
+  const mean = history.reduce((a, b) => a + b, 0) / history.length
+  return (latestChange - mean) / sigma
+}
+
+/**
+ * Count observations a fixed-cadence series should have had but does not
+ * (docs/07 T1.2).
+ *
+ * With an explicit 'cadenceDays' (the caller knows the indicator's frequency)
+ * the count is exact. Without one, cadence is inferred as the median gap of the
+ * observed series — which cannot see a series that published every other month
+ * consistently, and never invents a trading calendar (docs/03 §2 rule 12).
+ *
+ * @param {Array<{ t: string, v: number }>} points - normalized points.
+ * @param {{ cadenceDays?: number }} [options] - expected cadence.
+ * @returns {number} number of missing slots.
+ */
+export function missingCount(points, { cadenceDays } = {}) {
+  if (points.length < 2) return 0
+  const gaps = []
+  for (let i = 1; i < points.length; i += 1) gaps.push(daysBetween(points[i - 1].t, points[i].t))
+  const sorted = [...gaps].sort((a, b) => a - b)
+  const inferred = sorted[Math.floor(sorted.length / 2)]
+  const cadence = cadenceDays ?? inferred
+  if (!(cadence > 0)) return 0
+  let missing = 0
+  for (const gap of gaps) missing += Math.max(0, Math.round(gap / cadence) - 1)
+  return missing
+}
+
+/** Nominal days between observations, per frequency (documentation-only cadence). */
+export const FREQ_CADENCE_DAYS = {
+  daily: 1,
+  weekly: 7,
+  monthly: 31,
+  quarterly: 92,
+  annual: 366,
+}
+
+/**
+ * Assemble the 'SeriesStats' contract (docs/03 §1.4).
+ *
+ * @param {Array<{ t: string, v: number }>} input - points, any order.
+ * @param {{ decimals?: number, freq?: string }} [options] - rounding and frequency (for gap counting).
+ * @returns {object|undefined} stats object, or 'undefined' for an empty series.
+ */
+export function stats(input, { decimals, freq } = {}) {
+  const points = sortDedupe(input)
+  if (points.length === 0) return undefined
+
+  const latest = points[points.length - 1]
+  const prevPoint = points.length > 1 ? points[points.length - 2] : undefined
+  const values = points.map((p) => p.v)
+  const yoyResult = yoy(points)
+  const momResult = mom(points)
+  const sigma = stdDev(values)
+  // Both change fields are derived from the SAME difference and rounded to one
+  // decimal more than the reading itself, so they cannot contradict each other.
+  // Rounding `abs(latest - prev)` at display precision made a 0.05pp move show as
+  // `changeAbs: 0.0` beside `changePct: 1.5`, and an agent reading the panel
+  // reported that contradiction as a panel bug.
+  const changeDecimals = decimals === undefined ? 4 : decimals + 1
+  const change = prevPoint === undefined ? undefined : latest.v - prevPoint.v
+
+  const result = {
+    latest: round(latest.v, decimals),
+    latestAt: latest.t,
+    ...(prevPoint === undefined
+      ? {}
+      : {
+          prev: round(prevPoint.v, decimals),
+          changeAbs: round(change, changeDecimals),
+          ...(prevPoint.v === 0
+            ? {}
+            : { changePct: round((change / Math.abs(prevPoint.v)) * 100, decimals) }),
+        }),
+    ...(yoyResult === undefined ? {} : { yoy: round(yoyResult.value, decimals), yoyAlignedDrift: yoyResult.drift }),
+    ...(momResult === undefined ? {} : { mom: round(momResult.pct, decimals) }),
+    mean: round(values.reduce((a, b) => a + b, 0) / values.length, decimals),
+    min: round(Math.min(...values), decimals),
+    max: round(Math.max(...values), decimals),
+    stdDev: sigma === undefined ? 0 : round(sigma, decimals),
+    count: points.length,
+    missingCount: missingCount(points, { cadenceDays: FREQ_CADENCE_DAYS[freq] }),
+  }
+
+  const z = zScoreLatestChange(points)
+  if (z !== undefined) result.zScoreLatestChange = round(z, decimals)
+  const fitted = slope(points)
+  if (fitted !== undefined) {
+    result.slope = round(fitted, decimals)
+    const mean = values.reduce((a, b) => a + b, 0) / values.length
+    if (mean !== 0) result.slopeRel = round(fitted / mean, decimals)
+  }
+  const latestPercentile = percentileRank(values, latest.v)
+  if (latestPercentile !== undefined) result.percentile = latestPercentile
+
+  return result
+}
+
+/**
+ * Fraction of observations at or below 'value', linearly interpolated between
+ * the two bracketing ranks. 'undefined' below the percentile sample floor.
+ *
+ * @param {number[]} values - observations.
+ * @param {number} value - the value to rank.
+ * @returns {number|undefined} percentile in '[0, 1]'.
+ */
+export function percentileRank(values, value) {
+  if (values.length < MIN_PERCENTILE_N) return undefined
+  const sorted = [...values].sort((a, b) => a - b)
+  if (value <= sorted[0]) return 0
+  if (value >= sorted[sorted.length - 1]) return 1
+  let below = 0
+  for (const v of sorted) if (v <= value) below += 1
+  const rank = (below - 1) / (sorted.length - 1)
+  return Math.min(1, Math.max(0, rank))
+}
+
+/**
+ * Apply a catalog display transform to a point series (docs/03 §2 rules 5–7).
+ *
+ * Transform chains are expressed as 'display.transform' plus optional
+ * 'display.window'/'display.movingAvg':
+ *
+ * - 'raw' — unchanged;
+ * - 'diff' — 'v[i] - v[i-window]' (levels to changes);
+ * - 'pctChange' / 'mom' — percentage change against the previous observation;
+ * - 'yoy' — same-calendar-period percentage change;
+ * - 'annualize' — monthly × 12, quarterly × 4 (levels only).
+ *
+ * A trailing moving average ('movingAvg') is applied **after** the transform and
+ * drops the first 'window - 1' points, so a 3-month average of monthly changes
+ * never shows a partial window.
+ *
+ * @param {Array<{ t: string, v: number }>} points - normalized points.
+ * @param {object} display - catalog display spec.
+ * @returns {Array<{ t: string, v: number }>} transformed points (may be empty).
+ */
+export function applyTransform(points, display = {}) {
+  const base = sortDedupe(points)
+  const transform = display.transform ?? 'raw'
+  let out
+  switch (transform) {
+    case 'raw':
+      out = base
+      break
+    case 'diff':
+      out = diff(base, display.window ?? 1).filter((p) => p.v !== undefined)
+      break
+    case 'pctChange':
+    case 'mom':
+      out = base
+        .map((point, index) => {
+          if (index === 0) return undefined
+          const previous = base[index - 1]
+          if (previous.v === 0) return undefined
+          return { t: point.t, v: ((point.v - previous.v) / Math.abs(previous.v)) * 100 }
+        })
+        .filter(Boolean)
+      break
+    case 'yoy':
+      out = base
+        .map((point, index) => {
+          // Recompute yoy for every point, not only the last one.
+          const result = yoy(base.slice(0, index + 1))
+          return result === undefined ? undefined : { t: point.t, v: result.value }
+        })
+        .filter(Boolean)
+      break
+    case 'annualize':
+      out = base.map((point) => ({ t: point.t, v: point.v * (display.freq === 'quarterly' ? 4 : 12) }))
+      break
+    case 'ratio':
+      out = base
+      break
+    default:
+      throw new RangeError(`unknown display.transform: ${JSON.stringify(transform)}`)
+  }
+  if (display.movingAvg !== undefined) {
+    out = movingAverage(out, display.movingAvg).filter((p) => p.v !== undefined)
+  }
+  return out
+}
+
+/**
+ * Describe a transform's unit suffix, so the UI can label "(年化)" or a 3-month
+ * average without re-deriving it (docs/03 §2 rule 7).
+ *
+ * @param {object} display - catalog display spec.
+ * @returns {string} unit suffix ('' when none).
+ */
+export function transformSuffix(display = {}) {
+  const parts = []
+  if (display.transform === 'annualize') parts.push('年化')
+  if (display.movingAvg !== undefined) parts.push(`${display.movingAvg}期均值`)
+  return parts.length === 0 ? '' : ` (${parts.join('·')})`
+}