calcpace 1.9.6 → 1.9.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc7e42385a1c6bf01908929f49004b332943dd0971bcb2d93ac69c838bc94ad2
-  data.tar.gz: 955bff3b89fabb29e6a4223efd5e8654bc0a76c6b59b507a31a1db8673cebce8
+  metadata.gz: c753575818b486be4f9c955d69e062263d61fd604e415c82409203c7d8d03156
+  data.tar.gz: 95459f1aa861dec764b2cfae6b9cd69cab5d866e31547d843672e460c309999d
 SHA512:
-  metadata.gz: 750ec40b02ae3607bb01efd6333ffd0e6ccfa21689914a58e3bb6d8f0ce17a60c6c66f01465766786847979a83fa581130550877edcb57056a549b613e72925f
-  data.tar.gz: b1bec9ff070a7511a604e5a6d34c2912735b27b7695f16b4afaaf9f6f0fbb9e56135068a881ab8b4de732bcba501bfe6a2dce8d07eff5b13b0f45b3805b3863c
+  metadata.gz: eddb87f77382d6973059b517c9c2ce696d9cc31246f38db46651b1c62d155e52fafb022fff373220f0aced664b4213eddf9a4b57aa71564be22321799cc0f254
+  data.tar.gz: 1c5cfc3771471b3d89b9ba8eee8e742bf9508815e13489692d4ceae3d0f2a8a223a29f7b9205c57ceed8f3b7df28df27893c4e512f356489916ffe3644b05010

data/CHANGELOG.md

