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.
- checksums.yaml +4 -4
- data/.ruby-version +1 -1
- data/.tool-versions +1 -1
- data/CHANGELOG.md +32 -1
- data/Gemfile +1 -1
- data/Gemfile.lock +23 -20
- data/README.md +35 -957
- data/calcpace.gemspec +3 -2
- data/lib/calcpace/age_grading.rb +1 -2
- data/lib/calcpace/errors.rb +7 -0
- data/lib/calcpace/version.rb +1 -1
- data/lib/calcpace/vo2max_effort.rb +43 -0
- data/lib/calcpace/vo2max_estimator.rb +32 -12
- data/lib/calcpace.rb +1 -0
- metadata +9 -7
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 (
|
|
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) }
|
data/lib/calcpace/age_grading.rb
CHANGED
|
@@ -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
|
data/lib/calcpace/errors.rb
CHANGED
|
@@ -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
|
|
data/lib/calcpace/version.rb
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
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.
|
|
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
|
-
(
|
|
14
|
-
Tanda marathon from training volume), GPS track analysis (Haversine, elevation
|
|
15
|
-
per-km splits, Minetti grade-adjusted pace), heat, humidity, and altitude
|
|
16
|
-
age grading (2025 road tables), VO2max estimation (Daniels & Gilbert)
|
|
17
|
-
age/sex norms, and personalized training zones (Daniels paces & Karvonen
|
|
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:
|