calcpace 1.18.1 → 2.1.0

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.1'
+  VERSION = '2.1.0'
 end

data/lib/calcpace/vo2max_effort.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# How hard the runner says an effort was, for Vo2maxEstimator#estimate_detailed_vo2max
+#
+# Daniels & Gilbert assume an all-out effort, and the estimator can only guess
+# that from duration and heart rate. A declared effort answers it directly. It
+# never changes the VO2max value — only its confidence, sub_maximal and basis.
+module Vo2maxEffort
+  # From easiest. :easy and :moderate are training (talk test: a full
+  # conversation / short sentences), :hard is a few words at a time, :max is
+  # everything the runner had — a race or a test.
+  EFFORT_LEVELS = %i[easy moderate hard max].freeze
+
+  private
+
+  def normalize_effort(effort)
+    return if effort.nil?
+
+    level = effort.to_s.downcase.to_sym
+    return level if EFFORT_LEVELS.include?(level)
+
+    raise Calcpace::InvalidEffortError,
+          "Invalid effort: #{effort.inspect}. Valid efforts: #{EFFORT_LEVELS.map(&:inspect).join(', ')}"
+  end
+
+  # A declared easy or moderate effort wins over everything: the runner knows
+  # they held back, whatever the watch says. Heart rate wins over a declared
+  # max, as it did over the duration rule. A max shorter than five minutes stays
+  # with the duration rule: there the formula itself is unreliable.
+  #
+  # duration_confidence is the estimator's verdict from duration alone.
+  def effort_verdict(effort, time_min, duration_confidence:, hr_sub_maximal:)
+    if %i[easy moderate].include?(effort)
+      { confidence: :low, sub_maximal: true, basis: :declared }
+    elsif hr_sub_maximal
+      { confidence: :low, sub_maximal: true, basis: :heart_rate }
+    elsif effort == :max && time_min >= 5
+      { confidence: :high, sub_maximal: false, basis: :declared }
+    else
+      { confidence: duration_confidence, sub_maximal: false, basis: :duration }
+    end
+  end
+end

data/lib/calcpace/vo2max_estimator.rb

@@ -14,6 +14,8 @@
 # Accuracy: ±3–5 ml/kg/min vs laboratory testing. Best results with efforts
 # between 5 and 60 minutes at race pace (i.e. near-maximal effort).
 module Vo2maxEstimator
+  include Vo2maxEffort
+
   # Classification thresholds based on:
   # Daniels, J. (2014). Daniels' Running Formula (3rd ed.). Human Kinetics.
   # General ranges are consistent with ACSM guidelines and widely cited in
@@ -28,7 +30,11 @@ module Vo2maxEstimator
   ].freeze
 
   # Represents a contextualized VO2max estimation result
-  Vo2maxResult = Struct.new(:value, :confidence, :sub_maximal, :adjusted_distance_km)
+  #
+  # basis names what set confidence and sub_maximal: :declared (the effort
+  # given), :heart_rate (average HR under 85 % of max) or :duration (the
+  # Daniels & Gilbert window alone)
+  Vo2maxResult = Struct.new(:value, :confidence, :sub_maximal, :adjusted_distance_km, :basis)
 
   # Estimates VO2max from a race performance using Daniels & Gilbert formula
   #
@@ -59,8 +65,19 @@ module Vo2maxEstimator
     (vo2 / pct_vo2max).round(1)
   end
 
+  # The public signature: every input is a keyword a caller already passes, and
+  # bundling them into an options object would break the 2.x API.
+  # rubocop:disable Metrics/ParameterLists
+
   # Estimates a detailed and contextualized VO2max
   #
+  # Elevation is folded in with a flat heuristic — every 100 m of gain adds
+  # 600 m of equivalent flat distance — that ignores where the climbing is and
+  # gives nothing back for descents. It is kept as is so results stay
+  # comparable across versions. For a profile-aware view of a GPS track, see
+  # GradeAdjustedPace#grade_adjusted_pace and
+  # TrackCalculator#track_grade_adjusted_splits (Minetti et al., 2002).
+  #
   # @param distance [Numeric] race distance, in kilometres by default or in
   #   the unit given by distance_unit
   # @param time [String, Integer] finish time
@@ -68,11 +85,25 @@ module Vo2maxEstimator
   # @param hr_avg [Numeric] average heart rate during the effort
   # @param hr_max [Numeric] athlete's maximum heart rate
   # @param distance_unit [Symbol] unit of the distance input — :km (default) or :mi
