> ## Documentation Index
> Fetch the complete documentation index at: https://developer.neurofit.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Outcomes best practices

> How to design pre/post measurements and trends with the SDK, how to judge whether a change is real, and why a finger scan rather than a face scan.

The SDK is built to help you show that your app changes the body, not only how people say they feel. This page
collects what has worked in the NEUROFIT app and in the validation study.

## Pre/post around a session

The cleanest single-session design is a reading immediately before and immediately after your intervention
(a breathing exercise, a meditation, a coaching session).

* **Same posture, same place.** Seated, feet on the floor, phone resting on a table or the lap, both times.
* **Same finger and pressure.** The guidance handles this, but tell users to use the same fingertip.
* **Let the body settle first.** A minute of quiet sitting before the pre reading avoids measuring the walk to
  the chair.
* **Keep both readings at 60 s.** The accuracy figures apply to 60-second readings.
* **Use only `clean` and `usable` readings.** A `withheld` reading is a retry, not a data point.
* **Store `VitalsResult` whole**, including `flags`, `diagnostics`, `engineVersion` and `sdkVersion`, so you can
  audit and re-analyse later.

## Trends over days and weeks

For a trend, the reading conditions matter more than the count.

* **Morning, before caffeine, seated.** A consistent time of day removes most day-to-day noise.
* **Weekly averages beat daily values.** HRV (RMSSD) varies day to day in healthy people; a 7-day rolling mean
  is a steadier signal for a trend line.
* **Compare people with themselves.** Absolute HRV differs widely between people (age, fitness, genetics). A
  change from a person's own baseline is meaningful; a comparison to a population table usually is not.
* **Record context** your app already knows (sleep, training, illness) alongside readings, so a dip has an
  explanation rather than becoming a worry.

## Is a change real?

Every measurement has noise. A pre/post difference smaller than the measurement's own variation is not
evidence of a change. The SDK ships a helper that applies per-metric thresholds derived from the validation
study's 95% limits of agreement:

| Metric | Change beyond typical measurement variation |
| - | - |
| HRV (RMSSD) | more than 10 ms |
| Heart rate | more than 5 bpm |
| Breathing rate | more than 2 breaths per minute |

<CodeGroup>
  ```swift Swift theme={null}
  let change = VitalsChange.compare(baseline: before, followUp: after)
  if let rmssd = change.rmssdMs, rmssd.beyondTypicalVariation == true {
    print("HRV (RMSSD) changed by \(rmssd.delta) ms, beyond typical measurement variation")
  }
  ```

  ```kotlin Kotlin theme={null}
  val change = VitalsChange.compare(baseline = before, followUp = after)
  change.rmssdMs?.let { c ->
    if (c.beyondTypicalVariation == true) {
      Log.i("Vitals", "HRV (RMSSD) changed by ${c.delta} ms, beyond typical measurement variation")
    }
  }
  ```
</CodeGroup>

<Warning>
  These thresholds are provisional. They come from agreement with a chest strap, which is a lower bound on the
  variation you will see between two readings taken minutes apart. A repeatability analysis (same person, back to
  back readings) is under way and will replace the constants in a future release. Until then, treat "beyond
  typical variation" as a strong hint, not a verdict, and lean on group-level statistics for claims.
</Warning>

For a group claim, pre-register the metric (HRV (RMSSD) is the usual primary), the reading protocol, and the
analysis, and report the withheld rate along with the results.

## Wording for users

Calm and specific wording keeps people engaged with a metric that moves around.

* Prefer "your HRV (RMSSD) was 42 ms this morning, in your usual range" to "your HRV is low".
* Show change over a week or a month before change over a day.
* Explain a `withheld` reading as a signal-quality issue with the fingertip or lighting, not as a health signal.
* Never present the metrics as diagnosis. The SDK is not a medical device.

## Why a finger scan, not a face scan

RMSSD is the HRV number WHOOP, Oura, Polar and Fitbit report, and the hardest one to measure with a camera. It
is built from tiny beat-to-beat changes, so any error in timing a beat adds straight to it and makes HRV read
high.

That is a physics problem for face scans. On a face, the pulse is a faint colour change in reflected room light,
easily swamped by shifts in lighting and small head movements. A fingertip pressed over the flash is lit by a
bright, steady light right against the skin, giving a pulse about 6 times larger, or over 30 times the signal
power. The SDK's average HRV (RMSSD) error is 3.4 ms, while the best published face-scan result is 10.5 ms.

<Note>
  Facial pulse amplitude: Wang et al., Biomedical Optics Express, 2017 (15 participants, medians read from their
  Figure 2a), compared with the 30 NEUROFIT study participants using the same method. Face-video RMSSD:
  Bioengineering, 2023 (UBFC-rPPG dataset). Different studies, cameras and references, so not a head-to-head
  comparison.
</Note>

A finger scan also has practical advantages for outcomes work: the user controls the conditions (no dependence
on room lighting), the reading is the same indoors and outdoors, and the torch-lit fingertip is what the
validation study measured.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.