calcpace 1.18.1 → 2.0.0

data/lib/calcpace/environmental_adjuster.rb

@@ -1,34 +1,71 @@
 # frozen_string_literal: true
 
 require 'yaml'
+require_relative 'humidity'
 
 # Module for adjusting race performance based on environmental conditions
 #
 # Scientific basis:
-# - 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"
+#   (qualitative: slowing grows with WBGT, more for slower runners) and
+#   El Helou et al. (2012) "Impact of Environmental Parameters on Marathon
+#   Running Performance" (duration scaling, see HEAT_DURATION_FACTORS)
 # - Altitude: NCAA Altitude Adjustment Factors (TFRRS)
+# - Humidity: Australian Bureau of Meteorology simplified WBGT
+#   (WBGT = 0.567·Ta + 0.393·e + 3.94, e = vapour pressure in hPa)
 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
 
+  # Heat duration scaling: [minutes, factor] points, joined by straight lines
+  # and flat outside the first and last point. The base heat penalty in
+  # environmental_factors.yml is for a 60-minute effort (factor 1.0).
+  # - 30 min (0.5x) and 60 min (1.0x): kept from the original model; no
+  #   marathon dataset covers efforts this short.
+  # - 3 h (1.76x) and 4 h (2.81x, flat after): weighted least-squares fit to
+  #   El Helou et al. (2012) Table S3 — the time penalty against 15 °C at
+  #   20 °C and 25 °C for eight finisher groups (2:41–4:54) divided by the
+  #   60-minute base (itself fitted to the same table). The 2 h value (1.38x)
+  #   is the straight line 60 → 180 min: no group finishes between 1 h and
+  #   2:41. Derivation table in environmental_factors.yml.
+  HEAT_DURATION_FACTORS = [[30.0, 0.5], [60.0, 1.0], [180.0, 1.76], [240.0, 2.81]].freeze
+
+  # Relative humidity (%) the temperature-only heat curve stands for
+  # (see EnvironmentalAdjuster::Humidity)
+  REFERENCE_HUMIDITY = Humidity::REFERENCE_HUMIDITY
+
   # 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)
+  # @param humidity [Numeric, nil] relative humidity in % (0–100). Optional;
+  #   without it (and without dew_point) the heat curve assumes
+  #   REFERENCE_HUMIDITY. With it, the temperature is replaced by the effective
+  #   temperature that has the same simplified WBGT at REFERENCE_HUMIDITY.
+  # @param dew_point [Numeric, nil] dew point, in temperature_unit. Alternative
+  #   to humidity (pass one or the other), must not exceed the temperature
+  # @return [Hash] hash with :total_penalty_percent and breakdown in :factors;
+  #   when humidity or dew_point is given, :factors also carries
+  #   :effective_temperature_celsius
+  # @raise [ArgumentError] if humidity is outside 0–100, dew_point is above the
+  #   temperature, both are given, or either is given without a temperature
+  #
+  # @example
+  #   calc.calculate_penalty(temperature: 30, humidity: 90)[:total_penalty_percent] #=> 12.16
+  #   calc.calculate_penalty(temperature: 30, humidity: 90)[:factors][:effective_temperature_celsius] #=> 35.94
+  #   calc.calculate_penalty(temperature: 86, dew_point: 77, temperature_unit: :f)[:total_penalty_percent] #=> 11.07
+  def calculate_penalty(temperature: nil, temperature_unit: :c, altitude: nil, time_seconds: nil,
+                        humidity: nil, dew_point: nil)
+    effective = effective_temperature(temperature, temperature_unit, humidity, dew_point)
+    heat_penalty = calculate_heat_penalty(effective, time_seconds)
     altitude_penalty = calculate_altitude_penalty(altitude)
 
-    {
-      total_penalty_percent: (heat_penalty + altitude_penalty).round(2),
-      factors: {
-        heat: heat_penalty,
-        altitude: altitude_penalty
-      }
-    }
+    factors = { heat: heat_penalty, altitude: altitude_penalty }
+    factors[:effective_temperature_celsius] = effective.round(2) unless humidity.nil? && dew_point.nil?
+
+    { total_penalty_percent: (heat_penalty + altitude_penalty).round(2), factors: factors }
   end
 
   # Adjusts a given time based on environmental conditions
@@ -71,10 +108,19 @@ module EnvironmentalAdjuster
 
   private
 
