calcpace 2.1.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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 25afa206e47316900eab46723efcccac5586d0026dbdd81316566798ffff58c3
4
- data.tar.gz: e86c8acacd4cda1bdc4c9036bad53249029b285d6fd7a0ed467d8f67534c172d
3
+ metadata.gz: 21a43dcb40d89d292a5a5b5fdbd92d44e89aba2f79ac9ca061fa5cf519b69b2d
4
+ data.tar.gz: e87ed04bccb34335eee7a1fb9de2e2b96fe078543a9538fbe2cffc5c186fb0d8
5
5
  SHA512:
6
- metadata.gz: 220badb3ce50b0ca0cd3ad4e386944b58f09586ab5fb1b0d50cbc961d2cd9705c1a04c98c4b0a68c0bfa371557b2a43bb831a4441b6697240dfedf12a87e1d24
7
- data.tar.gz: e3458ad4525014a92bb3ca2c923df3e224f5cec0fb06c5957b6da34d675f1ff3a507ffb96bfc7a0293e72c9710a7a96086685cad1bf005adf4a50f412a1d95b5
6
+ metadata.gz: d7e417b2164aa643d56f1a25609618f1aa4a3ad1305b6bd56cb98831d2c2f9c8b19764976eef6fee2a0f899ee23b716df80a92b74ea3353ce163d47b48c2318d
7
+ data.tar.gz: 79d5ad5d293fc96b68c3dc7ab898e57b3bedee2804252de4170a3934010b2c74918a32c44bce6b97a9d6d78fa50db4ca080234ad858b983f850a8d7c29ecb882
data/.ruby-version CHANGED
@@ -1 +1 @@
1
- 4.0.4
1
+ 4.0.10
data/.tool-versions CHANGED
@@ -1,2 +1,2 @@
1
1
  nodejs 24.1.0
2
- ruby 4.0.4
2
+ ruby 4.0.10
data/CHANGELOG.md CHANGED
@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [2.1.1] - 2026-11-20
11
+
12
+ ### Changed
13
+ - Bump development Ruby from 4.0.4 to 4.0.10 (Regexp and String security fixes).
14
+ - Development dependency bumps: rubocop 1.92, minitest 6.1, rdoc 8.1,
15
+ simplecov 1.3, rake-compiler 1.3.3. The `Metrics/ModuleLength` exemption in
16
+ `AgeGrading` now uses `rubocop:disable-next` (new in RuboCop 1.92).
17
+ No library code changes.
18
+
10
19
  ## [2.1.0] - 2026-10-11
11
20
 
12
21
  ### Added
@@ -1021,7 +1030,8 @@ predictors are untouched.
1021
1030
 
1022
1031
  See git history for changes in earlier versions.
1023
1032
 
1024
- [Unreleased]: https://github.com/0jonjo/calcpace/compare/v2.1.0...HEAD
1033
+ [Unreleased]: https://github.com/0jonjo/calcpace/compare/v2.1.1...HEAD
1034
+ [2.1.1]: https://github.com/0jonjo/calcpace/compare/v2.1.0...v2.1.1
1025
1035
  [2.1.0]: https://github.com/0jonjo/calcpace/compare/v2.0.0...v2.1.0
1026
1036
  [2.0.0]: https://github.com/0jonjo/calcpace/compare/v1.18.1...v2.0.0
1027
1037
  [1.18.1]: https://github.com/0jonjo/calcpace/compare/v1.18.0...v1.18.1
data/Gemfile CHANGED
@@ -6,5 +6,5 @@ gem 'minitest', '~> 6.0'
6
6
  gem 'rake', '~> 13.2'
7
7
  gem 'rake-compiler', '~> 1.0'
8
8
  gem 'rdoc', '~> 8.0'
9
- gem 'rubocop', '~> 1.69'
9
+ gem 'rubocop', '~> 1.92'
10
10
  gem 'simplecov', '~> 1.1', require: false
data/Gemfile.lock CHANGED
@@ -4,53 +4,56 @@ GEM
4
4
  ast (2.4.3)
5
5
  drb (2.2.3)
6
6
  erb (6.0.7)
7
- json (2.21.2)
7
+ json (3.1.0)
8
8
  language_server-protocol (3.17.0.6)
9
9
  lint_roller (1.1.0)
10
10
  logger (1.7.0)
11
- minitest (6.0.6)
11
+ minitest (6.1.0)
12
12
  drb (~> 2.0)
13
- prism (~> 1.5)
14
- parallel (2.1.0)
15
- parser (3.3.12.0)
13
+ prism (>= 1.5, < 3)
14
+ parallel (2.3.0)
15
+ parser (3.3.14.0)
16
16
  ast (~> 2.4.1)
17
17
  racc
18
- prism (1.9.0)
18
+ prism (2.1.0)
19
+ prism (2.1.0-x86_64-linux-gnu)
19
20
  racc (1.8.1)
20
21
  rainbow (3.1.1)
21
22
  rake (13.4.2)
22
- rake-compiler (1.3.1)
23
+ rake-compiler (1.3.3)
23
24
  rake
24
- rbs (4.1.3)
25
+ rbs (4.2.0)
25
26
  logger
26
27
  prism (>= 1.6.0)
27
28
  tsort
28
- rdoc (8.0.0)
29
+ rdoc (8.1.0)
29
30
  erb
30
31
  prism (>= 1.6.0)
31
32
  rbs (>= 4.0.0)
32
33
  tsort
33
- regexp_parser (2.12.0)
34
- rubocop (1.89.0)
35
- json (~> 2.3)
34
+ regexp_parser (2.13.4)
35
+ rubocop (1.92.3)
36
+ json (>= 2.3)
36
37
  language_server-protocol (~> 3.17.0.2)
37
38
  lint_roller (~> 1.1.0)
38
39
  parallel (>= 1.10)
39
40
  parser (>= 3.3.0.2)
40
41
  rainbow (>= 2.2.2, < 4.0)
41
- regexp_parser (>= 2.9.3, < 3.0)
42
+ regexp_parser (>= 2.11.3, < 3.0)
42
43
  rubocop-ast (>= 1.49.0, < 2.0)
43
44
  ruby-progressbar (~> 1.7)
44
45
  unicode-display_width (>= 2.4.0, < 4.0)
45
- rubocop-ast (1.50.0)
46
+ rubocop-ast (1.53.0)
47
+ ast (~> 2.4)
46
48
  parser (>= 3.3.7.2)
47
- prism (~> 1.7)
49
+ prism (>= 1.7)
50
+ racc
48
51
  ruby-progressbar (1.13.0)
49
- simplecov (1.1.1)
52
+ simplecov (1.3.2)
50
53
  tsort (0.2.0)
51
- unicode-display_width (3.2.0)
52
- unicode-emoji (~> 4.1)
53
- unicode-emoji (4.2.0)
54
+ unicode-display_width (3.3.0)
55
+ unicode-emoji (~> 4.3)
56
+ unicode-emoji (4.3.0)
54
57
 
55
58
  PLATFORMS
56
59
  ruby
@@ -61,7 +64,7 @@ DEPENDENCIES
61
64
  rake (~> 13.2)
62
65
  rake-compiler (~> 1.0)
63
66
  rdoc (~> 8.0)
64
- rubocop (~> 1.69)
67
+ rubocop (~> 1.92)
65
68
  simplecov (~> 1.1)
66
69
 
67
70
  BUNDLED WITH
data/README.md CHANGED
@@ -4,7 +4,11 @@
4
4
 
5
5
  A Ruby gem for runners: pace, time, and distance calculations, unit conversions, race predictions (including personalized ones), GPS track analysis with grade-adjusted pace, heat, humidity and altitude adjustments, age grading, VO2max estimation and norms, and training zones.
6
6
 
