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