-  def calculate_heat_penalty(temp, unit, time_seconds)
-    return 0.0 if temp.nil?
+  # Air temperature in °C, moved to the temperature that has the same
+  # simplified WBGT at REFERENCE_HUMIDITY when humidity or dew point is known
+  def effective_temperature(temp, unit, humidity, dew_point)
+    Humidity.check_inputs!(temp, humidity, dew_point)
+    temp_c = temp && normalize_temperature(temp, unit)
+    return temp_c if temp_c.nil? || (humidity.nil? && dew_point.nil?)
+
+    Humidity.effective_temperature(temp_c, humidity: humidity,
+                                           dew_point_c: dew_point && normalize_temperature(dew_point, unit))
+  end
 
-    temp_c = normalize_temperature(temp, unit)
+  def calculate_heat_penalty(temp_c, time_seconds)
+    return 0.0 if temp_c.nil?
 
     data = FACTORS.fetch('heat')
     ideal_min, ideal_max = data.fetch('ideal_range_celsius')
@@ -89,23 +135,11 @@ module EnvironmentalAdjuster
   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
+    minutes = (time_seconds / 60.0).clamp(HEAT_DURATION_FACTORS.first.first, HEAT_DURATION_FACTORS.last.first)
+    (from_minutes, from_factor), (to_minutes, to_factor) =
+      HEAT_DURATION_FACTORS.each_cons(2).find { |_, (upper, _)| minutes <= upper }
+
+    from_factor + (((minutes - from_minutes) / (to_minutes - from_minutes)) * (to_factor - from_factor))
   end
 
   def normalize_temperature(temp, unit)

