calcpace 1.8.2 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6480fc19dccfe8c5ff2ee46c2ed4aced622298279acb451b8adfe9b1ae03b819
-  data.tar.gz: 1176a1d2c2a5bcf6f155b3a175927ca5aaa30d616bf3ee44fd98292b3c2af5bd
+  metadata.gz: 510953dda84be6757bd902b5dbb76752b362241abd69e47f1f321f0eaaa0c7e4
+  data.tar.gz: 3c8487adbd99edc3e5588b2c220f199a07a016d447cf768b9a1cc1474aec6b9e
 SHA512:
-  metadata.gz: e7fc6d4dc07267a4dc62ed61508af26715c8d40b2629a203ab25bb2ddf08342a43860014e4e9d2e916d7d5476771a981f7afc3bbdcec633b9827792005fcb4d8
-  data.tar.gz: 778a7d8ab6544c8fbab2cdc8d6b0d1502ceb00497ac2a5d1053270b42378d4922e83d827566c71c4597491db03aac5b238fffcb6732a012f437c28ff81578a5e
+  metadata.gz: 24f353d01da23bca0cb84a12070b7db967499fde606dfc247afcfc071dd7f791e42c9c746f1adb5a1beee1e0b1031b52721ae4739b7928824489fb63d957b0d8
+  data.tar.gz: eca2e3ea93439300bd9253832db99e6e1aad1b4008ec8dc0ef50881e73b5cc00587c38549a13cd5e795793e1f84afd76b23ee010afe10f9dfea7d47eb4adbf58

data/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.0] - 2026-03-24
+
+### Added
+- Cameron race predictor (`CameronPredictor` module) — alternative to Riegel for predicting race times
+  - `predict_time_cameron` — predicts race time in seconds using the Cameron formula
+  - `predict_time_cameron_clock` — same, returned as `HH:MM:SS` string
+  - `predict_pace_cameron` — predicted pace in seconds per kilometer
+  - `predict_pace_cameron_clock` — same, returned as `HH:MM:SS` string
+  - Formula: `T2 = T1 × (D2/D1) × [f(D1) / f(D2)]` where `f(d) = a + b × e^(-d/c)`, constants calibrated for km
+  - The exponential correction is larger when predicting from shorter distances, reflecting the greater anaerobic contribution at shorter race distances
+  - Accepts the same input formats as `RacePredictor`: string (`HH:MM:SS`, `MM:SS`) or numeric seconds
+  - 18 test cases covering standard predictions, round-trip consistency, clock format outputs, and error handling
+
 ## [1.8.2] - 2026-03-07
 
 ### Added

data/Gemfile.lock

@@ -8,7 +8,7 @@ GEM
     date (3.5.1)
     docile (1.4.1)
     erb (6.0.2)
-    json (2.19.0)
+    json (2.19.2)
     json-schema (6.2.0)
       addressable (~> 2.8)
       bigdecimal (>= 3.1, < 5)

data/README.md

@@ -1,4 +1,4 @@
-# Calcpace [![Gem Version](https://d25lcipzij17d.cloudfront.net/badge.svg?id=rb&r=r&ts=1683906897&type=6e&v=1.8.2&x2=0)](https://badge.fury.io/rb/calcpace)
+# Calcpace [![Gem Version](https://d25lcipzij17d.cloudfront.net/badge.svg?id=rb&r=r&ts=1683906897&type=6e&v=1.9.0&x2=0)](https://badge.fury.io/rb/calcpace)
 
 Calcpace is a Ruby gem designed for calculations and conversions related to distance and time. It can calculate velocity, pace, total time, and distance, accepting time in various formats, including HH:MM:SS. The gem supports conversion to 42 different units, including kilometers, miles, meters, and feet. It also provides methods to validate input.
 
@@ -7,7 +7,7 @@ Calcpace is a Ruby gem designed for calculations and conversions related to dist
 ### Add to your Gemfile
 
 ```ruby
-gem 'calcpace', '~> 1.8.2'
+gem 'calcpace', '~> 1.9'
 ```
 
 Then run:
