calcpace 1.18.0 → 2.0.0

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

data/lib/calcpace/track_calculator.rb

@@ -27,6 +27,19 @@ module TrackCalculator
   # Mean radius of the Earth in kilometers (IAU standard)
   EARTH_RADIUS_KM = 6371.0
 
+  # Shortest horizontal distance a grade is measured over in
+  # #track_grade_adjusted_splits. GPS elevation is noisy — a few metres between
+  # consecutive fixes even from a barometric altimeter — so a grade read
+  # between points 1 m apart can be ±300% on flat ground, and the grade factor's
+  # curvature turns that symmetric noise into a fake climb. Over 100 m, ±1–2 m
+  # of noise is ±1–2% of grade, while a hill longer than a track straight still
+  # shows up.
+  GRADE_SEGMENT_MIN_KM = 0.1
+
+  # Slack on GRADE_SEGMENT_MIN_KM so ten 10 m steps, which sum to a hair under
+  # 0.1 km in floating point, still close a 100 m grade segment (1 mm)
+  GRADE_SEGMENT_TOLERANCE_KM = 1e-6
+
   # Computes the great-circle distance between two GPS coordinates using
   # the Haversine formula.
   #
@@ -156,6 +169,49 @@ module TrackCalculator
     collect_splits(points, split_km, compact: compact)
   end
 
+  # Pace splits with a grade-adjusted pace (GAP) for each split.
+  #
+  # Each split is the hash #track_splits returns — same :km, :elapsed and :pace,
+  # split boundaries computed the same way — plus :gap, the flat-ground pace of
+  # equal effort for that split (Minetti et al., 2002; see GradeAdjustedPace).
+  # #track_splits itself is unchanged.
+  #
+  # How :gap is computed:
+  # - The track is cut into grade segments of at least GRADE_SEGMENT_MIN_KM
+  #   (100 m) of horizontal distance, and each gets one grade: its net
+  #   elevation change over its length. A leftover shorter than that at the end
+  #   of a stretch is merged into the segment before it. Grades are clamped to
+  #   ±45%, the range the model was measured on.
+  # - A stretch between points without :ele (or with a NaN/infinite one) is
+  #   flat (factor 1.0), and a missing :ele ends the grade segment in progress.
+  #   A stretch with elevation shorter than one grade segment and with no full
+  #   segment before it to join — or a whole track that short — is flat too.
+  # - Distances are the horizontal (Haversine) ones; the factor is applied to
+  #   them as is, without the √(1 + grade²) slope correction (0.5% at 10%).
+  # - Each split's distance is weighted by the grade factor of the segments it
+  #   covers, and :gap is the split's time over that flat-equivalent distance.
+  #   A split on flat ground, or with no elevation data, has :gap equal to :pace.
+  #
+  # @param points [Array<Hash>] points with :lat, :lon and :time keys, and
+  #   optionally :ele (metres), as for #track_splits
+  # @param split_km [Numeric] split interval in kilometers (default: 1.0)
+  # @param compact [Boolean] when true, :pace and :gap use the compact display format
+  # @return [Array<Hash>] split hashes with :km, :elapsed, :pace and :gap
+  #   (:gap formatted like :pace)
+  # @raise [ArgumentError] if split_km is not positive
+  # @raise [ArgumentError] if any point is missing a :time key
+  #
+  # @example a steady 5% climb at 5:00/km
+  #   calc.track_grade_adjusted_splits(points, 1.0)
+  #   #=> [{ km: 1.0, elapsed: 300, pace: "05:00", gap: "03:51" }, ...]
+  def track_grade_adjusted_splits(points, split_km = 1.0, compact: false)
+    raise ArgumentError, 'split_km must be positive' unless split_km.is_a?(Numeric) && split_km.positive?
+    return [] if points.nil? || points.size < 2
+
+    validate_points_have_time(points)
+    collect_splits(points, split_km, compact: compact, grade_factors: segment_grade_factors(points))
+  end
+
   private
 
   def haversine_km(lat1, lon1, lat2, lon2)
@@ -253,41 +309,56 @@ module TrackCalculator
     format('%<min>02d:%<sec>02d', min: pace_seconds / 60, sec: pace_seconds % 60)
   end
 