data/lib/calcpace/grade_adjusted_pace.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+# Module for grade-adjusted pace (GAP): the flat-ground pace that costs the
+# same energy as a pace run on a slope
+#
+# Uses the energy cost of running on gradients measured by Minetti et al.
+# (2002) on ten runners on a treadmill inclined from −45% to +45%:
+#
+#   Cr(i) = 155.4·i⁵ − 30.4·i⁴ − 43.3·i³ + 46.3·i² + 19.5·i + 3.6   (R² = 0.999)
+#
+# where Cr is the metabolic cost in J·kg⁻¹·m⁻¹ and i the gradient as a
+# fraction (rise over horizontal run, 0.05 = 5%). The adjustment factor is
+# Cr(i) / Cr(0): running a metre of 10% climb costs about 1.66 flat metres,
+# a metre of 10% descent about 0.60. Cost is cheapest near −20% and rises
+# again on steeper descents, where braking takes over.
+#
+# The flat-equivalent pace is pace / factor: the speed that, on level ground,
+# spends energy at the same rate. Minetti found the cost per metre independent
+# of speed, so the factor does not depend on how fast the runner is going.
+#
+# Limits worth knowing:
+# - The polynomial is a fit to treadmill measurements between −0.45 and +0.45;
+#   grades outside that range are clamped to it rather than extrapolated.
+# - It is a metabolic model. It does not account for the muscular cost of long
+#   descents, technical terrain or the fact that a runner rarely holds the
+#   metabolic equivalent on a steep climb — field GAP models fitted to heart
+#   rate (Strava's, for instance) are gentler on climbs.
+# - Its constant term (3.6) is the fit's value on the flat; Minetti measured
+#   3.40 ± 0.24 J·kg⁻¹·m⁻¹ there. The factor divides by Cr(0) so it is exactly
+#   1.0 on the flat.
+#
+# Reference: Minetti, A. E., Moia, C., Roi, G. S., Susta, D., & Ferretti, G.
+# (2002). Energy cost of walking and running at extreme uphill and downhill
+# slopes. Journal of Applied Physiology, 93(3), 1039–1046.
+# https://doi.org/10.1152/japplphysiol.01177.2001
+module GradeAdjustedPace
+  # Gradient range of Minetti et al.'s measurements, as fractions
+  MINETTI_GRADE_RANGE = (-0.45..0.45)
+
+  # Polynomial coefficients for Cr(i), highest power first (J·kg⁻¹·m⁻¹)
+  MINETTI_RUNNING_COEFFICIENTS = [155.4, -30.4, -43.3, 46.3, 19.5, 3.6].freeze
+
+  # Returns how many flat metres one metre at a given gradient is worth
+  #
+  # @param grade [Numeric] gradient as a fraction (0.05 = 5% uphill, −0.05 = 5%
+  #   downhill); clamped to −0.45..0.45, the range Minetti et al. measured
+  # @return [Float] Cr(grade) / Cr(0) — 1.0 on the flat, above 1 uphill,
+  #   below 1 on moderate descents
+  # @raise [ArgumentError] if grade is not a finite number
+  #
+  # @example
+  #   calc.grade_adjustment_factor(0)     #=> 1.0
+  #   calc.grade_adjustment_factor(0.1)   #=> 1.6578372222222222
+  #   calc.grade_adjustment_factor(-0.1)  #=> 0.5976961111111111
+  def grade_adjustment_factor(grade)
+    check_grade(grade)
+
+    minetti_running_cost(grade.to_f.clamp(MINETTI_GRADE_RANGE)) / minetti_running_cost(0.0)
+  end
+
+  # Converts a pace run on a slope into the flat pace of equal effort
+  #
+  # @param pace [Numeric, String] pace in seconds per unit or time string (MM:SS or HH:MM:SS)
+  # @param grade [Numeric] gradient as a fraction (see #grade_adjustment_factor)
+  # @param unit [Symbol, String] unit the pace is expressed in — :km (default) or
+  #   :mi. The factor is per distance, so the result comes back in the same unit
+  #   and the unit only has to be a supported one
+  # @return [Float] flat-equivalent pace in seconds per unit
+  # @raise [ArgumentError] if grade is not a finite number
+  # @raise [Calcpace::NonPositiveInputError] if pace is not positive
+  # @raise [Calcpace::InvalidTimeFormatError] if a string pace is not a valid clock
+  # @raise [Calcpace::UnsupportedUnitError] if unit is not :km or :mi
+  #
+  # @example
+  #   calc.grade_adjusted_pace(360, 0.1)              #=> 217.1503903847952
+  #   calc.grade_adjusted_pace('05:00', -0.05)        #=> 393.31023895122013
+  #   calc.grade_adjusted_pace(480, 0.05, unit: :mi)  #=> 368.82127811700303
+  def grade_adjusted_pace(pace, grade, unit: :km)
+    pace_unit_meters(unit)
+    factor = grade_adjustment_factor(grade)
+    pace_seconds = pace_seconds_from(pace)
+    check_positive(pace_seconds, 'Pace')
+
+    pace_seconds.to_f / factor
+  end
+
+  # Grade-adjusted pace as a clock string
+  #
+  # @param pace [Numeric, String] pace in seconds per unit or time string
+  # @param grade [Numeric] gradient as a fraction
+  # @param unit [Symbol, String] unit the pace is expressed in — :km (default) or :mi
+  # @param compact [Boolean] when true, return the compact display format
+  # @return [String] flat-equivalent pace in HH:MM:SS format, or 'M:SS' / 'H:MM:SS'
+  #   with compact: true
+  #
+  # @example
+  #   calc.grade_adjusted_pace_clock('06:00', 0.1)                 #=> '00:03:37'
+  #   calc.grade_adjusted_pace_clock('06:00', 0.1, compact: true)  #=> '3:37'
+  def grade_adjusted_pace_clock(pace, grade, unit: :km, compact: false)
+    convert_to_clocktime(grade_adjusted_pace(pace, grade, unit: unit), compact: compact)
+  end
+
+  private
+
+  def check_grade(grade)
+    return if grade.is_a?(Numeric) && grade.to_f.finite?
+
+    raise ArgumentError, "Grade must be a finite number (a fraction: 0.05 = 5%), got #{grade.inspect}"
+  end
+
+  def minetti_running_cost(grade)
+    MINETTI_RUNNING_COEFFICIENTS.reduce(0.0) { |sum, coefficient| (sum * grade) + coefficient }
+  end
+end

