calcpace 2.0.0 → 2.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/calcpace.gemspec CHANGED
@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
11
11
  spec.summary = 'Running calculations: pace, race predictions, GPS track analysis, ' \
12
12
  'heat and altitude adjustments, age grading, VO2max, and training zones.'
13
13
  spec.description = 'Ruby gem for runners: pace, time, and distance calculations, ' \
14
- 'unit conversions (30+ units), race time predictions (Riegel, Cameron, ' \
14
+ 'unit conversions (40+ conversions), race time predictions (Riegel, Cameron, ' \
15
15
  'personal Riegel exponent, and Tanda marathon from training volume), ' \
16
16
  'GPS track analysis (Haversine, elevation gain, per-km splits, ' \
17
17
  'Minetti grade-adjusted pace), heat, humidity, and altitude adjustments, ' \
@@ -24,10 +24,11 @@ Gem::Specification.new do |spec|
24
24
  spec.required_ruby_version = '>= 3.3.0'
25
25
 
26
26
  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
27
+ spec.metadata['documentation_uri'] = "#{spec.homepage}/blob/main/docs/USAGE.md"
27
28
  spec.metadata['rubygems_mfa_required'] = 'true'
28
29
 
29
30
  spec.files = Dir.chdir(File.expand_path(__dir__)) do
30
- `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
31
+ `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|docs)/}) }
31
32
  end
32
33
  spec.bindir = 'exe'
33
34
  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
@@ -26,7 +26,7 @@ require_relative 'checker'
26
26
  # - age-graded time
27
27
  # - open standard time for the selected distance/sex
28
28
  # - performance category
29
- # rubocop:disable Metrics/ModuleLength
29
+ # rubocop:disable-next Metrics/ModuleLength
30
30
  module AgeGrading
31
31
  # normalize_age / normalize_sex live in Checker, shared with Vo2maxNorms
32
32
  include Checker
@@ -232,4 +232,3 @@ module AgeGrading
232
232
  lower_factor + ((upper_factor - lower_factor) * ratio)
233
233
  end
234
234
  end
235
- # rubocop:enable Metrics/ModuleLength
@@ -20,6 +20,13 @@ class Calcpace
20
20
  end
21
21
  end
22
22
 
23
+ # Raised when an effort is not one of Vo2maxEffort::EFFORT_LEVELS
24
+ class InvalidEffortError < Error
25
+ def initialize(msg = 'Invalid effort. Valid efforts: :easy, :moderate, :hard, :max')
26
+ super
27
+ end
28
+ end
29
+
23
30
  # Raised when versioned/static gem data fails an internal consistency check
24
31
  class InvalidDataError < Error; end
25
32
 
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  class Calcpace
4
- VERSION = '2.0.0'
4
+ VERSION = '2.1.1'
5
5
  end
@@ -0,0 +1,43 @@
1
+ # frozen_string_literal: true
2
+
3
+ # How hard the runner says an effort was, for Vo2maxEstimator#estimate_detailed_vo2max
4
+ #
5
+ # Daniels & Gilbert assume an all-out effort, and the estimator can only guess
6
+ # that from duration and heart rate. A declared effort answers it directly. It
7
+ # never changes the VO2max value — only its confidence, sub_maximal and basis.
8
+ module Vo2maxEffort
9
+ # From easiest. :easy and :moderate are training (talk test: a full
10
+ # conversation / short sentences), :hard is a few words at a time, :max is
11
+ # everything the runner had — a race or a test.
12
+ EFFORT_LEVELS = %i[easy moderate hard max].freeze
13
+
14
+ private
15
+
16
+ def normalize_effort(effort)
17
+ return if effort.nil?
18
+
19
+ level = effort.to_s.downcase.to_sym
20
+ return level if EFFORT_LEVELS.include?(level)
21
+
22
+ raise Calcpace::InvalidEffortError,
23
+ "Invalid effort: #{effort.inspect}. Valid efforts: #{EFFORT_LEVELS.map(&:inspect).join(', ')}"
24
+ end
25
+
26
+ # A declared easy or moderate effort wins over everything: the runner knows
27
+ # they held back, whatever the watch says. Heart rate wins over a declared
28
+ # max, as it did over the duration rule. A max shorter than five minutes stays
29
+ # with the duration rule: there the formula itself is unreliable.
30
+ #
31
+ # duration_confidence is the estimator's verdict from duration alone.
32
+ def effort_verdict(effort, time_min, duration_confidence:, hr_sub_maximal:)
33
+ if %i[easy moderate].include?(effort)
34
+ { confidence: :low, sub_maximal: true, basis: :declared }
35
+ elsif hr_sub_maximal
36
+ { confidence: :low, sub_maximal: true, basis: :heart_rate }
37
+ elsif effort == :max && time_min >= 5
38
+ { confidence: :high, sub_maximal: false, basis: :declared }
39
+ else
40
+ { confidence: duration_confidence, sub_maximal: false, basis: :duration }
41
+ end
42
+ end
43
+ end
@@ -14,6 +14,8 @@
14
14
  # Accuracy: ±3–5 ml/kg/min vs laboratory testing. Best results with efforts