@@ -308,6 +308,46 @@ The formula works best for:
 - Results are estimates - actual performance varies by individual fitness, training focus, and race conditions
 - The formula is most accurate when predicting between similar distance ranges (e.g., 10K to half marathon)
 
+### Race Time Predictions — Cameron Formula
+
+An alternative predictor using the **Cameron formula**, which applies an exponential correction based on the known distance. Unlike Riegel's fixed power-law exponent, Cameron's correction is larger when predicting from shorter races (where anaerobic capacity plays a bigger role) and diminishes as the known distance increases.
+
+```ruby
+calc = Calcpace.new
+
+# Predict marathon time from 10K
+calc.predict_time_cameron_clock('10k', '00:42:00', 'marathon')
+# => "02:57:46"
+
+# Predict 10K from 5K
+calc.predict_time_cameron_clock('5k', '00:20:00', '10k')
+# => "00:42:24"
+
+# Get predicted pace per km
+calc.predict_pace_cameron_clock('10k', '00:42:00', 'marathon')
+# => "00:04:13"
+
+# Raw seconds (useful for further calculations)
+calc.predict_time_cameron('5k', '00:20:00', 'half_marathon')
+# => 5382.7 (approximately 1:29:42)
+```
+
+#### How the Cameron Formula Works
+
+**Formula:** `T2 = T1 × (D2/D1) × [(a + b × e^(-D1/c)) / (a + b × e^(-D2/c))]`
+
+Where:
+- **T1** = known time, **D1** = known distance (km)
+- **T2** = predicted time, **D2** = target distance (km)
+- **a = 0.000495**, **b = 0.000985**, **c = 1.4485** (empirical constants)
+
+The exponential correction factor `f(d) = a + b × e^(-d/c)` decreases as distance grows. When predicting from a short race to a long one, `f(D1) > f(D2)`, making `T2` grow slightly faster than a pure linear extrapolation — accounting for the greater fatigue at longer distances.
+
+**Compared to Riegel:**
+- Predicting from short distances (5K): Cameron tends to be more conservative (slower prediction) — acknowledges that 5K speed has a larger anaerobic component
+- Predicting from moderate distances (10K): Cameron tends to be slightly more optimistic — 10K is already a strong predictor of marathon aerobic capacity
+- Both formulas are estimates; real performance depends on training specificity, conditions, and individual physiology
+
 ### Other Useful Methods
 
 Calcpace also provides other useful methods:

data/lib/calcpace/cameron_predictor.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+# Module for predicting race times using the Cameron formula
+#
+# An alternative to the Riegel formula (RacePredictor module) that uses an
+# exponential correction to better account for physiological differences across
+# distances. The correction is larger when predicting from shorter races, where
+# anaerobic contribution is greater, and diminishes as the known distance approaches
+# the target distance.
+#
+# Formula: T2 = T1 × (D2/D1) × [(a + b × e^(-D1/c)) / (a + b × e^(-D2/c))]
+#
+# Constants (calibrated for distances in km):
+#   a = 0.000495
+#   b = 0.000985
+#   c = 1.4485
+#
+# Reference: Dave Cameron, "A Critical Examination of Racing Predictions" (1997)
+module CameronPredictor
+  # Cameron formula constants (calibrated for distances in km)
+  CAMERON_A = 0.000495
+  CAMERON_B = 0.000985
+  CAMERON_C = 1.4485
+
+  # Predicts race time using the Cameron formula
+  #
+  # @param from_race [String, Symbol] known race distance ('5k', '10k', 'half_marathon', 'marathon', etc.)
+  # @param from_time [String, Numeric] time achieved at known distance (HH:MM:SS or seconds)
+  # @param to_race [String, Symbol] target race distance to predict
+  # @return [Float] predicted time in seconds
+  # @raise [ArgumentError] if races are invalid or distances are the same
+  #
+  # @example Predict marathon time from 10K
+  #   predict_time_cameron('10k', '00:42:00', 'marathon')
+  #   #=> ~10,666 seconds (approximately 2:57:46)
+  #
+  # @example Predict 10K time from 5K
+  #   predict_time_cameron('5k', '00:20:00', '10k')
+  #   #=> ~2,544 seconds (approximately 42:24)
+  def predict_time_cameron(from_race, from_time, to_race)
+    from_distance = race_distance(from_race)
+    to_distance   = race_distance(to_race)
+
+    if from_distance == to_distance
+      raise ArgumentError,
+            "From and to races must be different distances (both are #{from_distance}km)"
+    end
+
+    time_seconds = from_time.is_a?(String) ? convert_to_seconds(from_time) : from_time
+    check_positive(time_seconds, 'Time')
+
+    # Cameron formula: T2 = T1 × (D2/D1) × [cameron_factor(D1) / cameron_factor(D2)]
+    time_seconds * (to_distance / from_distance) *
+      (cameron_factor(from_distance) / cameron_factor(to_distance))
+  end
+
+  # Predicts race time using the Cameron formula, returned as a clock time string
+  #
+  # @param from_race [String, Symbol] known race distance
+  # @param from_time [String, Numeric] time achieved at known distance
+  # @param to_race [String, Symbol] target race distance to predict
+  # @return [String] predicted time in HH:MM:SS format
+  #
+  # @example
+  #   predict_time_cameron_clock('10k', '00:42:00', 'marathon')
+  #   #=> '02:57:46'
+  def predict_time_cameron_clock(from_race, from_time, to_race)
+    convert_to_clocktime(predict_time_cameron(from_race, from_time, to_race))
+  end
+
+  # Predicts pace per kilometer using the Cameron formula
+  #
+  # @param from_race [String, Symbol] known race distance
+  # @param from_time [String, Numeric] time achieved at known distance
+  # @param to_race [String, Symbol] target race distance to predict
+  # @return [Float] predicted pace in seconds per kilometer
+  #
+  # @example
+  #   predict_pace_cameron('5k', '00:20:00', 'marathon')
+  #   #=> ~255.1 (approximately 4:15/km)
+  def predict_pace_cameron(from_race, from_time, to_race)
+    predict_time_cameron(from_race, from_time, to_race) / race_distance(to_race)
+  end
+
+  # Predicts pace per kilometer using the Cameron formula, returned as a clock time string
+  #
+  # @param from_race [String, Symbol] known race distance
+  # @param from_time [String, Numeric] time achieved at known distance
+  # @param to_race [String, Symbol] target race distance to predict
+  # @return [String] predicted pace in HH:MM:SS format
+  #
+  # @example
+  #   predict_pace_cameron_clock('5k', '00:20:00', 'marathon')
+  #   #=> '00:02:32'
+  def predict_pace_cameron_clock(from_race, from_time, to_race)
+    convert_to_clocktime(predict_pace_cameron(from_race, from_time, to_race))
+  end
+
+  private
+
+  # Computes the Cameron exponential correction factor for a given distance
+  #
+  # @param distance_km [Float] distance in kilometers
+  # @return [Float] correction factor value
+  def cameron_factor(distance_km)
+    CAMERON_A + (CAMERON_B * Math.exp(-distance_km / CAMERON_C))
+  end
+end

data/lib/calcpace/version.rb

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

data/lib/calcpace.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'calcpace/calculator'
+require_relative 'calcpace/cameron_predictor'
 require_relative 'calcpace/checker'
 require_relative 'calcpace/converter'
 require_relative 'calcpace/converter_chain'
@@ -33,6 +34,7 @@ require_relative 'calcpace/race_splits'
 # @see https://github.com/0jonjo/calcpace
 class Calcpace
   include Calculator
+  include CameronPredictor
   include Checker
   include Converter
   include ConverterChain

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: calcpace
 version: !ruby/object:Gem::Version
-  version: 1.8.2
+  version: 1.9.0
 platform: ruby
 authors:
 - João Gilberto Saraiva
@@ -31,6 +31,7 @@ files:
 - calcpace.gemspec
 - lib/calcpace.rb
 - lib/calcpace/calculator.rb
+- lib/calcpace/cameron_predictor.rb
 - lib/calcpace/checker.rb
 - lib/calcpace/converter.rb
 - lib/calcpace/converter_chain.rb
@@ -61,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: A Ruby gem for pace, distance, and time calculations.
 test_files: []