7
- > **See it in action:** [calcpace.app](https://calcpace.app) — free running calculators, race predictors and a training log, all powered by this gem.
7
+ - **Built on published models:** Riegel, Cameron, Daniels & Gilbert, El Helou, Minetti, FRIEND and the 2025 age-grading tables. The guide names the source behind each number and says where the published data ends and an extrapolation begins.
8
+ - **Checked:** the single-line examples in this README and in the [usage guide](https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md) run in the test suite against the real code.
9
+ - **No runtime dependencies.** Ruby >= 3.3.
10
+
11
+ > **See it in action:** [calcpace.app](https://calcpace.app) — free running calculators, race predictors and a training log in 16 languages, all powered by this gem. Also on Android: [Google Play](https://play.google.com/store/apps/details?id=app.calcpace.twa).
8
12
 
9
13
  ## Installation
10
14
 
@@ -12,998 +16,44 @@ A Ruby gem for runners: pace, time, and distance calculations, unit conversions,
12
16
  gem 'calcpace', '~> 2.1'
13
17
  ```
14
18
 
15
- ## Usage
19
+ ## Quick tour
16
20
 
17
21
  ```ruby
18
22
  require 'calcpace'
19
23
  calc = Calcpace.new
20
- ```
21
-
22
- ---
23
-
24
- ### Basic Calculations
25
-
26
- ```ruby
27
- calc.velocity(3625, 12275) # => 3.386 (distance / time)
28
- calc.pace(3665, 12) # => 305.4 (time / distance)
29
- calc.time(210, 12) # => 2520 (pace × distance)
30
- calc.distance(9660, 120) # => 80.5 (velocity × time)
31
-
32
- # Clocktime input/output (HH:MM:SS or MM:SS; seconds below 60, and minutes too when hours are given)
33
- calc.clock_pace('01:00:00', 10) # => "00:06:00"
34
- calc.clock_time('00:05:31', 12.6) # => "01:09:30"
35
- calc.checked_distance('01:21:32', '00:06:27') # => 12.64
36
- ```
37
-
38
- ---
39
-
40
- ### Environmental Performance Adjustments
41
24
 
42
- Adjust race performance based on heat, humidity and altitude. Calculations are based on scientific models
43
- (El Helou et al. 2012 and Ely et al. 2007 for heat, the Australian Bureau of Meteorology's
44
- simplified WBGT for humidity, NCAA standards for altitude).
45
-
46
- - **Altitude**: no penalty up to 300 m, then a linear ramp to the first NCAA point
47
- (914.4 m → 1.41%), the NCAA table up to 2438.4 m (5.90%), and an extrapolated
48
- curve beyond it (3000 m → 7.92%, 3500 m → 9.97%, 4000 m → 12.2%, capped there).
49
- São Paulo (760 m) gets ~1.06%.
50
- - **Heat**: a 60-minute baseline `4.3 · ((T − 15) / 10)^1.5` (0% at 15 °C,
51
- 1.52% at 20 °C, 4.3% at 25 °C, 7.9% at 30 °C; extrapolated to 12.16% at
52
- 35 °C and capped there, so 35–40 °C and hotter all read like 35 °C), stored
53
- as points every 2.5 °C, then
54
- scaled by effort duration: 0.5× up to 30 min, 1.0× at 60 min, 1.76× at 3 h,
55
- 2.81× at 4 h and beyond (linear in between, so 1.38× at 2 h). The exponent
56
- and the 3 h / 4 h points are fitted to El Helou et al. (2012, Table S3: eight
57
- finisher groups, 2:41–4:54, time penalty against 15 °C at 20 and 25 °C,
58
- which grows ~2.8× from 20 to 25 °C in every group); the derivation table is
59
- in `lib/calcpace/data/environmental_factors.yml`. The 25 °C / 60-minute
60
- anchor (4.3%) and the 30/60-minute factors have no direct published source.
61
- - **Humidity** (optional): pass `humidity:` (relative humidity, %) or
62
- `dew_point:` (in `temperature_unit`). Without either, the heat curve assumes
63
- 50% humidity. With one, the temperature is replaced by the effective
64
- temperature that has the same simplified WBGT (`0.567·Ta + 0.393·e + 3.94`)
65
- at 50% humidity, and `factors` reports it as `:effective_temperature_celsius`.
66
-
67
- | Heat penalty (%) | 20 min | 60 min | 120 min | 180 min | 240 min | 300 min |
68
- | --- | --- | --- | --- | --- | --- | --- |
69
- | 20 °C | 0.76 | 1.52 | 2.1 | 2.68 | 4.27 | 4.27 |
70
- | 25 °C | 2.15 | 4.3 | 5.93 | 7.57 | 12.08 | 12.08 |
71
- | 30 °C | 3.95 | 7.9 | 10.9 | 13.9 | 22.2 | 22.2 |
72
- | 35 °C | 6.08 | 12.16 | 16.78 | 21.4 | 34.17 | 34.17 |
73
- | 40 °C | 6.08 | 12.16 | 16.78 | 21.4 | 34.17 | 34.17 |
74
-
75
- | 30 °C at | Effective temperature | 60 min | 4 h |
76
- | --- | --- | --- | --- |
77
- | 30% RH | 26.69 °C | 5.46% | 15.34% |
78
- | 50% RH (= no humidity) | 30.0 °C | 7.9% | 22.2% |
79
- | 70% RH | 33.07 °C | 10.46% | 29.39% |
80
- | 90% RH | 35.94 °C (capped at 35 °C) | 12.16% | 34.17% |
81
-
82
- Above ~25 °C the numbers are extrapolations of the fitted curve: the marathon
83
- studies behind it have no data there (El Helou's hottest race was 25.2 °C). The
84
- cap at 35 °C is a deliberate choice for the same reason: the uncapped curve gave
85
- 47.77% for 4 h at 40 °C.
86
-
87
- ```ruby
88
- # Calculate penalty for 25°C and 2000m altitude (Defaults to 60-min effort)
89
- penalty = calc.calculate_penalty(temperature: 25, altitude: 2000)
90
- # => {
91
- # total_penalty_percent: 8.62,
92
- # factors: { heat: 4.3, altitude: 4.32 }
93
- # }
94
-
95
- # Fahrenheit support
96
- calc.calculate_penalty(temperature: 80, temperature_unit: :f)
97
- # => { total_penalty_percent: 5.44, ... }
98
-
99
- # Humidity: 30 °C at 90% hits like 35.94 °C at 50% (which reads like the 35 °C cap)
25
+ calc.clock_pace('01:00:00', 10) # => "00:06:00"
26
+ calc.predict_time_clock('5k', '00:27:12', 'marathon') # => "04:20:52"
100
27
  calc.calculate_penalty(temperature: 30, humidity: 90)[:total_penalty_percent] # => 12.16
101
- calc.calculate_penalty(temperature: 30, humidity: 90)[:factors][:effective_temperature_celsius] # => 35.94
102
- calc.calculate_penalty(temperature: 86, dew_point: 77, temperature_unit: :f)[:total_penalty_percent] # => 11.07
103
-
104
- # Adjust a 3:30 marathon time (12600s) for these conditions (High exposure penalty)
105
- result = calc.adjust_time(12600, temperature: 25, altitude: 2000)
106
- # => {
107
- # original_time: 12600,
108
- # adjusted_time: 14382.9,
109
- # adjusted_time_clock: "03:59:42",
110
- # penalty_percent: 14.15,
111
- # factors: { heat: 9.83, altitude: 4.32 }
112
- # }
113
-
114
- # Predicted adjusted times (Riegel formula)
115
- calc.predict_time_adjusted('5k', '00:20:00', '10k', temperature: 28)
116
- # => { adjusted_time: 2613.0, adjusted_time_clock: "00:43:33", penalty_percent: 4.44, ... }
117
-
118
- # Predicted adjusted times (Cameron formula)
119
- calc.predict_time_cameron_adjusted('10k', '00:40:00', 'marathon', temperature: 80, temperature_unit: :f)
120
- # => { adjusted_time: 12400.47, adjusted_time_clock: "03:26:40", penalty_percent: 10.28, ... }
121
- ```
122
-
123
- ---
124
-
125
- ### Unit Conversions
126
-
127
- 30+ units supported. String or symbol format:
128
-
129
- ```ruby
130
- calc.convert(10, :km_to_mi) # => 6.213711922...
131
- calc.convert(10, 'mi to km') # => 16.09344
132
- calc.convert(1, :m_s_to_km_h) # => 3.6
133
-
134
- # Chain conversions
135
- calc.convert_chain(1, [:km_to_mi, :mi_to_feet]) # => 3280.84
136
- ```
137
-
138
- See all units: `calc.list_all`, `calc.list_distance`, `calc.list_speed`.
139
-
140
- ---
141
-
142
- ### Pace Conversions
143
-
144
- ```ruby
145
- calc.pace_km_to_mi('05:00') # => "00:08:02"
146
- calc.pace_mi_to_km('08:00') # => "00:04:58"
147
- calc.convert_pace(300, :km_to_mi) # => "00:08:02"
148
- ```
149
-
150
- All three take a `compact:` keyword for the display format a runner reads on a
151
- screen, the same one `convert_to_clocktime` offers:
152
-
153
- ```ruby
154
- calc.pace_km_to_mi('05:00', compact: true) # => "8:02"
155
- calc.pace_mi_to_km(480, compact: true) # => "4:58"
156
- calc.convert_pace('05:00', :km_to_mi, compact: true) # => "8:02"
157
- ```
158
-
159
- ---
160
-
161
- ### Race Pace & Time
162
-
163
- Every method that takes a race accepts either a standard race name or a plain
164
- distance in kilometers — most races are not a 5K or a marathon.
165
-
166
- ```ruby
167
- calc.race_time_clock('05:00', 'marathon') # => "03:30:58"
168
- calc.race_pace_clock('04:00:00', 'marathon') # => "00:05:41"
169
- calc.list_races # => { '5k' => 5.0, '10k' => 10.0, 'half_marathon' => 21.0975, 'marathon' => 42.195, '100k' => 100.0, ... }
170
-
171
- # Any distance, named or not — 7.79 km and '7.79' mean the same thing
172
- calc.race_time_clock('05:00', 7.79) # => "00:38:57"
173
- calc.race_time_clock('05:00', '7.79') # => "00:38:57"
174
- calc.race_pace_clock('00:26:59', 7.79) # => "00:03:27"
175
- ```
176
-
177
- A distance must be positive (`Calcpace::NonPositiveInputError` otherwise), and
178
- anything that is neither a number nor a known race name still raises
179
- `ArgumentError` — `'7.79k'` is a typo, not a distance.
180
-
181
- ---
182
-
183
- ### Race Splits
184
-
185
- ```ruby
186
- # Even pace — default
187
- calc.race_splits('half_marathon', target_time: '01:30:00', split_distance: '5k')
188
- # => ["00:21:20", "00:42:40", "01:03:59", "01:25:19", "01:30:00"]
189
-
190
- # Strategies: :even (default), :negative (second half faster), :positive (first half faster)
191
- # :negative runs the first half 1% slower than average pace and the second half 1% faster;
192
- # :positive is the mirror image. A 3:00:00 marathon splits 1:30:54 + 1:29:06 (:negative).
193
- calc.race_splits('10k', target_time: '00:40:00', split_distance: '5k', strategy: :negative)
194
- # => ["00:20:12", "00:40:00"]
195
-
196
- # The race may be a plain distance too; the last split is always the finish
197
- calc.race_splits(7.79, target_time: '00:26:59', split_distance: '1k')
198
- # => ["00:03:28", "00:06:56", "00:10:23", "00:13:51", "00:17:19", "00:20:47", "00:24:15", "00:26:59"]
199
- ```
200
-
201
- ---
202
-
203
- ### Race Time Predictions
204
-
205
- **Riegel formula** (`T2 = T1 × (D2/D1)^1.06`):
206
-
207
- ```ruby
208
- calc.predict_time_clock('5k', '00:20:00', 'marathon') # => "03:11:49"
209
- calc.predict_pace_clock('5k', '00:20:00', 'marathon') # => "00:04:32"
210
- calc.equivalent_performance('10k', '00:42:00', '5k')
211
- # => { time: 1208.6727903498331, time_clock: "00:20:08", pace: 241.73455806996662, pace_clock: "00:04:01" }
212
- ```
213
-
214
- **Cameron formula** (Dave Cameron's velocity-ratio model, fitted to world bests from
215
- 800 m to the marathon — more conservative than Riegel when predicting the marathon
216
- from shorter races):
217
-
218
- `T2 = T1 × (D2/D1) × f(D1)/f(D2)`, with `f(d) = 13.49681 − 0.000030363·d + 835.7114 / d^0.7905`
219
- and `d` in metres (distances are still passed in km or as race names).
220
- Both distances must be at most `CameronPredictor::CAMERON_MAX_DISTANCE_KM` (100 km):
221
- the model is fitted up to the marathon and breaks down far beyond it, so longer
222
- distances raise `ArgumentError`.
223
-
224
- ```ruby
225
- calc.predict_time_cameron_clock('10k', '00:42:00', 'marathon') # => "03:16:46"
226
- calc.predict_pace_cameron_clock('10k', '00:42:00', 'marathon') # => "00:04:39"
227
- ```
228
-
229
- **Any distance, on either end.** Both formulas are arithmetic on two distances,
230
- so neither end has to be a standard race:
231
-
232
- ```ruby
233
- # From a 7.79 km club race in 26:59
234
- calc.predict_time_clock(7.79, '00:26:59', 'half_marathon') # => "01:17:34"
235
- calc.predict_time_cameron_clock(7.79, '00:26:59', 'half_marathon') # => "01:17:26"
236
-
237
- # To an unnamed distance, and between two of them
238
- calc.predict_time_clock('10k', '00:42:00', 15) # => "01:04:33"
239
- calc.predict_time_clock(7.79, '00:26:59', 15) # => "00:54:02"
240
-
241
- calc.equivalent_performance(7.79, '00:26:59', '10k')
242
- # => { time: 2109.682710043339, time_clock: "00:35:09", pace: 210.96827100433387, pace_clock: "00:03:30" }
243
- ```
244
-
245
- Predicting a distance from itself has no answer, so it raises — for a name, a
246
- number, or one of each:
247
-
248
- ```ruby
249
- calc.predict_time(10.0, 2520, '10k')
250
- # => ArgumentError: From and to races must be different distances (both are 10.0km)
251
- ```
252
-
253
- Both formulas were fitted around race distances and degrade as the jump grows:
254
- a marathon predicted from a 1 km time is arithmetic, not a forecast. The gem
255
- computes what you ask for and does not second-guess the gap — that judgement is
256
- the caller's, and it always was, standard race names included.
257
-
258
- ---
259
-
260
- ### Personalized Predictions
261
-
262
- **Marathon from training volume** — Tanda (2011), no race result needed. The
263
- inputs are the mean weekly distance and the mean training pace over the 8 weeks
264
- ending one week before the race:
265
-
266
- ```ruby
267
- calc.predict_marathon_from_training(weekly_distance: 60, training_pace: '05:00')
268
- # => { time: 11981.88, time_clock: "03:19:41", pace: 283.96, pace_clock: "00:04:43",
269
- # within_validated_range: true, out_of_range: [] }
270
-
271
- calc.predict_marathon_from_training(weekly_distance: 40, training_pace: '05:30')
272
- # => { time: 13158.72, time_clock: "03:39:18", pace: 311.86, pace_clock: "00:05:11",
273
- # within_validated_range: false, out_of_range: [:weekly_distance, :marathon_time] }
274
-
275
- # unit: :mi — weekly miles, pace per mile in and out
276
- calc.predict_marathon_from_training(weekly_distance: 25, training_pace: '08:00', unit: :mi)[:pace_clock] # => "00:07:53"
28
+ calc.race_splits('10k', target_time: '00:40:00', split_distance: '5k', strategy: :negative) # => ["00:20:12", "00:40:00"]
29
+ calc.estimate_vo2max(10.0, '00:40:00') # => 51.9
30
+ calc.age_grade(10.0, '00:45:00', age: 55, sex: :male)[:age_grade_percent] # => 68.9
31
+ calc.training_paces(50.0)[:threshold].fast_clock # => "00:04:15"
277
32
  ```
278
33
 
279
- The equation is `Pm = 17.1 + 140.0 · exp(−0.0053 · K) + 0.55 · P` (Pm marathon
280
- pace in s/km, K km/week, P s/km). Training pace is the plain average of every
281
- run — total time over total distance, warm-ups and easy days included — not the
282
- pace of the hard sessions. The paper reports a standard error of about 4 minutes.
283
- `weekly_distance` may be a number or a numeric string (`'60'`); `training_pace`
284
- is seconds or an `MM:SS` / `HH:MM:SS` string.
285
-
286
- It was fitted on 22 experienced runners (21 men) and 46 marathons, so it is only
287
- validated inside that sample: 40.4–110.7 km/week, training pace 253.3–330.6 s/km (4:13–5:30/km),
288
- finish 2:47–3:36. Outside it the prediction is still returned, and
289
- `out_of_range` names what fell outside (`:weekly_distance`, `:training_pace`,
290
- `:marathon_time`) — a warning, not an error. A low-volume runner at an easy pace
291
- will usually see all three.
292
-
293
- > G. Tanda, "Prediction of marathon performance time on the basis of training
294
- > indices", *Journal of Human Sport and Exercise* 6(3):511–520, 2011.
295
- > doi:10.4100/jhse.2011.63.05
296
-
297
- **Personal Riegel exponent** — fit the fatigue factor to two of your own races
298
- instead of the population 1.06:
299
-
300
- ```ruby
301
- calc.riegel_exponent('10k', '00:45:00', 'half_marathon', '01:42:00') # => 1.0961
302
-
303
- calc.predict_time_personal('10k', '00:45:00', 'half_marathon', '01:42:00', 'marathon')
304
- # => { time: 13083.04, time_clock: "03:38:03", exponent: 1.0961, raw_exponent: 1.0961, clamped: false }
305
- ```
306
-
307
- The standard Riegel gives 3:32:39 from that half and 3:27:00 from that 10K; this
308
- runner fades more than average, and the personal exponent says so.
309
-
310
- When the target lies outside the two races, the prediction extrapolates from
311
- whichever race is closer to it (in log-distance), with the exponent clamped to
312
- 1.01–1.20:
313
-
314
- ```ruby
315
- calc.predict_time_personal('5k', '00:20:00', '10k', '00:50:00', 'half_marathon')
316
- # => { time: 7348.5, time_clock: "02:02:28", exponent: 1.2, raw_exponent: 1.3219, clamped: true }
317
- ```
318
-
319
- When the target lies between them, it interpolates along the curve through both
320
- performances with the raw exponent, never clamped: the runner's own data
321
- already brackets the answer, and the result does not depend on which race comes
322
- first.
323
-
324
- ```ruby
325
- calc.predict_time_personal(5, 1200, 20, 3000, 10)[:time] # => 1897.37
326
- calc.predict_time_personal(20, 3000, 5, 1200, 10)[:time] # => 1897.37
327
- ```
328
-
329
- An exponent outside that range — or `clamped: true` — usually means one of the
330
- two races was not an all-out effort, or was run on a course or day that does
331
- not compare with the other — the raw exponent in an interpolation
332
- (0.661 above) is worth the same suspicion. Both races may be names or distances
333
- in km; two races at the same distance, or a target equal to one of them, raise
334
- `ArgumentError`. Times are seconds or `HH:MM:SS` / `MM:SS` strings; anything
335
- else raises `Calcpace::InvalidTimeFormatError`.
336
-
337
- ---
338
-
339
- ### GPS Track Analysis
340
-
341
- Accepts an array of hashes with `:lat`, `:lon`, and optionally `:ele` (metres) and `:time` (`Time`):
342
-
343
- ```ruby
344
- points = [
345
- { lat: -23.5505, lon: -46.6333, ele: 760.0, time: Time.parse('2024-01-01 07:00:00') },
346
- { lat: -23.5510, lon: -46.6400, ele: 765.0, time: Time.parse('2024-01-01 07:05:00') },
347
- { lat: -23.5520, lon: -46.6480, ele: 758.0, time: Time.parse('2024-01-01 07:10:00') },
348
- ]
349
-
350
- calc.haversine_distance(-23.5505, -46.6333, -23.5510, -46.6340)
351
- # => 0.09045636644035066 (km)
352
-
353
- calc.track_distance(points) # => 1.51 (km)
354
- calc.elevation_gain(points) # => { gain: 5.0, loss: 7.0 }
355
-
356
- calc.track_splits(points, 1.0)
357
- # => [{ km: 1.0, elapsed: 415, pace: "06:55" },
358
- # { km: 1.51, elapsed: 600, pace: "06:04" }]
359
-
360
- # Compact pace for display; :km and :elapsed are unchanged
361
- calc.track_splits(points, 1.0, compact: true)
362
- # => [{ km: 1.0, elapsed: 415, pace: "6:55" },
363
- # { km: 1.51, elapsed: 600, pace: "6:04" }]
364
- ```
34
+ ## What's in it
365
35
 
366
- The last entry is the partial split — the leftover distance after the last full
367
- one, so its `:km` is the track total rather than a multiple of `split_km`.
36
+ Every method, with examples, is in the **[usage guide](https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md)**:
368
37
 
369
- Two things to know about `compact:` here. A split slower than an hour per unit
370
- is where the formats stop differing by padding alone: the padded one keeps
371
- counting minutes (`"66:33"`), as `track_splits` always has, while the compact
372
- one rolls them into an hour field (`"1:06:33"`). And a track that steps
373
- backwards in time — a watch resyncing its clock, a paused device, two segments
374
- merged out of order — produces a negative split, reported with a leading minus
375
- in both formats (`"-00:40"` / `"-0:40"`) rather than raising.
376
-
377
- **Haversine formula** — great-circle distance on a sphere (R = 6,371 km). Accuracy: ~0.3% of GPS/WGS84. Best for running and cycling distances; not for geodetic surveying.
378
-
379
- #### Grade-adjusted pace (GAP)
380
-
381
- The flat-ground pace that costs the same energy as a pace run on a slope, from
382
- the energy cost of running on gradients measured by **Minetti et al. (2002)**.
383
- The grade is a fraction (rise over horizontal distance): `0.05` is 5% uphill,
384
- `-0.05` is 5% downhill.
385
-
386
- ```ruby
387
- calc.grade_adjustment_factor(0.1) # => 1.6578372222222222 (a metre at +10% ≈ 1.66 flat metres)
388
- calc.grade_adjustment_factor(-0.1) # => 0.5976961111111111
389
-
390
- calc.grade_adjusted_pace(360, 0.1) # => 217.1503903847952 (s/km)
391
- calc.grade_adjusted_pace_clock('06:00', 0.1) # => "00:03:37"
392
- calc.grade_adjusted_pace_clock('06:00', 0.1, compact: true) # => "3:37"
393
- calc.grade_adjusted_pace(480, 0.05, unit: :mi) # => 368.82127811700303 (s/mi)
394
-
395
- # Per-split GAP for a GPS track: the track_splits fields plus :gap
396
- calc.track_grade_adjusted_splits(points, 1.0)
397
- # => [{ km: 1.0, elapsed: 415, pace: "06:55", gap: "06:50" },
398
- # { km: 1.51, elapsed: 600, pace: "06:04", gap: "06:21" }]
399
- ```
400
-
401
- | Grade | −10% | −5% | 0% | +5% | +10% |
402
- |-------|------|-----|----|-----|------|
403
- | Factor | 0.598 | 0.763 | 1.000 | 1.301 | 1.658 |
404
-
405
- **Formula** (J·kg⁻¹·m⁻¹, R² = 0.999):
406
- ```
407
- Cr(i) = 155.4·i⁵ − 30.4·i⁴ − 43.3·i³ + 46.3·i² + 19.5·i + 3.6
408
- factor = Cr(i) / Cr(0)
409
- GAP = pace / factor
410
- ```
411
-
412
- - Grades are clamped to **±45%**, the range Minetti et al. measured; nothing
413
- is extrapolated beyond it. Running is cheapest near −20% and gets dearer
414
- again on steeper descents.
415
- - It is a metabolic model: it does not see the muscular cost of long descents
416
- or technical terrain, and field models fitted to heart rate (Strava's, for
417
- instance) are gentler on steep climbs.
418
- - `track_grade_adjusted_splits` leaves `track_splits` untouched: it returns the
419
- same `:km`, `:elapsed` and `:pace` with `:gap` added (formatted like `:pace`,
420
- `compact:` applies to both). GPS elevation is noisy, so grades are measured
421
- over **grade segments of at least 100 m** of horizontal distance — read
422
- between fixes a metre apart, ±2 m of jitter would be a ±400% grade. A short
423
- leftover at the end of a stretch joins the segment before it. Stretches
424
- between points without `:ele` (or with a NaN/infinite one) count as flat,
425
- so a track with no elevation has `:gap` equal to `:pace`; so does a stretch
426
- with elevation shorter than 100 m that has no full segment before it to
427
- join (between missing fixes, or a whole track that short).
428
- - Track distances are horizontal (Haversine), and the factor is applied to
429
- them without the √(1 + grade²) slope-length correction — 0.5% at 10%.
430
- - `estimate_detailed_vo2max` keeps its own flat elevation heuristic (100 m of
431
- gain = 600 m of flat), so its numbers do not change.
432
-
433
- *Minetti, A. E., Moia, C., Roi, G. S., Susta, D., & Ferretti, G. (2002). Energy cost of walking and running at extreme uphill and downhill slopes. Journal of Applied Physiology, 93(3), 1039–1046. https://doi.org/10.1152/japplphysiol.01177.2001*
434
-
435
- ---
436
-
437
- ### Age Grading (Road Races)
438
-
439
- Age grading compares race results across different ages and sexes by using
440
- age factors and open standards.
441
-
442
- ```ruby
443
- result = calc.age_grade(10.0, '00:45:00', age: 55, sex: :male)
444
- # numeric distances also accepted in miles: calc.age_grade(6.21371, '00:45:00', age: 55, sex: :male, distance_unit: :mi)
445
- # => {
446
- # age_grade_percent: 68.9,
447
- # category: "Local Class",
448
- # age_graded_time_seconds: 2297.97,
449
- # age_graded_time_clock: "00:38:17",
450
- # open_standard_seconds: 1584.0,
451
- # open_standard_clock: "00:26:24",
452
- # factor: 0.8511,
453
- # table_version: "MLDR_2025_ROAD_ONE_YEAR_FACTORS_V1"
454
- # }
455
-
456
- calc.age_grade_percent(5.0, '00:22:30', age: 40, sex: :female) # => 65.0
457
- calc.age_grade_label(65.0) # => "Local Class"
458
- ```
459
-
460
- `category` (and `age_grade_label`) returns one of:
461
-
462
- | Age grade | Category |
38
+ | Area | What it does |
463
39
  | --- | --- |
464
- | 100%+ | Approximate World Record Level |
465
- | 90–99.9% | World Class |
466
- | 80–89.9% | National Class |
467
- | 70–79.9% | Regional Class |
468
- | 60–69.9% | Local Class |
469
- | 50–59.9% | Intermediate |
470
- | 40–49.9% | Recreational |
471
- | below 40% | Active Beginner |
472
-
473
- The Alan Jones road tables are numeric age factors and open
474
- standards only — they define no categories at all. The bands from Local Class
475
- (60%) upward follow the USATF Masters / National Masters News convention; the
476
- three bands below 60% are calcpace's own extension — most recreational
477
- runners land there, and one catch-all label for everybody under 60% tells
478
- them nothing.
479
-
480
- The bands apply to the percentage as reported by `age_grade`, rounded to one
481
- decimal, so calling `age_grade_label` directly on an unrounded value can land
482
- one band lower at an edge.
483
-
484
- Supported distances: 5K, 10K, half marathon, marathon.
485
-
486
- A numeric distance within **2%** of one of those is graded as that standard —
487
- a GPS watch rarely reads a 5K as exactly 5.000 km:
488
-
489
- ```ruby
490
- calc.age_grade_percent(5.0, '00:25:00', age: 40, sex: :male) # => 54.1
491
- calc.age_grade_percent(5.0374, '00:25:00', age: 40, sex: :male) # => 54.1
492
-
493
- calc.age_grade(7.79, '00:26:59', age: 36, sex: :male)
494
- # => ArgumentError: Unsupported distance 7.79km. Supported: 5.0, 10.0, 21.0975, 42.195 km
495
- ```
496
-
497
- That refusal is deliberate, and it is where age grading parts ways with the
498
- predictors above. A prediction is a formula and works at any distance; an age
499
- grade is a lookup in the road table, which publishes a factor per *specific*
500
- distance. There is no world standard for 7.79 km, so there is no honest
501
- percentage to return — interpolating one would produce a number with the look
502
- of an official standard and none of the authority.
503
-
504
- Age factors and open standards come from Alan Jones' **2025 road** age-grading
505
- tables, approved on 2025-01-10 by the USATF Masters Long Distance Running
506
- Council — the standard for road races, the same tables behind Howard Grubb's
507
- MLDR road calculator. The source spreadsheets are `MaleRoadStd2025.xlsx` and
508
- `FemaleRoadStd2025.xlsx`, linked here at the commit the bundled data was
509
- taken from:
510
- https://github.com/AlanLyttonJones/Age-Grade-Tables/tree/4aac6737cb9f216c90a0a610355667cd3d921c61/2025%20Files
511
- The bundled data has one factor per year of age from 18 to 100 (older ages use
512
- the age-100 factor) and lives in `lib/calcpace/data/mldr_2025_road.yml` (factors)
513
- and `lib/calcpace/data/mldr_2025_road_open_standards.yml` (open standards and
514
- category labels).
515
-
516
- | Distance | Open standard (men) | Open standard (women) |
517
- | --- | --- | --- |
518
- | 5K | 12:49 | 13:54 |
519
- | 10K | 26:24 | 28:46 |
520
- | Half marathon | 57:31 | 1:02:52 |
521
- | Marathon | 2:00:35 | 2:09:56 |
522
-
523
- Field meanings:
524
- - `age_graded_time_clock`: your result after applying the age factor (normalized performance time).
525
- - `open_standard_clock`: the open standard reference time used to compute the percentage for that distance/sex.
526
- - `age_grade_percent`: `(open_standard_seconds / age_graded_time_seconds) * 100`.
527
-
528
- ---
529
-
530
- ### VO2max Estimation
531
-
532
- Estimate aerobic fitness from a race result using the **Daniels & Gilbert formula** (1979):
533
-
534
- ```ruby
535
- calc.estimate_vo2max(10.0, '00:40:00') # => 51.9 ml/kg/min
536
- calc.estimate_vo2max(42.195, '03:30:00') # => 44.6
537
- calc.estimate_vo2max(5.0, 2400) # also accepts total seconds
538
- calc.estimate_vo2max(6.21371, '00:40:00', distance_unit: :mi) # => 51.9 (miles input)
539
-
540
- calc.vo2max_label(51.9) # => "Very Good"
541
- ```
542
-
543
- | VO2max (ml/kg/min) | Level |
544
- |--------------------|-----------|
545
- | ≥ 70 | Elite |
546
- | 60–69 | Excellent |
547
- | 50–59 | Very Good |
548
- | 40–49 | Good |
549
- | 30–39 | Fair |
550
- | < 30 | Beginner |
551
-
552
- *Thresholds based on Daniels, J. (2014). Daniels' Running Formula (3rd ed.), consistent with ACSM guidelines and McArdle, Katch & Katch (2015) Exercise Physiology.*
553
-
554
- **Formula:**
555
- ```
556
- velocity (m/min) = distance_m / time_min
557
- VO2 = −4.60 + 0.182258·v + 0.000104·v²
558
- %VO2max = 0.8 + 0.1894393·e^(−0.012778·t) + 0.2989558·e^(−0.1932605·t)
559
- VO2max = VO2 / %VO2max
560
- ```
561
-
562
- Accuracy: ±3–5 ml/kg/min vs. laboratory testing. Best with efforts between **5 and 60 minutes** at near-maximal pace.
563
-
564
- #### By age and sex
565
-
566
- The fixed thresholds above are the same for everyone. Give `vo2max_label` an
567
- age and a sex and it reads the value against people of the same sex and age
568
- decade instead, using the **FRIEND registry** percentiles of VO2max measured on
569
- a treadmill (Kaminsky, Arena & Myers, 2015):
570
-
571
- ```ruby
572
- calc.vo2max_label(45) # => "Good" (fixed thresholds, unchanged)
573
- calc.vo2max_label(45, age: 25, sex: :male) # => "Fair"
574
- calc.vo2max_label(45, age: 60, sex: :male) # => "Elite"
575
- calc.vo2max_label(45, age: 25, sex: :female) # => "Very Good"
576
- calc.vo2max_label(45, age: 60, sex: :female) # => "Elite"
577
-
578
- calc.vo2max_percentile(45, age: 25, sex: :male) # => 40.5
579
- calc.vo2max_percentile(45, age: 25, sex: :female) # => 75.7
580
- calc.vo2max_percentile(45, age: 60, sex: :male) # => 95.0
581
- ```
582
-
583
- | Percentile (same sex and age decade) | Level |
584
- |--------------------------------------|-----------|
585
- | ≥ 95th | Elite |
586
- | 90th–94th | Excellent |
587
- | 75th–89th | Very Good |
588
- | 50th–74th | Good |
589
- | 25th–49th | Fair |
590
- | < 25th | Beginner |
591
-
592
- - The cuts sit on percentiles the table publishes (5th, 10th, 25th, 50th,
593
- 75th, 90th, 95th), so a label never depends on interpolation. They are
594
- calcpace's choice: FRIEND publishes percentiles, not labels.
595
- - `vo2max_percentile` interpolates linearly between the published percentiles,
596
- rounded to one decimal, and is bounded to the table: `5.0` means at or below
597
- the 5th percentile, `95.0` at or above the 95th.
598
- - Age decades (20–29 … 70–79) are used as published, without blending, so a
599
- 29- and a 30-year-old read different rows. Ages 18–19 use the 20–29 row and
600
- 80+ the 70–79 row; under 18 raises `ArgumentError`, as does a sex other than
601
- male/female. Age and sex must be given together.
602
- - The registry measured VO2max in a lab; a VO2max estimated from a race time
603
- carries its own ±3–5 ml/kg/min on top.
604
-
605
- *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 (rows "Men/Women from FRIEND"; 7,783 treadmill tests on adults free of known cardiovascular disease). https://doi.org/10.1016/j.mayocp.2015.07.026. The same table also lists the Cooper Clinic norms printed in ACSM's Guidelines for Exercise Testing and Prescription (9th ed., 2014); those are predicted from treadmill time rather than measured, and are not used here.*
606
-
607
- #### Contextualized estimation
608
-
609
- `estimate_detailed_vo2max` returns a richer result that accounts for elevation, heart rate, and formula reliability:
610
-
611
- ```ruby
612
- # Mountain 10K: 200 m elevation gain, avg HR 172, max HR 190
613
- result = calc.estimate_detailed_vo2max(
614
- 10.0, '00:48:30',
615
- elevation_gain_m: 200,
616
- hr_avg: 172,
617
- hr_max: 190
618
- )
619
-
620
- result.value # => 47.7 (corrected for 1.2 km of equivalent flat distance)
621
- result.adjusted_distance_km # => 11.2 (10 km + 200 m × 6 flat-equivalent)
622
- result.confidence # => :high (48 min is inside the 5–60 min optimal window)
623
- result.sub_maximal # => false (172/190 = 90.5 % HRmax → maximal effort)
624
-
625
- calc.vo2max_label(result.value) # => "Good"
626
-
627
- # Compare: same effort ignoring elevation → underestimates VO2max
628
- flat = calc.estimate_detailed_vo2max(10.0, '00:48:30')
629
- flat.value # => 41.5
630
-
631
- # Easy recovery run: sub-maximal effort flag + confidence downgrade
632
- easy = calc.estimate_detailed_vo2max(10.0, '01:05:00', hr_avg: 135, hr_max: 190)
633
- easy.sub_maximal # => true (135/190 = 71 % HRmax < 85 %)
634
- easy.confidence # => :low (formula assumes race-pace effort)
635
- easy.value # => 29.3 (underestimates real aerobic capacity)
636
- ```
637
-
638
- | `confidence` | Effort duration | Notes |
639
- |---|---|---|
640
- | `:high` | 5–60 min | Daniels & Gilbert optimal window |
641
- | `:medium` | > 60–120 min | Muscular fatigue starts distorting the estimate |
642
- | `:low` | < 5 min or > 120 min | Anaerobic / glycogen-depletion effects dominate |
643
-
644
- > If `hr_avg > hr_max`, a `Calcpace::Error` is raised (physiologically impossible input).
645
- > If you provide heart rate data, both `hr_avg` and `hr_max` must be present.
646
- > `elevation_gain_m` must be zero or positive.
647
-
648
- `result.basis` says what set the confidence: `:duration` (the table above), `:heart_rate` (average HR under 85 % of max) or `:declared` (the `effort:` below).
649
-
650
- #### Effort
651
-
652
- The formula assumes an all-out effort, and duration is only a proxy for that. When the runner knows how hard it was, pass `effort:` — one of `Calcpace::EFFORT_LEVELS`, easiest first (a Symbol or a String):
653
-
654
- | `effort` | How it felt | `confidence` | `sub_maximal` |
655
- |---|---|---|---|
656
- | `:easy` | Could talk freely | `:low` | `true` |
657
- | `:moderate` | Short sentences, still comfortable | `:low` | `true` |
658
- | `:hard` | A few words at a time | duration and heart-rate rules, as without `effort:` | |
659
- | `:max` | Everything I had: a race or a test | `:high` from 5 min on, however long it took (unless HR < 85 %) | `false` (unless HR < 85 %) |
660
- | `nil` (default) | — | exactly as in 2.0.0 | |
661
-
662
- ```ruby
663
- calc.estimate_detailed_vo2max(42.195, '03:30:00').confidence # => :low (over 2 h)
664
- calc.estimate_detailed_vo2max(42.195, '03:30:00', effort: :max).confidence # => :high (a race says it was all-out)
665
- calc.estimate_detailed_vo2max(10.0, '00:55:00', effort: :easy).sub_maximal # => true
666
- calc.estimate_detailed_vo2max(10.0, '00:55:00', effort: :easy).basis # => :declared
667
- ```
668
-
669
- - **The value never changes.** An easy run still gives the number the formula gives, which then reads as "at least this much"; only `confidence`, `sub_maximal` and `basis` move.
670
- - An easy or moderate effort is sub-maximal whatever the heart rate says. Heart rate under 85 % of max still overrules a declared `:max` (`basis: :heart_rate`), and a `:max` under five minutes keeps the duration rule, where the formula itself is unreliable.
671
- - Without heart rate, `:hard` and `:max` are not sub-maximal: nothing says they were.
672
- - An unknown effort raises `Calcpace::InvalidEffortError`.
673
-
674
- ---
675
-
676
- ### Training Zones
677
-
678
- Personalized training paces (Daniels' Running Formula) and Karvonen heart-rate zones:
679
-
680
- ```ruby
681
- zones = calc.training_paces(50.0)
682
- zones[:threshold].fast_clock # => "00:04:15" per km
683
- zones[:easy].slow_clock # => "00:05:52" per km
684
- zones[:marathon].fast_clock # => "00:04:31" per km (the VDOT-predicted marathon pace)
685
-
686
- calc.training_paces(50.0, unit: :mi)[:threshold].fast_clock # => "00:06:51" per mile
687
-
688
- calc.training_paces_from_race(10.0, '00:40:00') # from a recent race result
689
- calc.training_paces_from_race('5mile', '00:35:00', unit: :mi) # race names work too
690
- calc.training_paces_from_race(6.2, '00:40:00', distance_unit: :mi, unit: :mi) # race distance in miles
691
-
692
- calc.hr_zones(hr_max: 190, hr_rest: 55)
693
- # => [#<struct zone=1, min_bpm=123, max_bpm=136>, ... zone=5, max_bpm=190]
694
-
695
- calc.hr_zones_from_max(hr_max: 190)
696
- # => [#<struct zone=1, min_bpm=95, max_bpm=114>, ... zone=5, max_bpm=190]
697
- # %HRmax fallback — prefer hr_zones (Karvonen) when resting HR is known
698
- ```
699
-
700
- | Zone | %VO2max | Purpose |
701
- |------|---------|---------|
702
- | Easy | 59–74% | Base building, recovery |
703
- | Marathon | 75% – predicted marathon pace (0.800–0.849) | Marathon race pace |
704
- | Threshold | 83–88% | Lactate threshold, tempo runs |
705
- | Interval | 95–100% | VO2max development |
706
- | Repetition | 105–110% | Speed and running economy |
707
-
708
- Pace accuracy vs published VDOT tables: within a few seconds per km
709
- (threshold matches exactly; easy band is a range heuristic). The fast end of the
710
- marathon band is the marathon pace `predict_time_from_vo2max` gives for the same
711
- VO2max (Daniels' M pace is the predicted marathon race pace); that prediction
712
- covers VO2max 10–100, and outside it the race-pace intensity of the nearest bound
713
- is used. That intensity is 0.800–0.849 of VO2max (0.805 at VO2max 30, 0.830 at 70),
714
- so the marathon band stays slower than the threshold band below VO2max ~69.5, as in
715
- Daniels. `TRAINING_INTENSITIES[:marathon][:high]` stays 0.84 as the nominal upper
716
- bound; `PREDICTED_RACE_PACE_ZONES` lists the zones whose fast end is the predicted
717
- race pace.
718
-
719
- `unit:` sets the unit of the returned pace bands; `distance_unit:` sets the unit of a
720
- numeric race distance you pass in. Combining `distance_unit:` with a race name raises
721
- `ArgumentError` — `'10k'` already carries its own distance. Mile bands are computed
722
- natively (not converted from the km bands), so they can differ by ±1 s from
723
- `pace_km_to_mi(km_band)`.
724
-
725
- All mile factors derive from the exact international mile (1609.344 m), so distances,
726
- pace bands, and age-grading tolerances agree to the metre.
727
-
728
- #### Time in heart-rate zones
729
-
730
- `time_in_zones` splits a recorded heart-rate series into the time spent in each zone.
731
- It takes two plain arrays and the zones, so a Strava `heartrate`/`time` stream pair
732
- fits without translation, and so does the same pair read out of a FIT file:
733
-
734
- ```ruby
735
- zones = calc.hr_zones_from_max(hr_max: 190)
736
-
737
- in_zones = calc.time_in_zones(
738
- heartrate: [120, 120, 140, 140, 160],
739
- time: [0, 60, 120, 180, 240],
740
- zones: zones
741
- )
742
-
743
- in_zones.map(&:seconds) # => [0, 120, 120, 60, 0]
744
- in_zones.map(&:share) # => [0.0, 0.4, 0.4, 0.2, 0.0]
745
- in_zones[1].zone # => 2
746
-
747
- # The same call in one line, if you would rather not name the zones
748
- calc.time_in_zones(heartrate: [120, 140], time: [0, 60], zones: calc.hr_zones_from_max(hr_max: 190)).map(&:seconds) # => [0, 60, 60, 0, 0]
749
- calc.time_in_zones(heartrate: [120, 140], time: [0, 60], zones: calc.hr_zones_from_max(hr_max: 190)).map(&:share) # => [0.0, 0.5, 0.5, 0.0, 0.0]
750
- ```
751
-
752
- Five rows always come back, in zone order, zeros included — `seconds` whole, `share`
753
- a fraction of the counted time with three decimals. The shares are whole thousandths
754
- that add up to 1000 — rounded together, largest remainder first — so a bar chart
755
- drawn from them fills its track (the Float sum may sit one ulp from 1.0).
756
-
757
- **A sample lasts until the next one** (`time[i + 1] - time[i]`), and the last sample,
758
- which has no next, is given the previous delta so a series does not lose its final
759
- seconds; a single sample lasts 0 s.
760
-
761
- That rule has a consequence worth knowing before trusting the numbers. **A pause is a
762
- gap in `time`, and the whole gap is booked to the sample before it** — stop five
763
- minutes at a café and those five minutes land in whatever zone the last beat before
764
- the pause was in. There is no `max_gap` here to guess a cut-off with. If you have
765
- Strava's `moving` stream, nil the heart rate of every paused sample before calling,
766
- which hands them to the next rule.
767
-
768
- A sample with a nil or non-positive heart rate contributes nothing: its duration is
769
- **dropped, not reassigned**, because a dropout says nothing about which zone the
770
- runner was in — so the counted time can be less than the wall clock, and the shares
771
- are shares of what was counted.
772
-
773
- Mismatched array lengths, a series that is not an array, a nil inside `time`, a
774
- `time` that goes backwards, or a heart rate that is neither nil nor a number all
775
- raise `Calcpace::Error`. Empty arrays return the five zero rows.
776
-
777
- #### Which zone is this beat in?
778
-
779
- `hr_zone_for` is the lookup `time_in_zones` uses, exposed on its own:
780
-
781
- ```ruby
782
- calc.hr_zone_for(150, calc.hr_zones_from_max(hr_max: 190)).zone # => 3
783
- calc.hr_zone_for(114, calc.hr_zones_from_max(hr_max: 190)).zone # => 2
784
- calc.hr_zone_for(205, calc.hr_zones_from_max(hr_max: 190)).zone # => 5
785
- ```
786
-
787
- It returns the `HrZone`, or nil when the reading is nil or not positive — a sensor
788
- dropout. Two rules are worth stating because a hand-rolled `between?` lookup gets
789
- both wrong:
790
-
791
- - **On a shared boundary the higher zone wins.** Zones are contiguous, so 114 bpm is
792
- both the top of Z1 and the bottom of Z2; it counts as Z2, the way a watch reads it.
793
- - **Readings outside the range are clamped**, below Z1 to Z1 and above Z5 to Z5. A
794
- reading above `hr_max` means the `hr_max` is wrong, not that the beat did not
795
- happen — and an `hr_max` a few beats off is the most common thing an athlete
796
- carries around. Clamping keeps that a distortion of the split instead of making
797
- minutes of a run disappear.
798
-
799
- ---
800
-
801
- ### Lap Analysis
802
-
803
- A watch records laps; it does not record intent. `interval_structure` reads the shape
804
- of a session out of the laps themselves, by **contrast** — never by a label:
805
-
806
- ```ruby
807
- # Warm-up, 6 x (1 km hard / 400 m jog), cool-down
808
- laps = [{ distance: 2.0, elapsed: 720 }] +
809
- ([{ distance: 1.0, elapsed: 252 }, { distance: 0.4, elapsed: 156 }] * 6) +
810
- [{ distance: 1.5, elapsed: 495 }]
811
-
812
- structure = calc.interval_structure(laps)
813
- # => #<struct reps=6, work_distance=1.0, ... rest_duration=156>
814
-
815
- structure.reps # => 6
816
- structure.work_distance # => 1.0 (km, median rep)
817
- structure.work_pace # => 252 (seconds per km, distance-weighted)
818
- structure.rest_pace # => 390
819
- structure.rest_duration # => 156 (mean rest lap, seconds)
820
- ```
821
-
822
- `to_a` gives all five at once, which is short enough to show whole. This is the
823
- smallest session that has a structure — two reps and the jog between them:
824
-
825
- ```ruby
826
- calc.interval_structure([{ distance: 1.0, elapsed: 252 }, { distance: 0.4, elapsed: 156 }, { distance: 1.0, elapsed: 252 }]).to_a # => [2, 1.0, 252, 390, 156]
827
-
828
- # unit: converts both paces; distances stay in kilometres
829
- calc.interval_structure([{ distance: 1.0, elapsed: 252 }, { distance: 0.4, elapsed: 156 }, { distance: 1.0, elapsed: 252 }], unit: :mi).to_a # => [2, 1.0, 406, 628, 156]
830
- ```
831
-
832
- Laps are plain hashes of a distance in kilometres and an elapsed time in seconds —
833
- what a Strava lap, a FIT lap and a hand-written array all reduce to. Distance `0` is
834
- legal: it is a standing recovery, and it means an infinite pace.
835
-
836
- A lap counts as **work** when it covers at least 0.1 km and is at least 15% faster
837
- than every lap touching it. Everything before the first work lap is warm-up,
838
- everything after the last is cool-down, and a lap between two work laps is rest. Two
839
- work laps can never touch — each would have to be 0.85 of the other — so every pair
840
- of reps has a recovery between it.
841
-
842
- An **edge lap** — the first or the last — has only one neighbour, so contrast alone
843
- is a free pass: a 5:30/km cool-down beats the 6:30/km jog it happens to touch and
844
- walks in as an extra rep. So an edge lap is admitted only if it also agrees with the
845
- reps found in the middle: within ±25% of their median distance, and no more than 10%
846
- slower than their pace. When the interior found nothing there is nothing to agree
847
- with, and the plain contrast rule stands — which is why the three-lap example above
848
- still reads as two reps.
849
-
850
- The method returns **nil** when the laps describe no structure, and most runs do not:
851
-
852
- ```ruby
853
- # A steady 10 km, ten laps of 1 km within five seconds of each other
854
- steady = [300, 298, 302, 296, 304, 300, 299, 301, 305, 295].map do |elapsed|
855
- { distance: 1.0, elapsed: elapsed }
856
- end
857
-
858
- calc.interval_structure(steady) # => nil
859
-
860
- # An easy 3 km with two red lights: fast next to a pause is not a rep
861
- calc.interval_structure([{ distance: 1.0, elapsed: 300 }, { distance: 0.0, elapsed: 45 }, { distance: 1.0, elapsed: 300 }]) # => nil
862
- ```
863
-
864
- Nil is returned when there are fewer than two work laps, when the work laps disagree
865
- about distance — more than ±25% from their median makes it a fartlek or a hilly run,
866
- which has fast laps but no set to report — or when **no work lap ever beat a finite
867
- pace**. That last rule is what the red-light example trips: a zero-distance lap has
868
- an infinite pace and everything is 15% faster than infinity, so without it every easy
869
- run with a paused lap would come back as a set of reps.
870
-
871
- `rest_pace` is nil when the recoveries covered no distance at all; a standing
872
- recovery has a duration but no pace, and reporting infinity would be worse than
873
- reporting nothing. A lap missing `:distance` or `:elapsed`, a negative distance, a
874
- distance over 100 km (a caller who passed metres), or a non-positive elapsed time
875
- raises `Calcpace::Error`; an empty array returns nil.
876
-
877
- ---
878
-
879
- ### Stride & Cadence
880
-
881
- Pace, cadence and stride length are one identity, so any two of them give the third:
882
-
883
- ```ruby
884
- calc.stride_length('05:00', 170) # => 1.18
885
- calc.stride_length('04:00', 180) # => 1.39
886
- calc.stride_length('08:02', 170, unit: :mi) # => 1.18
887
-
888
- calc.cadence_for_stride('05:00', 1.18) # => 169.5
889
- calc.cadence_for_stride('05:30', 1.15) # => 158.1
890
- ```
891
-
892
- `stride_length` returns metres per step (2 decimals); `cadence_for_stride` is its
893
- inverse and returns steps per minute (1 decimal). Pace takes the same forms as
894
- everywhere else — a clock string (`'05:00'`, `'00:05:00'`) or seconds per unit
895
- (`300`) — and `unit:` says which unit that pace is per: `:km` (default) or `:mi`.
896
- `8:02/mi` is `5:00/km` rounded down to the second (exactly 8:02.8), so the two strides
897
- agree to the centimetre at this cadence.
898
-
899
- Cadence is steps per minute counting **both feet** — the number a watch shows during a
900
- run, typically 160–185 spm. Strava's API reports cadence as one-leg RPM, so a value
901
- read from there must be doubled before it is passed in.
902
-
903
- ---
904
-
905
- ### Fitness Predictor (race times from VO2max)
906
-
907
- The inverse of `estimate_vo2max`: what a given fitness is worth over a race.
908
-
909
- ```ruby
910
- calc.predict_time_from_vo2max(50, '5k') # => 1196.02 (seconds)
911
- calc.predict_time_from_vo2max_clock(50, 'marathon') # => "03:10:39"
912
-
913
- calc.predict_time_from_vo2max(50, 10.0) # numeric distance in km
914
- calc.predict_time_from_vo2max_clock(50, 6.2, distance_unit: :mi) # => "00:41:13"
915
-
916
- calc.race_times_from_vo2max(50)['10k']
917
- # => { time: 2479.6, time_clock: "00:41:19", pace: 247.96, pace_clock: "00:04:07" }
918
-
919
- calc.race_times_from_vo2max(50, races: %w[5k 10mile], unit: :mi)['5k']
920
- # => { time: 1196.02, time_clock: "00:19:56", pace: 384.96, pace_clock: "00:06:24" }
921
- ```
922
-
923
- `race_times_from_vo2max` returns the whole table in one call — default races are
924
- `5k`, `10k`, `half_marathon`, and `marathon`, and `unit:` sets the pace unit. In
925
- `predict_time_from_vo2max`, `distance_unit:` sets the unit of a numeric distance;
926
- combining it with a race name raises `ArgumentError`, as elsewhere in the gem.
927
-
928
- The Daniels & Gilbert curve has no closed-form inverse, so the time is found by
929
- bisection — which makes the round trip exact:
930
-
931
- ```ruby
932
- calc.estimate_vo2max(5.0, calc.predict_time_from_vo2max(50, '5k')) # => 50.0
933
- ```
934
-
935
- Predictions match Daniels' published VDOT table within a few seconds for the shorter
936
- races and about a minute for the marathon. VO2max values outside 10–100 ml/kg/min
937
- raise `ArgumentError` — beyond that range the model stops describing running.
938
-
939
- ---
940
-
941
- ### Other Utilities
942
-
943
- ```ruby
944
- calc.convert_to_seconds('01:00:00') # => 3600
945
- calc.convert_to_clocktime(3600) # => "01:00:00"
946
- calc.check_time('01:00:00') # => nil (valid)
947
- ```
948
-
949
- Every time or pace string the gem reads goes through `convert_to_seconds`, so
950
- every method reads the same clocks, and every clock the gem writes is among them:
951
-
952
- ```ruby
953
- calc.convert_to_seconds('75:00') # => 4500 (MM:SS keeps counting minutes)
954
- calc.convert_to_seconds('400:00:00') # => 1440000 (any number of hours)
955
- calc.convert_to_seconds('1 03:46:40') # => 100000 (convert_to_clocktime's day prefix)
956
- calc.convert_to_seconds('-0:40') # => -40 (a backwards track_splits split)
957
- ```
958
-
959
- Seconds must be two digits below 60, and so must minutes when hours are given;
960
- after a day prefix the hours are two digits below 24. A leading `-` is the only
961
- sign, blanks or surrounding whitespace are not trimmed, and the string must be
962
- in a valid, ASCII-compatible encoding (UTF-8, not UTF-16). Anything else —
963
- `'05:99'`, `'1:60:00'`, `'1 3:46:40'`, `' 05:00'`, `'abc'` — raises
964
- `Calcpace::InvalidTimeFormatError`. A negative clock parses, but every method
965
- that needs a positive time or pace rejects it with `Calcpace::NonPositiveInputError`.
966
-
967
- `convert_to_clocktime` takes a `compact:` keyword for the format a runner reads
968
- on a screen — no zero hour, no leading zero on the most significant component:
969
-
970
- ```ruby
971
- calc.convert_to_clocktime(292, compact: true) # => "4:52"
972
- calc.convert_to_clocktime(45, compact: true) # => "0:45"
973
- calc.convert_to_clocktime(5025, compact: true) # => "1:23:45"
974
- calc.convert_to_clocktime(100_000, compact: true) # => "27:46:40"
975
- ```
976
-
977
- Past 24 hours the compact format keeps counting hours, where the padded one
978
- prefixes a day count (`"1 03:46:40"`). Fractional seconds truncate in both.
979
- A negative number of seconds raises `Calcpace::NonPositiveInputError`; zero is a
980
- valid duration (`"00:00:00"` / `"0:00"`).
981
-
982
- The same `compact:` keyword is accepted by `convert_pace`, `pace_km_to_mi`,
983
- `pace_mi_to_km`, and `track_splits`. It always defaults to `false`, so every
984
- call without it returns exactly what it returned before.
985
-
986
- ---
987
-
988
- ### Errors
989
-
990
- All errors inherit from `Calcpace::Error`:
991
-
992
- - `Calcpace::NonPositiveInputError` — numeric input is zero, negative, NaN or infinite
993
- - `Calcpace::InvalidTimeFormatError` — time string that is not a clock the gem writes
994
- (`[-][D ]H:MM:SS` or `[-]M:SS`, see Other Utilities): seconds must be below 60, and
995
- so must minutes when hours are given (`'05:99'` and `'1:60:00'` raise)
996
- - `Calcpace::UnsupportedUnitError` — unknown conversion (`convert`) or unknown
997
- `unit:` / `distance_unit:` keyword
998
- - `Calcpace::InvalidDataError` — the bundled data table failed its load-time
999
- consistency check (raised on `require`, never for user input)
1000
-
1001
- Argument validation that is not about units or numbers raises a plain `ArgumentError`:
1002
- unknown race names, unsupported age-grading distances, and invalid `age` / `sex` values.
1003
-
1004
- ---
1005
-
1006
- ### Testing
40
+ | [Basic calculations](https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md#basic-calculations) | Pace, time, distance and velocity, in seconds or `HH:MM:SS` |
41
+ | [Environmental adjustments](https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md#environmental-performance-adjustments) | Heat, humidity and altitude penalties, applied to a time or a prediction |
42
+ | [Unit](https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md#unit-conversions) and [pace conversions](https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md#pace-conversions) | 40+ conversions between distance and speed units; pace per km ↔ per mile |
43
+ | [Race pace & time](https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md#race-pace--time) | Any named race or plain distance |
44
+ | [Race splits](https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md#race-splits) | Even, negative or positive splits |
45
+ | [Race time predictions](https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md#race-time-predictions) | Riegel and Cameron |
46
+ | [Personalized predictions](https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md#personalized-predictions) | Tanda marathon from training volume, personal Riegel exponent |
47
+ | [GPS track analysis](https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md#gps-track-analysis) | Distance, elevation gain, per-km splits, grade-adjusted pace (Minetti) |
48
+ | [Age grading](https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md#age-grading-road-races) | 2025 road tables |
49
+ | [VO2max estimation](https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md#vo2max-estimation) | Daniels & Gilbert, FRIEND age/sex norms, effort and elevation context |
50
+ | [Training zones](https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md#training-zones) | Daniels paces, Karvonen and %HRmax zones, time in zones |
51
+ | [Lap analysis](https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md#lap-analysis) | Reads an interval session (reps, work and rest paces) from laps |
52
+ | [Stride & cadence](https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md#stride--cadence) | Stride length from pace and cadence, and back |
53
+ | [Fitness predictor](https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md#fitness-predictor-race-times-from-vo2max) | Race times from a VO2max |
54
+ | [Other utilities](https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md#other-utilities) and [errors](https://github.com/0jonjo/calcpace/blob/main/docs/USAGE.md#errors) | Helpers and the error classes |
55
+
56
+ ## Testing
1007
57
 
1008
58
  ```bash
1009
59
  bundle exec rake
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,6 +24,7 @@ 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
@@ -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
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  class Calcpace
4
- VERSION = '2.1.0'
4
+ VERSION = '2.1.1'
5
5
  end
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.1.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: []
@@ -69,6 +69,7 @@ licenses:
69
69
  metadata:
70
70
  source_code_uri: https://github.com/0jonjo/calcpace
71
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
72
73
  rubygems_mfa_required: 'true'
73
74
  rdoc_options: []
74
75
  require_paths: