calcpace 1.18.0 → 2.0.0

data/lib/calcpace/age_grading.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'yaml'
+require_relative 'errors'
+require_relative 'checker'
 
 # Module for age-grading race performances with a versioned table
 #
@@ -10,8 +12,14 @@ require 'yaml'
 # Current scope:
 # - Common road distances: 5K, 10K, half marathon, marathon
 # - Sex: male/female
-# - Age: 18+
-# - Data file is versioned and replaceable (`lib/calcpace/data/wma_2023_road.yml`)
+# - Age: 18+, one factor per year up to 100 (older ages use the age-100 factor)
+# - Data: Alan Jones' 2025 road age-grading tables, approved by the USATF
+#   Masters Long Distance Running Council (github.com/AlanLyttonJones/Age-Grade-Tables).
+#   The files are versioned and replaceable: factors in
+#   `lib/calcpace/data/mldr_2025_road.yml`, open standards and category labels in
+#   `lib/calcpace/data/mldr_2025_road_open_standards.yml`
+#
+# The WMA_DATA constant keeps its historical name: it now holds the road table
 #
 # Returned values include:
 # - age grade percentage
@@ -20,17 +28,29 @@ require 'yaml'
 # - performance category
 # rubocop:disable Metrics/ModuleLength
 module AgeGrading
-  DATA_PATH = File.expand_path('data/wma_2023_road.yml', __dir__).freeze
-  OPEN_STANDARDS_DATA_PATH = File.expand_path('data/wma_2023_open_standards.yml', __dir__).freeze
+  # normalize_age / normalize_sex live in Checker, shared with Vo2maxNorms
+  include Checker
+
+  DATA_PATH = File.expand_path('data/mldr_2025_road.yml', __dir__).freeze
+  OPEN_STANDARDS_DATA_PATH = File.expand_path('data/mldr_2025_road_open_standards.yml', __dir__).freeze
   WMA_DATA = YAML.safe_load_file(DATA_PATH, permitted_classes: [],
                                             aliases: false).freeze
   OPEN_STANDARDS_DATA = YAML.safe_load_file(OPEN_STANDARDS_DATA_PATH, permitted_classes: [],
                                                                       aliases: false).freeze
   TABLE_VERSION = OPEN_STANDARDS_DATA.fetch('meta').fetch('table_version').freeze
 
-  AGE_GRADE_LABELS = OPEN_STANDARDS_DATA.fetch('age_grade_classifications').map do |entry|
+  raw_age_grade_labels = OPEN_STANDARDS_DATA.fetch('age_grade_classifications').map do |entry|
     { min: entry.fetch('min').to_f, label: entry.fetch('label') }