data/lib/calcpace/humidity.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module EnvironmentalAdjuster
+  # Turns air temperature plus humidity into the effective temperature the heat
+  # curve is read at.
+  #
+  # The heat curve is keyed on air temperature, but heat stress depends on
+  # humidity too: sweat evaporates less in humid air. Wet-bulb globe temperature
+  # (WBGT) captures both. The Australian Bureau of Meteorology's simplified WBGT,
+  # for outdoor conditions with moderate sun and light wind, is
+  #
+  #   WBGT = 0.567·Ta + 0.393·e + 3.94
+  #   e    = RH/100 · 6.105·exp(17.27·Ta / (237.7 + Ta))   (hPa)
+  #
+  # The effective temperature is the air temperature that, at
+  # REFERENCE_HUMIDITY, has the same WBGT as the real (temperature, humidity)
+  # pair: WBGT(T_eff, REFERENCE_HUMIDITY) = WBGT(T, RH). Solving that equation
+  # (rather than adding ΔWBGT / 0.567) keeps the reference air's own vapour
+  # pressure rising with temperature, as it does along the temperature-only
+  # curve; the shortcut would roughly double the humidity effect at 30 °C.
+  module Humidity
+    # Relative humidity (%) the temperature-only heat curve stands for. The
+    # simplified WBGT equals the air temperature at 51–56% RH between 20 °C and
+    # 35 °C, so at 50% the curve reads the same whether its input is taken as
+    # air temperature or as WBGT; 50% is also mid-range for the marathons
+    # behind the duration factor (El Helou et al. 2012: mean race-day RH
+    # 51–78%). humidity: 50 gives the same numbers as no humidity at all.
+    REFERENCE_HUMIDITY = 50.0
+
+    # Simplified WBGT coefficients (Australian Bureau of Meteorology)
+    WBGT_TEMPERATURE_COEFFICIENT = 0.567
+    WBGT_VAPOUR_PRESSURE_COEFFICIENT = 0.393
+
+    # Bisection: the bracket is ±40 °C around the air temperature (0–100% RH
+    # moves the effective temperature by far less) and 60 halvings take it
+    # below 1e-16 °C
+    BRACKET_CELSIUS = 40.0
+    BISECTION_STEPS = 60
+
+    # Lowest accepted dew point (°C). The Magnus formula has a pole at
+    # −237.7 °C, and no weather on Earth has a dew point anywhere near −100 °C.
+    MIN_DEW_POINT_CELSIUS = -100.0
+
+    module_function
+
+    # @param temp [Numeric, nil] air temperature in any unit (nil = none given)
+    # @param humidity [Object] relative humidity input
+    # @param dew_point [Object] dew point input
+    # @raise [ArgumentError] if the combination or a value is invalid
+    def check_inputs!(temp, humidity, dew_point)
+      return if humidity.nil? && dew_point.nil?
+      raise ArgumentError, 'Pass either humidity or dew_point, not both' if humidity && dew_point
+      raise ArgumentError, 'humidity and dew_point need a finite temperature' unless finite_number?(temp)
+
+      check_values!(humidity, dew_point)
+    end
+
+    def check_values!(humidity, dew_point)
+      unless valid_dew_point?(dew_point)
+        raise ArgumentError, "dew_point must be a finite number (got #{dew_point.inspect})"
+      end
+      return if valid_humidity?(humidity)
+
+      raise ArgumentError, "humidity must be a relative humidity between 0 and 100 (got #{humidity.inspect})"
+    end
+
+    # @param temp_c [Float] air temperature in °C
+    # @param humidity [Numeric, nil] relative humidity in %
+    # @param dew_point_c [Numeric, nil] dew point in °C (used when humidity is nil)
+    # @return [Float] effective temperature in °C, unrounded (round only for
+    #   display, so that humidity: REFERENCE_HUMIDITY reads the curve at
+    #   exactly the air temperature)
+    # @raise [ArgumentError] if the dew point is above the air temperature or
+    #   below MIN_DEW_POINT_CELSIUS
+    def effective_temperature(temp_c, humidity: nil, dew_point_c: nil)
+      # The exact solution; bisection would land within an ulp of it, which a
+      # later rounding step can still tip over a boundary
+      return temp_c if humidity == REFERENCE_HUMIDITY
+
+      vapour = humidity ? humidity / 100.0 * saturation_vapour_pressure(temp_c) : dew_point_vapour(dew_point_c, temp_c)
+      temperature_at_reference_humidity(temp_c, vapour)
+    end
+
+    # Saturation vapour pressure in hPa (the Magnus form the Bureau of
+    # Meteorology pairs with its simplified WBGT)
+    def saturation_vapour_pressure(temp_c)
+      6.105 * Math.exp(17.27 * temp_c / (237.7 + temp_c))
+    end
+
+    # The temperature-and-humidity part of the simplified WBGT (the 3.94
+    # constant cancels out when two WBGTs are compared)
+    def wbgt_without_constant(temp_c, vapour_hpa)
+      (WBGT_TEMPERATURE_COEFFICIENT * temp_c) + (WBGT_VAPOUR_PRESSURE_COEFFICIENT * vapour_hpa)
+    end
+
+    # Solves WBGT(x, REFERENCE_HUMIDITY) = WBGT(temp_c, vapour) for x. The left
+    # side rises strictly with x, so bisection converges.
+    def temperature_at_reference_humidity(temp_c, vapour_hpa)
+      target = wbgt_without_constant(temp_c, vapour_hpa)
+      low = temp_c - BRACKET_CELSIUS
+      high = temp_c + BRACKET_CELSIUS
+      BISECTION_STEPS.times do
+        mid = (low + high) / 2.0
+        reference_wbgt(mid) < target ? low = mid : high = mid
+      end
+      (low + high) / 2.0
+    end
+
+    def reference_wbgt(temp_c)
+      wbgt_without_constant(temp_c, REFERENCE_HUMIDITY / 100.0 * saturation_vapour_pressure(temp_c))
+    end
+
+    def dew_point_vapour(dew_point_c, temp_c)
+      if dew_point_c < MIN_DEW_POINT_CELSIUS
+        raise ArgumentError, "dew_point (#{dew_point_c} °C) is below #{MIN_DEW_POINT_CELSIUS} °C"
+      end
+      if dew_point_c > temp_c
+        raise ArgumentError, "dew_point (#{dew_point_c} °C) cannot be above the temperature (#{temp_c} °C)"
+      end
+
+      saturation_vapour_pressure(dew_point_c)
+    end
+
+    def valid_dew_point?(dew_point)
+      dew_point.nil? || finite_number?(dew_point)
+    end
+
+    def valid_humidity?(humidity)
+      humidity.nil? || (finite_number?(humidity) && humidity.to_f.between?(0.0, 100.0))
+    end
+
+    # Real numbers only: Complex is Numeric too, and has no order to compare
+    def finite_number?(value)
+      value.is_a?(Numeric) && value.real? && value.to_f.finite?
+    end
+  end
+end

data/lib/calcpace/personalized_predictor.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+# Module for race predictions built from the runner's own data rather than from
+# a population-wide constant
+#
+# Two models live here:
+#
+# - Tanda (2011): marathon time from the volume and pace of the last weeks of
+#   training — no race result needed.
+# - A personal Riegel exponent fitted to two of the runner's own performances,
+#   used instead of the fixed 1.06 of RacePredictor#predict_time.
+module PersonalizedPredictor
+  # Tanda (2011) regression coefficients for marathon pace in seconds per km:
+  #
+  #   Pm = 17.1 + 140.0 · exp(−0.0053 · K) + 0.55 · P
+  #
+  # K = mean weekly distance (km/week), P = mean training pace (s/km), both
+  # averaged over the 8 weeks ending one week before the race.
+  #
+  # @see https://doi.org/10.4100/jhse.2011.63.05 G. Tanda, "Prediction of
+  #   marathon performance time on the basis of training indices", Journal of
+  #   Human Sport and Exercise 6(3):511–520, 2011
+  TANDA_INTERCEPT = 17.1
+  TANDA_VOLUME_AMPLITUDE = 140.0
+  TANDA_VOLUME_DECAY = 0.0053
+  TANDA_PACE_SLOPE = 0.55
+
+  # Ranges spanned by the paper's sample (Table 2: 22 runners, 21 of them men,
+  # 46 marathons). The equation was fitted inside them; outside, it is an
+  # extrapolation. The author names the finish-time range as the validity range.
+  TANDA_WEEKLY_DISTANCE_RANGE_KM = (40.4..110.7)
+  TANDA_TRAINING_PACE_RANGE_SECONDS_PER_KM = (253.3..330.6)
+  TANDA_MARATHON_TIME_RANGE_SECONDS = ((167 * 60.0)..(216 * 60.0))
+
+  TANDA_MARATHON_KM = 42.195
+
+  # Personal Riegel exponents outside this range almost never describe fitness:
+  # below 1.01 the longer race was run at practically the shorter one's pace,
+  # above 1.20 the runner slows down more than even an untrained endurance
+  # profile would — in both cases one of the two races was most likely not an
+  # all-out effort (or not on a comparable course or day).
+  PERSONAL_EXPONENT_RANGE = (1.01..1.20)
+
+  # Predicts marathon time from training volume and pace — Tanda (2011)
+  #
+  # Uses Pm = 17.1 + 140.0 · exp(−0.0053 · K) + 0.55 · P, where Pm is marathon
+  # pace (s/km), K the mean weekly distance (km/week) and P the mean training
+  # pace (s/km) over the 8 weeks ending one week before the race. Training pace
+  # is the plain average of every run, warm-ups and recoveries included (total
+  # time ÷ total distance), not the pace of the quality sessions. The paper
+  # reports a standard error of about 4 minutes on the finish time.
+  #
+  # Inputs or a predicted time outside the paper's sample do not raise — the
+  # prediction is still returned, flagged in :out_of_range.
+  #
+  # @param weekly_distance [Numeric, String] mean weekly training distance, in
+  #   unit per week — a number or a numeric string ('60')
+  # @param training_pace [Numeric, String] mean training pace per unit, in
+  #   seconds or as a clock string ('05:30')
+  # @param unit [Symbol, String] :km (default) or :mi — applies to both inputs
+  #   and to the returned pace
+  # @return [Hash] :time (seconds), :time_clock (HH:MM:SS), :pace (seconds per
+  #   unit), :pace_clock, :within_validated_range (Boolean) and :out_of_range
+  #   (Array of :weekly_distance, :training_pace and/or :marathon_time)
+  # @raise [Calcpace::NonPositiveInputError] if an input is not a positive,
+  #   finite number (or numeric string, for weekly_distance)
+  # @raise [Calcpace::InvalidTimeFormatError] if training_pace is neither a
+  #   number nor an HH:MM:SS / MM:SS string
+  # @raise [Calcpace::UnsupportedUnitError] if unit is not :km or :mi
+  #
+  # @example
+  #   calc.predict_marathon_from_training(weekly_distance: 60, training_pace: '05:00')[:time_clock] # => "03:19:41"
+  #   calc.predict_marathon_from_training(weekly_distance: 60, training_pace: '05:00')[:pace] # => 283.96
+  #   calc.predict_marathon_from_training(weekly_distance: 40, training_pace: '05:30')[:out_of_range]
+  #   # => [:weekly_distance, :marathon_time]
+  def predict_marathon_from_training(weekly_distance:, training_pace:, unit: :km)
+    weekly = personal_number(weekly_distance)
+    check_positive(weekly, 'Weekly distance')
+    pace_seconds = personal_time_seconds(training_pace)
+    check_positive(pace_seconds, 'Training pace')
+
+    km_per_unit = normalize_distance_km(1, unit)
+    weekly_km = weekly * km_per_unit
+    pace_km = pace_seconds / km_per_unit
+
+    marathon_pace_km = tanda_marathon_pace(weekly_km, pace_km)
+    tanda_result(marathon_pace_km, km_per_unit, tanda_out_of_range(weekly_km, pace_km, marathon_pace_km))
+  end
+
+  # Fits a personal Riegel exponent to two performances
+  #
+  # k = ln(t2 / t1) / ln(d2 / d1). The fixed 1.06 of RacePredictor is a
+  # population average; a runner's own k says how much they slow down as the
+  # distance grows. A value far from 1.06 — below about 1.01 or above about
+  # 1.20 — usually means one of the two races was not an all-out effort, or
+  # was run on a course or day that is not comparable.
+  #
+  # @param race1 [Numeric, String, Symbol] distance in km or race name
+  # @param time1 [String, Numeric] time at race1 (HH:MM:SS or seconds)
+  # @param race2 [Numeric, String, Symbol] distance in km or race name
+  # @param time2 [String, Numeric] time at race2 (HH:MM:SS or seconds)
+  # @return [Float] the exponent (order of the two performances does not matter)
+  # @raise [ArgumentError] if both races are the same distance or a race name is unknown
+  # @raise [Calcpace::NonPositiveInputError] if a distance or time is not positive
+  #
+  # @example
+  #   calc.riegel_exponent('10k', '00:45:00', 'half_marathon', '01:42:00') # => 1.0961
+  def riegel_exponent(race1, time1, race2, time2)
+    distance1, seconds1 = personal_performance(race1, time1)
+    distance2, seconds2 = personal_performance(race2, time2)
+    ensure_different_distances!(distance1, distance2)
+
+    Math.log(seconds2 / seconds1) / Math.log(distance2 / distance1)
+  end
+
+  # Predicts a race time with a personal Riegel exponent
+  #
+  # Fits k to the two performances (see #riegel_exponent), then:
+  #
+  # - Target between the two races: interpolates along the Riegel curve that
+  #   passes through both performances, with the raw k and no clamping — the
+  #   runner's own data already brackets the answer, and it is the same
+  #   whichever performance it is scaled from or in which order they are given.
+  # - Target outside the pair: extrapolates from the performance closer to it
+  #   in log-distance (the shorter extrapolation), with k clamped to
+  #   PERSONAL_EXPONENT_RANGE.
+  #
+  # @param race1 [Numeric, String, Symbol] distance in km or race name
+  # @param time1 [String, Numeric] time at race1 (HH:MM:SS or seconds)
+  # @param race2 [Numeric, String, Symbol] distance in km or race name
+  # @param time2 [String, Numeric] time at race2 (HH:MM:SS or seconds)
+  # @param to_race [Numeric, String, Symbol] target distance in km or race name
+  # @return [Hash] :time (seconds), :time_clock (HH:MM:SS), :exponent (the one
+  #   used, after any clamping), :raw_exponent (as fitted), :clamped (Boolean,
+  #   always false when the target lies between the two races)
+  # @raise [ArgumentError] if the two races are the same distance, the target
+  #   is one of them, or a race name is unknown
+  # @raise [Calcpace::NonPositiveInputError] if a distance or time is not positive
+  # @raise [Calcpace::InvalidTimeFormatError] if a time is neither a number nor
+  #   an HH:MM:SS / MM:SS string
+  #
+  # @example
+  #   calc.predict_time_personal(5, 1200, 20, 3000, 10)[:time] # => 1897.37
+  #   calc.predict_time_personal('10k', '00:45:00', 'half_marathon', '01:42:00', 'marathon')[:time_clock]
+  #   # => "03:38:03"
+  #   calc.predict_time_personal('10k', '00:45:00', 'half_marathon', '01:42:00', 'marathon')[:clamped] # => false
+  def predict_time_personal(race1, time1, race2, time2, to_race)
+    raw = riegel_exponent(race1, time1, race2, time2)
+    target = race_distance(to_race)
+    performances = [personal_performance(race1, time1), personal_performance(race2, time2)].sort
+    performances.map(&:first).each { |distance| ensure_different_distances!(distance, target) }
+    (anchor_distance, anchor_seconds), exponent = personal_prediction_basis(performances, target, raw)
+
+    time = (anchor_seconds * ((target / anchor_distance)**exponent)).round(2)
+    { time: time, time_clock: convert_to_clocktime(time), exponent: exponent.round(4),
+      raw_exponent: raw.round(4), clamped: exponent != raw }
+  end
+
+  private
+
+  def tanda_marathon_pace(weekly_km, pace_km)
+    TANDA_INTERCEPT + (TANDA_VOLUME_AMPLITUDE * Math.exp(-TANDA_VOLUME_DECAY * weekly_km)) +
+      (TANDA_PACE_SLOPE * pace_km)
+  end
+
+  def tanda_out_of_range(weekly_km, pace_km, marathon_pace_km)
+    checks = {
+      weekly_distance: TANDA_WEEKLY_DISTANCE_RANGE_KM.cover?(weekly_km),
+      training_pace: TANDA_TRAINING_PACE_RANGE_SECONDS_PER_KM.cover?(pace_km),
+      marathon_time: TANDA_MARATHON_TIME_RANGE_SECONDS.cover?(marathon_pace_km * TANDA_MARATHON_KM)
+    }
+    checks.reject { |_name, inside| inside }.keys
+  end
+
+  def tanda_result(marathon_pace_km, km_per_unit, out_of_range)
+    time = (marathon_pace_km * TANDA_MARATHON_KM).round(2)
+    pace = (marathon_pace_km * km_per_unit).round(2)
+
+    {
+      time: time,
+      time_clock: convert_to_clocktime(time),
+      pace: pace,
+      pace_clock: convert_to_clocktime(pace),
+      within_validated_range: out_of_range.empty?,
+      out_of_range: out_of_range
+    }
+  end
+
+  # A performance as [distance in km, time in seconds], validated
+  def personal_performance(race, time)
+    seconds = personal_time_seconds(time)
+    check_positive(seconds, 'Time')
+    [race_distance(race), seconds.to_f]
+  end
+
+  # Seconds from a number, or from a strictly validated clock string — the same
+  # rule as Calculator, AgeGrading and Vo2maxEstimator
+  def personal_time_seconds(time)
+    return time if time.is_a?(Numeric)
+
+    check_time(time)
+    convert_to_seconds(time)
+  end
+
+  # A number, or a numeric string read the way race distances are; nil otherwise
+  def personal_number(value)
+    value.is_a?(Numeric) ? value : Float(value, exception: false)
+  end
+
+  # [anchor performance, exponent] for a target, given performances sorted by
+  # distance. Between the two, the raw curve through both; outside, the closer
+  # performance with the clamped exponent
+  def personal_prediction_basis(performances, target, raw)
+    shorter, longer = performances
+    return [shorter, raw] if target.between?(shorter.first, longer.first)
+
+    closer = performances.min_by { |distance, _seconds| Math.log(target / distance).abs }
+    [closer, raw.clamp(PERSONAL_EXPONENT_RANGE.min, PERSONAL_EXPONENT_RANGE.max)]
+  end
+end

data/lib/calcpace/race_predictor.rb

@@ -128,15 +128,20 @@ module RacePredictor
   # @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:
+  # @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
   #
   # @example Predict marathon time from 5K adjusted for heat (25C)
   #   predict_time_adjusted('5k', '00:20:00', 'marathon', temperature: 25)
-  #   #=> { adjusted_time: 13140.19, penalty_percent: 14.17, ... }
+  #   #=> { adjusted_time: 12483.01, penalty_percent: 8.46, ... }
+  #   calc.predict_time_adjusted('5k', '00:20:00', 'marathon', temperature: 25)[:penalty_percent] #=> 8.46
+  #   calc.predict_time_adjusted('5k', '00:20:00', '10k', temperature: 25, humidity: 80)[:penalty_percent] #=> 4.87
   def predict_time_adjusted(from_race, from_time, to_race, **)
     predicted_seconds = predict_time(from_race, from_time, to_race)
     adjust_time(predicted_seconds, **)

data/lib/calcpace/race_splits.rb

@@ -22,7 +22,7 @@ module RaceSplits
   #
   # @example Negative splits (second half faster)
   #   race_splits('10k', target_time: '00:40:00', split_distance: '5k', strategy: :negative)
-  #   #=> ["00:20:48", "00:40:00"] (first 5k slower, second 5k faster)
+  #   #=> ["00:20:12", "00:40:00"] (first 5k 1% slower, second 5k 1% faster)
   def race_splits(race, target_time:, split_distance:, strategy: :even)
     total_distance = race_distance(race)
     target_seconds = target_time.is_a?(String) ? convert_to_seconds(target_time) : target_time