+  # @param effort [Symbol, String, nil] how hard the runner says it was, one of
+  #   Vo2maxEffort::EFFORT_LEVELS. It never changes the value, only how far it can be
+  #   trusted: :easy and :moderate make it sub-maximal and low confidence
+  #   whatever the duration or heart rate; :max makes it high confidence from
+  #   five minutes on, however long it took, unless heart rate says
+  #   sub-maximal; :hard and nil leave the duration and heart-rate rules as
+  #   they are.
   # @return [Vo2maxResult] structured result with value and metadata
   #   (adjusted_distance_km is always in kilometres)
   # @raise [Calcpace::NonPositiveInputError] if distance or time are not positive
   # @raise [Calcpace::UnsupportedUnitError] if distance_unit is not :km or :mi
-  def estimate_detailed_vo2max(distance, time, elevation_gain_m: 0, hr_avg: nil, hr_max: nil, distance_unit: :km)
+  # @raise [Calcpace::InvalidEffortError] if effort is not one of Vo2maxEffort::EFFORT_LEVELS
+  #
+  # @example a marathon run all-out
+  #   calc.estimate_detailed_vo2max(42.195, '03:30:00').confidence               #=> :low
+  #   calc.estimate_detailed_vo2max(42.195, '03:30:00', effort: :max).confidence #=> :high
+  def estimate_detailed_vo2max(distance, time, elevation_gain_m: 0, hr_avg: nil, hr_max: nil, distance_unit: :km,
+                               effort: nil)
+    effort = normalize_effort(effort)
     distance_km = normalize_distance_km(distance, distance_unit)
     # Validated before the elevation adjustment, which would otherwise turn a
     # negative distance into a positive equivalent-flat one
@@ -80,31 +111,45 @@ module Vo2maxEstimator
 
     adj_dist_km = adjusted_distance_for_vo2(distance_km, elevation_gain_m)
     vo2max_val  = estimate_vo2max(adj_dist_km, time)
-    confidence  = calculate_time_confidence(parse_time_minutes(time))
-
-    hr_data = validate_and_analyze_hr(hr_avg, hr_max)
-    confidence = :low if hr_data[:sub_maximal]
+    time_min    = parse_time_minutes(time)
+    hr_data     = validate_and_analyze_hr(hr_avg, hr_max)
+    verdict     = effort_verdict(effort, time_min, duration_confidence: calculate_time_confidence(time_min),
+                                                   hr_sub_maximal: hr_data[:sub_maximal])
 
-    Vo2maxResult.new(
-      value: vo2max_val,
-      confidence: confidence,
-      sub_maximal: hr_data[:sub_maximal],
-      adjusted_distance_km: adj_dist_km.round(2)
-    )
+    Vo2maxResult.new(value: vo2max_val, adjusted_distance_km: adj_dist_km.round(2), **verdict)
   end
+  # rubocop:enable Metrics/ParameterLists
 
   # Returns a descriptive label for a given VO2max value
   #
+  # Without age and sex, the label comes from fixed thresholds that are the same
+  # for everyone (see VO2MAX_LABELS) — exactly as it always has. With both, it
+  # comes from where the value sits among people of the same sex and age
+  # decade, measured on a treadmill in the FRIEND registry (see
+  # Vo2maxNorms#vo2max_percentile and Vo2maxNorms::VO2MAX_PERCENTILE_LABELS):
+  # the same 45 ml/kg/min is "Fair" for a 25-year-old man and "Elite" for a
+  # 60-year-old woman.
+  #
   # @param value [Numeric] VO2max in ml/kg/min
+  # @param age [Integer, nil] age in years (18 or over, a fractional age is
+  #   truncated); give it with sex
+  # @param sex [String, Symbol, nil] male or female; give it with age
   # @return [String] label: "Beginner", "Fair", "Good", "Very Good", "Excellent", or "Elite"
-  # @raise [ArgumentError] if value is not positive
+  # @raise [Calcpace::NonPositiveInputError] if value is not positive
+  # @raise [ArgumentError] if only one of age and sex is given, or either is invalid
   #
   # @example
-  #   calc.vo2max_label(51.9) #=> "Very Good"
-  def vo2max_label(value)
+  #   calc.vo2max_label(51.9)                     #=> "Very Good"
+  #   calc.vo2max_label(45)                       #=> "Good"
+  #   calc.vo2max_label(45, age: 25, sex: :male)  #=> "Fair"
+  #   calc.vo2max_label(45, age: 60, sex: :female) #=> "Elite"
+  def vo2max_label(value, age: nil, sex: nil)
     check_positive(value.to_f, 'VO2max value')
+    return VO2MAX_LABELS.find { |entry| value.to_f >= entry[:min] }[:label] if age.nil? && sex.nil?
+    raise ArgumentError, 'Age and sex must be provided together' if age.nil? || sex.nil?
 
-    VO2MAX_LABELS.find { |entry| value.to_f >= entry[:min] }[:label]
+    percentile = raw_vo2max_percentile(value.to_f, age, sex)
+    Vo2maxNorms::VO2MAX_PERCENTILE_LABELS.find { |entry| percentile >= entry[:min] }[:label]
   end
 
   private