-  end.freeze
+  end
+  AGE_GRADE_LABELS = raw_age_grade_labels.sort_by { |entry| -entry[:min] }.freeze
+
+  age_grade_label_mins = AGE_GRADE_LABELS.map { |entry| entry[:min] }
+  unless age_grade_label_mins.all?(&:finite?) &&
+         age_grade_label_mins == age_grade_label_mins.uniq &&
+         age_grade_label_mins.last == 0.0
+    raise Calcpace::InvalidDataError,
+          "age_grade_classifications must have unique finite mins ending at 0.0, got #{age_grade_label_mins.inspect}"
+  end
 
   DISTANCE_TO_METERS = {
     5.0 => '5000',
@@ -50,7 +70,7 @@ module AgeGrading
   # How far a distance may sit from a standard and still be graded as it. 2% is
   # the same window calcpace.app uses to decide a run "is a 5K", so the gem and
   # the site never disagree about the same run. It stays a matching tolerance,
-  # not an interpolation: a distance outside it has no WMA factor and is refused
+  # not an interpolation: a distance outside it has no table factor and is refused
   STANDARD_DISTANCE_TOLERANCE_RATIO = 0.02
 
   # Floor for the window above, so a future shorter standard still matches
@@ -115,6 +135,7 @@ module AgeGrading
   #
   # @param percent [Numeric] age-grade percentage
   # @return [String] category label
+  # @raise [ArgumentError] when percent is not numeric, is negative, or is NaN
   def age_grade_label(percent)
     percent_value = begin
       Float(percent)
@@ -123,6 +144,7 @@ module AgeGrading
     end
 
     raise ArgumentError, 'Age-grade percent must be greater than or equal to 0' if percent_value.negative?
+    raise ArgumentError, 'Age-grade percent must be a number' if percent_value.nan?
 
     AGE_GRADE_LABELS.find { |entry| percent_value >= entry[:min] }[:label]
   end
@@ -168,23 +190,6 @@ module AgeGrading
     convert_to_seconds(time.to_s)
   end
 
-  def normalize_age(age)
-    age_value = Integer(age)
-  rescue ArgumentError, TypeError
-    raise ArgumentError, 'Age must be an integer greater than or equal to 18'
-  else
-    raise ArgumentError, 'Age must be at least 18' if age_value < 18
-
-    age_value
-  end
-
-  def normalize_sex(sex)
-    normalized = sex.to_s.strip.downcase.to_sym
-    return normalized if %i[male female].include?(normalized)
-
-    raise ArgumentError, "Sex must be 'male' or 'female'"
-  end
-
   def interpolated_factor(sex, age, distance_m)
     table = factor_table(sex, distance_m)
     ages = table.keys.map(&:to_i).sort

data/lib/calcpace/cameron_predictor.rb

@@ -2,25 +2,40 @@
 
 # Module for predicting race times using the Cameron formula
 #
-# An alternative to the Riegel formula (RacePredictor module) that uses an
-# exponential correction to better account for physiological differences across
-# distances. The correction is larger when predicting from shorter races, where
-# anaerobic contribution is greater, and diminishes as the known distance approaches
-# the target distance.
+# An alternative to the Riegel formula (RacePredictor module). Dave Cameron fitted
+# a velocity-ratio function to world-best times from 800 m to the marathon; unlike
+# Riegel's single power law, the drop-off it predicts grows with distance, so it is
+# more conservative than Riegel when predicting the marathon from shorter races.
 #
-# Formula: T2 = T1 × (D2/D1) × [(a + b × e^(-D1/c)) / (a + b × e^(-D2/c))]
+# Formula (distances in metres, times in seconds):
+#   f(d) = 13.49681 − 0.000030363 × d + 835.7114 / d^0.7905
+#   T2   = T1 × (D2/D1) × f(D1) / f(D2)
 #
-# Constants (calibrated for distances in km):
-#   a = 0.000495
-#   b = 0.000985
-#   c = 1.4485
+# Distances are accepted in kilometres (or as race names) like every other method
+# in this gem, and converted to metres before f(d) is evaluated.
 #
-# Reference: Dave Cameron, "A Critical Examination of Racing Predictions" (1997)
+# Valid range: the model was fitted from 800 m to the marathon, and f(d) crosses
+# zero near 445 km, beyond which it returns negative or absurd times. Distances
+# above CAMERON_MAX_DISTANCE_KM (100 km, so the standard '100k' race stays usable)
+# raise ArgumentError on either end of the prediction.
+#
+# References:
+# - Dave Cameron, metric version of his model posted to the t-and-f mailing list,
+#   20 Jun 2001: https://www.mail-archive.com/t-and-f@lists.uoregon.edu/msg11312.html
+# - had2know.org Cameron calculator (same constants, distances in metres; worked
+#   example 3.5 mi in 51:30 → 5 mi in ~75:08):
+#   https://www.had2know.org/sports/race-performance-prediction-calculator-cameron.html
 module CameronPredictor
-  # Cameron formula constants (calibrated for distances in km)
-  CAMERON_A = 0.000495
-  CAMERON_B = 0.000985
-  CAMERON_C = 1.4485
+  # Constant term of Cameron's velocity-ratio function f(d)
+  CAMERON_CONSTANT = 13.49681
+  # Linear coefficient of f(d), per metre
+  CAMERON_LINEAR_COEFFICIENT = 0.000030363
+  # Numerator of the power term of f(d)
+  CAMERON_POWER_COEFFICIENT = 835.7114
+  # Exponent of the power term of f(d)
+  CAMERON_POWER_EXPONENT = 0.7905
+  # Longest distance (km), on either end, a Cameron prediction accepts
+  CAMERON_MAX_DISTANCE_KM = 100.0
 
   # Predicts race time using the Cameron formula
   #
@@ -29,26 +44,28 @@ module CameronPredictor
   # @param from_time [String, Numeric] time achieved at known distance (HH:MM:SS or seconds)
   # @param to_race [Numeric, String, Symbol] target distance in kilometers or race name
   # @return [Float] predicted time in seconds
-  # @raise [ArgumentError] if a race name is invalid or the distances are the same
+  # @raise [ArgumentError] if a race name is invalid, the distances are the same,
+  #   or either distance exceeds CAMERON_MAX_DISTANCE_KM (100 km)
   # @raise [Calcpace::NonPositiveInputError] if a numeric distance is not positive
   #
   # @example Predict marathon time from 10K
   #   predict_time_cameron('10k', '00:42:00', 'marathon')
-  #   #=> ~10,654 seconds (approximately 2:57:34)
+  #   #=> ~11,807 seconds (approximately 3:16:46)
   #
   # @example Predict 10K time from 5K
   #   predict_time_cameron('5k', '00:20:00', '10k')
-  #   #=> ~2,546 seconds (approximately 42:26)
+  #   #=> ~2,500 seconds (approximately 41:39)
   def predict_time_cameron(from_race, from_time, to_race)
     from_distance = race_distance(from_race)
     to_distance   = race_distance(to_race)
 
+    ensure_cameron_range!(from_distance, to_distance)
     ensure_different_distances!(from_distance, to_distance)
 
     time_seconds = from_time.is_a?(String) ? convert_to_seconds(from_time) : from_time
     check_positive(time_seconds, 'Time')
 
-    # Cameron formula: T2 = T1 × (D2/D1) × [cameron_factor(D1) / cameron_factor(D2)]
+    # Cameron formula: T2 = T1 × (D2/D1) × [f(D1) / f(D2)]
     time_seconds * (to_distance / from_distance) *
       (cameron_factor(from_distance) / cameron_factor(to_distance))
   end
@@ -59,10 +76,11 @@ module CameronPredictor
   # @param from_time [String, Numeric] time achieved at known distance
   # @param to_race [Numeric, String, Symbol] target distance in kilometers or race name
   # @return [String] predicted time in HH:MM:SS format
+  # @raise [ArgumentError] if either distance exceeds CAMERON_MAX_DISTANCE_KM (100 km)
   #
   # @example
   #   predict_time_cameron_clock('10k', '00:42:00', 'marathon')
-  #   #=> '02:57:34'
+  #   #=> '03:16:46'
   def predict_time_cameron_clock(from_race, from_time, to_race)
     convert_to_clocktime(predict_time_cameron(from_race, from_time, to_race))
   end
@@ -73,10 +91,11 @@ module CameronPredictor
   # @param from_time [String, Numeric] time achieved at known distance
   # @param to_race [Numeric, String, Symbol] target distance in kilometers or race name
   # @return [Float] predicted pace in seconds per kilometer
+  # @raise [ArgumentError] if either distance exceeds CAMERON_MAX_DISTANCE_KM (100 km)
   #
   # @example
   #   predict_pace_cameron('5k', '00:20:00', 'marathon')
-  #   #=> ~255.1 (approximately 4:15/km)
+  #   #=> ~277.6 (approximately 4:37/km)
   def predict_pace_cameron(from_race, from_time, to_race)
     predict_time_cameron(from_race, from_time, to_race) / race_distance(to_race)
   end
@@ -87,10 +106,11 @@ module CameronPredictor
   # @param from_time [String, Numeric] time achieved at known distance
   # @param to_race [Numeric, String, Symbol] target distance in kilometers or race name
   # @return [String] predicted pace in HH:MM:SS format
+  # @raise [ArgumentError] if either distance exceeds CAMERON_MAX_DISTANCE_KM (100 km)
   #
   # @example
   #   predict_pace_cameron_clock('5k', '00:20:00', 'marathon')
-  #   #=> '00:04:15'
+  #   #=> '00:04:37'
   def predict_pace_cameron_clock(from_race, from_time, to_race)
     convert_to_clocktime(predict_pace_cameron(from_race, from_time, to_race))
   end
@@ -100,8 +120,19 @@ module CameronPredictor
   # @param from_race [Numeric, String, Symbol] known distance in kilometers or race name
   # @param from_time [String, Numeric] time achieved at known distance
   # @param to_race [Numeric, String, Symbol] target distance in kilometers or race name
-  # @param options [Hash] environmental options (temperature, altitude, etc.)
+  # @param options [Hash] environmental options, forwarded to
+  #   EnvironmentalAdjuster#calculate_penalty:
+  #   - :temperature [Numeric]
+  #   - :temperature_unit [Symbol, String] :c or :f
+  #   - :altitude [Numeric]
+  #   - :humidity [Numeric] relative humidity, 0–100 % (optional)
+  #   - :dew_point [Numeric] dew point in temperature_unit (optional, instead of :humidity)
   # @return [Hash] hash with adjusted prediction and penalty details
+  # @raise [ArgumentError] if either distance exceeds CAMERON_MAX_DISTANCE_KM (100 km)
+  #
+  # @example
+  #   calc.predict_time_cameron_adjusted('5k', '00:20:00', '10k', temperature: 25, humidity: 80)[:adjusted_time_clock]
+  #   #=> '00:43:41'
   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, **)
@@ -109,11 +140,26 @@ module CameronPredictor
 
   private
 
-  # Computes the Cameron exponential correction factor for a given distance
+  # Rejects distances outside the range where Cameron's model is meaningful
+  #
+  # @param distances [Array<Float>] distances in kilometers
+  # @raise [ArgumentError] if any distance exceeds CAMERON_MAX_DISTANCE_KM
+  def ensure_cameron_range!(*distances)
+    too_long = distances.find { |distance| distance > CAMERON_MAX_DISTANCE_KM }
+    return unless too_long
+
+    raise ArgumentError,
+          "Cameron formula is only valid up to #{CAMERON_MAX_DISTANCE_KM} km (got #{too_long} km)"
+  end
+
+  # Evaluates Cameron's velocity-ratio function f(d) for a given distance
   #
-  # @param distance_km [Float] distance in kilometers
-  # @return [Float] correction factor value
+  # @param distance_km [Float] distance in kilometers (converted to metres, the
+  #   unit Cameron's constants are calibrated for)
+  # @return [Float] value of f(d)
   def cameron_factor(distance_km)
-    CAMERON_A + (CAMERON_B * Math.exp(-distance_km / CAMERON_C))
+    meters = distance_km * 1000.0
+    CAMERON_CONSTANT - (CAMERON_LINEAR_COEFFICIENT * meters) +
+      (CAMERON_POWER_COEFFICIENT / (meters**CAMERON_POWER_EXPONENT))
   end
 end