15
15
  # between 5 and 60 minutes at race pace (i.e. near-maximal effort).
16
16
  module Vo2maxEstimator
17
+ include Vo2maxEffort
18
+
17
19
  # Classification thresholds based on:
18
20
  # Daniels, J. (2014). Daniels' Running Formula (3rd ed.). Human Kinetics.
19
21
  # General ranges are consistent with ACSM guidelines and widely cited in
@@ -28,7 +30,11 @@ module Vo2maxEstimator
28
30
  ].freeze
29
31
 
30
32
  # Represents a contextualized VO2max estimation result
31
- Vo2maxResult = Struct.new(:value, :confidence, :sub_maximal, :adjusted_distance_km)
33
+ #
34
+ # basis names what set confidence and sub_maximal: :declared (the effort
35
+ # given), :heart_rate (average HR under 85 % of max) or :duration (the
36
+ # Daniels & Gilbert window alone)
37
+ Vo2maxResult = Struct.new(:value, :confidence, :sub_maximal, :adjusted_distance_km, :basis)
32
38
 
33
39
  # Estimates VO2max from a race performance using Daniels & Gilbert formula
34
40
  #
@@ -59,6 +65,10 @@ module Vo2maxEstimator
59
65
  (vo2 / pct_vo2max).round(1)
60
66
  end
61
67
 
68
+ # The public signature: every input is a keyword a caller already passes, and
69
+ # bundling them into an options object would break the 2.x API.
70
+ # rubocop:disable Metrics/ParameterLists
71
+
62
72
  # Estimates a detailed and contextualized VO2max
63
73
  #
64
74
  # Elevation is folded in with a flat heuristic — every 100 m of gain adds
@@ -75,11 +85,25 @@ module Vo2maxEstimator
75
85
  # @param hr_avg [Numeric] average heart rate during the effort
76
86
  # @param hr_max [Numeric] athlete's maximum heart rate
77
87
  # @param distance_unit [Symbol] unit of the distance input — :km (default) or :mi
88
+ # @param effort [Symbol, String, nil] how hard the runner says it was, one of
89
+ # Vo2maxEffort::EFFORT_LEVELS. It never changes the value, only how far it can be
90
+ # trusted: :easy and :moderate make it sub-maximal and low confidence
91
+ # whatever the duration or heart rate; :max makes it high confidence from
92
+ # five minutes on, however long it took, unless heart rate says
93
+ # sub-maximal; :hard and nil leave the duration and heart-rate rules as
94
+ # they are.
78
95
  # @return [Vo2maxResult] structured result with value and metadata
79
96
  # (adjusted_distance_km is always in kilometres)
80
97
  # @raise [Calcpace::NonPositiveInputError] if distance or time are not positive
81
98
  # @raise [Calcpace::UnsupportedUnitError] if distance_unit is not :km or :mi
82
- def estimate_detailed_vo2max(distance, time, elevation_gain_m: 0, hr_avg: nil, hr_max: nil, distance_unit: :km)
99
+ # @raise [Calcpace::InvalidEffortError] if effort is not one of Vo2maxEffort::EFFORT_LEVELS
100
+ #
101
+ # @example a marathon run all-out
102
+ # calc.estimate_detailed_vo2max(42.195, '03:30:00').confidence #=> :low
103
+ # calc.estimate_detailed_vo2max(42.195, '03:30:00', effort: :max).confidence #=> :high
104
+ def estimate_detailed_vo2max(distance, time, elevation_gain_m: 0, hr_avg: nil, hr_max: nil, distance_unit: :km,
105
+ effort: nil)
106
+ effort = normalize_effort(effort)
83
107
  distance_km = normalize_distance_km(distance, distance_unit)
