calcpace 1.9.6 → 1.9.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc7e42385a1c6bf01908929f49004b332943dd0971bcb2d93ac69c838bc94ad2
-  data.tar.gz: 955bff3b89fabb29e6a4223efd5e8654bc0a76c6b59b507a31a1db8673cebce8
+  metadata.gz: 6d9eb6ddf00dde81f5405ab23cf97f609eaf5b11e2f49f69724cc1579e976dc3
+  data.tar.gz: 97400c042ef3109c0479655e07bb55e72f136b4dcc5ba044cdd9ae6311ad8dd4
 SHA512:
-  metadata.gz: 750ec40b02ae3607bb01efd6333ffd0e6ccfa21689914a58e3bb6d8f0ce17a60c6c66f01465766786847979a83fa581130550877edcb57056a549b613e72925f
-  data.tar.gz: b1bec9ff070a7511a604e5a6d34c2912735b27b7695f16b4afaaf9f6f0fbb9e56135068a881ab8b4de732bcba501bfe6a2dce8d07eff5b13b0f45b3805b3863c
+  metadata.gz: 6b74a386783c041329e47dbc6308f2844afe7be54fff27049d54f9d91dc00cc696522cdbd1a035cbd401299276a7c75ab9438220248b14b9b815bca39cd52609
+  data.tar.gz: 8328528b5680a4eaca14ad9ee9dddc233069386888d1e59cd676614a5d6a7292cc777360cfeabf0cc6d8fa7d8e9f4266feb3dbed7bc0de0b2ebb8d03025bc457

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.7'
 ```
 
 ## 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:

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.7'
 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.7
 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