data/lib/calcpace/checker.rb

@@ -7,46 +7,126 @@ require_relative 'errors'
 # This module provides validation methods for numeric inputs and time format strings
 # used throughout the Calcpace gem.
 module Checker
-  # Validates that a number is positive (greater than zero)
+  # Validates that a number is positive (greater than zero) and finite
+  #
+  # NaN and infinity are rejected too: NaN is not positive, and an infinite
+  # distance or time would flow through the formulas into nonsense (a finite
+  # "prediction") or a FloatDomainError far from the input that caused it. So
+  # is an Integer too large for a Float (a clock with hundreds of hour digits
+  # parses to one), which would turn into Infinity inside the formulas.
   #
   # @param number [Numeric] the number to validate
   # @param name [String] the name of the parameter for error messages
-  # @raise [Calcpace::NonPositiveInputError] if number is not positive
+  # @raise [Calcpace::NonPositiveInputError] if number is not positive or not finite
   # @return [void]
   #
   # @example
-  #   check_positive(10, 'Distance') #=> nil (valid)
-  #   check_positive(-5, 'Time')     #=> raises NonPositiveInputError
-  #   check_positive(0, 'Speed')     #=> raises NonPositiveInputError
+  #   check_positive(10, 'Distance')              #=> nil (valid)
+  #   check_positive(-5, 'Time')                  #=> raises NonPositiveInputError
+  #   check_positive(0, 'Speed')                  #=> raises NonPositiveInputError
+  #   check_positive(Float::INFINITY, 'Distance') #=> raises NonPositiveInputError
   def check_positive(number, name = 'Input')
-    return if number.is_a?(Numeric) && number.positive?
+    unless number.is_a?(Numeric) && number.positive?
+      raise Calcpace::NonPositiveInputError, "#{name} must be a positive number"
+    end
+    # An Integer is always finite, but one past Float::MAX overflows to
+    # Infinity the moment a formula calls to_f on it
+    return if number.finite? && number.to_f.finite?
 
-    raise Calcpace::NonPositiveInputError,
-          "#{name} must be a positive number"
+    raise Calcpace::NonPositiveInputError, "#{name} must be a finite positive number"
   end
 
-  # Validates that a time string is in the correct format
+  # The clock grammar every time and pace string in the gem is read with. It
+  # covers every clock the gem writes (and a few it never writes, such as
+  # '-1 03:46:40' or '000000000:00'):
+  # - an optional leading '-' (track_splits reports a backwards split as '-0:40')
+  # - an optional day prefix, 'D HH:MM:SS', as convert_to_clocktime writes
+  #   durations above 24 hours ('1 03:46:40'); the hour field after it is two
+  #   digits below 24
+  # - H:MM:SS, where the hours have any number of digits ('400:00:00') and the
+  #   minutes and seconds are two digits below 60
+  # - M:SS, where the minutes have any number of digits and keep counting past
+  #   the hour ('75:00', '123:45') and the seconds are two digits below 60
+  # Nothing else: no '+', no blanks or surrounding whitespace, ASCII digits only,
+  # and only in a String whose encoding is valid and ASCII-compatible.
+  CLOCK_FORMAT = /
+    \A(?<sign>-)?
+    (?:(?<days>\d+)[ ](?=(?:[01]\d|2[0-3]):[0-5]\d:))?
+    (?:(?<hours>\d+):(?<minutes>[0-5]\d)|(?<total_minutes>\d+))
+    :(?<seconds>[0-5]\d)\z
+  /x
+
+  # Validates that a time string is a well-formed clock
   #
