Module: EnvironmentalAdjuster

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

Overview

Module for adjusting race performance based on environmental conditions

Scientific basis:

  • Heat: Matthew Ely et al. (2007) “Impact of Weather on Marathon-Running Performance”

  • Altitude: NCAA Altitude Adjustment Factors (TFRRS)

Constant Summary collapse

DATA_PATH = 
File.expand_path('data/environmental_factors.yml', __dir__).freeze
FACTORS = 
YAML.safe_load_file(DATA_PATH, permitted_classes: [], aliases: false).freeze

Instance Method Summary collapse

Instance Method Details

#adjust_time(time_seconds) ⇒ Hash

Adjusts a given time based on environmental conditions

Parameters:

  • time_seconds (Numeric) —

    original time in seconds

  • options (Hash) —

    environmental options

Returns:

  • (Hash) —

    hash with adjusted time and penalty details



39
40
41
42
43
44
45
46
47
48
49
50
51
 
# File 'lib/calcpace/environmental_adjuster.rb', line 39

def adjust_time(time_seconds, **)
  penalty = calculate_penalty(time_seconds: time_seconds, **)
  percent = penalty[:total_penalty_percent]
  adjusted_seconds = (time_seconds * (1 + (percent / 100.0))).round(2)

  {
    original_time: time_seconds,
    adjusted_time: adjusted_seconds,
    adjusted_time_clock: convert_to_clocktime(adjusted_seconds),
    penalty_percent: percent,
    factors: penalty[:factors]
  }
end

#calculate_penalty(temperature: nil, temperature_unit: :c, altitude: nil, time_seconds: nil) ⇒ Hash

Calculates the performance penalty percentage for given environmental conditions

Parameters:

  • temperature (Numeric, nil) (defaults to: nil) —

    ambient temperature

  • temperature_unit (Symbol, String) (defaults to: :c) —

    :c (Celsius) or :f (Fahrenheit)

  • altitude (Numeric, nil) (defaults to: nil) —

    altitude in meters

  • time_seconds (Numeric, nil) (defaults to: nil) —

    duration of the effort in seconds

Returns:

  • (Hash) —

    hash with :total_penalty_percent and breakdown in :factors



21
22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/calcpace/environmental_adjuster.rb', line 21

def calculate_penalty(temperature: nil, temperature_unit: :c, altitude: nil, time_seconds: nil)
  heat_penalty = calculate_heat_penalty(temperature, temperature_unit, time_seconds)
  altitude_penalty = calculate_altitude_penalty(altitude)

  {
    total_penalty_percent: (heat_penalty + altitude_penalty).round(2),
    factors: {
      heat: heat_penalty,
      altitude: altitude_penalty
    }
  }
end

#normalize_time(time_seconds) ⇒ Hash

Normalizes a time achieved in non-ideal conditions to its ideal equivalent

Parameters:

  • time_seconds (Numeric) —

    performance time in seconds

  • options (Hash) —

    environmental options

Returns:

  • (Hash) —

    hash with normalized time and penalty details



58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/calcpace/environmental_adjuster.rb', line 58

def normalize_time(time_seconds, **)
  penalty = calculate_penalty(time_seconds: time_seconds, **)
  percent = penalty[:total_penalty_percent]
  normalized_seconds = (time_seconds / (1 + (percent / 100.0))).round(2)

  {
    original_time: time_seconds,
    normalized_time: normalized_seconds,
    normalized_time_clock: convert_to_clocktime(normalized_seconds),
    penalty_percent: percent,
    factors: penalty[:factors]
  }
end