sportanalytics
Running and cycling analytics in Rust.
0.2.0 ships Daniels–Gilbert VDOT, race-time prediction, training zones, and USATF MLDR 2025 road age grading for running, plus FTP, critical power, Coggan zones, ACSM / Hawley–Noakes VO2, and Martin road power–speed for cycling.
The published crate name is sportanalytics. Sports live in sibling
modules (sportanalytics::running, sportanalytics::cycling); the crate root
does not re-export Error. Sport helpers return running::Error /
cycling::Error.
📦 Install
Default (no extra dependencies):
[]
= "0.2.0"
Optional JSON support:
[]
= { = "0.2.0", = ["serde"] }
Then in code:
use *;
// or: use sportanalytics::cycling::*;
- Running items are also available from
sportanalytics::prelude(running-only). - Sport functions return
running::Error/cycling::Error(no crate-rootError). - Mix sports with
Box<dyn std::error::Error>.
🏃➡️ Running Metrics
use ;
- Pace and zone
Displaydefault to/km. - For miles, call
.display(LengthUnit::Mile). - Distances accept kilometres or international miles (
Distance::from_km,Distance::from_miles, or"8mi".parse::<Distance>()). Internal math is in metres and seconds.
Run Examples:
cargo run --example from_5k # examples/running/from_5k.rs
cargo run --example age_grade # examples/running/age_grade.rs
Features
| Function | What data or formula it uses |
|---|---|
vdot / vo2max_from_races |
Daniels–Gilbert 1979 VDOT (effective VO2max) |
predict_times |
Daniels invert, Riegel, or Cameron |
predict_daniels_and_cameron |
Daniels and Cameron in one call |
training_zones / training_zones_from_vdot |
Daniels %VDOT pace bands (E/M/T/I/R) |
age_grade / age_equivalent |
USATF MLDR 2025 single-year road tables (CC0); both return Result |
- Age and gender are used only by age grading.
- If you need an age-adjusted figure, run the prediction first, then pass a
predicted time into
age_equivalent. - Ages outside 5..=99 and unsupported distances result in error: use
?or.unwrap().
Age grading
Example:
use ;
- Named distances are 3K, 5K, 10K, half marathon, and marathon; other lengths use
Distance::from_meters/Distance::from_km/Distance::from_miles/Distance::custom, or parse strings such as"8k"and"8mi". - Training zones are inverted from the oxygen-cost equations at fixed %VDOT (E 0.59–0.74, M 0.75–0.84, T 0.83–0.88, I 0.95–1.00, R 1.05–1.10).
- Zone edges are typed
Pacevalues. - This crate does not ship Daniels’ copyrighted lookup tables.
Full types and formulas: docs.rs/sportanalytics.
Accuracy / non-goals
- VDOT is effective VO2max (economy included). This crate implements the Daniels–Gilbert Oxygen Power (1979) equations, not the copyrighted printed lookup tables.
- Daniels predictions are VDOT-equivalent performances. Riegel is a power law
(
k = 1.06). Cameron is a distance-weighted road fit. None include hills, heat, or wind. - Age grading looks up the official USATF MLDR 2025 road tables
(approved 2025-01-10). Ages 5–99 (
AgeOutOfRangeotherwise). Off-grid distances interpolate age standards in log-distance between neighbouring official events (Jones 2025). Road 3K returnsUnsupportedAgeGradeDistance. This crate uses the same published table as the Howard Grubb MLDR 2025 calculator. - Predictions assume a flat, all-out effort and similar training specificity.
- Published Daniels Running Formula charts will differ by a few seconds/km from equation output.
🚴♀️ Cycling Metrics
Example:
use ;
use Duration;
Run Examples:
cargo run --example from_20min # examples/cycling/from_20min.rs
cargo run --example from_tt # examples/cycling/from_tt.rs
Road speed from power
Example:
use ;
Features
| Function | What data or formula it uses |
|---|---|
ftp_from_20min / ftp_from_protocol |
Operational FTP from field protocols |
critical_power |
Two-parameter CP + W′ (~2–30 min; hour from short pairs biased high) |
predict_power / predict_power_from_cp |
CP, %FTP curve, or power Riegel |
training_zones |
Coggan Z1–Z7 + sweet spot (%FTP) |
estimated_vo2max |
ACSM MAP → relative VO2 field estimate |
power_for_speed / speed_for_power |
Martin et al. 1998 power balance |
age_equivalent_ftp |
Trained-endurance decline curve (not official tables) |
FTP is an operational training anchor, not laboratory lactate threshold. Estimated VO2 is a field estimate, not gas analysis. Age helpers use ages 15..=90 and are not USATF/VTTA age grading.
🛠️ Builds
- Default builds have no crate dependencies (
stdonly). EnableserdeforSerialize/Deserialize. - Crate 0.2.0 ships running and cycling. Further sports should be sibling
modules; do not dump new sports onto the crate root or into
prelude.
📋 Attribution
The running and cycling modules implement published equations. They are not copied from another crate or from copyrighted pace/power charts.
Running
- VDOT / equivalents / training intensities: Jack Daniels and Jimmy Gilbert, Oxygen Power (1979): oxygen cost of running and sustainable %VO2max versus duration. This crate implements those equations (not copyrighted printed pace grids). Training zones invert the oxygen-cost curve at fixed % of VDOT (E 0.59–0.74, M 0.75–0.84, T 0.83–0.88, I 0.95–1.00, R 1.05–1.10).
- Riegel: Pete Riegel (1977, Runner’s World; 1981, American Scientist) —
T2 = T1 * (D2/D1)^1.06. The exponent1.06is the published default. It is not fitted per athlete. - Cameron: David Cameron’s published road-race fit (commonly dated late
1990s):
T2 = T1 * (D2/D1) * f(D1)/f(D2)withf(x) = 13.49681 - 0.000030363 x + 835.7114 / x^0.7905(xin metres). - Age grading: USATF Masters Long Distance Running (MLDR) 2025 road tables
by Alan Jones and Tom Bernhard (approved 2025-01-10). Source:
AlanLyttonJones/Age-Grade-Tables
(
2025 Files/AgeGrade.zip). Table data is CC0-1.0; the crate code is MIT.
Cycling
- FTP protocols / Coggan %FTP zones: public coaching conventions (operational threshold and training bands), not laboratory LT and not copyrighted power-profile charts.
- Critical power: two-parameter
P = CP + W′/tlinear fit (valid ~2–30 min; hour power from a short+medium pair is biased high). - VO2 estimate: ACSM relative
10.8 × W/kg + 7; optional Hawley & Noakes 1992 absolute0.01141 × Wpeak + 0.435L/min. - Road power–speed: Martin et al. 1998 cycling power balance (CdA, Crr, grade, wind, drivetrain η); steady-state only (no KE, drafting, or coasting).
- Age factor: trained-endurance decline approximation (linear ~0.5%/year after 35; Tanaka & Seals-style); sex unused; not VTTA/CTT/WMA tables.
🦀 MSRV
Rust 1.71 (edition 2021).
✍ Contributing
See CONTRIBUTING.md. This project follows the Rust Code of Conduct.
📜 License
MIT for crate code. Embedded USATF MLDR 2025 age-grade table data is CC0-1.0 (Alan Jones / Tom Bernhard).