@@ -7,6 +7,29 @@ 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
+- Environmental Performance Adjustments module (`EnvironmentalAdjuster`)
+  - Adjust race results and predictions based on temperature and altitude
+  - Scientific basis: Matthew Ely et al. (2007) for heat and NCAA standards for altitude
+  - Data-driven penalty tables stored in `lib/calcpace/data/environmental_factors.yml`
+  - Support for interpolation between data points in penalty tables
+  - Transparent return values including penalty percentage and factor breakdown
+- New prediction methods with environmental support:
+  - `predict_time_adjusted` (Riegel-based)
+  - `predict_time_cameron_adjusted` (Cameron-based)
+- `adjust_time` and `calculate_penalty` methods for direct environmental impact analysis
+
 ## [1.9.6] - 2026-05-15
 
 ### Changed

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.6'
+gem 'calcpace', '~> 1.9.8'
 ```
 
 ## Usage
@@ -33,6 +33,44 @@ calc.checked_distance('01:21:32', '00:06:27') # => 12.64
 
 ---
 
+### Environmental Performance Adjustments
+
+Adjust race performance based on heat and altitude. Calculations are based on scientific models
+(Matthew Ely 2007 for heat, NCAA standards for altitude).
+
+```ruby
+# Calculate penalty for 25°C and 2000m altitude (Defaults to 60-min effort)
+penalty = calc.calculate_penalty(temperature: 25, altitude: 2000)
+# => {
+#      total_penalty_percent: 8.62,
+#      factors: { heat: 4.3, altitude: 4.32 }
+#    }
+
+# Fahrenheit support
+calc.calculate_penalty(temperature: 80, temperature_unit: :f)
+# => { total_penalty_percent: 5.03, ... }
+
+# Adjust a 3:30 marathon time (12600s) for these conditions (High exposure penalty)
+result = calc.adjust_time(12600, temperature: 25, altitude: 2000)
+# => {
+#      original_time: 12600,
+#      adjusted_time: 15176.7,
+#      adjusted_time_clock: "04:12:56",
+#      penalty_percent: 20.45,
+#      factors: { heat: 16.13, altitude: 4.32 }
+#    }
+
+# Predicted adjusted times (Riegel formula)
+calc.predict_time_adjusted('5k', '00:20:00', '10k', temperature: 28)
+# => { adjusted_time: 2599.74, adjusted_time_clock: "00:43:19", penalty_percent: 3.91, ... }
+
+# Predicted adjusted times (Cameron formula)
+calc.predict_time_cameron_adjusted('10k', '00:40:00', 'marathon', temperature: 80, temperature_unit: :f)
+# => { adjusted_time: 11585.88, adjusted_time_clock: "03:13:05", penalty_percent: 14.18, ... }
+```
+
+---
+
 ### Unit Conversions
 
 30+ units supported. String or symbol format:
@@ -183,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
@@ -193,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/cameron_predictor.rb

@@ -96,6 +96,18 @@ module CameronPredictor
     convert_to_clocktime(predict_pace_cameron(from_race, from_time, to_race))
   end
 
+  # Predicts race time adjusted for environmental conditions using Cameron formula
+  #
+  # @param from_race [String, Symbol] known race distance
+  # @param from_time [String, Numeric] time achieved at known distance
+  # @param to_race [String, Symbol] target race distance to predict
+  # @param options [Hash] environmental options (temperature, altitude, etc.)
+  # @return [Hash] hash with adjusted prediction and penalty details
+  def predict_time_cameron_adjusted(from_race, from_time, to_race, **)
+    predicted_seconds = predict_time_cameron(from_race, from_time, to_race)
+    adjust_time(predicted_seconds, **)
+  end
+
   private
 
   # Computes the Cameron exponential correction factor for a given distance

data/lib/calcpace/data/environmental_factors.yml

@@ -0,0 +1,31 @@
+# Environmental Performance Adjustment Factors
+#
+# Sources:
+# - Altitude: NCAA Altitude Adjustment Factors (TFRRS)
+#   Ref: ~3.76% penalty for 1828.8m (6000ft).
+# - Heat: Matthew Ely et al. (2007) "Impact of Weather on Marathon-Running Performance"
+#   NOTE: These heat factors are the BASELINE for a 60-minute effort.
+#   The final penalty is scaled by a DurationFactor (0.5x to 4.5x) based on total exposure time.
+
+# Altitude adjustments (NCAA standards)
+altitude:
+  threshold_meters: 914.4
+  data_points:
+    0: 0.0
+    914.4: 1.41
+    1219.2: 2.15
+    1524.0: 2.90
+    1828.8: 3.76
+    2133.6: 4.75
+    2438.4: 5.90
+
+# Heat adjustments (60-minute baseline)
+# These values represent the penalty for a 1-hour run.
+# For longer/shorter runs, the DurationFactor will scale these up/down.
+heat:
+  ideal_range_celsius: [10.0, 15.0]
+  data_points:
+    15: 0.0
+    20: 2.8    # Base for 60m. For 3h (3.0x) = 8.4% (Ely: 9%)
+    25: 4.3    # Base for 60m. For 3h (3.0x) = 12.9% (Ely: 12%)
+    30: 6.5    # Base for 60m. For 3h (3.0x) = 19.5%

data/lib/calcpace/environmental_adjuster.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+# Module for adjusting race performance based on environmental conditions
+#
+# Scientific basis:
+# - Heat: Matthew Ely et al. (2007) "Impact of Weather on Marathon-Running Performance"
+# - Altitude: NCAA Altitude Adjustment Factors (TFRRS)
+module EnvironmentalAdjuster
+  DATA_PATH = File.expand_path('data/environmental_factors.yml', __dir__).freeze
+  FACTORS = YAML.safe_load_file(DATA_PATH, permitted_classes: [], aliases: false).freeze
+
+  # Calculates the performance penalty percentage for given environmental conditions
+  #
+  # @param temperature [Numeric, nil] ambient temperature
+  # @param temperature_unit [Symbol, String] :c (Celsius) or :f (Fahrenheit)
+  # @param altitude [Numeric, nil] altitude in meters
+  # @param time_seconds [Numeric, nil] duration of the effort in seconds
+  # @return [Hash] hash with :total_penalty_percent and breakdown in :factors
+  def calculate_penalty(temperature: nil, temperature_unit: :c, altitude: nil, time_seconds: nil)
+    heat_penalty = calculate_heat_penalty(temperature, temperature_unit, time_seconds)
+    altitude_penalty = calculate_altitude_penalty(altitude)
+
+    {
+      total_penalty_percent: (heat_penalty + altitude_penalty).round(2),
+      factors: {
+        heat: heat_penalty,
+        altitude: altitude_penalty
+      }
+    }
+  end
+
+  # Adjusts a given time based on environmental conditions
+  #
+  # @param time_seconds [Numeric] original time in seconds
+  # @param options [Hash] environmental options
+  # @return [Hash] hash with adjusted time and penalty details
+  def adjust_time(time_seconds, **)
+    penalty = calculate_penalty(time_seconds: time_seconds, **)
+    percent = penalty[:total_penalty_percent]
+    adjusted_seconds = (time_seconds * (1 + (percent / 100.0))).round(2)
+
+    {
+      original_time: time_seconds,
+      adjusted_time: adjusted_seconds,
+      adjusted_time_clock: convert_to_clocktime(adjusted_seconds),
+      penalty_percent: percent,
+      factors: penalty[:factors]
+    }
+  end
+
+  # Normalizes a time achieved in non-ideal conditions to its ideal equivalent
+  #
+  # @param time_seconds [Numeric] performance time in seconds
+  # @param options [Hash] environmental options
+  # @return [Hash] hash with normalized time and penalty details
+  def normalize_time(time_seconds, **)
+    penalty = calculate_penalty(time_seconds: time_seconds, **)
+    percent = penalty[:total_penalty_percent]
+    normalized_seconds = (time_seconds / (1 + (percent / 100.0))).round(2)
+
+    {
+      original_time: time_seconds,
+      normalized_time: normalized_seconds,
+      normalized_time_clock: convert_to_clocktime(normalized_seconds),
+      penalty_percent: percent,
+      factors: penalty[:factors]
+    }
+  end
+
+  private
+
+  def calculate_heat_penalty(temp, unit, time_seconds)
+    return 0.0 if temp.nil?
+
+    temp_c = normalize_temperature(temp, unit)
+
+    data = FACTORS.fetch('heat')
+    ideal_min, ideal_max = data.fetch('ideal_range_celsius')
+    return 0.0 if temp_c.between?(ideal_min, ideal_max)
+
+    points = data.fetch('data_points')
+    base_penalty = interpolate_environmental_factor(points, temp_c)
+
+    (base_penalty * duration_factor(time_seconds)).round(2)
+  end
+
+  def duration_factor(time_seconds)
+    return 1.0 if time_seconds.nil?
+
+    minutes = time_seconds / 60.0
+
+    # Rule based on Matthew Ely (2007) heat degradation curve.
+    # Scaled for piecewise linear interpolation to avoid jumps.
+    if minutes <= 30
+      0.5
+    elsif minutes <= 60
+      # Scale from 0.5x (30m) up to 1.0x (60m)
+      0.5 + (((minutes - 30.0) / 30.0) * 0.5)
+    elsif minutes <= 180
+      # Scale from 1.0x (60m) up to 3.0x (180m / 3h)
+      1.0 + (((minutes - 60.0) / 120.0) * 2.0)
+    else
+      # Scale from 3.0x (3h) up to 4.5x (4h)
+      capped_minutes = [minutes, 240.0].min
+      3.0 + (((capped_minutes - 180.0) / 60.0) * 1.5)
+    end
+  end
+
+  def normalize_temperature(temp, unit)
+    return temp.to_f if %i[c celsius].include?(unit.to_s.downcase.to_sym)
+    return ((temp.to_f - 32) * 5.0 / 9.0).round(2) if %i[f fahrenheit].include?(unit.to_s.downcase.to_sym)
+
+    raise ArgumentError, "Unsupported temperature unit '#{unit}'. Supported: :c, :f"
+  end
+
+  def calculate_altitude_penalty(alt)
+    return 0.0 if alt.nil?
+
+    data = FACTORS.fetch('altitude')
+    threshold = data.fetch('threshold_meters')
+    return 0.0 if alt <= threshold
+
+    points = data.fetch('data_points')
+    interpolate_environmental_factor(points, alt)
+  end
+
+  def interpolate_environmental_factor(points, value)
+    key_map, sorted_floats = environmental_key_mapping(points)
+
+    return points.fetch(key_map[sorted_floats.first]).to_f if value <= sorted_floats.first
+    return points.fetch(key_map[sorted_floats.last]).to_f if value >= sorted_floats.last
+
+    lower_val, upper_val = neighboring_environmental_points(sorted_floats, value)
+    return points.fetch(key_map[lower_val]).to_f if lower_val == upper_val
+
+    interpolate_values(points, key_map, lower_val, upper_val, value)
+  end
+
+  def environmental_key_mapping(points)
+    map = points.keys.to_h { |k| [k.to_f, k] }
+    [map, map.keys.sort]
+  end
+
+  def neighboring_environmental_points(sorted_floats, value)
+    lower = sorted_floats.select { |k| k <= value }.max
+    upper = sorted_floats.select { |k| k >= value }.min
+    [lower, upper]
+  end
+
+  def interpolate_values(points, key_map, lower_val, upper_val, value)
+    lower_factor = points.fetch(key_map[lower_val]).to_f
+    upper_factor = points.fetch(key_map[upper_val]).to_f
+
+    ratio = (value - lower_val) / (upper_val - lower_val)
+    (lower_factor + ((upper_factor - lower_factor) * ratio)).round(2)
+  end
+end

data/lib/calcpace/race_predictor.rb

@@ -123,4 +123,23 @@ module RacePredictor
       pace_clock: convert_to_clocktime(predicted_pace)
     }
   end
+
+  # Predicts race time adjusted for environmental conditions
+  #
+  # @param from_race [String, Symbol] known race distance
+  # @param from_time [String, Numeric] time achieved at known distance
+  # @param to_race [String, Symbol] target race distance to predict
+  # @param options [Hash] environmental options:
+  #   - :temperature [Numeric]
+  #   - :temperature_unit [Symbol, String] :c or :f
+  #   - :altitude [Numeric]
+  # @return [Hash] hash with adjusted prediction and penalty details
+  #
+  # @example Predict marathon time from 5K adjusted for heat (25C)
+  #   predict_time_adjusted('5k', '00:20:00', 'marathon', temperature: 25)
+  #   #=> { adjusted_time: 12213.4, penalty_percent: 6.0, ... }
+  def predict_time_adjusted(from_race, from_time, to_race, **)
+    predicted_seconds = predict_time(from_race, from_time, to_race)
+    adjust_time(predicted_seconds, **)
+  end
 end

data/lib/calcpace/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Calcpace
-  VERSION = '1.9.6'
+  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

data/lib/calcpace.rb

@@ -3,6 +3,7 @@
 require_relative 'calcpace/calculator'
 require_relative 'calcpace/cameron_predictor'
 require_relative 'calcpace/age_grading'
+require_relative 'calcpace/environmental_adjuster'
 require_relative 'calcpace/checker'
 require_relative 'calcpace/converter'
 require_relative 'calcpace/converter_chain'
@@ -37,6 +38,7 @@ require_relative 'calcpace/vo2max_estimator'
 # @see https://github.com/0jonjo/calcpace
 class Calcpace
   include AgeGrading
+  include EnvironmentalAdjuster
   include Calculator
   include CameronPredictor
   include Checker

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: calcpace
 version: !ruby/object:Gem::Version
-  version: 1.9.6
+  version: 1.9.8
 platform: ruby
 authors:
 - João Gilberto Saraiva
@@ -37,8 +37,10 @@ files:
 - lib/calcpace/checker.rb
 - lib/calcpace/converter.rb
 - lib/calcpace/converter_chain.rb
+- lib/calcpace/data/environmental_factors.yml
 - lib/calcpace/data/wma_2023_open_standards.yml
 - lib/calcpace/data/wma_2023_road.yml
+- lib/calcpace/environmental_adjuster.rb
 - lib/calcpace/errors.rb
 - lib/calcpace/pace_calculator.rb
 - lib/calcpace/pace_converter.rb