Module: RacePredictor

Included in:
Calcpace
Defined in:
lib/calcpace/race_predictor.rb

Overview

Module for predicting race times based on performance at other distances

This module uses the Riegel formula to predict race times based on a known performance at a different distance. The formula accounts for the endurance fatigue factor that occurs as race distance increases.

Constant Summary collapse

RIEGEL_EXPONENT =

Riegel formula exponent (represents endurance/fatigue factor)

1.06

Instance Method Summary collapse

Instance Method Details

#equivalent_performance(from_race, from_time, to_race) ⇒ Hash

Calculates the equivalent performance at a different distance

This is useful for comparing performances across different race distances. For example, "My 10K time is equivalent to what 5K time?"

Examples:

equivalent_performance('10k', '00:42:00', '5k')
#=> {
      time: 1208.67,
      time_clock: "00:20:08",
      pace: 241.73,
      pace_clock: "00:04:01"
    }

Parameters:

  • from_race (Numeric, String, Symbol) —

    known distance in kilometers or race name

  • from_time (String, Numeric) —

    time achieved at known distance

  • to_race (Numeric, String, Symbol) —

    target distance in kilometers or race name

Returns:

  • (Hash) —

    hash with :time (seconds), :time_clock (HH:MM:SS), :pace (/km), :pace_clock



114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/calcpace/race_predictor.rb', line 114

def equivalent_performance(from_race, from_time, to_race)
  predicted_time = predict_time(from_race, from_time, to_race)
  predicted_pace = predict_pace(from_race, from_time, to_race)

  {
    time: predicted_time,
    time_clock: convert_to_clocktime(predicted_time),
    pace: predicted_pace,
    pace_clock: convert_to_clocktime(predicted_pace)
  }
end

#predict_pace(from_race, from_time, to_race) ⇒ Float

Predicts the pace per kilometer for a target race

Examples:

predict_pace('5k', '00:20:00', 'marathon')
#=> 272.77 (approximately 4:32/km)

Parameters:

  • from_race (Numeric, String, Symbol) —

    known distance in kilometers or race name

  • from_time (String, Numeric) —

    time achieved at known distance

  • to_race (Numeric, String, Symbol) —

    target distance in kilometers or race name

Returns:

  • (Float) —

    predicted pace in seconds per kilometer



75
76
77
78
79
 
# File 'lib/calcpace/race_predictor.rb', line 75

def predict_pace(from_race, from_time, to_race)
  predicted_seconds = predict_time(from_race, from_time, to_race)
  to_distance = race_distance(to_race)
  predicted_seconds / to_distance
end

#predict_pace_clock(from_race, from_time, to_race) ⇒ String

Predicts the pace per kilometer and returns it as a clock time string

Examples:

predict_pace_clock('5k', '00:20:00', 'marathon')
#=> '00:04:32' (4:32/km)

Parameters:

  • from_race (Numeric, String, Symbol) —

    known distance in kilometers or race name

  • from_time (String, Numeric) —

    time achieved at known distance

  • to_race (Numeric, String, Symbol) —

    target distance in kilometers or race name

Returns:

  • (String) —

    predicted pace in MM:SS format



91
92
93
94
 
# File 'lib/calcpace/race_predictor.rb', line 91

def predict_pace_clock(from_race, from_time, to_race)
  pace_seconds = predict_pace(from_race, from_time, to_race)
  convert_to_clocktime(pace_seconds)
end

#predict_time(from_race, from_time, to_race) ⇒ Float

Predicts race time for a target distance based on a known performance

Uses the Riegel formula: T2 = T1 × (D2/D1)^1.06 where:

  • T1 = time at known distance
  • D1 = known distance
  • T2 = predicted time at target distance
  • D2 = target distance
  • 1.06 = endurance/fatigue factor (longer races require proportionally more time)

Examples:

Predict marathon time from 5K

predict_time('5k', '00:20:00', 'marathon')
#=> 11509.32 (approximately 3:11:49)

Predict 10K time from half marathon

predict_time('half_marathon', '01:30:00', '10k')
#=> 2447.42 (approximately 40:47)

Parameters:

  • from_race (Numeric, String, Symbol) —

    known distance in kilometers (7.79, '7.79') or a standard race name ('5k', '10k', 'half_marathon', 'marathon', '100k', etc.)

  • from_time (String, Numeric) —

    time achieved at known distance (HH:MM:SS or seconds)

  • to_race (Numeric, String, Symbol) —

    target distance in kilometers or race name

Returns:

  • (Float) —

    predicted time in seconds

Raises:



37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/calcpace/race_predictor.rb', line 37

def predict_time(from_race, from_time, to_race)
  from_distance = race_distance(from_race)
  to_distance = race_distance(to_race)

  ensure_different_distances!(from_distance, to_distance)

  time_seconds = from_time.is_a?(String) ? convert_to_seconds(from_time) : from_time
  check_positive(time_seconds, 'Time')

  # Riegel formula: T2 = T1 × (D2/D1)^1.06
  time_seconds * ((to_distance / from_distance)**RIEGEL_EXPONENT)
end

#predict_time_adjusted(from_race, from_time, to_race) ⇒ Hash

Predicts race time adjusted for environmental conditions

Examples:

Predict marathon time from 5K adjusted for heat (25C)

predict_time_adjusted('5k', '00:20:00', 'marathon', temperature: 25)
#=> { adjusted_time: 13140.19, penalty_percent: 14.17, ... }

Parameters:

  • from_race (Numeric, String, Symbol) —

    known distance in kilometers or race name

  • from_time (String, Numeric) —

    time achieved at known distance

  • to_race (Numeric, String, Symbol) —

    target distance in kilometers or race name

  • options (Hash) —

    environmental options:

    • :temperature [Numeric]
    • :temperature_unit [Symbol, String] :c or :f
    • :altitude [Numeric]

Returns:

  • (Hash) —

    hash with adjusted prediction and penalty details



140
141
142
143
 
# File 'lib/calcpace/race_predictor.rb', line 140

def predict_time_adjusted(from_race, from_time, to_race, **)
  predicted_seconds = predict_time(from_race, from_time, to_race)
  adjust_time(predicted_seconds, **)
end

#predict_time_clock(from_race, from_time, to_race) ⇒ String

Predicts race time and returns it as a clock time string

Examples:

predict_time_clock('5k', '00:20:00', 'marathon')
#=> '03:11:49'

Parameters:

  • from_race (Numeric, String, Symbol) —

    known distance in kilometers or race name

  • from_time (String, Numeric) —

    time achieved at known distance

  • to_race (Numeric, String, Symbol) —

    target distance in kilometers or race name

Returns:

  • (String) —

    predicted time in HH:MM:SS format



60
61
62
63
 
# File 'lib/calcpace/race_predictor.rb', line 60

def predict_time_clock(from_race, from_time, to_race)
  predicted_seconds = predict_time(from_race, from_time, to_race)
  convert_to_clocktime(predicted_seconds)
end