Skip to content

Wellness Readiness Algorithm: Clinical Review ​

Document version: 1.0 Algorithm version: V2 (source: formulas.ts, weights.ts, calculator.ts) Intended audience: Clinical / Medical reviewer assessing algorithmic soundness


1. Executive Summary ​

The PPP Wellness Readiness Algorithm calculates a daily Readiness Score (0-100) for medical professionals, summarising their physical and mental preparedness for clinical duties. The score integrates data from four streams: (1) hospital timesheets and surgical logbooks, (2) wearable biometric devices, (3) self-reported lifestyle data, and (4) an optional subjective wellbeing questionnaire (WHO-5).

The algorithm decomposes readiness into 17 scored components spanning workload, sleep, stress, recovery, lifestyle, and biometrics. Each component produces a normalised score (0 = worst, 1 = optimal, >1 = bonus possible for some components). These 17 scores are multiplied by clinically-derived weights and summed to produce the overall readiness score, which is then used to generate sleep guidance (recommended hours) and workload guidance (activity level recommendation).

The system is designed to surface early indicators of fatigue, under-recovery, or overwork rather than to diagnose clinical conditions. It complements, but does not replace, professional medical judgement.


2. Data Sources ​

SourceTypeMetrics Provided
PPP TimesheetInternal (automatic)Hours at work, break duration
PPP Surgical LogbookInternal (automatic)Primary & secondary operating session durations (up to 3 sessions each)
Wearable Devices (WHOOP, Oura, Garmin, Apple Health, Google Fit, Samsung)External (OAuth/device sync)Sleep duration, deep sleep, REM sleep, HRV, HRV deviation, resting HR, respiratory rate, core temperature, SpO2
Self-Report / App InputManual entryScreen time, phone pickups, training sessions, stress periods, meditation time, active recovery

When multiple wearable providers supply the same metric type, a priority resolver selects the most recent or highest-priority value. PPP-sourced metrics (timesheet, logbook) always take precedence for work-related data.


3. The 17 Scoring Components ​

3.1 Time at Work (weight: 12%) ​

What it measures: Total hours on-site from clock-in to clock-out (inclusive of breaks).

Clinical rationale: Extended work hours are a well-established risk factor for fatigue-related errors in healthcare settings. The European Working Time Directive limits shifts to reduce this risk.

Scoring behaviour:

  • 0 hours: score = 1.0 (no work = full readiness)
  • 0-4 hours: mild linear decrease (1.0 -> 0.8). Short shifts have negligible fatigue impact.
  • 4-9.5 hours: moderate decrease (0.8 -> 0.36). Standard shift length range.
  • 9.5-13 hours: steep decrease (0.36 -> 0.0). Long shifts significantly impair readiness.
  • 13 hours: score = 0.0 (floor)

3.2 Operating (Primary Surgeon) (weight: 9%) ​

What it measures: Fatigue from primary operating sessions (surgeon is the lead operator).

Clinical rationale: Operating as primary surgeon demands sustained concentration, fine motor control, and decision-making. Fatigue accumulates both within individual sessions and cumulatively across multiple procedures.

Scoring behaviour: Composite of two sub-scores:

  • Multi-stream readiness (60% of component): evaluates each session's duration via a fatigue ramp (penalty increases non-linearly as session length grows past 30, 60, 90, 120 minutes)
  • Cumulative fatigue (40% of component): evaluates total operating minutes for the day

A single 120-minute session produces approximately 0.17 penalty; three 120-minute sessions would produce 0.50 penalty (divided by 3 = readiness ~0.83).

3.3 Operating (Secondary/Assisting) (weight: 3%) ​

What it measures: Same as 3.2 but for secondary/assisting surgeon role.

Clinical rationale: Assisting imposes cognitive and physical demands, but at lower intensity than leading a procedure. The 3:1 weight ratio (primary 9% vs secondary 3%) reflects this reduced but non-trivial burden.

3.4 Phone Usage (weight: 6%) ​

What it measures: Total screen time (hours) and phone pickups per hour.

Clinical rationale: Excessive phone use correlates with disrupted attention, fragmented rest periods, and reduced sleep quality. Frequent pickups indicate compulsive checking behaviour.

Scoring behaviour:

  • Duration penalty: 0-2h (low), 2-4h (moderate), 4-6h (high), 6h+ (severe)
  • Pickup penalty: adds up to 0.30 penalty when pickups exceed 1/hour
  • Combined penalties are capped such that score cannot go below 0

3.5 Training Strain (weight: 6%) ​

What it measures: Physical training load calculated as (minutes x intensity) summed across primary and secondary training sessions.

Clinical rationale: Exercise is beneficial for recovery when moderate, but intense training sessions on days with demanding clinical duties can deplete physical reserves.

Scoring behaviour: Tiered penalty system based on total load:

  • 0-50 load units: minimal penalty (~10%)
  • 50-100: moderate penalty (10-30%)
  • 100-150: significant penalty (30-60%)
  • 150-200: high penalty (60-85%)
  • 200+: severe penalty approaching 100%

3.6 Stress Time (weight: 8%) ​

What it measures: Duration of self-reported high-stress periods (up to 3 periods per day).

Clinical rationale: Psychological stress activates the hypothalamic-pituitary-adrenal (HPA) axis, depleting cognitive resources and impairing decision-making. Sustained stress periods have cumulative effects.

Scoring behaviour: Each period's contribution follows an escalating tier system:

  • 0-20 min: 0.0025/min (low)
  • 20-40 min: 0.005/min (moderate)
  • 40-60 min: 0.0075/min (elevated)
  • 60-90 min: 0.01/min (high)
  • 90+ min: 0.012/min (severe)

Multiple periods are summed as total penalty.

3.7 Sleep Duration (weight: 10%) ​

What it measures: Total sleep hours from the previous night.

Clinical rationale: Sleep is the primary physiological recovery mechanism. The American Academy of Sleep Medicine recommends 7-9 hours for adults. Insufficient sleep is the strongest predictor of impaired cognitive performance in healthcare workers.

Scoring behaviour:

  • <6h: linear ramp from 0 to 1 (severely insufficient)
  • 6-8h: score rises from ~0.0 to 1.0 (the 6-8h range maps linearly from 1-(8-h)/2)
  • 8-10.5h: score exceeds 1.0 with diminishing returns (bonus for extra sleep, exponential saturation)
  • 10.5h: further small bonus with heavy saturation

This is one of the few components where score can exceed 1.0 (up to ~1.24), reflecting evidence that extra sleep provides tangible recovery benefit.

3.8 Sleep Quality (weight: 10%) ​

What it measures: Deep sleep and REM sleep duration (minutes) from wearable data.

Clinical rationale: Sleep architecture matters as much as duration. Deep (N3) sleep is essential for physical restoration and immune function. REM sleep consolidates procedural memory and emotional regulation - both critical for surgeons.

Scoring behaviour: Exponential saturation model:

  • Score = 0.6 x (1 - e^(-0.03 x deep)) + 0.4 x (1 - e^(-0.02 x REM))
  • Deep sleep is weighted 60%, REM 40%
  • Approaches ~0.93 asymptotically with very high values (e.g., 200min deep + 200min REM)
  • 90min deep + 90min REM yields ~0.72

3.9 Breaks (weight: 6%) ​

What it measures: Whether adequate break time was taken relative to hours worked.

Clinical rationale: Regular breaks during clinical duties reduce cumulative fatigue and maintain attention. Research shows that breaks every 4-6 hours are necessary to sustain cognitive performance.

Scoring behaviour:

  • Work blocks = ceil(hours / 6). For an 8-hour shift, this is 2 blocks.
  • Minimum breaks = 20 min/block; optimal breaks = 40 min/block
  • Below minimum: linear penalty (score < 1.0)
  • Within optimal range: score = 1.0
  • Above optimal: small bonus (0.005 per extra minute) - reflecting that extra rest is marginally beneficial

3.10 Meditation (weight: 6%) ​

What it measures: Minutes of meditation or mindfulness practice.

Clinical rationale: Mindfulness meditation reduces cortisol levels, improves attentional control, and enhances emotional regulation. A growing evidence base supports its use for healthcare worker wellbeing.

Scoring behaviour:

  • 0-15 min: linear from 0 to 1 (building toward optimal)
  • 15+ min: score exceeds 1.0 with small bonus that grows sub-linearly

3.11 Active Recovery (weight: 6%) ​

What it measures: Movement minutes and light activity sessions (walks, yoga, stretching).

Clinical rationale: Light physical activity promotes blood circulation, reduces muscle tension, and supports parasympathetic nervous system recovery. Distinct from training strain, which represents effortful exercise.

Scoring behaviour: Sum of two sub-components:

  • Movement (dominant): <10min = 0.05/min linear; 10-30min = 0.5 + 0.025/min; 30+min = 1.0 + small bonus
  • Light sessions: up to 0.4 additional for 10+ sessions

3.12 HRV (weight: 8%) ​

What it measures: Heart rate variability in milliseconds (typically rMSSD or similar metric from wearable).

Clinical rationale: HRV is a validated biomarker of autonomic nervous system balance. Higher HRV indicates greater parasympathetic (recovery) tone. Low HRV is associated with fatigue, stress, and reduced cognitive performance.

Scoring behaviour:

  • <30ms: score = 0 (severely suppressed autonomic function)
  • 30-60ms: linear from 0 to 0.35 (below optimal)
  • 60ms: exponential approach toward 1.0 (0.35 + 0.65 x (1 - e^(-0.06 x (v-60))))

  • At 90ms: ~0.73; at 120ms: ~0.93

3.13 Resting Heart Rate (weight: 2%) ​

What it measures: Resting heart rate relative to personal baseline (default: 60 bpm).

Clinical rationale: Elevated resting HR above personal baseline suggests incomplete recovery, acute stress, or illness onset.

Scoring behaviour:

  • At or below baseline: score = 1.0
  • Above baseline: linear decay to 0 over 10 bpm (e.g., baseline+5 = 0.5; baseline+10 = 0)

3.14 Respiratory Rate (weight: 2%) ​

What it measures: Breathing rate relative to personal baseline (default: 20 breaths/min).

Clinical rationale: Elevated respiratory rate during rest can indicate physiological stress, anxiety, or early illness.

Scoring behaviour:

  • At or below baseline: score = 1.0
  • Above baseline: linear decay to 0 over 5 breaths/min

3.15 Core Temperature (weight: 2%) ​

What it measures: Core body temperature relative to personal baseline (default: 37.3 C).

Clinical rationale: Elevated core temperature can indicate infection, inadequate recovery, or circadian disruption.

Scoring behaviour:

  • At or below baseline: score = 1.0
  • Above baseline: linear decay to 0 over 0.7 C (e.g., 37.65 C with 37.3 baseline = 0.5)

3.16 SpO2 (weight: 2%) ​

What it measures: Blood oxygen saturation relative to personal baseline (default: 95%).

Clinical rationale: Decreased SpO2 can indicate respiratory compromise, sleep apnoea effects, or altitude-related desaturation.

Scoring behaviour:

  • At or above baseline: score = 1.0
  • Below baseline: linear decay to 0 over 5 percentage points

3.17 HRV Deviation (weight: 2%) ​

What it measures: HRV deviation from personal baseline (default: 60ms). This captures day-to-day variability in autonomic function.

Clinical rationale: A drop in HRV below personal norm suggests acute physiological stress or incomplete recovery, even if absolute HRV is within normal range.

Scoring behaviour:

  • At or above baseline: score = 1.0
  • Below baseline: linear decay to 0 over 30ms

4. Weighting Rationale ​

CategoryComponentsTotal WeightRationale
WorkloadTime at Work (12%), Operating Primary (9%), Operating Secondary (3%)24%The single largest category, reflecting that clinical workload is the primary driver of acute fatigue for medical professionals. Primary operating carries 3x the weight of secondary to reflect the cognitive differential.
SleepDuration (10%), Quality (10%)20%Sleep is the strongest evidence-based predictor of next-day cognitive performance. Duration and quality are equally weighted as both are independently important.
Stress & RecoveryStress Time (8%), Meditation (6%), Active Recovery (6%)20%Psychological stress and recovery practices have strong evidence for affecting clinical performance. Stress carries slightly more weight as it is more directly harmful.
LifestylePhone Usage (6%), Training Strain (6%), Breaks (6%)18%Behavioural factors that influence recovery quality. Each carries equal weight.
BiometricsHRV (8%), Resting HR (2%), Resp Rate (2%), Core Temp (2%), SpO2 (2%), HRV Deviation (2%)18%Objective physiological markers. HRV receives the highest weight in this category as the most validated single biomarker of recovery status. The remaining biometrics each contribute small but meaningful signals.

Total: 100% (verified: 0.12 + 0.09 + 0.03 + 0.06 + 0.06 + 0.08 + 0.10 + 0.10 + 0.06 + 0.06 + 0.06 + 0.08 + 0.02 + 0.02 + 0.02 + 0.02 + 0.02 = 1.00)


5. Guidance System ​

5.1 Sleep Guidance ​

The recommended sleep hours are calculated inversely from the readiness score:

recommendedHours = clamp(6 + (1 - readinessScore) * 4, min=6, max=10)
Readiness ScoreRecommended HoursGuidance LevelMessage
> 87.5 (hours < 6.5)6.0 - 6.5NormalNormal recovery: 6-6.5 hrs sufficient
50 - 87.5 (hours 6.5-8)6.5 - 8.0ModerateModerate recovery: aim for 7-8 hrs
12.5 - 50 (hours 8-9.5)8.0 - 9.5EnhancedEnhanced recovery: aim for 8.5-9.5 hrs
< 12.5 (hours >= 9.5)9.5 - 10.0MaximizeMaximize recovery: target 10+ hrs sleep

5.2 Workload Guidance ​

Readiness ScoreGuidance LevelMessage
>= 75HighHigh readiness. You can handle demanding tasks and intense training.
50 - 74ModerateModerate readiness. Maintain steady pace, avoid overexertion.
< 50LowLow readiness. Focus on recovery, limit strenuous activities.

6. WHO-5 Wellbeing Questionnaire ​

The system also supports a WHO-5 Well-Being Index questionnaire (5 items, 0-5 Likert scale each, total 0-25, displayed as percentage 0-100). This is administered separately from the readiness algorithm and provides a subjective psychological wellbeing measure.

The WHO-5 score is not combined into the readiness score. It is presented alongside it to give clinicians a complete picture that pairs objective readiness (algorithm-derived) with subjective wellbeing (self-reported).


7. Worked Example ​

Scenario: A surgeon who worked a 10.5-hour shift with 120 + 60 minutes of primary operating, had 7 hours of sleep, moderate biometrics, and limited recovery time.

Input Values ​

MetricValue
Hours at work10.5
Primary operating sessions120, 60, 0 min
Secondary operating sessions0, 0, 0 min
Break minutes30
Screen time3 hrs
Phone pickups/hr4
Training (primary)30 min, intensity 7
Stress periods20, 15, 0 min
Sleep duration7 hrs
Deep sleep90 min
REM sleep60 min
Meditation10 min
Active recovery20 min movement, 0 sessions
HRV55 ms
Resting HR62 bpm
Respiratory rate18/min
Core temperature37.1 C
SpO297%
HRV deviation50 ms

Component Score Calculation ​

ComponentScoreWeightContribution
Time at Work0.280012%0.033600
Operating (Primary)0.82579%0.074317
Operating (Secondary)1.00003%0.030000
Phone Usage0.45006%0.027000
Training Strain0.02006%0.001200
Stress Time0.86258%0.069000
Sleep Duration0.500010%0.050000
Sleep Quality0.611810%0.061177
Breaks0.75006%0.045000
Meditation0.66676%0.040000
Active Recovery0.75006%0.045000
HRV0.24268%0.019406
Resting HR0.80002%0.016000
Respiratory Rate1.00002%0.020000
Core Temperature1.00002%0.020000
SpO21.00002%0.020000
HRV Deviation0.66672%0.013333
TOTAL100%0.5850

Final Output ​

  • Readiness Score: 58.5 / 100 (moderate)
  • Sleep Guidance: Enhanced - aim for 8.5-9.5 hrs (recommended: 7.7 hrs)
  • Workload Guidance: Moderate - maintain steady pace, avoid overexertion

Interpretation ​

This surgeon has moderate readiness primarily dragged down by:

  1. Long work hours (10.5h -> score 0.28)
  2. High training strain (30min x intensity 7 = load 210 -> score 0.02)
  3. Relatively low HRV (55ms -> score 0.24)
  4. Below-optimal sleep duration (7h -> score 0.50)

The algorithm correctly identifies this as a fatigued state requiring enhanced recovery, despite acceptable biometrics (respiratory rate, core temperature, SpO2 all optimal).


8. Scoring Behaviour Summary Table ​

ComponentInput UnitOptimal RangeScore at OptimalDegradation PatternFloor
Time at Workhours0-41.0-0.8Linear 0.08/hr to 9.5h, then 0.11/hr0 at 13h
Operating Primaryminutes (sessions)low session times~1.0Non-linear fatigue ramp per session + cumulative0
Operating Secondaryminutes (sessions)low session times~1.0Same as primary0
Phone Usagehours + pickups/hr<2h, <1 pickup/hr~0.95Tiered + pickup penalty0
Training Strainload (min*intensity)<50~0.9Tiered penalty escalation0
Stress Timeminutes (3 periods)01.0Escalating tier per period0
Sleep Durationhours7-81.0Linear below 6h; bonus >8h0 at 0h
Sleep Qualitydeep+REM minutes>90 deep, >90 REM~0.72Exponential saturation0 at 0/0
Breaksminutes20-40 min/6h block1.0Linear below minimum; bonus above optimal0 at 0min
Meditationminutes15+1.0+Linear to 15min; bonus above0 at 0min
Active Recoveryminutes + sessions30+ min1.0+Tiered movement + session bonus0 at 0/0
HRVms>600.35-1.0Zero below 30ms; linear to 60ms; exponential above0 below 30ms
Resting HRbpm<= baseline1.0Linear decay over 10bpm above baseline0
Respiratory Ratebreaths/min<= baseline1.0Linear decay over 5 above baseline0
Core TemperatureC<= baseline1.0Linear decay over 0.7C above baseline0
SpO2%>= baseline1.0Linear decay over 5% below baseline0
HRV Deviationms>= baseline1.0Linear decay over 30ms below baseline0