84
108
  # Validated before the elevation adjustment, which would otherwise turn a
85
109
  # negative distance into a positive equivalent-flat one
@@ -87,18 +111,14 @@ module Vo2maxEstimator
87
111
 
88
112
  adj_dist_km = adjusted_distance_for_vo2(distance_km, elevation_gain_m)
89
113
  vo2max_val = estimate_vo2max(adj_dist_km, time)
90
- confidence = calculate_time_confidence(parse_time_minutes(time))
91
-
92
- hr_data = validate_and_analyze_hr(hr_avg, hr_max)
93
- confidence = :low if hr_data[:sub_maximal]
114
+ time_min = parse_time_minutes(time)
115
+ hr_data = validate_and_analyze_hr(hr_avg, hr_max)
116
+ verdict = effort_verdict(effort, time_min, duration_confidence: calculate_time_confidence(time_min),
117
+ hr_sub_maximal: hr_data[:sub_maximal])
94
118
 
95
- Vo2maxResult.new(
96
- value: vo2max_val,
97
- confidence: confidence,
98
- sub_maximal: hr_data[:sub_maximal],
99
- adjusted_distance_km: adj_dist_km.round(2)
100
- )
119
+ Vo2maxResult.new(value: vo2max_val, adjusted_distance_km: adj_dist_km.round(2), **verdict)
101
120
  end
121
+ # rubocop:enable Metrics/ParameterLists
102
122
 
103
123
  # Returns a descriptive label for a given VO2max value
104
124
  #
data/lib/calcpace.rb CHANGED
@@ -20,6 +20,7 @@ require_relative 'calcpace/race_splits'
20
20
  require_relative 'calcpace/stride_calculator'
21
21
  require_relative 'calcpace/track_calculator'
22
22
  require_relative 'calcpace/training_zones'
23
+ require_relative 'calcpace/vo2max_effort'
23
24
  require_relative 'calcpace/vo2max_estimator'
24
25
  require_relative 'calcpace/vo2max_norms'
25
26
 
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: calcpace
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.0.0
4
+ version: 2.1.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - João Gilberto Saraiva
@@ -10,12 +10,12 @@ cert_chain: []
10
10
  date: 1980-01-02 00:00:00.000000000 Z
11
11
  dependencies: []
12
12
  description: 'Ruby gem for runners: pace, time, and distance calculations, unit conversions
13
- (30+ units), race time predictions (Riegel, Cameron, personal Riegel exponent, and
14
- Tanda marathon from training volume), GPS track analysis (Haversine, elevation gain,
15
- per-km splits, Minetti grade-adjusted pace), heat, humidity, and altitude adjustments,
16
- age grading (2025 road tables), VO2max estimation (Daniels & Gilbert) with FRIEND
17
- age/sex norms, and personalized training zones (Daniels paces & Karvonen heart-rate
18
- zones).'
13
+ (40+ conversions), race time predictions (Riegel, Cameron, personal Riegel exponent,
14
+ and Tanda marathon from training volume), GPS track analysis (Haversine, elevation
15
+ gain, per-km splits, Minetti grade-adjusted pace), heat, humidity, and altitude
16
+ adjustments, age grading (2025 road tables), VO2max estimation (Daniels & Gilbert)
17
+ with FRIEND age/sex norms, and personalized training zones (Daniels paces & Karvonen
18
+ heart-rate zones).'
19
19
  email:
20
20
  - joaogilberto@tuta.io
21
21
  executables: []
@@ -60,6 +60,7 @@ files:
60
60
  - lib/calcpace/track_calculator.rb
61
61
  - lib/calcpace/training_zones.rb
62
62
  - lib/calcpace/version.rb
63
+ - lib/calcpace/vo2max_effort.rb
63
64
  - lib/calcpace/vo2max_estimator.rb
64
65
  - lib/calcpace/vo2max_norms.rb
65
66
  homepage: https://github.com/0jonjo/calcpace
@@ -68,6 +69,7 @@ licenses:
68
69
  metadata:
69
70
  source_code_uri: https://github.com/0jonjo/calcpace
70
71
  changelog_uri: https://github.com/0jonjo/calcpace/blob/main/CHANGELOG.md
72
+ documentation_uri: https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md
71
73
  rubygems_mfa_required: 'true'
72
74
  rdoc_options: []
73
75
  require_paths: