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: 1228.5,
      time_clock: "00:20:28",
      pace: 245.7,
      pace_clock: "00:04:06"
    }

Parameters:

  • from_race (String, Symbol) —

    known race distance

  • from_time (String, Numeric) —

    time achieved at known distance

  • to_race (String, Symbol) —

    target race distance for comparison

Returns:

  • (Hash) —

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



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

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')
#=> 263.6 (approximately 4:24/km)

Parameters:

  • from_race (String, Symbol) —

    known race distance

  • from_time (String, Numeric) —

    time achieved at known distance

  • to_race (String, Symbol) —

    target race distance to predict

Returns:

  • (Float) —

    predicted pace in seconds per kilometer



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

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:24' (4:24/km)

Parameters:

  • from_race (String, Symbol) —

    known race distance

  • from_time (String, Numeric) —

    time achieved at known distance

  • to_race (String, Symbol) —

    target race distance to predict

Returns:

  • (String) —

    predicted pace in MM:SS format



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

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')
#=> 11123.4 (approximately 3:05:23)

Predict 10K time from half marathon

predict_time('half_marathon', '01:30:00', '10k')
#=> 2565.8 (approximately 42:46)

Parameters:

  • from_race (String, Symbol) —

    known race distance (‘5k’, ‘10k’, ‘half_marathon’, ‘marathon’, ‘100k’, etc.)

  • from_time (String, Numeric) —

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

  • to_race (String, Symbol) —

    target race distance to predict

Returns:

  • (Float) —

    predicted time in seconds

Raises:

  • (ArgumentError) —

    if races are invalid or distances are the same



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

def predict_time(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')

  # Riegel formula: T2 = T1 × (D2/D1)^1.06
  time_seconds * ((to_distance / from_distance)**RIEGEL_EXPONENT)
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:05:23'

Parameters:

  • from_race (String, Symbol) —

    known race distance

  • from_time (String, Numeric) —

    time achieved at known distance

  • to_race (String, Symbol) —

    target race distance to predict

Returns:

  • (String) —

    predicted time in HH:MM:SS format



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

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