-  def collect_splits(points, split_km, compact:)
+  # grade_factors, when given, holds one grade factor per segment (see
+  # #segment_grade_factors) and turns on the :gap field; without it the splits
+  # are exactly the ones #track_splits has always returned.
+  def collect_splits(points, split_km, compact:, grade_factors: nil)
     state = { splits: [], start_time: point_time(points.first),
               split_start_time: point_time(points.first),
-              accumulated_km: 0.0, split_number: 1, compact: compact }
+              accumulated_km: 0.0, split_number: 1, compact: compact,
+              grade_factors: grade_factors, flat_equivalent_km: 0.0 }
 
-    points.each_cons(2) { |a, b| process_segment(a, b, split_km, state) }
+    if grade_factors
+      points.each_cons(2).with_index { |(a, b), index| process_segment(a, b, split_km, state, index) }
+    else
+      points.each_cons(2) { |a, b| process_segment(a, b, split_km, state) }
+    end
     append_partial_split(points.last, split_km, state)
     state[:splits]
   end
 
-  def process_segment(point_a, point_b, split_km, state)
-    segment_km = haversine_distance(dig_key(point_a, :lat), dig_key(point_a, :lon),
-                                    dig_key(point_b, :lat), dig_key(point_b, :lon))
+  # index is only given, and the segment only tracked, when computing :gap —
+  # track_splits keeps its original per-segment cost
+  def process_segment(point_a, point_b, split_km, state, index = nil)
+    segment_km = segment_distance_km(point_a, point_b)
     state[:accumulated_km] += segment_km
+    state[:segment] = { assigned_km: 0.0, factor: state[:grade_factors].fetch(index) } if index
 
     while state[:accumulated_km] >= split_km * state[:split_number]
       record_split(point_a, point_b, segment_km, split_km, state)
     end
+
+    accumulate_flat_equivalent(state, segment_km)
   end
 
   def record_split(point_a, point_b, segment_km, split_km, state)
     offset = (split_km * state[:split_number]) - (state[:accumulated_km] - segment_km)
+    accumulate_flat_equivalent(state, offset)
     boundary_time = interpolate_time(point_a, point_b, segment_km, offset)
     state[:splits] << build_split_entry(boundary_time, split_km, state)
     state[:split_start_time] = boundary_time
     state[:split_number] += 1
+    state[:flat_equivalent_km] = 0.0
   end
 
   def build_split_entry(boundary_time, split_km, state)
     split_elapsed = (boundary_time - state[:split_start_time]).round
