calcpace 1.9.9 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 690aa2af75618e2e2721e8459546019798dd11ed62aad22389339da03ca9aeb5
-  data.tar.gz: b82e4c2c7bd29f62c95db7068952224baba43d271310b2cb6be2bac4d6ee0c73
+  metadata.gz: 6d89d16ea156af81fa6cd59976eebf680d435b38b41a65fcd46ee79ec2ea5fe6
+  data.tar.gz: b79d25c3f1da091543d1f1a930350bdd846ff15369f7e8476303e99aeccbcc79
 SHA512:
-  metadata.gz: ab5ae1f4fdee60fd08886ec8ee6576f019200c7fa276cbcca847ef527d58e9d544a61c4f0680facf3a380c3e54dddf949851863849bc8669873ec6ae8770d6c0
-  data.tar.gz: 71425df084bee6d3f2faaa367bdb69ace1a4f5033025ea0097124cb1d7368527b77f7706aed8d2c25644f036f4e6af63e581226aac04d54bfe022ba876bc8d9e
+  metadata.gz: 1582ebc32a95e1e7702881c0efc16da68768a6616382bb1fb8102e83c9be665ac3f8eb3524f1581f0ec82db1d05e1db2eedf2217b822f959a2dc62711e6b8aa5
+  data.tar.gz: 9b95fd1feacc28b87a6477788a76bf141651cfa0ee254d4923ccc44cb9f6af63feb666046835c01d3ff5ddd65fb1632ef5d7825b540933ea3295f1ae406f55d3

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.10.0] - 2026-07-11
+
+### Added
+- Training Zones module (`TrainingZones`)
+  - `training_paces(vo2max)`: personalized Easy/Marathon/Threshold/Interval/Repetition
+    pace bands per km, inverting the Daniels & Gilbert velocity equation
+  - `training_paces_from_race(distance_km, time)`: pace bands straight from a race result
+  - `hr_zones(hr_max:, hr_rest:)`: five Karvonen (Heart Rate Reserve) heart-rate zones
+  - Structured results (`PaceBand`, `HrZone`) with seconds and clock formats
+
+## [1.9.10] - 2026-07-09
+
+### Changed
+- Refactor `TrackCalculator`: extract a single `dig_key` helper for symbol/string key access, removing duplicated fallback logic across coordinate, elevation, and time readers (no behavior change)
+
 ## [1.9.9] - 2026-06-17
 
 ### Changed
@@ -200,7 +215,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 See git history for changes in earlier versions.
 
-[Unreleased]: https://github.com/0jonjo/calcpace/compare/v1.9.6...HEAD
+[Unreleased]: https://github.com/0jonjo/calcpace/compare/v1.10.0...HEAD
+[1.10.0]: https://github.com/0jonjo/calcpace/compare/v1.9.10...v1.10.0
 [1.9.6]: https://github.com/0jonjo/calcpace/compare/v1.9.5...v1.9.6
 [1.9.5]: https://github.com/0jonjo/calcpace/compare/v1.9.4...v1.9.5
 [1.6.0]: https://github.com/0jonjo/calcpace/releases/tag/v1.6.0

data/README.md

@@ -1,11 +1,11 @@
-# Calcpace [![Gem Version](https://d25lcipzij17d.cloudfront.net/badge.svg?id=rb&r=r&ts=1683906897&type=6e&v=1.9.8&x2=0)](https://badge.fury.io/rb/calcpace)
+# Calcpace [![Gem Version](https://d25lcipzij17d.cloudfront.net/badge.svg?id=rb&r=r&ts=1683906897&type=6e&v=1.10.0&x2=0)](https://badge.fury.io/rb/calcpace)
 
-A Ruby gem for running and cycling calculations: pace, time, distance, unit conversions, race predictions, GPS track analysis, and VO2max estimation.
+A Ruby gem for runners: pace, time, and distance calculations, unit conversions, race predictions, GPS track analysis, age grading, VO2max estimation, and training zones.
 
 ## Installation
 
 ```ruby
-gem 'calcpace', '~> 1.9.8'
+gem 'calcpace', '~> 1.10.0'
 ```
 
 ## Usage
@@ -276,6 +276,34 @@ easy.value        # => 29.3   (underestimates real aerobic capacity)
 
 ---
 
+### Training Zones
+
+Personalized training paces (Daniels' Running Formula) and Karvonen heart-rate zones:
+
+```ruby
+zones = calc.training_paces(50.0)
+zones[:threshold].fast_clock   # => "00:04:15" per km
+zones[:easy].slow_clock        # => "00:05:52" per km
+
+calc.training_paces_from_race(10.0, '00:40:00')  # from a recent race result
+
+calc.hr_zones(hr_max: 190, hr_rest: 55)
+# => [#<struct zone=1, min_bpm=123, max_bpm=136>, ... zone=5, max_bpm=190]
+```
+
+| Zone | %VO2max | Purpose |
+|------|---------|---------|
+| Easy | 59–74% | Base building, recovery |
+| Marathon | 75–84% | Marathon race pace |
+| Threshold | 83–88% | Lactate threshold, tempo runs |
+| Interval | 95–100% | VO2max development |
+| Repetition | 105–110% | Speed and running economy |
+
+Pace accuracy vs published VDOT tables: within a few seconds per km
+(threshold matches exactly; easy band is a range heuristic).
+
+---
+
 ### Other Utilities
 
 ```ruby

data/calcpace.gemspec

@@ -8,11 +8,12 @@ Gem::Specification.new do |spec|
   spec.authors       = ['João Gilberto Saraiva']
   spec.email         = ['joaogilberto@tuta.io']
 
-  spec.summary       = 'Pace, distance, GPS track analysis, and VO2max calculations for runners and cyclists.'
-  spec.description   = 'Ruby gem for running and cycling calculations: pace, time, distance, ' \
-                       'unit conversions (30+ units), race predictions (Riegel & Cameron), ' \
+  spec.summary       = 'Running calculations: pace, race predictions, GPS track analysis, VO2max, and training zones.'
+  spec.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), ' \
-                       'and VO2max estimation (Daniels & Gilbert).'
+                       'age grading (WMA 2023), VO2max estimation (Daniels & Gilbert), and ' \
+                       'personalized training zones (Daniels paces & Karvonen heart-rate zones).'
   spec.homepage      = 'https://github.com/0jonjo/calcpace'
   spec.metadata['source_code_uri'] = spec.homepage
   spec.license = 'MIT'

data/lib/calcpace/track_calculator.rb

@@ -74,8 +74,8 @@ module TrackCalculator
     return 0.0 if points.nil? || points.size < 2
 
     total = points.each_cons(2).sum do |a, b|
-      haversine_distance(fetch_coord(a, :lat), fetch_coord(a, :lon),
-                         fetch_coord(b, :lat), fetch_coord(b, :lon))
+      haversine_distance(dig_key(a, :lat), dig_key(a, :lon),
+                         dig_key(b, :lat), dig_key(b, :lon))
     end
 
     total.round(2)
@@ -180,25 +180,24 @@ module TrackCalculator
     end
   end
 
-  def fetch_coord(point, key)
+  def dig_key(point, key)
     point[key] || point[key.to_s]
   end
 
   def fetch_ele(point)
-    val = point[:ele] || point['ele']
-    val&.to_f
+    dig_key(point, :ele)&.to_f
   end
 
   def validate_points_have_time(points)
     points.each_with_index do |pt, i|
-      next if pt[:time] || pt['time']
+      next if dig_key(pt, :time)
 
       raise ArgumentError, "Point at index #{i} is missing :time key required for splits"
     end
   end
 
   def point_time(point)
-    t = point[:time] || point['time']
+    t = dig_key(point, :time)
     t.respond_to?(:to_f) ? t.to_f : t
   end
 
@@ -228,8 +227,8 @@ module TrackCalculator
   end
 
   def process_segment(point_a, point_b, split_km, state)
-    segment_km = haversine_distance(fetch_coord(point_a, :lat), fetch_coord(point_a, :lon),
-                                    fetch_coord(point_b, :lat), fetch_coord(point_b, :lon))
+    segment_km = haversine_distance(dig_key(point_a, :lat), dig_key(point_a, :lon),
+                                    dig_key(point_b, :lat), dig_key(point_b, :lon))
     state[:accumulated_km] += segment_km
 
     while state[:accumulated_km] >= split_km * state[:split_number]

data/lib/calcpace/training_zones.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+# Module for deriving personalized training zones from VO2max
+#
+# Training paces invert the Daniels & Gilbert (1979) velocity equation:
+#   VO2 = -4.60 + 0.182258 * v + 0.000104 * v²   (v in m/min)
+# Solving the quadratic for v at a target %VO2max gives the running
+# velocity for each training intensity (Daniels' Running Formula).
+#
+# Heart rate zones use the Karvonen method (Heart Rate Reserve):
+#   target = hr_rest + pct * (hr_max - hr_rest)
+module TrainingZones
+  # Training intensities as fraction of VO2max (Daniels' Running Formula)
+  TRAINING_INTENSITIES = {
+    easy: { low: 0.59, high: 0.74 },
+    marathon: { low: 0.75, high: 0.84 },
+    threshold: { low: 0.83, high: 0.88 },
+    interval: { low: 0.95, high: 1.00 },
+    repetition: { low: 1.05, high: 1.10 }
+  }.freeze
+
+  # A pace band for one training zone (paces per kilometre).
+  # slow = lower-intensity end of the band, fast = higher-intensity end.
+  PaceBand = Struct.new(:slow_seconds, :fast_seconds, :slow_clock, :fast_clock)
+
+  # Heart-rate zone boundaries as fractions of Heart Rate Reserve (Karvonen)
+  HR_ZONE_BOUNDARIES = [0.50, 0.60, 0.70, 0.80, 0.90, 1.00].freeze
+
+  # One heart-rate training zone (1 = recovery … 5 = maximal)
+  HrZone = Struct.new(:zone, :min_bpm, :max_bpm)
+
+  # Derives training pace bands from a VO2max value
+  #
+  # @param vo2max [Numeric] VO2max in ml/kg/min (must be > 0)
+  # @return [Hash{Symbol => PaceBand}] keys: :easy, :marathon, :threshold,
+  #   :interval, :repetition — paces per km
+  # @raise [Calcpace::NonPositiveInputError] if vo2max is not positive
+  #
+  # @example
+  #   calc.training_paces(50.0)[:threshold].fast_clock #=> "00:04:15"
+  def training_paces(vo2max)
+    check_positive(vo2max.to_f, 'VO2max')
+
+    TRAINING_INTENSITIES.transform_values do |band|
+      slow = pace_seconds_at_pct(vo2max.to_f, band[:low])
+      fast = pace_seconds_at_pct(vo2max.to_f, band[:high])
+
+      PaceBand.new(
+        slow_seconds: slow,
+        fast_seconds: fast,
+        slow_clock: convert_to_clocktime(slow),
+        fast_clock: convert_to_clocktime(fast)
+      )
+    end
+  end
+
+  # Derives training pace bands from a recent race result
+  #
+  # Convenience wrapper: estimates VO2max via Daniels & Gilbert
+  # (see Vo2maxEstimator#estimate_vo2max) and derives the bands from it.
+  #
+  # @param distance_km [Numeric] race distance in kilometres (must be > 0)
+  # @param time [String, Integer] finish time as "HH:MM:SS" / "MM:SS" or total seconds
+  # @return [Hash{Symbol => PaceBand}] same shape as #training_paces
+  # @raise [Calcpace::NonPositiveInputError] if distance or time are not positive
+  # @raise [Calcpace::InvalidTimeFormatError] if time string is malformed
+  #
+  # @example
+  #   calc.training_paces_from_race(10.0, '00:40:00')[:easy].slow_clock #=> "00:05:42"
+  def training_paces_from_race(distance_km, time)
+    training_paces(estimate_vo2max(distance_km, time))
+  end
+
+  # Computes the five Karvonen heart-rate training zones
+  #
+  # target_bpm = hr_rest + pct * (hr_max - hr_rest)
+  #
+  # @param hr_max [Numeric] maximum heart rate in bpm (must be > 0)
+  # @param hr_rest [Numeric] resting heart rate in bpm (must be > 0 and < hr_max)
+  # @return [Array<HrZone>] five contiguous zones from Z1 (50–60% HRR) to Z5 (90–100% HRR)
+  # @raise [Calcpace::NonPositiveInputError] if any rate is not positive
+  # @raise [Calcpace::Error] if hr_rest >= hr_max
+  #
+  # @example
+  #   calc.hr_zones(hr_max: 190, hr_rest: 55).last.max_bpm #=> 190
+  def hr_zones(hr_max:, hr_rest:)
+    max  = hr_max.to_f
+    rest = hr_rest.to_f
+    check_heart_rates(max, rest)
+
+    reserve = max - rest
+    points  = HR_ZONE_BOUNDARIES.map { |pct| (rest + (pct * reserve)).round }
+
+    points.each_cons(2).with_index(1).map do |(min_bpm, max_bpm), zone|
+      HrZone.new(zone: zone, min_bpm: min_bpm, max_bpm: max_bpm)
+    end
+  end
+
+  private
+
+  def check_heart_rates(hr_max, hr_rest)
+    check_positive(hr_max, 'Maximum heart rate')
+    check_positive(hr_rest, 'Resting heart rate')
+    return if hr_rest < hr_max
+
+    raise Calcpace::Error,
+          "Resting heart rate (#{hr_rest}) must be lower than maximum heart rate (#{hr_max})"
+  end
+
+  # Inverts Daniels & Gilbert: velocity (m/min) that demands a given VO2
+  def velocity_at_vo2(vo2)
+    a = 0.000104
+    b = 0.182258
+    c = -(4.60 + vo2)
+
+    (-b + Math.sqrt((b**2) - (4 * a * c))) / (2 * a)
+  end
+
+  def pace_seconds_at_pct(vo2max, pct)
+    velocity = velocity_at_vo2(vo2max * pct)
+    (60_000.0 / velocity).round
+  end
+end

data/lib/calcpace/version.rb

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

data/lib/calcpace.rb

@@ -13,6 +13,7 @@ require_relative 'calcpace/pace_converter'
 require_relative 'calcpace/race_predictor'
 require_relative 'calcpace/race_splits'
 require_relative 'calcpace/track_calculator'
+require_relative 'calcpace/training_zones'
 require_relative 'calcpace/vo2max_estimator'
 
 # Calcpace - A Ruby gem for pace, distance, and time calculations
@@ -49,6 +50,7 @@ class Calcpace
   include RacePredictor
   include RaceSplits
   include TrackCalculator
+  include TrainingZones
   include Vo2maxEstimator
 
   # Creates a new Calcpace instance

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: calcpace
 version: !ruby/object:Gem::Version
-  version: 1.9.9
+  version: 1.10.0
 platform: ruby
 authors:
 - João Gilberto Saraiva
@@ -9,9 +9,11 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: 'Ruby gem for running and cycling calculations: pace, time, distance,
-  unit conversions (30+ units), race predictions (Riegel & Cameron), GPS track analysis
-  (Haversine, elevation gain, per-km splits), and VO2max estimation (Daniels & Gilbert).'
+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
+  zones).'
 email:
 - joaogilberto@tuta.io
 executables: []
@@ -47,6 +49,7 @@ files:
 - lib/calcpace/race_predictor.rb
 - lib/calcpace/race_splits.rb
 - lib/calcpace/track_calculator.rb
+- lib/calcpace/training_zones.rb
 - lib/calcpace/version.rb
 - lib/calcpace/vo2max_estimator.rb
 homepage: https://github.com/0jonjo/calcpace
@@ -72,6 +75,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Pace, distance, GPS track analysis, and VO2max calculations for runners and
-  cyclists.
+summary: 'Running calculations: pace, race predictions, GPS track analysis, VO2max,
+  and training zones.'
 test_files: []