-  # Accepted formats:
-  # - HH:MM:SS (hours:minutes:seconds) - e.g., "01:30:45"
-  # - MM:SS (minutes:seconds) - e.g., "05:30"
-  # - H:MM:SS or M:SS (single digit hours/minutes) - e.g., "1:30:45"
+  # Accepts what CLOCK_FORMAT describes, i.e. every clock the gem formats:
+  # H:MM:SS / HH:MM:SS with any number of hour digits, M:SS / MM:SS with any
+  # number of minute digits, the 'D HH:MM:SS' day prefix of convert_to_clocktime
+  # and an optional leading '-'. Seconds must be below 60, and so must minutes
+  # once an hour field is present ("1:60:00" is not a clock); MM:SS keeps
+  # counting minutes past the hour, so "75:00" is a valid 75-minute time.
+  #
+  # A negative clock is well formed (track_splits writes one for a backwards
+  # split); methods that need a positive time or pace reject it with
+  # Calcpace::NonPositiveInputError after parsing.
   #
   # @param time_string [String] the time string to validate
   # @raise [Calcpace::InvalidTimeFormatError] if format is invalid
   # @return [void]
   #
   # @example
-  #   check_time('01:30:45') #=> nil (valid)
-  #   check_time('5:30')     #=> nil (valid)
-  #   check_time('invalid')  #=> raises InvalidTimeFormatError
+  #   check_time('01:30:45')   #=> nil (valid)
+  #   check_time('5:30')       #=> nil (valid)
+  #   check_time('75:00')      #=> nil (valid, 75 minutes)
+  #   check_time('1 03:46:40') #=> nil (valid, 1 day 3:46:40)
+  #   check_time('-0:40')      #=> nil (valid, a backwards split)
+  #   check_time('05:99')      #=> raises InvalidTimeFormatError
+  #   check_time('1:60:00')    #=> raises InvalidTimeFormatError
+  #   check_time('invalid')    #=> raises InvalidTimeFormatError
   def check_time(time_string)
-    # Check if string is valid and matches expected patterns
-    return if time_string.is_a?(String) &&
-              (time_string =~ /\A\d{1,2}:\d{2}:\d{2}\z/ ||
-               time_string =~ /\A\d{1,2}:\d{2}\z/)
+    clock_match(time_string)
+    nil
+  end
+
+  private
+
+  # @return [MatchData] the CLOCK_FORMAT match for a valid clock
+  # @raise [Calcpace::InvalidTimeFormatError] otherwise
+  def clock_match(time_string)
+    match = CLOCK_FORMAT.match(time_string) if clock_encoding?(time_string)
+    return match if match
 
     raise Calcpace::InvalidTimeFormatError,
-          'It must be a valid time in the XX:XX:XX or XX:XX format'
+          'It must be a valid time in the XX:XX:XX or XX:XX format ' \
+          '(seconds below 60, and minutes too when hours are given)'
+  end
+
+  # Only a String in a valid, ASCII-compatible encoding can be a clock: the
+  # pattern cannot match UTF-16/UTF-32, and a broken byte sequence raises
+  # ArgumentError inside the regexp engine instead of a clock error
+  def clock_encoding?(time_string)
+    time_string.is_a?(String) && time_string.valid_encoding? && time_string.encoding.ascii_compatible?
+  end
+
+  # Age in whole years, 18 or over — the rule AgeGrading and Vo2maxNorms share
+  #
+  # @raise [ArgumentError] if age is not an integer or is under 18
+  def normalize_age(age)
+    age_value = Integer(age)
+  rescue ArgumentError, TypeError
+    raise ArgumentError, 'Age must be an integer greater than or equal to 18'
+  else
+    raise ArgumentError, 'Age must be at least 18' if age_value < 18
+
+    age_value
+  end
+
+  # :male or :female, from any case of a String or Symbol — shared like normalize_age
+  #
+  # @raise [ArgumentError] for anything else
+  def normalize_sex(sex)
+    normalized = sex.to_s.strip.downcase.to_sym
+    return normalized if %i[male female].include?(normalized)
+
+    raise ArgumentError, "Sex must be 'male' or 'female'"
   end
 end

data/lib/calcpace/converter.rb

@@ -77,24 +77,29 @@ module Converter
 
   # Converts a time string to total seconds
   #
+  # Every method in the gem that takes a time or pace string goes through
+  # here, so they all read the same clocks: the ones Checker#check_time
+  # accepts, which cover every clock the gem writes — signed track_splits
+  # paces ('-0:40' is -40), minutes past the hour ('75:00'), any number of
+  # hours ('400:00:00') and the day prefix of convert_to_clocktime
+  # ('1 03:46:40'). Methods that need a positive time reject a negative one
+  # afterwards.
+  #
   # @param time [String] time string in HH:MM:SS or MM:SS format
-  # @return [Integer] total seconds
+  # @return [Integer] total seconds (negative for a '-' clock)
+  # @raise [Calcpace::InvalidTimeFormatError] if the string is not a valid clock
   #
   # @example
-  #   convert_to_seconds('01:30:00') #=> 5400 (1 hour 30 minutes)
-  #   convert_to_seconds('05:30')    #=> 330 (5 minutes 30 seconds)
+  #   convert_to_seconds('01:30:00')   #=> 5400 (1 hour 30 minutes)
+  #   convert_to_seconds('05:30')      #=> 330 (5 minutes 30 seconds)
+  #   convert_to_seconds('1 03:46:40') #=> 100000
+  #   convert_to_seconds('-0:40')      #=> -40
+  #   convert_to_seconds('05:99')      #=> raises InvalidTimeFormatError
   def convert_to_seconds(time)
-    parts = time.split(':').map(&:to_i)
-    case parts.length
-    when 2
-      minute, seconds = parts
-      (minute * 60) + seconds
-    when 3
-      hour, minute, seconds = parts
-      (hour * 3600) + (minute * 60) + seconds
-    else
-      0
-    end
+    clock = clock_match(time)
+    minutes = clock[:total_minutes] || clock[:minutes]
+    total = (clock[:days].to_i * 86_400) + (clock[:hours].to_i * 3600) + (minutes.to_i * 60) + clock[:seconds].to_i
+    clock[:sign] ? -total : total
   end
 
   # Converts seconds to a clocktime string

data/lib/calcpace/data/environmental_factors.yml

@@ -3,29 +3,109 @@
 # 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"
+# - Heat: Ely et al. (2007) "Impact of Weather on Marathon-Running Performance",
+#   MSSE 39(3):487-493 — qualitative source: marathon times slow progressively
+#   from 5 to 25 °C WBGT, and more for slower runners (top men 1.7 / 2.5 / 3.3 /
+#   4.5% off the course record in WBGT 5-10 / 10-15 / 15-20 / 20-25 °C).
 #   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.
+#   The final penalty is scaled by a DurationFactor (0.5x at 30 min, 1.0x at
+#   60 min, 1.76x at 3 h, 2.81x at 4 h and beyond; see
+#   EnvironmentalAdjuster::HEAT_DURATION_FACTORS) based on total exposure time.
+#   Both the shape of the base curve and the 3 h / 4 h factors are fitted to
+#   El Helou et al. (2012), PLoS One 7(5):e37407, Table S3 (1.79 M finishers of
+#   Berlin, Boston, Chicago, London, New York and Paris, 2001-2010).
+#   Derivation (reproduced by the El Helou tests in test_environmental_adjuster.rb):
+#   1. Speed loss (%) at 15, 20 and 25 °C: straight line between the table's
+#      points (each group's optimum -10 ... +20 °C, every 5 °C).
+#   2. Time penalty against 15 °C (where the curve is zero):
+#      P = ((1 - loss15) / (1 - lossT) - 1) x 100.
+#   3. Base shape: P25 / P20 is 2.70-2.97 in all seven groups that have both
+#      (table below). With P ∝ (T - 15)^p, p = log2(P25 / P20); the sex-weighted
+#      mean (each sex half the weight) is p = 1.497 -> 1.5. The base is
+#      4.3 · ((T - 15) / 10)^1.5, anchored at the original base(25) = 4.3,
+#      which is the only value available for a 60-minute effort.
+#   4. Ratio = P / base(T) (1.52 at 20 °C, 4.3 at 25 °C); finish time =
+#      42195 m / the group's speed at its optimum.
+#   5. Weighted least squares over the 15 ratios (men P1 at 25 °C is beyond
+#      the table), each sex half the weight (men 7, women 8), 1.0x at 60 min
+#      fixed, 180 and 240 min free, flat after 240: 1.761 and 2.814 -> 1.76 and
+#      2.81. An extra free point at 150 min cut the weighted residual by 1%
+#      only; one at 210 min made the curve non-monotonic (2.97 at 210 > 2.73
+#      at 240). Neither was kept.
+#
+#   | Group        | Finish | loss@15 | loss@20 | loss@25 | P20  | P25   | P25/P20 | ratio @20 | @25  |
+#   | men P1       | 2:41   | 1.88    | 3.93    | n/a*    | 2.14 | n/a*  | n/a*    | 1.41      | n/a* |
+#   | women P1     | 3:06   | 0.79    | 3.13    | 7.27    | 2.42 | 6.99  | 2.89    | 1.59      | 1.63 |
+#   | men Q1       | 3:31   | 2.86    | 7.00    | 13.58   | 4.46 | 12.41 | 2.78    | 2.93      | 2.89 |
+#   | men median   | 3:57   | 3.18    | 7.93    | 15.63   | 5.17 | 14.76 | 2.86    | 3.40      | 3.43 |
+#   | women Q1     | 4:00   | 1.86    | 4.73    | 9.26    | 3.02 | 8.16  | 2.70    | 1.99      | 1.90 |
+#   | women median | 4:25   | 2.09    | 5.30    | 10.40   | 3.39 | 9.27  | 2.73    | 2.23      | 2.16 |
+#   | men Q3       | 4:28   | 2.92    | 7.91    | 16.38   | 5.42 | 16.10 | 2.97    | 3.57      | 3.74 |
+#   | women Q3     | 4:54   | 2.03    | 5.37    | 10.80   | 3.54 | 9.83  | 2.78    | 2.33      | 2.29 |
+#   * men P1's optimum is 3.81 °C, so 25 °C is beyond its last point (+20 °C).
+#   (P1 = first percentile, Q1/Q3 = quartiles; losses and P in %.)
+#   Caveat: the model has no sex input. With one curve, men's slower groups are
+#   under-read at 25 °C (median 11.9% vs 14.76% observed) and women's over-read
+#   (median 12.08% vs 9.27%).
+# - Humidity: the points are read at air temperature with ~50% relative
+#   humidity (EnvironmentalAdjuster::REFERENCE_HUMIDITY). With humidity: or
+#   dew_point:, the temperature is first moved to the effective temperature
+#   with the same simplified WBGT (Australian Bureau of Meteorology).
+#
+# Interpolation: at or below threshold_meters the altitude penalty is 0; above it
+# both tables are interpolated linearly between points and clamped to the first and
+# last point.
 
-# Altitude adjustments (NCAA standards)
+# Altitude adjustments
+# - 300 m: start of the curve. Below ~300 m altitude has no measurable effect; the
+#   ramp from 300 m to the first NCAA point (914.4 m) replaces the old step, where
+#   914 m gave 0% and 915 m gave 1.41%.
+# - 914.4 m .. 2438.4 m: NCAA table (3000 ft .. 8000 ft), unchanged.
+# - 3000 m, 3500 m, 4000 m: EXTRAPOLATION beyond the NCAA table, from a quadratic
+#   fit to the NCAA points: p = 0.3647·x² + 1.9482·x, with x = altitude_km − 0.3.
+#   The penalty is capped at the 4000 m value.
 altitude:
-  threshold_meters: 914.4
+  threshold_meters: 300
   data_points:
-    0: 0.0
+    300: 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
+    3000: 7.92     # extrapolated (quadratic fit), not NCAA
+    3500: 9.97     # extrapolated (quadratic fit), not NCAA
+    4000: 12.2     # extrapolated (quadratic fit), not NCAA
 
 # 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.
+# Points follow base(T) = 4.3 · ((T − 15) / 10)^1.5, every 2.5 °C so that the
+# straight lines between them stay within 0.08 points of the curve:
+# - exponent 1.5: El Helou et al. (2012) Table S3, see the derivation above;
+#   the penalty against 15 °C grows 2.70-2.97x from 20 to 25 °C in every
+#   group (2^1.497 = 2.82).
+# - anchor base(25) = 4.3: kept from the original model; it is the only value
+#   available for short efforts and has no direct published source.
+# - 27.5-35 °C: EXTRAPOLATION of the same law. The marathon data stop at
+#   ~25 °C (El Helou's hottest race: 25.2 °C).
+# - Above 35 °C: CAPPED at the 35 °C value (12.16), a deliberate choice, not
+#   data. Everything beyond 25.2 °C is extrapolation, and the uncapped law
+#   (14.51 at 37.5 °C, 17.0 at 40 °C) gave 47.77% for 4 h at 40 °C. 37.5 °C and
+#   40 °C therefore read like 35 °C, and anything hotter is clamped to the last
+#   point as before.
 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%
