calcpace 1.9.7 → 1.9.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d9eb6ddf00dde81f5405ab23cf97f609eaf5b11e2f49f69724cc1579e976dc3
-  data.tar.gz: 97400c042ef3109c0479655e07bb55e72f136b4dcc5ba044cdd9ae6311ad8dd4
+  metadata.gz: c753575818b486be4f9c955d69e062263d61fd604e415c82409203c7d8d03156
+  data.tar.gz: 95459f1aa861dec764b2cfae6b9cd69cab5d866e31547d843672e460c309999d
 SHA512:
-  metadata.gz: 6b74a386783c041329e47dbc6308f2844afe7be54fff27049d54f9d91dc00cc696522cdbd1a035cbd401299276a7c75ab9438220248b14b9b815bca39cd52609
-  data.tar.gz: 8328528b5680a4eaca14ad9ee9dddc233069386888d1e59cd676614a5d6a7292cc777360cfeabf0cc6d8fa7d8e9f4266feb3dbed7bc0de0b2ebb8d03025bc457
+  metadata.gz: eddb87f77382d6973059b517c9c2ce696d9cc31246f38db46651b1c62d155e52fafb022fff373220f0aced664b4213eddf9a4b57aa71564be22321799cc0f254
+  data.tar.gz: 1c5cfc3771471b3d89b9ba8eee8e742bf9508815e13489692d4ceae3d0f2a8a223a29f7b9205c57ceed8f3b7df28df27893c4e512f356489916ffe3644b05010

data/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.9.8] - 2026-05-23
+
+### Added
+- Contextualized VO2max estimation (`Vo2maxEstimator#estimate_detailed_vo2max`)
+  - Confidence Score based on effort duration (Daniels & Gilbert optimal window)
+  - Elevation Adjustment (Equivalent Flat Distance) using Naismith-based heuristic
+  - Sub-maximal effort detection via Heart Rate intensity validation (%HRmax)
+  - Structured result object (`Vo2maxResult`) with value, confidence, and metadata
+
 ## [1.9.7] - 2026-05-16
 
 ### Added

data/README.md

@@ -5,7 +5,7 @@ A Ruby gem for running and cycling calculations: pace, time, distance, unit conv
 ## Installation
 
 ```ruby
-gem 'calcpace', '~> 1.9.7'
+gem 'calcpace', '~> 1.9.8'
 ```
 
 ## Usage
@@ -221,6 +221,8 @@ calc.vo2max_label(51.9)  # => "Very Good"
 | 30–39              | Fair      |
 | < 30               | Beginner  |
 
+*Thresholds based on Daniels, J. (2014). Daniels' Running Formula (3rd ed.), consistent with ACSM guidelines and McArdle, Katch & Katch (2015) Exercise Physiology.*
+
 **Formula:**
 ```
 velocity (m/min) = distance_m / time_min
@@ -231,6 +233,47 @@ VO2max           = VO2 / %VO2max
 
 Accuracy: ±3–5 ml/kg/min vs. laboratory testing. Best with efforts between **5 and 60 minutes** at near-maximal pace.
 
+#### Contextualized estimation
+
+`estimate_detailed_vo2max` returns a richer result that accounts for elevation, heart rate, and formula reliability:
+
+```ruby
+# Mountain 10K: 200 m elevation gain, avg HR 172, max HR 190
+result = calc.estimate_detailed_vo2max(
+  10.0, '00:48:30',
+  elevation_gain_m: 200,
+  hr_avg: 172,
+  hr_max: 190
+)
+
+result.value              # => 47.7  (corrected for 1.2 km of equivalent flat distance)
+result.adjusted_distance_km # => 11.2  (10 km + 200 m × 6 flat-equivalent)
+result.confidence         # => :high  (48 min is inside the 5–60 min optimal window)
+result.sub_maximal        # => false  (172/190 = 90.5 % HRmax → maximal effort)
+
+calc.vo2max_label(result.value)  # => "Good"
+
+# Compare: same effort ignoring elevation → underestimates VO2max
+flat = calc.estimate_detailed_vo2max(10.0, '00:48:30')
+flat.value  # => 41.5
+
+# Easy recovery run: sub-maximal effort flag + confidence downgrade
+easy = calc.estimate_detailed_vo2max(10.0, '01:05:00', hr_avg: 135, hr_max: 190)
+easy.sub_maximal  # => true   (135/190 = 71 % HRmax < 85 %)
+easy.confidence   # => :low   (formula assumes race-pace effort)
+easy.value        # => 29.3   (underestimates real aerobic capacity)
+```
+
+| `confidence` | Effort duration | Notes |
+|---|---|---|
+| `:high` | 5–60 min | Daniels & Gilbert optimal window |
+| `:medium` | > 60–120 min | Muscular fatigue starts distorting the estimate |
+| `:low` | < 5 min or > 120 min | Anaerobic / glycogen-depletion effects dominate |
+
+> If `hr_avg > hr_max`, a `Calcpace::Error` is raised (physiologically impossible input).
+> If you provide heart rate data, both `hr_avg` and `hr_max` must be present.
+> `elevation_gain_m` must be zero or positive.
+
 ---
 
 ### Other Utilities

data/lib/calcpace/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Calcpace
-  VERSION = '1.9.7'
+  VERSION = '1.9.8'
 end

data/lib/calcpace/vo2max_estimator.rb

@@ -14,6 +14,10 @@
 # Accuracy: ±3–5 ml/kg/min vs laboratory testing. Best results with efforts
 # between 5 and 60 minutes at race pace (i.e. near-maximal effort).
 module Vo2maxEstimator
+  # Classification thresholds based on:
+  # Daniels, J. (2014). Daniels' Running Formula (3rd ed.). Human Kinetics.
+  # General ranges are consistent with ACSM guidelines and widely cited in
+  # exercise physiology literature (McArdle, Katch & Katch, 2015).
   VO2MAX_LABELS = [
     { min: 70, label: 'Elite' },
     { min: 60, label: 'Excellent' },
@@ -23,6 +27,9 @@ module Vo2maxEstimator
     { min: 0,  label: 'Beginner' }
   ].freeze
 
+  # Represents a contextualized VO2max estimation result
+  Vo2maxResult = Struct.new(:value, :confidence, :sub_maximal, :adjusted_distance_km)
+
   # Estimates VO2max from a race performance using Daniels & Gilbert formula
   #
   # @param distance_km [Numeric] race distance in kilometres (must be > 0)
@@ -48,6 +55,30 @@ module Vo2maxEstimator
     (vo2 / pct_vo2max).round(1)
   end
 
+  # Estimates a detailed and contextualized VO2max
+  #
+  # @param distance_km [Numeric] race distance in kilometres
+  # @param time [String, Integer] finish time
+  # @param elevation_gain_m [Numeric] total elevation gain in metres
+  # @param hr_avg [Numeric] average heart rate during the effort
+  # @param hr_max [Numeric] athlete's maximum heart rate
+  # @return [Vo2maxResult] structured result with value and metadata
+  def estimate_detailed_vo2max(distance_km, time, elevation_gain_m: 0, hr_avg: nil, hr_max: nil)
+    adj_dist_km = adjusted_distance_for_vo2(distance_km, elevation_gain_m)
+    vo2max_val  = estimate_vo2max(adj_dist_km, time)
+    confidence  = calculate_time_confidence(parse_time_minutes(time))
+
+    hr_data = validate_and_analyze_hr(hr_avg, hr_max)
+    confidence = :low if hr_data[:sub_maximal]
+
+    Vo2maxResult.new(
+      value: vo2max_val,
+      confidence: confidence,
+      sub_maximal: hr_data[:sub_maximal],
+      adjusted_distance_km: adj_dist_km.round(2)
+    )
+  end
+
   # Returns a descriptive label for a given VO2max value
   #
   # @param value [Numeric] VO2max in ml/kg/min
@@ -64,6 +95,47 @@ module Vo2maxEstimator
 
   private
 
+  def adjusted_distance_for_vo2(distance_km, elevation_gain_m)
+    check_non_negative(elevation_gain_m, 'Elevation gain')
+
+    # Naismith-based heuristic: 100m gain = +600m flat
+    ((distance_km.to_f * 1000) + (elevation_gain_m.to_f * 6.0)) / 1000.0
+  end
+
+  def validate_and_analyze_hr(hr_avg, hr_max)
+    if hr_avg.nil? ^ hr_max.nil?
+      raise Calcpace::Error, 'Average heart rate and maximum heart rate must be provided together'
+    end
+
+    return { sub_maximal: false } unless hr_avg && hr_max
+
+    check_positive(hr_avg, 'Average heart rate')
+    check_positive(hr_max, 'Maximum heart rate')
+
+    avg = hr_avg.to_f
+    max = hr_max.to_f
+
+    raise Calcpace::Error, "Average heart rate (#{avg}) cannot exceed maximum heart rate (#{max})" if avg > max
+
+    { sub_maximal: (avg / max) < 0.85 }
+  end
+
+  def calculate_time_confidence(time_min)
+    if time_min.between?(5, 60)
+      :high
+    elsif time_min > 60 && time_min <= 120
+      :medium
+    else
+      :low
+    end
+  end
+
+  def check_non_negative(number, name = 'Input')
+    return if number.is_a?(Numeric) && number >= 0
+
+    raise Calcpace::Error, "#{name} must be zero or a positive number"
+  end
+
   def vo2_at_velocity(velocity)
     -4.60 + (0.182258 * velocity) + (0.000104 * (velocity**2))
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: calcpace
 version: !ruby/object:Gem::Version
-  version: 1.9.7
+  version: 1.9.8
 platform: ruby
 authors:
 - João Gilberto Saraiva