calcpace 1.18.1 → 2.0.0

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

data/lib/calcpace/vo2max_estimator.rb

@@ -61,6 +61,13 @@ module Vo2maxEstimator
 
   # 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
@@ -95,16 +102,34 @@ module Vo2maxEstimator
 
   # 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

data/lib/calcpace/vo2max_norms.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require_relative 'errors'
+require_relative 'checker'
+
+# Module for reading a VO2max against people of the same age and sex
+#
+# Uses the FRIEND registry (Fitness Registry and the Importance of Exercise
+# National Database) percentiles of VO2max measured by cardiopulmonary
+# exercise testing in 7,783 treadmill tests on US adults free of known
+# cardiovascular disease:
+#
+#   Kaminsky, L. A., Arena, R., & Myers, J. (2015). Reference Standards for
+#   Cardiorespiratory Fitness Measured With Cardiopulmonary Exercise Testing:
+#   Data From the Fitness Registry and the Importance of Exercise National
+#   Database. Mayo Clinic Proceedings, 90(11), 1515–1523, Table 3.
+#   https://doi.org/10.1016/j.mayocp.2015.07.026
+#
+# The table is stored, with its provenance, in
+# `lib/calcpace/data/friend_2015_vo2max_percentiles.yml`.
+# Vo2maxEstimator#vo2max_label uses it when given age and sex.
+module Vo2maxNorms
+  # check_positive, normalize_age and normalize_sex: the same rules as AgeGrading
+  include Checker
+
+  # Percentile norms by age and sex: FRIEND registry, measured treadmill VO2max
+  # (Kaminsky, Arena & Myers, Mayo Clin Proc 2015;90(11):1515–1523, Table 3).
+  # See the data file for the full provenance.
+  NORMS_DATA_PATH = File.expand_path('data/friend_2015_vo2max_percentiles.yml', __dir__).freeze
+  norms_data = YAML.safe_load_file(NORMS_DATA_PATH, permitted_classes: [], aliases: false)
+  VO2MAX_NORMS_VERSION = norms_data.fetch('meta').fetch('table_version').freeze
+  VO2MAX_NORM_PERCENTILES = norms_data.fetch('percentiles').map(&:to_f).freeze
+  VO2MAX_NORMS = %w[M F].to_h do |sex|
+    bands = norms_data.fetch(sex).to_h { |age, row| [Integer(age), row.map(&:to_f).freeze] }
+    [sex.freeze, bands.freeze]
+  end.freeze
+
+  VO2MAX_NORMS.each do |sex, bands|
+    bands.each do |age, row|
+      next if row.size == VO2MAX_NORM_PERCENTILES.size && row.each_cons(2).all? { |low, high| high > low }
+
+      raise Calcpace::InvalidDataError,
+            "VO2max norms #{sex} #{age}: expected #{VO2MAX_NORM_PERCENTILES.size} rising values, got #{row.inspect}"
+    end
+  end
+
+  # Percentile cut for each label when vo2max_label is given age and sex. The
+  # cuts sit on percentiles the table publishes, so a label never depends on
+  # interpolation: at or above the 95th percentile is Elite, the 90th
+  # Excellent, the 75th Very Good, the median Good, the 25th Fair, and below
+  # the 25th Beginner. These cuts are calcpace's choice — FRIEND publishes
+  # percentiles, not labels.
+  VO2MAX_PERCENTILE_LABELS = [
+    { min: 95, label: 'Elite' },
+    { min: 90, label: 'Excellent' },
+    { min: 75, label: 'Very Good' },
+    { min: 50, label: 'Good' },
+    { min: 25, label: 'Fair' },
+    { min: 0,  label: 'Beginner' }
+  ].freeze
+
+  # Approximate percentile of a VO2max among people of the same sex and age
+  #
+  # Reads the FRIEND registry percentiles (Kaminsky, Arena & Myers, 2015,
+  # Table 3: 5th, 10th, 25th, 50th, 75th, 90th and 95th, by decade from 20–29 to
+  # 70–79) and interpolates linearly between the two published percentiles
+  # around the value. The registry measured VO2max in a lab; an estimate from a
+  # race time carries its own ±3–5 ml/kg/min on top.
+  #
+  # - Age decades are used as published, without blending across them, so a
+  #   29- and a 30-year-old read different rows. Ages 18–19 use the 20–29 row and
+  #   80 or over the 70–79 row; under 18 is rejected (adult norms do not apply).
+  # - The result is bounded to the table: 5.0 means at or below the 5th
+  #   percentile, 95.0 at or above the 95th.
+  #
+  # @param value [Numeric] VO2max in ml/kg/min
+  # @param age [Integer] age in years (18 or over; a fractional age is
+  #   truncated, as in AgeGrading)
+  # @param sex [String, Symbol] male or female
+  # @return [Float] percentile between 5.0 and 95.0, rounded to one decimal
+  # @raise [Calcpace::NonPositiveInputError] if value is not positive
+  # @raise [ArgumentError] if age is under 18 or not a number, or sex is not male/female
+  #
+  # @example
+  #   calc.vo2max_percentile(48.0, age: 25, sex: :male)  #=> 50.0
+  #   calc.vo2max_percentile(45, age: 25, sex: :male)    #=> 40.5
+  #   calc.vo2max_percentile(45, age: 25, sex: :female)  #=> 75.7
+  #   calc.vo2max_percentile(45, age: 60, sex: :male)    #=> 95.0
+  def vo2max_percentile(value, age:, sex:)
+    check_positive(value.to_f, 'VO2max value')
+
+    raw_vo2max_percentile(value.to_f, age, sex).round(1)
+  end
+
+  private
+
+  # Unrounded percentile, so a label is decided against the published values
+  # themselves rather than a rounded reading of them. normalize_age and
+  # normalize_sex come from Checker — one rule for age and sex gem-wide.
+  def raw_vo2max_percentile(value, age, sex)
+    row = vo2max_norm_row(normalize_age(age), normalize_sex(sex))
+    return VO2MAX_NORM_PERCENTILES.first if value <= row.first
+    return VO2MAX_NORM_PERCENTILES.last if value >= row.last
+
+    upper = row.index { |norm| norm > value }
+    interpolate_percentile(row, upper, value)
+  end
+
+  def vo2max_norm_row(age, sex)
+    bands = VO2MAX_NORMS.fetch(sex == :male ? 'M' : 'F')
+    band = bands.keys.select { |lower| lower <= age }.max || bands.keys.min
+    bands.fetch(band)
+  end
+
+  def interpolate_percentile(row, upper, value)
+    low_norm, high_norm = row.values_at(upper - 1, upper)
+    low_pct, high_pct = VO2MAX_NORM_PERCENTILES.values_at(upper - 1, upper)
+    low_pct + ((high_pct - low_pct) * (value - low_norm) / (high_norm - low_norm))
+  end
+end

data/lib/calcpace.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'calcpace/version'
 require_relative 'calcpace/errors'
 require_relative 'calcpace/calculator'
 require_relative 'calcpace/cameron_predictor'
@@ -9,15 +10,18 @@ require_relative 'calcpace/checker'
 require_relative 'calcpace/converter'
 require_relative 'calcpace/converter_chain'
 require_relative 'calcpace/fitness_predictor'
+require_relative 'calcpace/grade_adjusted_pace'
 require_relative 'calcpace/lap_analyzer'
 require_relative 'calcpace/pace_calculator'
 require_relative 'calcpace/pace_converter'
+require_relative 'calcpace/personalized_predictor'
 require_relative 'calcpace/race_predictor'
 require_relative 'calcpace/race_splits'
 require_relative 'calcpace/stride_calculator'
 require_relative 'calcpace/track_calculator'
 require_relative 'calcpace/training_zones'
 require_relative 'calcpace/vo2max_estimator'
+require_relative 'calcpace/vo2max_norms'
 
 # Calcpace - A Ruby gem for pace, distance, and time calculations
 #
@@ -49,15 +53,18 @@ class Calcpace
   include Converter
   include ConverterChain
   include FitnessPredictor
+  include GradeAdjustedPace
   include LapAnalyzer
   include PaceCalculator
   include PaceConverter
+  include PersonalizedPredictor
   include RacePredictor
   include RaceSplits
   include StrideCalculator
   include TrackCalculator
   include TrainingZones
   include Vo2maxEstimator
+  include Vo2maxNorms
 
   # Creates a new Calcpace instance
   #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: calcpace
 version: !ruby/object:Gem::Version