+    17.5: 0.54
+    20: 1.52   # Base for 60m. For 3h (1.76x) = 2.68%, for 4h (2.81x) = 4.27%
+    22.5: 2.79
+    25: 4.3    # Base for 60m (anchor). For 3h = 7.57%, for 4h = 12.08%
+    27.5: 6.01 # EXTRAPOLATION from here on
+    30: 7.9    # For 3h = 13.9%, for 4h = 22.2%
+    32.5: 9.95
+    35: 12.16  # For 3h = 21.4%, for 4h = 34.17%; the cap starts here
+    37.5: 12.16 # CAP: same as 35 °C (uncapped law: 14.51)
+    40: 12.16   # CAP: same as 35 °C (uncapped law: 17.0); clamped above

data/lib/calcpace/data/friend_2015_vo2max_percentiles.yml

@@ -0,0 +1,49 @@
+# VO2max percentiles by age and sex (ml/kg/min), treadmill CPX with measured VO2max
+#
+# Source: Kaminsky LA, Arena R, Myers J. Reference Standards for
+# Cardiorespiratory Fitness Measured With Cardiopulmonary Exercise Testing:
+# Data From the Fitness Registry and the Importance of Exercise National
+# Database (FRIEND). Mayo Clinic Proceedings 2015;90(11):1515-1523.
+# doi:10.1016/j.mayocp.2015.07.026 (author manuscript: PMC4919021)
+#
+# Table 3, "Sex-Specific Percentiles for CRF From Treadmill Exercise Tests With
+# Measured VO2max Obtained From FRIEND [...]", rows "Men from FRIEND" and
+# "Women from FRIEND". 7,783 treadmill tests (4,611 on men, 3,172 on women)
+# on US adults free of known cardiovascular disease (Table 3 footnote; the
+# paper notes some had other conditions, e.g. diabetes or obesity), VO2max
+# measured by cardiopulmonary exercise testing (not predicted).
+#
+# The same Table 3 also reproduces the Cooper Clinic percentiles as printed in
+# ACSM's Guidelines for Exercise Testing and Prescription, 9th ed. (2014),
+# pp. 88-93 — the paper's reference 13 and, in its words, "the only widely
+# cited reference data in the United States". They are not used here: those
+# VO2max values were predicted from Balke treadmill time rather than measured,
+# and their spread is much narrower (95th percentile for men aged 20-29: 55.5
+# predicted against 66.3 measured).
+#
+# Each row lists the VO2max at the percentiles in `percentiles`, in order.
+# Age bands are keyed by their lower bound and span ten years (20 = 20-29).
+
+meta:
+  table_version: "FRIEND 2015 (Kaminsky et al., Mayo Clin Proc 90:1515, Table 3)"
+  doi: "10.1016/j.mayocp.2015.07.026"
+  units: "ml/kg/min"
+  modality: "treadmill, measured VO2max"
+
+percentiles: [5, 10, 25, 50, 75, 90, 95]
+
+M:
+  20: [29.0, 32.1, 40.1, 48.0, 55.2, 61.8, 66.3]
+  30: [27.2, 30.2, 35.9, 42.4, 49.2, 56.5, 59.8]
+  40: [24.2, 26.8, 31.9, 37.8, 45.0, 52.1, 55.6]
+  50: [20.9, 22.8, 27.1, 32.6, 39.7, 45.6, 50.7]
+  60: [17.4, 19.8, 23.7, 28.2, 34.5, 40.3, 43.0]
+  70: [16.3, 17.1, 20.4, 24.4, 30.4, 36.6, 39.7]
+
+F:
+  20: [21.7, 23.9, 30.5, 37.6, 44.7, 51.3, 56.0]
+  30: [19.0, 20.9, 25.3, 30.2, 36.1, 41.4, 45.8]
+  40: [17.0, 18.8, 22.1, 26.7, 32.4, 38.4, 41.7]
+  50: [16.0, 17.3, 19.9, 23.4, 27.6, 32.0, 35.9]
+  60: [13.4, 14.6, 17.2, 20.0, 23.8, 27.0, 29.4]
+  70: [13.1, 13.6, 15.6, 18.3, 20.8, 23.1, 24.1]