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
| Source | Type | Metrics Provided |
|---|---|---|
| PPP Timesheet | Internal (automatic) | Hours at work, break duration |
| PPP Surgical Logbook | Internal (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 Input | Manual entry | Screen 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
| Category | Components | Total Weight | Rationale |
|---|---|---|---|
| Workload | Time 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. |
| Sleep | Duration (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 & Recovery | Stress 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. |
| Lifestyle | Phone Usage (6%), Training Strain (6%), Breaks (6%) | 18% | Behavioural factors that influence recovery quality. Each carries equal weight. |
| Biometrics | HRV (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 Score | Recommended Hours | Guidance Level | Message |
|---|---|---|---|
| > 87.5 (hours < 6.5) | 6.0 - 6.5 | Normal | Normal recovery: 6-6.5 hrs sufficient |
| 50 - 87.5 (hours 6.5-8) | 6.5 - 8.0 | Moderate | Moderate recovery: aim for 7-8 hrs |
| 12.5 - 50 (hours 8-9.5) | 8.0 - 9.5 | Enhanced | Enhanced recovery: aim for 8.5-9.5 hrs |
| < 12.5 (hours >= 9.5) | 9.5 - 10.0 | Maximize | Maximize recovery: target 10+ hrs sleep |
5.2 Workload Guidance
| Readiness Score | Guidance Level | Message |
|---|---|---|
| >= 75 | High | High readiness. You can handle demanding tasks and intense training. |
| 50 - 74 | Moderate | Moderate readiness. Maintain steady pace, avoid overexertion. |
| < 50 | Low | Low 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
| Metric | Value |
|---|---|
| Hours at work | 10.5 |
| Primary operating sessions | 120, 60, 0 min |
| Secondary operating sessions | 0, 0, 0 min |
| Break minutes | 30 |
| Screen time | 3 hrs |
| Phone pickups/hr | 4 |
| Training (primary) | 30 min, intensity 7 |
| Stress periods | 20, 15, 0 min |
| Sleep duration | 7 hrs |
| Deep sleep | 90 min |
| REM sleep | 60 min |
| Meditation | 10 min |
| Active recovery | 20 min movement, 0 sessions |
| HRV | 55 ms |
| Resting HR | 62 bpm |
| Respiratory rate | 18/min |
| Core temperature | 37.1 C |
| SpO2 | 97% |
| HRV deviation | 50 ms |
Component Score Calculation
| Component | Score | Weight | Contribution |
|---|---|---|---|
| Time at Work | 0.2800 | 12% | 0.033600 |
| Operating (Primary) | 0.8257 | 9% | 0.074317 |
| Operating (Secondary) | 1.0000 | 3% | 0.030000 |
| Phone Usage | 0.4500 | 6% | 0.027000 |
| Training Strain | 0.0200 | 6% | 0.001200 |
| Stress Time | 0.8625 | 8% | 0.069000 |
| Sleep Duration | 0.5000 | 10% | 0.050000 |
| Sleep Quality | 0.6118 | 10% | 0.061177 |
| Breaks | 0.7500 | 6% | 0.045000 |
| Meditation | 0.6667 | 6% | 0.040000 |
| Active Recovery | 0.7500 | 6% | 0.045000 |
| HRV | 0.2426 | 8% | 0.019406 |
| Resting HR | 0.8000 | 2% | 0.016000 |
| Respiratory Rate | 1.0000 | 2% | 0.020000 |
| Core Temperature | 1.0000 | 2% | 0.020000 |
| SpO2 | 1.0000 | 2% | 0.020000 |
| HRV Deviation | 0.6667 | 2% | 0.013333 |
| TOTAL | 100% | 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:
- Long work hours (10.5h -> score 0.28)
- High training strain (30min x intensity 7 = load 210 -> score 0.02)
- Relatively low HRV (55ms -> score 0.24)
- 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
| Component | Input Unit | Optimal Range | Score at Optimal | Degradation Pattern | Floor |
|---|---|---|---|---|---|
| Time at Work | hours | 0-4 | 1.0-0.8 | Linear 0.08/hr to 9.5h, then 0.11/hr | 0 at 13h |
| Operating Primary | minutes (sessions) | low session times | ~1.0 | Non-linear fatigue ramp per session + cumulative | 0 |
| Operating Secondary | minutes (sessions) | low session times | ~1.0 | Same as primary | 0 |
| Phone Usage | hours + pickups/hr | <2h, <1 pickup/hr | ~0.95 | Tiered + pickup penalty | 0 |
| Training Strain | load (min*intensity) | <50 | ~0.9 | Tiered penalty escalation | 0 |
| Stress Time | minutes (3 periods) | 0 | 1.0 | Escalating tier per period | 0 |
| Sleep Duration | hours | 7-8 | 1.0 | Linear below 6h; bonus >8h | 0 at 0h |
| Sleep Quality | deep+REM minutes | >90 deep, >90 REM | ~0.72 | Exponential saturation | 0 at 0/0 |
| Breaks | minutes | 20-40 min/6h block | 1.0 | Linear below minimum; bonus above optimal | 0 at 0min |
| Meditation | minutes | 15+ | 1.0+ | Linear to 15min; bonus above | 0 at 0min |
| Active Recovery | minutes + sessions | 30+ min | 1.0+ | Tiered movement + session bonus | 0 at 0/0 |
| HRV | ms | >60 | 0.35-1.0 | Zero below 30ms; linear to 60ms; exponential above | 0 below 30ms |
| Resting HR | bpm | <= baseline | 1.0 | Linear decay over 10bpm above baseline | 0 |
| Respiratory Rate | breaths/min | <= baseline | 1.0 | Linear decay over 5 above baseline | 0 |
| Core Temperature | C | <= baseline | 1.0 | Linear decay over 0.7C above baseline | 0 |
| SpO2 | % | >= baseline | 1.0 | Linear decay over 5% below baseline | 0 |
| HRV Deviation | ms | >= baseline | 1.0 | Linear decay over 30ms below baseline | 0 |
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:
| Metric | Default Baseline | Note |
|---|---|---|
| Resting HR | 60 bpm | May be too high for fit individuals; too low for some populations |
| Respiratory Rate | 20 breaths/min | Upper end of normal range |
| Core Temperature | 37.3 C | Slightly above the commonly cited 37.0 C |
| SpO2 | 95% | Lower bound of normal; healthy individuals typically 96-99% |
| HRV Deviation | 60 ms | Varies 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:
- Groups metrics by type
- Selects the value from the highest-priority connected source
- 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
| File | Purpose |
|---|---|
scoring/formulas.ts | All 17 pure scoring functions |
config/weights.ts | Component weight definitions |
scoring/calculator.ts | Orchestration pipeline (metrics -> inputs -> scores -> final) |
scoring/scoreService.ts | Guidance calculations, persistence, business logic |
scoring/types.ts | TypeScript type definitions for all data structures |
constants/wellness.ts | Baselines, metric types, data source definitions |
docs/wellness-algorithm-explorer.ipynb | Interactive Jupyter notebook for formula exploration |