-  version: 1.18.1
+  version: 2.0.0
 platform: ruby
 authors:
 - João Gilberto Saraiva
@@ -10,9 +10,11 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: 'Ruby gem for runners: pace, time, and distance calculations, unit conversions
-  (30+ units), race time predictions (Riegel & Cameron), GPS track analysis (Haversine,
-  elevation gain, per-km splits), age grading (WMA 2023), VO2max estimation (Daniels
-  & Gilbert), and personalized training zones (Daniels paces & Karvonen heart-rate
+  (30+ units), race time predictions (Riegel, Cameron, personal Riegel exponent, and
+  Tanda marathon from training volume), GPS track analysis (Haversine, elevation gain,
+  per-km splits, Minetti grade-adjusted pace), heat, humidity, and altitude adjustments,
+  age grading (2025 road tables), VO2max estimation (Daniels & Gilbert) with FRIEND
+  age/sex norms, and personalized training zones (Daniels paces & Karvonen heart-rate
   zones).'
 email:
 - joaogilberto@tuta.io
@@ -40,14 +42,18 @@ files:
 - lib/calcpace/converter.rb
 - lib/calcpace/converter_chain.rb
 - lib/calcpace/data/environmental_factors.yml
-- lib/calcpace/data/wma_2023_open_standards.yml
-- lib/calcpace/data/wma_2023_road.yml
+- lib/calcpace/data/friend_2015_vo2max_percentiles.yml
+- lib/calcpace/data/mldr_2025_road.yml
+- lib/calcpace/data/mldr_2025_road_open_standards.yml
 - lib/calcpace/environmental_adjuster.rb
 - lib/calcpace/errors.rb
 - lib/calcpace/fitness_predictor.rb
+- lib/calcpace/grade_adjusted_pace.rb
+- lib/calcpace/humidity.rb
 - lib/calcpace/lap_analyzer.rb
 - lib/calcpace/pace_calculator.rb
 - lib/calcpace/pace_converter.rb
+- lib/calcpace/personalized_predictor.rb
 - lib/calcpace/race_predictor.rb
 - lib/calcpace/race_splits.rb
 - lib/calcpace/stride_calculator.rb
@@ -55,6 +61,7 @@ files:
 - lib/calcpace/training_zones.rb
 - lib/calcpace/version.rb
 - lib/calcpace/vo2max_estimator.rb
+- lib/calcpace/vo2max_norms.rb
 homepage: https://github.com/0jonjo/calcpace
 licenses:
 - MIT
@@ -76,8 +83,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
-summary: 'Running calculations: pace, race predictions, GPS track analysis, VO2max,
-  and training zones.'
+summary: 'Running calculations: pace, race predictions, GPS track analysis, heat and
+  altitude adjustments, age grading, VO2max, and training zones.'
 test_files: []

data/lib/calcpace/data/wma_2023_open_standards.yml

@@ -1,40 +0,0 @@
-meta:
-  source: "WMA/Masters Rankings age grading tables (2023)"
-  url: "https://howardgrubb.co.uk/athletics/wmatnf23.html"
-  table_version: "WMA_2023_ONE_YEAR_FACTORS_V1"
-
-# The WMA / Alan Jones (Howard Grubb) tables are numeric age factors and open
-# standards only — they define no categories at all. The bands from Local
-# Class (60%) upward follow the USATF Masters / National Masters News
-# convention; the three bands under 60% are Calcpace's own extension, added
-# to give recreational runners a meaningful label instead of a single
-# catch-all.
-age_grade_classifications:
-  - min: 100.0
-    label: "Approximate World Record Level"
-  - min: 90.0
-    label: "World Class"
-  - min: 80.0
-    label: "National Class"
-  - min: 70.0
-    label: "Regional Class"
-  - min: 60.0
-    label: "Local Class"
-  - min: 50.0
-    label: "Intermediate"
-  - min: 40.0
-    label: "Recreational"
-  - min: 0.0
-    label: "Active Beginner"
-
-open_standards_seconds:
-  M:
-    "5000": 755.0
-    "10000": 1571.0
-    "21097": 3451.0
-    "42195": 7269.0
-  F:
-    "5000": 846.0
-    "10000": 1741.0
-    "21097": 3772.0
-    "42195": 8044.0