Skip to content
opsinjs
Edit this page

Health

Trends and uncertainty

What a screen may say about change over time, about old, estimated or missing values, and about where a number came from.

opsinjs publishes no minimum window, change threshold, freshness window or accuracy figure for any metric. The metric's clinical owner supplies each one.

  1. Direction (up, down, unchanged) is arithmetic. Valence (better, worse) is a clinical judgement about one metric for one person, often unavailable. Keep them apart.
  2. Where no valence is defined, show direction only: no colour, status or adjective on the arrow.
  3. Draw no trend below the metric's declared minimum window. Two readings give a difference, not a direction.
  4. Below the metric's declared change threshold, say no change: "About the same as your average over the last 4 weeks."
  5. Name the baseline and window on screen, never a bare delta.
  6. Plot readings at their real times, show gaps, and never truncate the axis to steepen a slope (Data visualisation).
  7. A trend never sets a status. Status comes from the latest value against its range, so rising inside the usual range is not attention.
  8. Never extrapolate: no projected line, no "at this rate", no predicted value.
  9. Every chart has a text twin stating the same baseline, window and direction.
  10. Draw missing readings as missing, never interpolated or plotted as zero: "No readings between 3 and 17 March."
  11. A smoothed series keeps its raw points visible.

The product owns the baseline and the sentence. The screen is Trend review.

Staleness and missing data

A value is fresh, stale, partial, estimated or absent (States), and the reader must be able to tell which.

  1. Every value has a timestamp: relative for recency, absolute on demand.
  2. Each metric declares its own freshness window; none is defaulted.
  3. Staleness is shown by de-emphasising the value itself, not only in a caption.
  4. A stale value shows its age and a way to refresh, neither at full weight nor withheld.
  5. An estimate is labelled at the number with its source and rounded more coarsely (Numbers and units): "Estimated from your watch. Roughly 7 hours 30 minutes."
  6. A failed fetch and an empty history get different sentences and next actions. Neither is ever rendered as a number.
  7. A loading placeholder implies no value: no plausible number, chart shape or status colour.
  8. Status degrades with certainty. Check it first: a value of unestablished recency, completeness or provenance never drives attention or urgent.
  9. State a partial result; never average over the gap: "3 of your 4 devices have reported today."
  10. Offline is a state of its own: say the device is offline rather than showing last values as current (Offline and stale data).

Your data layer supplies each reading's time, marks estimates, separates failure from absence and names the reporting sources.

Not written yet. Specify the presentation of an explicit uncertainty interval: a measured value with a stated error bound, in text and in a chart.

Provenance

Each class bounds what the interface may assert:

  • Clinically measured (a laboratory result): compare against an attributed range and carry a status.
  • Device measured (a validated home cuff, a scale): compare against a range where the device's method supports it, and carry a status where a clinical rule says so.
  • Device estimated (optical heart rate in motion, sleep stages): show as an estimate and as trends, never with a clinical status on its own.
  • Self-reported (a typed weight, a remembered dose): record and display as reported, never as measured.
  1. Record provenance at capture; it travels with the value, never reconstructed or defaulted.
  2. Show it in plain words at the value and in its accessible name: "from your cuff", "estimated by your watch", "you entered this".
  3. Status is bounded by class. An estimate never escalates on its own, so a wrist reading taken mid-run raises no cardiac alert, and may prompt a cuff reading instead.
  4. Never combine classes in one figure, such as a weekly average, without saying so.
  5. Name the device ("your Model X cuff"), never marketing ("clinically validated technology").
  6. Attribute and link a manufacturer's accuracy claim. Never restate it as the product's own, strengthen it, or invent a figure.
  7. State once, at the number, what the device does not do: a wrist sensor does not measure blood pressure.
  8. Label a model output as one, with its inputs.
  9. Never silently correct self-reported data. Query an implausible entry with the reader.
  10. Exports carry provenance (Sharing with a clinician).

Components

TrendSparkline requires minimumPoints, and below it draws nothing and says so. changeThreshold has no default, and without it the caption names no direction. A gap is an explicit value: null. RelativeTime has no staleness default; staleAfterHours adds the stale words and muted treatment. Value renders null as an absence, never 0.

No component carries a provenance class, so rules 22 to 31 are the caller's. ResultCard takes provenance as free text, so never pass it a status derived from an estimate or a self-report. MetricTile's event defaults to measured, unchecked against how the figure was obtained. SourceCitation renders provenance beside a value, not in its accessible name, and checks nothing.

Not written yet. Specify the four provenance classes as a shared type and a prop on every component that renders a health value, so that rule 24 is enforced rather than reviewed.

Evidence

Every rule here is opinion; no study is cited. Rules 3 and 4 follow from measurement variability. The four classes are our model, coarse so a non-expert can assign them.

Take any accuracy claim from the manufacturer's current documentation or a study you have read. Differences in optical sensing across skin tones are discussed in research and by regulators. We give no figure or citation: ask your supplier, and apply rule 28.