calcpace 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d60f32c2e712a9f2c4ab9a1a8724ac9b932838acab9bbe1db333f557d0cf1797
-  data.tar.gz: 6bd621feb8849df93ab197bbe77795da67878ddfa46ee493acd8e2ffe53a651e
+  metadata.gz: 25afa206e47316900eab46723efcccac5586d0026dbdd81316566798ffff58c3
+  data.tar.gz: e86c8acacd4cda1bdc4c9036bad53249029b285d6fd7a0ed467d8f67534c172d
 SHA512:
-  metadata.gz: f6b76162fc0e1e575c1c1fc8d06c782cf603775c374c1a75dc5bacab50e2958a99c18ba47e429b65bc154f72d12d127e7c0fae99f9d59cd4dc2d3a54541fe335
-  data.tar.gz: 260a67baea8e765b473261c0c24bfc12af6672404713f92bec266c070c5c0ae5beaa7da4ef9b3714d9286f868158fddca5c74e9bb0da182d78bd393947191fdb
+  metadata.gz: 220badb3ce50b0ca0cd3ad4e386944b58f09586ab5fb1b0d50cbc961d2cd9705c1a04c98c4b0a68c0bfa371557b2a43bb831a4441b6697240dfedf12a87e1d24
+  data.tar.gz: e3458ad4525014a92bb3ca2c923df3e224f5cec0fb06c5957b6da34d675f1ff3a507ffb96bfc7a0293e72c9710a7a96086685cad1bf005adf4a50f412a1d95b5

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-10-11
+
+### Added
+- **`effort:` in `estimate_detailed_vo2max`** — how hard the runner says it
+  was, one of `EFFORT_LEVELS` (`:easy`, `:moderate`, `:hard`, `:max`; Symbol
+  or String, any case). The value is never changed; only how far it can be
+  trusted. `:easy`/`:moderate` → sub-maximal and `:low` whatever the duration
+  or heart rate; `:max` → `:high` from five minutes on however long it took,
+  unless average heart rate is under 85 % of max; `:hard` and `nil` → the
+  2.0.0 rules. An unknown effort raises `Calcpace::InvalidEffortError`.
+- **`Vo2maxResult#basis`** — what set the confidence: `:declared`,
+  `:heart_rate` or `:duration`. Added as the last member, so positional
+  construction and reading the four existing members are unchanged. It is
+  always set, so it does show up in `==` (a result no longer equals a
+  four-member `Vo2maxResult.new(...)`), in `to_a`/`to_h` (five entries) and in
+  array patterns (`in [value, confidence, sub_maximal, adjusted]` no longer
+  matches; use a hash pattern or add a fifth element).
+
+Without `effort:` every result is the same as in 2.0.0.
+
 ## [2.0.0] - 2026-10-02
 
 A major release. Four physiological models gave unrealistic numbers and now
@@ -1001,7 +1021,8 @@ predictors are untouched.
 
 See git history for changes in earlier versions.
 
-[Unreleased]: https://github.com/0jonjo/calcpace/compare/v2.0.0...HEAD
+[Unreleased]: https://github.com/0jonjo/calcpace/compare/v2.1.0...HEAD
+[2.1.0]: https://github.com/0jonjo/calcpace/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/0jonjo/calcpace/compare/v1.18.1...v2.0.0
 [1.18.1]: https://github.com/0jonjo/calcpace/compare/v1.18.0...v1.18.1
 [1.18.0]: https://github.com/0jonjo/calcpace/compare/v1.17.0...v1.18.0

data/README.md

@@ -1,3 +1,5 @@
+<p align="center"><img src="https://raw.githubusercontent.com/0jonjo/calcpace/main/docs/logo.svg" alt="calcpace logo" width="128"></p>
+
 # Calcpace [![Gem Version](https://badge.fury.io/rb/calcpace.svg)](https://badge.fury.io/rb/calcpace)
 
 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.
@@ -7,7 +9,7 @@ A Ruby gem for runners: pace, time, and distance calculations, unit conversions,
 ## Installation
 
 ```ruby
-gem 'calcpace', '~> 2.0'
+gem 'calcpace', '~> 2.1'
 ```
 
 ## Usage
@@ -643,6 +645,32 @@ easy.value        # => 29.3   (underestimates real aerobic capacity)
 > If you provide heart rate data, both `hr_avg` and `hr_max` must be present.
 > `elevation_gain_m` must be zero or positive.
 
+`result.basis` says what set the confidence: `:duration` (the table above), `:heart_rate` (average HR under 85 % of max) or `:declared` (the `effort:` below).
+
+#### Effort
+
+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):
+
+| `effort` | How it felt | `confidence` | `sub_maximal` |
+|---|---|---|---|
+| `:easy` | Could talk freely | `:low` | `true` |
+| `:moderate` | Short sentences, still comfortable | `:low` | `true` |
+| `:hard` | A few words at a time | duration and heart-rate rules, as without `effort:` | |
+| `: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 %) |
+| `nil` (default) | — | exactly as in 2.0.0 | |
+
+```ruby
+calc.estimate_detailed_vo2max(42.195, '03:30:00').confidence                # => :low   (over 2 h)
+calc.estimate_detailed_vo2max(42.195, '03:30:00', effort: :max).confidence  # => :high  (a race says it was all-out)
+calc.estimate_detailed_vo2max(10.0, '00:55:00', effort: :easy).sub_maximal  # => true
+calc.estimate_detailed_vo2max(10.0, '00:55:00', effort: :easy).basis        # => :declared
+```
+
+- **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.
+- 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.
+- Without heart rate, `:hard` and `:max` are not sub-maximal: nothing says they were.
+- An unknown effort raises `Calcpace::InvalidEffortError`.
+
 ---
 
 ### Training Zones

data/calcpace.gemspec

@@ -27,7 +27,7 @@ Gem::Specification.new do |spec|
   spec.metadata['rubygems_mfa_required'] = 'true'
 
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|docs)/}) }
   end
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }

data/lib/calcpace/errors.rb

@@ -20,6 +20,13 @@ class Calcpace
     end
   end
 
+  # Raised when an effort is not one of Vo2maxEffort::EFFORT_LEVELS
+  class InvalidEffortError < Error
+    def initialize(msg = 'Invalid effort. Valid efforts: :easy, :moderate, :hard, :max')
+      super
+    end
+  end
+
   # Raised when versioned/static gem data fails an internal consistency check
   class InvalidDataError < Error; end
 

data/lib/calcpace/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Calcpace
-  VERSION = '2.0.0'
+  VERSION = '2.1.0'
 end

data/lib/calcpace/vo2max_effort.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# How hard the runner says an effort was, for Vo2maxEstimator#estimate_detailed_vo2max
+#
+# Daniels & Gilbert assume an all-out effort, and the estimator can only guess
+# that from duration and heart rate. A declared effort answers it directly. It
+# never changes the VO2max value — only its confidence, sub_maximal and basis.
+module Vo2maxEffort
+  # From easiest. :easy and :moderate are training (talk test: a full
+  # conversation / short sentences), :hard is a few words at a time, :max is
+  # everything the runner had — a race or a test.
+  EFFORT_LEVELS = %i[easy moderate hard max].freeze
+
+  private
+
+  def normalize_effort(effort)
+    return if effort.nil?
+
+    level = effort.to_s.downcase.to_sym
+    return level if EFFORT_LEVELS.include?(level)
+
+    raise Calcpace::InvalidEffortError,
+          "Invalid effort: #{effort.inspect}. Valid efforts: #{EFFORT_LEVELS.map(&:inspect).join(', ')}"
+  end
+
+  # A declared easy or moderate effort wins over everything: the runner knows
+  # they held back, whatever the watch says. Heart rate wins over a declared
+  # max, as it did over the duration rule. A max shorter than five minutes stays
+  # with the duration rule: there the formula itself is unreliable.
+  #
+  # duration_confidence is the estimator's verdict from duration alone.
+  def effort_verdict(effort, time_min, duration_confidence:, hr_sub_maximal:)
+    if %i[easy moderate].include?(effort)
+      { confidence: :low, sub_maximal: true, basis: :declared }
+    elsif hr_sub_maximal
+      { confidence: :low, sub_maximal: true, basis: :heart_rate }
+    elsif effort == :max && time_min >= 5
+      { confidence: :high, sub_maximal: false, basis: :declared }
+    else
+      { confidence: duration_confidence, sub_maximal: false, basis: :duration }
+    end
+  end
+end

data/lib/calcpace/vo2max_estimator.rb

@@ -14,6 +14,8 @@
 # Accuracy: ±3–5 ml/kg/min vs laboratory testing. Best results with efforts
 # between 5 and 60 minutes at race pace (i.e. near-maximal effort).
 module Vo2maxEstimator
+  include Vo2maxEffort
+
   # Classification thresholds based on:
   # Daniels, J. (2014). Daniels' Running Formula (3rd ed.). Human Kinetics.
   # General ranges are consistent with ACSM guidelines and widely cited in
@@ -28,7 +30,11 @@ module Vo2maxEstimator
   ].freeze
 
   # Represents a contextualized VO2max estimation result
-  Vo2maxResult = Struct.new(:value, :confidence, :sub_maximal, :adjusted_distance_km)
+  #
+  # basis names what set confidence and sub_maximal: :declared (the effort
+  # given), :heart_rate (average HR under 85 % of max) or :duration (the
+  # Daniels & Gilbert window alone)
+  Vo2maxResult = Struct.new(:value, :confidence, :sub_maximal, :adjusted_distance_km, :basis)
 
   # Estimates VO2max from a race performance using Daniels & Gilbert formula
   #
@@ -59,6 +65,10 @@ module Vo2maxEstimator
     (vo2 / pct_vo2max).round(1)
   end
 
+  # The public signature: every input is a keyword a caller already passes, and
+  # bundling them into an options object would break the 2.x API.
+  # rubocop:disable Metrics/ParameterLists
+
   # Estimates a detailed and contextualized VO2max
   #
   # Elevation is folded in with a flat heuristic — every 100 m of gain adds
@@ -75,11 +85,25 @@ module Vo2maxEstimator
   # @param hr_avg [Numeric] average heart rate during the effort
   # @param hr_max [Numeric] athlete's maximum heart rate
   # @param distance_unit [Symbol] unit of the distance input — :km (default) or :mi
+  # @param effort [Symbol, String, nil] how hard the runner says it was, one of
+  #   Vo2maxEffort::EFFORT_LEVELS. It never changes the value, only how far it can be
+  #   trusted: :easy and :moderate make it sub-maximal and low confidence
+  #   whatever the duration or heart rate; :max makes it high confidence from
+  #   five minutes on, however long it took, unless heart rate says
+  #   sub-maximal; :hard and nil leave the duration and heart-rate rules as
+  #   they are.
   # @return [Vo2maxResult] structured result with value and metadata
   #   (adjusted_distance_km is always in kilometres)
   # @raise [Calcpace::NonPositiveInputError] if distance or time are not positive
   # @raise [Calcpace::UnsupportedUnitError] if distance_unit is not :km or :mi
-  def estimate_detailed_vo2max(distance, time, elevation_gain_m: 0, hr_avg: nil, hr_max: nil, distance_unit: :km)
+  # @raise [Calcpace::InvalidEffortError] if effort is not one of Vo2maxEffort::EFFORT_LEVELS
+  #
+  # @example a marathon run all-out
+  #   calc.estimate_detailed_vo2max(42.195, '03:30:00').confidence               #=> :low
+  #   calc.estimate_detailed_vo2max(42.195, '03:30:00', effort: :max).confidence #=> :high
+  def estimate_detailed_vo2max(distance, time, elevation_gain_m: 0, hr_avg: nil, hr_max: nil, distance_unit: :km,
+                               effort: nil)
+    effort = normalize_effort(effort)
     distance_km = normalize_distance_km(distance, distance_unit)
     # Validated before the elevation adjustment, which would otherwise turn a
     # negative distance into a positive equivalent-flat one
@@ -87,18 +111,14 @@ module Vo2maxEstimator
 
     adj_dist_km = adjusted_distance_for_vo2(distance_km, elevation_gain_m)
     vo2max_val  = estimate_vo2max(adj_dist_km, time)
-    confidence  = calculate_time_confidence(parse_time_minutes(time))
-
-    hr_data = validate_and_analyze_hr(hr_avg, hr_max)
-    confidence = :low if hr_data[:sub_maximal]
+    time_min    = parse_time_minutes(time)
+    hr_data     = validate_and_analyze_hr(hr_avg, hr_max)
+    verdict     = effort_verdict(effort, time_min, duration_confidence: calculate_time_confidence(time_min),
+                                                   hr_sub_maximal: hr_data[:sub_maximal])
 
-    Vo2maxResult.new(
-      value: vo2max_val,
-      confidence: confidence,
-      sub_maximal: hr_data[:sub_maximal],
-      adjusted_distance_km: adj_dist_km.round(2)
-    )
+    Vo2maxResult.new(value: vo2max_val, adjusted_distance_km: adj_dist_km.round(2), **verdict)
   end
+  # rubocop:enable Metrics/ParameterLists
 
   # Returns a descriptive label for a given VO2max value
   #

data/lib/calcpace.rb

@@ -20,6 +20,7 @@ require_relative 'calcpace/race_splits'
 require_relative 'calcpace/stride_calculator'
 require_relative 'calcpace/track_calculator'
 require_relative 'calcpace/training_zones'
+require_relative 'calcpace/vo2max_effort'
 require_relative 'calcpace/vo2max_estimator'
 require_relative 'calcpace/vo2max_norms'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: calcpace
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - João Gilberto Saraiva
@@ -60,6 +60,7 @@ files:
 - lib/calcpace/track_calculator.rb
 - lib/calcpace/training_zones.rb
 - lib/calcpace/version.rb
+- lib/calcpace/vo2max_effort.rb
 - lib/calcpace/vo2max_estimator.rb
 - lib/calcpace/vo2max_norms.rb
 homepage: https://github.com/0jonjo/calcpace