@@ -133,25 +133,27 @@ module RaceSplits
   end
 
   # Calculates negative splits (second half faster than first half)
-  # First half is ~4% slower, second half is ~4% faster
+  # First half is run at a pace 1% slower than average, second half 1% faster
+  # (e.g. a 3:00:00 marathon goes through halfway in 1:30:54, then 1:29:06)
   #
   # @param total_distance [Float] total race distance in kilometers
   # @param target_seconds [Float] target finish time in seconds
   # @param split_km [Float] split distance in kilometers
   # @return [Array<String>] array of cumulative split times
   def calculate_negative_splits(total_distance, target_seconds, split_km)
-    calculate_variable_splits(total_distance, target_seconds, split_km, first_factor: 1.04, second_factor: 0.96)
+    calculate_variable_splits(total_distance, target_seconds, split_km, first_factor: 1.01, second_factor: 0.99)
   end
 
   # Calculates positive splits (first half faster than second half)
-  # First half is ~4% faster, second half is ~4% slower
+  # First half is run at a pace 1% faster than average, second half 1% slower
+  # (e.g. a 3:00:00 marathon goes through halfway in 1:29:06, then 1:30:54)
   #
   # @param total_distance [Float] total race distance in kilometers
   # @param target_seconds [Float] target finish time in seconds
   # @param split_km [Float] split distance in kilometers
   # @return [Array<String>] array of cumulative split times
   def calculate_positive_splits(total_distance, target_seconds, split_km)
-    calculate_variable_splits(total_distance, target_seconds, split_km, first_factor: 0.96, second_factor: 1.04)
+    calculate_variable_splits(total_distance, target_seconds, split_km, first_factor: 0.99, second_factor: 1.01)
   end
 
   # Shared logic for variable pace split strategies