9. Limitations and Considerations ​

9.1 Default Baselines ​

The biometric components (resting HR, respiratory rate, core temperature, SpO2, HRV deviation) compare against default population baselines rather than personalised baselines. The defaults are:

MetricDefault BaselineNote
Resting HR60 bpmMay be too high for fit individuals; too low for some populations
Respiratory Rate20 breaths/minUpper end of normal range
Core Temperature37.3 CSlightly above the commonly cited 37.0 C
SpO295%Lower bound of normal; healthy individuals typically 96-99%
HRV Deviation60 msVaries significantly by age and fitness level

Recommendation: Allow personalised baselines calibrated from each user's data over a 2-4 week period.

9.2 Missing Data Handling ​

When a metric is not available (no wearable connected, no data synced), its value defaults to 0. This means:

  • Missing HRV -> score 0 (penalising)
  • Missing resting HR -> score 1.0 (at baseline, not penalised)
  • Missing sleep duration -> score 0 (penalising)

This asymmetry means that users without wearable devices will receive systematically lower scores for wearable-dependent components (sleep quality, HRV, HRV deviation) while biometric baselines (resting HR, respiratory rate, core temp, SpO2) will score perfectly since 0 <= baseline.

Recommendation: Consider excluding unmeasured components from the weighted average rather than penalising with zero scores.

9.3 Sleep Need Modifier ​

A sleepNeedModifier() function exists in the codebase but is currently unused (input parameter j32Minutes is always 0). This was intended to adjust the readiness score based on accumulated sleep debt but is not yet activated.

9.4 Bonus Scores (>1.0) ​

Several components can score above 1.0: sleep duration, breaks, meditation, active recovery. This means the overall readiness score can theoretically exceed 1.0 (displayed as >100), though in practice the high-weight components (workload, stress) tend to cap the overall score below 1.0.

9.5 Light Sessions Not Tracked ​

The active recovery component includes a lightSessions parameter that is hardcoded to 0 - the mobile app does not yet collect this data. This limits the maximum active recovery score to the movement component alone.

9.6 Training Strain Intensity Scale ​

Training intensity uses a numeric scale but the scale definition (1-10? RPE?) is not explicitly documented. Reviewers should verify that the expected input range aligns with clinical exercise intensity scales.

9.7 Sleep Duration Discontinuity at 6 Hours ​

The sleep duration scoring formula has a discontinuity at exactly 6 hours. The hours < 6 branch yields 6/6 = 1.0, but the hours <= 8 branch yields 1 - (8-6)/2 = 0.0. This means a user sleeping 5.99 hours scores ~1.0 while a user sleeping exactly 6.0 hours scores 0.0. This is a known artefact of the piecewise formula design. In practice, sleep duration values from wearables are unlikely to land on exactly 6.000h, but the discontinuity should be reviewed and potentially smoothed.

9.8 No Temporal Decay ​

The algorithm assesses a single day's snapshot. There is no multi-day fatigue accumulation model - a surgeon who has worked five consecutive 12-hour shifts will score the same on day 5 as day 1 (given identical metrics). The sleep need modifier (9.3) was intended to address this gap.


10. Data Source Priority ​

When multiple wearable providers supply the same metric (e.g., both WHOOP and Oura report HRV), the system uses a priority resolver that:

  1. Groups metrics by type
  2. Selects the value from the highest-priority connected source
  3. Falls back to the next source if the primary is unavailable

The priority hierarchy is configurable but defaults to the order in which sources are connected. PPP-sourced metrics (timesheet hours, logbook operating times) are always authoritative and cannot be overridden by external sources.


Appendix: File Reference ​

FilePurpose
scoring/formulas.tsAll 17 pure scoring functions
config/weights.tsComponent weight definitions
scoring/calculator.tsOrchestration pipeline (metrics -> inputs -> scores -> final)
scoring/scoreService.tsGuidance calculations, persistence, business logic
scoring/types.tsTypeScript type definitions for all data structures
constants/wellness.tsBaselines, metric types, data source definitions
docs/wellness-algorithm-explorer.ipynbInteractive Jupyter notebook for formula exploration

Internal documentation — org members only