-    {
+    entry = {
       km: (split_km * state[:split_number]).round(2),
       elapsed: (boundary_time - state[:start_time]).round,
       pace: seconds_to_pace(split_elapsed, split_km, compact: state[:compact])
     }
+    with_gap(entry, split_elapsed, state)
   end
 
   def append_partial_split(last_point, split_km, state)
@@ -295,11 +366,113 @@ module TrackCalculator
     return unless remaining_km > 0.001
 
     last_time = point_time(last_point)
-    state[:splits] << {
+    split_elapsed = (last_time - state[:split_start_time]).round
+    entry = {
       km: state[:accumulated_km].round(2),
       elapsed: (last_time - state[:start_time]).round,
-      pace: seconds_to_pace((last_time - state[:split_start_time]).round, remaining_km,
-                            compact: state[:compact])
+      pace: seconds_to_pace(split_elapsed, remaining_km, compact: state[:compact])
     }
+    state[:splits] << with_gap(entry, split_elapsed, state)
+  end
+
+  def segment_distance_km(point_a, point_b)
+    haversine_distance(dig_key(point_a, :lat), dig_key(point_a, :lon),
+                       dig_key(point_b, :lat), dig_key(point_b, :lon))
+  end
+
+  # Adds the flat-equivalent distance of the current segment up to
+  # distance_into_segment, for the part not yet credited to an earlier split
+  def accumulate_flat_equivalent(state, distance_into_segment)
+    return unless state[:grade_factors]
+
+    segment = state[:segment]
+
+    state[:flat_equivalent_km] += (distance_into_segment - segment[:assigned_km]) * segment[:factor]
+    segment[:assigned_km] = distance_into_segment
+  end
+
+  def with_gap(entry, split_elapsed, state)
+    return entry unless state[:grade_factors]
+
+    entry.merge(gap: seconds_to_pace(split_elapsed, state[:flat_equivalent_km], compact: state[:compact]))
+  end
+
+  # One grade factor per segment (consecutive point pair). Segments are grouped
+  # into grade segments of at least GRADE_SEGMENT_MIN_KM, each with one grade
+  # (net elevation change over horizontal distance); see
+  # #track_grade_adjusted_splits for the rules.
+  def segment_grade_factors(points)
+    factors = Array.new(points.size - 1, 1.0)
+    window = new_grade_window
+
+    points.each_cons(2).with_index do |(a, b), index|
+      window = extend_grade_window(window, factors, a, b, index)
+    end
+    close_grade_window(window, factors, final: true)
+    factors
+  end
+
+  def new_grade_window(previous = nil)
+    { indexes: [], km: 0.0, start_ele: nil, end_ele: nil, previous: previous }
+  end
+
+  def extend_grade_window(window, factors, point_a, point_b, index)
+    ele_a = finite_ele(point_a)
+    ele_b = finite_ele(point_b)
+    if ele_a.nil? || ele_b.nil?
+      close_grade_window(window, factors, final: true)
+      return new_grade_window
+    end
+
+    add_to_grade_window(window, index, segment_distance_km(point_a, point_b), ele_a, ele_b)
+    return window unless full_grade_window?(window)
+
+    close_grade_window(window, factors, final: false)
+    new_grade_window(window.except(:previous))
+  end
+
+  # Grade segments treat a NaN or infinite elevation like a missing one
+  def finite_ele(point)
+    ele = fetch_ele(point)
+    ele if ele&.finite?
+  end
+
+  def add_to_grade_window(window, index, segment_km, ele_a, ele_b)
+    window[:start_ele] ||= ele_a
+    window[:end_ele] = ele_b
+    window[:indexes] << index
+    window[:km] += segment_km
+  end
+
+  # A full window gets its own grade. A short leftover — the end of the track
+  # or of a stretch with elevation — is merged into the full window before it;
+  # with no full window before it (a stretch shorter than a grade segment
+  # between missing elevations, or a whole track that short) it stays flat
+  # rather than being graded over a few noisy metres.
+  def close_grade_window(window, factors, final:)
+    return if window[:indexes].empty?
+
+    unless full_grade_window?(window)
+      return unless final && window[:previous]
+
+      window = merge_grade_windows(window[:previous], window)
+    end
+    factor = grade_adjustment_factor(window_grade(window))
+    window[:indexes].each { |index| factors[index] = factor }
+  end
+
+  def full_grade_window?(window)
+    window[:km] >= GRADE_SEGMENT_MIN_KM - GRADE_SEGMENT_TOLERANCE_KM
+  end
+
+  def merge_grade_windows(previous, window)
+    { indexes: previous[:indexes] + window[:indexes], km: previous[:km] + window[:km],
+      start_ele: previous[:start_ele], end_ele: window[:end_ele] }
+  end
+
+  def window_grade(window)
+    return 0.0 unless window[:km].positive?
+
+    (window[:end_ele] - window[:start_ele]) / (window[:km] * 1000.0)
   end
 end

data/lib/calcpace/training_zones.rb

@@ -9,8 +9,15 @@
 #
 # Heart rate zones use the Karvonen method (Heart Rate Reserve):
 #   target = hr_rest + pct * (hr_max - hr_rest)
+#
+# Not standalone: it is a part of Calcpace and calls into its siblings —
+# Vo2maxEstimator (estimate_vo2max, vo2_at_velocity), FitnessPredictor
+# (predict_time_from_vo2max, for the marathon band), PaceCalculator
+# (race_distance), Converter and Checker.
 module TrainingZones
-  # Training intensities as fraction of VO2max (Daniels' Running Formula)
+  # Training intensities as fraction of VO2max (Daniels' Running Formula).
+  # The marathon :high (0.84) is the nominal upper bound only: the band's fast
+  # end is the predicted race pace (see PREDICTED_RACE_PACE_ZONES).
   TRAINING_INTENSITIES = {
     easy: { low: 0.59, high: 0.74 },
     marathon: { low: 0.75, high: 0.84 },
@@ -19,6 +26,14 @@ module TrainingZones
     repetition: { low: 1.05, high: 1.10 }
   }.freeze
 
+  # Zones whose fast end is the VDOT-predicted race pace instead of
+  # TRAINING_INTENSITIES[zone][:high]. Daniels' M pace is the runner's
+  # predicted marathon race pace (FitnessPredictor#predict_time_from_vo2max),
+  # which is 0.800–0.849 of VO2max across VO2max 10–100 (0.805 at 30, 0.830
+  # at 70). That keeps the marathon band slower than the threshold band
+  # (from 0.83) below VO2max ~69.5.
+  PREDICTED_RACE_PACE_ZONES = %i[marathon].freeze
+
   # A pace band for one training zone (paces per kilometre or mile).
   # slow = lower-intensity end of the band, fast = higher-intensity end.
   PaceBand = Struct.new(:slow_seconds, :fast_seconds, :slow_clock, :fast_clock)
@@ -46,27 +61,27 @@ module TrainingZones
   # @param vo2max [Numeric] VO2max in ml/kg/min (must be > 0)
   # @param unit [Symbol] pace unit — :km (default) or :mi
   # @return [Hash{Symbol => PaceBand}] keys: :easy, :marathon, :threshold,
-  #   :interval, :repetition — paces per chosen unit
+  #   :interval, :repetition — paces per chosen unit. The marathon band runs
+  #   from 75% of VO2max to the VDOT-predicted marathon pace; the prediction
+  #   covers VO2max 10–100, and outside that range the race-pace intensity of
+  #   the nearest bound is used
   # @raise [Calcpace::NonPositiveInputError] if vo2max is not positive
   # @raise [Calcpace::UnsupportedUnitError] if unit is not :km or :mi
   #
   # @example
   #   calc.training_paces(50.0)[:threshold].fast_clock             #=> "00:04:15"
   #   calc.training_paces(50.0, unit: :mi)[:threshold].fast_clock  #=> "00:06:51"
+  #   calc.training_paces(50.0)[:marathon].fast_clock              #=> "00:04:31"
   def training_paces(vo2max, unit: :km)
     check_positive(vo2max.to_f, 'VO2max')
     meters = pace_unit_meters(unit)
 
-    TRAINING_INTENSITIES.transform_values do |band|
+    TRAINING_INTENSITIES.to_h do |zone, band|
       slow = pace_seconds_at_pct(vo2max.to_f, band[:low], meters)
-      fast = pace_seconds_at_pct(vo2max.to_f, band[:high], meters)
-
-      PaceBand.new(
-        slow_seconds: slow,
-        fast_seconds: fast,
-        slow_clock: convert_to_clocktime(slow),
-        fast_clock: convert_to_clocktime(fast)
-      )
+      fast = pace_seconds_at_pct(vo2max.to_f, fast_intensity(zone, band, vo2max.to_f), meters)
+
+      [zone, PaceBand.new(slow_seconds: slow, fast_seconds: fast,
+                          slow_clock: convert_to_clocktime(slow), fast_clock: convert_to_clocktime(fast))]
     end
   end
 
@@ -336,6 +351,22 @@ module TrainingZones
           "Resting heart rate (#{hr_rest}) must be lower than maximum heart rate (#{hr_max})"
   end
 
+  def fast_intensity(zone, band, vo2max)
+    PREDICTED_RACE_PACE_ZONES.include?(zone) ? marathon_race_intensity(vo2max) : band[:high]
+  end
+
+  # Fraction of VO2max a runner holds at the VDOT-predicted marathon pace.
+  # The prediction only covers FitnessPredictor::SUPPORTED_VO2MAX_RANGE, so
+  # beyond it the fraction of the nearest bound is used (it barely moves
+  # there: 0.800 at VO2max 10, 0.849 at 100).
+  def marathon_race_intensity(vo2max)
+    range = FitnessPredictor::SUPPORTED_VO2MAX_RANGE
+    vo2 = vo2max.clamp(range.min, range.max)
+    seconds = predict_time_from_vo2max(vo2, 'marathon')
+
+    vo2_at_velocity(race_distance('marathon') * Converter::Distance::KM_TO_METERS * 60.0 / seconds) / vo2
+  end
+
   # Inverts Daniels & Gilbert: velocity (m/min) that demands a given VO2
   def velocity_at_vo2(vo2)
     a = 0.000104

data/lib/calcpace/version.rb

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