runby_pace 0.2.50 → 0.2.50.111

data/lib/runby_pace/run_types/find_divisor.rb

@@ -1,47 +1,43 @@
-module RunbyPace
+# frozen_string_literal: true
 
+module Runby
+  # Extend RunTypes with additional behavior. (See comments for details)
   module RunTypes
-
     # Currently, to find the radius of the curve in the pace table data for a given run time,
     #   we start with a radius equal to that of the midpoint of the X axis for the data when
-    #   plotted on a graph. Then we use a radius divisor for the PaceData for each run type to
-    #   dial in the height of the curve. (See RunbyPace::PaceData)
+    #   plotted on a graph. Then we use a radius divisor for the PaceCalculator for each run type to
+    #   dial in the height of the curve. (See Runby::PaceCalculator)
     # This method, #find_divisor, accepts a hash of "golden paces" for a run type along with
     #   the number of seconds of allowable deviation from the golden pace. Then it proceeds
     #   to brute force the divisor.
-    # @param [Hash] golden_paces
+    # @param [GoldenPaceSet] golden_pace_set
     # @param [String] allowable_deviation
     # @return [decimal]
-    def self.find_divisor(golden_paces, allowable_deviation = '00:01')
-      _, first_pace = golden_paces.first
-      last_pace = golden_paces[:'42:00']
+    def self.find_divisor(golden_pace_set, allowable_deviation = '00:01')
       viable_divisors = []
 
       (1.0..5.0).step(0.025) do |candidate_divisor|
         viable_divisor = nil
 
-        golden_paces.each do |five_k, golden_pace|
-          five_k_time = RunbyPace::PaceTime.new(five_k.to_s)
-          pace_data = RunbyPace::PaceData.new(first_pace, last_pace, candidate_divisor)
+        golden_pace_set.each do |five_k, golden_pace|
+          five_k_time = Runby::RunbyTime.new(five_k.to_s)
+          pace_data = Runby::PaceCalculator.new(golden_pace_set, candidate_divisor)
           calculated_pace = pace_data.calc(five_k_time)
-          if !calculated_pace.almost_equals?(golden_pace, allowable_deviation)
+          unless calculated_pace.almost_equals?(golden_pace, allowable_deviation)
             viable_divisor = nil
             break
           end
           viable_divisor = candidate_divisor
         end
 
-        if viable_divisor != nil
-          viable_divisors << viable_divisor
-        end
+        viable_divisors << viable_divisor unless viable_divisor.nil?
       end
 
-      if viable_divisors.length > 0
+      unless viable_divisors.empty?
         # puts viable_divisors
         midpoint = (viable_divisors.length - 1) / 2
         return viable_divisors[midpoint]
       end
     end
-
   end
 end

data/lib/runby_pace/run_types/five_kilometer_race_run.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Runby
+  module RunTypes
+    # Your 5K race pace, which is also useful for running repetitions at this pace
+    class FiveKilometerRaceRun < RunType
+      def description
+        '5K Race Pace'
+      end
+
+      def explanation
+        'The 5K race (~3.1 miles) is an excellent gauge of overall fitness. Running repetitions of varying duration at 5K race pace can boost stroke volume, blood volume, mitochondrial and capillary density, etc.'
+      end
+
+      def lookup_pace(five_k_time, distance_units = :km)
+        five_k_time = RunbyTime.new(five_k_time)
+        pace = Pace.new(five_k_time / 5, '1km').convert_to(distance_units)
+        PaceRange.new(pace, pace)
+      end
+    end
+  end
+end

data/lib/runby_pace/run_types/long_run.rb

@@ -1,31 +1,53 @@
-module RunbyPace
+# frozen_string_literal: true
 
+module Runby
   module RunTypes
-
+    # Arguably one of the most important run types, the "long run" is harder than an "easy run", but easier than
+    #  a "distance run". It should remain conversational.
     class LongRun < RunType
-      attr_reader :slow_pace_data, :fast_pace_data
+      attr_reader :slow_pace_calculator, :fast_pace_calculator
 
       def description
         'Long Run'
       end
 
+      def explanation
+        'For many runners, the long run is the favorite run of the week. It is usually only ran once per week, and accounts for 20-25% of your weekly training volume. Remember that it\'s not a race. It should remain comfortable.'
+      end
+
       def initialize
-        @fast_pace_data = PaceData.new(GoldenPaces::fast[:'14:00'], GoldenPaces::fast[:'42:00'], 2.125)
-        @slow_pace_data = PaceData.new(GoldenPaces::slow[:'14:00'], GoldenPaces::slow[:'42:00'], 1.55)
+        @fast_pace_calculator = PaceCalculator.new(GoldenPaces.fast, 2.125)
+        @slow_pace_calculator = PaceCalculator.new(GoldenPaces.slow, 1.55)
       end
 
-      def pace(five_k_time)
-        fast = @fast_pace_data.calc(five_k_time)
-        slow = @slow_pace_data.calc(five_k_time)
+      def lookup_pace(five_k_time, distance_units = :km)
+        fast = @fast_pace_calculator.calc(five_k_time, distance_units)
+        slow = @slow_pace_calculator.calc(five_k_time, distance_units)
         PaceRange.new(fast, slow)
       end
 
+      # Used in testing, contains hashes mapping 5K race times with the recommended pace-per-km for this run type.
       class GoldenPaces
         def self.fast
-          { '14:00': '04:00', '15:00': '04:16', '20:00': '05:31', '25:00': '06:44', '30:00': '07:54', '35:00':'09:01', '40:00':'10:07', '42:00':'10:32'}
+          GoldenPaceSet.new('14:00': '04:00',
+                            '15:00': '04:16',
+                            '20:00': '05:31',
+                            '25:00': '06:44',
+                            '30:00': '07:54',
+                            '35:00': '09:01',
+                            '40:00': '10:07',
+                            '42:00': '10:32')
         end
+
         def self.slow
-          { '14:00': '04:39', '15:00': '04:57', '20:00': '06:22', '25:00': '07:43', '30:00': '09:00', '35:00':'10:15', '40:00':'11:26', '42:00':'11:53'}
+          GoldenPaceSet.new('14:00': '04:39',
+                            '15:00': '04:57',
+                            '20:00': '06:22',
+                            '25:00': '07:43',
+                            '30:00': '09:00',
+                            '35:00': '10:15',
+                            '40:00': '11:26',
+                            '42:00': '11:53')
         end
       end
     end

data/lib/runby_pace/run_types/mile_race_run.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Runby
+  module RunTypes
+    # Your mile race pace, which is also useful for running repetitions at this pace
+    class MileRaceRun < RunType
+      def description
+        'Mile Race Pace'
+      end
+
+      def explanation
+        'Repetitions run at a pace you would use to race one mile can increase the stroke volume of your heart, strengthen your lungs, increase the number of capillaries around your intermediate and fast twitch fibers, and increase mitochondrial densities around the same.'
+      end
+
+      def lookup_pace(five_k_time, distance_units = :km)
+        five_k_time = RunbyTime.new(five_k_time)
+        mile = Distance.new('1 mile')
+        mile_time = RunMath.predict_race_time('5K', five_k_time, mile)
+        pace = Pace.new(mile_time, mile).convert_to(distance_units)
+        PaceRange.new(pace, pace)
+      end
+    end
+  end
+end

data/lib/runby_pace/run_types/slow_tempo_run.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+require_relative 'tempo_run'
+
+module Runby
+  module RunTypes
+    # The "slow tempo" pace roughly equates to your marathon pace.
+    class SlowTempoRun < TempoRun
+      def description
+        'Slow Tempo Run'
+      end
+
+      def explanation
+        'The slow tempo run is an interval workout of 20-40 minutes per repetition. The pace roughly corresponds to that of your marathon race pace.'
+      end
+
+      def lookup_pace(five_k_time, distance_units = :km)
+        slow = @slow_pace_calculator.calc(five_k_time, distance_units)
+        PaceRange.new(slow, slow)
+      end
+    end
+  end
+end

data/lib/runby_pace/run_types/tempo_run.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Runby
+  module RunTypes
+    # Combines the fast and slow tempo runs into one convenient range of paces
+    class TempoRun < RunType
+      attr_reader :slow_pace_calculator, :fast_pace_calculator
+
+      def description
+        'Tempo Run'
+      end
+
+      def explanation
+        'Ran at a comfortably hard pace that you could maintain for about an hour, if pressed. However, tempo runs are interval workouts, so you won\'t run for longer than 15-40 minutes per repetition'
+      end
+
+      def initialize
+        @fast_pace_calculator = PaceCalculator.new(GoldenPaces.fast, 4.025)
+        @slow_pace_calculator = PaceCalculator.new(GoldenPaces.slow, 3.725)
+      end
+
+      def lookup_pace(five_k_time, distance_units = :km)
+        fast = @fast_pace_calculator.calc(five_k_time, distance_units)
+        slow = @slow_pace_calculator.calc(five_k_time, distance_units)
+        PaceRange.new(fast, slow)
+      end
+
+      # Used in testing, contains hashes mapping 5K race times with the recommended pace-per-km for this run type.
+      class GoldenPaces
+        def self.fast
+          GoldenPaceSet.new('14:00': '03:07',
+                            '15:00': '03:20',
+                            '20:00': '04:21',
+                            '25:00': '05:20',
+                            '30:00': '06:19',
+                            '35:00': '07:16',
+                            '40:00': '08:12',
+                            '42:00': '08:35')
+        end
+
+        def self.slow
+          GoldenPaceSet.new('14:00': '03:18',
+                            '15:00': '03:31',
+                            '20:00': '04:35',
+                            '25:00': '05:37',
+                            '30:00': '06:38',
+                            '35:00': '07:38',
+                            '40:00': '08:36',
+                            '42:00': '08:59')
+        end
+      end
+    end
+  end
+end

data/lib/runby_pace/run_types/ten_kilometer_race_run.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Runby
+  module RunTypes
+    # Your 10K race pace, which is also useful for running repetitions at this pace
+    class TenKilometerRaceRun < RunType
+      def description
+        '10K Race Pace'
+      end
+
+      def explanation
+        'Repetitions ran at 10K race pace (10 km is about 6.2 miles) are like 5K pace repetitions, but less intense. They elicit many of the same benefits and help increase speed in races from the 10K to the half-marathon.'
+      end
+
+      def lookup_pace(five_k_time, distance_units = :km)
+        five_k_time = RunbyTime.new(five_k_time)
+        ten_k_time = RunMath.predict_race_time('5K', five_k_time, '10K')
+        pace = Pace.new(ten_k_time / 10, '1km').convert_to(distance_units)
+        PaceRange.new(pace, pace)
+      end
+    end
+  end
+end

data/lib/runby_pace/runby_range.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Runby
+  # Base class for ranges of Runby data, e.g. PaceRange, SpeedRange, ...
+  class RunbyRange
+    attr_reader :fast, :slow
+
+    def initialize
+      @fast = nil
+      @slow = nil
+      raise 'RunbyRange is a base class for PaceRange and SpeedRange. Instantiate one of them instead.'
+    end
+
+    def to_s(format: :short)
+      if @fast == @slow
+        @fast.to_s(format: format)
+      else
+        "#{@fast}-#{@slow}"
+      end
+    end
+  end
+end

data/lib/runby_pace/runby_time.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Runby
+  # Represents a human-readable time in the format MM:ss
+  class RunbyTime
+    include Comparable
+
+    attr_reader :time_s, :hours_part, :minutes_part, :seconds_part
+
+    def self.new(time)
+      return time if time.is_a? RunbyTime
+      return RunbyTime.parse time if time.is_a?(String) || time.is_a?(Symbol)
+      return from_minutes(time) if time.is_a? Numeric
+      super
+    end
+
+    def initialize(time)
+      init_from_parts time if time.is_a? RunbyTimeParser::TimeParts
+      freeze
+    end
+
+    # @param [numeric] total_seconds
+    def self.from_seconds(total_seconds)
+      hours = total_seconds.abs.to_i / 60 / 60
+      minutes = (total_seconds.abs.to_i / 60) % 60
+      seconds = total_seconds.abs.to_i % 60
+      if hours.positive?
+        RunbyTime.new format('%d:%02d:%02d', hours, minutes, seconds)
+      else
+        RunbyTime.new format('%02d:%02d', minutes, seconds)
+      end
+    end
+
+    # @param [numeric] total_minutes
+    def self.from_minutes(total_minutes)
+      from_seconds(total_minutes * 60.0)
+    end
+
+    # @param [numeric] total_hours
+    def self.from_hours(total_hours)
+      from_seconds(total_hours * 60.0 * 60.0)
+    end
+
+    def self.parse(str)
+      RunbyTimeParser.parse str
+    end
+
+    def self.try_parse(str, is_five_k = false)
+      time, error_message, warning_message = nil
+      begin
+        time = parse str
+      rescue StandardError => ex
+        error_message = "#{ex.message} (#{str})"
+      end
+      warning_message = check_5k_sanity(time) if !time.nil? && is_five_k
+      { time: time, error: error_message, warning: warning_message }
+    end
+
+    def self.check_5k_sanity(time)
+      return unless time.is_a? RunbyTime
+      return '5K times of less than 14:00 are unlikely' if time.minutes_part < 14
+      return '5K times of greater than 42:00 are not fully supported' if time.total_seconds > (42 * 60)
+    end
+
+    def to_s
+      @time_s
+    end
+
+    def total_hours
+      @hours_part + (@minutes_part / 60.0) + (@seconds_part / 60.0 / 60.0)
+    end
+
+    def total_seconds
+      @hours_part * 60 * 60 + @minutes_part * 60 + @seconds_part
+    end
+
+    def total_minutes
+      @hours_part * 60 + @minutes_part + (@seconds_part / 60.0)
+    end
+
+    # @param [RunbyTime] other
+    def -(other)
+      raise "Cannot subtract #{other.class} from a Runby::RunbyTime" unless other.is_a?(RunbyTime)
+      RunbyTime.from_seconds(total_seconds - other.total_seconds)
+    end
+
+    # @param [RunbyTime] other
+    def +(other)
+      raise "Cannot add Runby::RunbyTime to a #{other.class}" unless other.is_a?(RunbyTime)
+      RunbyTime.from_seconds(total_seconds + other.total_seconds)
+    end
+
+    # @param [Numeric] other
+    # @return [RunbyTime]
+    def *(other)
+      raise "Cannot multiply Runby::RunbyTime with a #{other.class}" unless other.is_a?(Numeric)
+      RunbyTime.from_minutes(total_minutes * other)
+    end
+
+    # @param [RunbyTime, Numeric] other
+    # @return [Numeric, RunbyTime]
+    def /(other)
+      raise "Cannot divide Runby::RunbyTime by #{other.class}" unless other.is_a?(RunbyTime) || other.is_a?(Numeric)
+      case other
+      when RunbyTime
+        total_seconds / other.total_seconds
+      when Numeric
+        RunbyTime.from_seconds(total_seconds / other)
+      end
+    end
+
+    def <=>(other)
+      raise "Unable to compare Runby::RunbyTime to #{other.class}(#{other})" unless [RunbyTime, String].include? other.class
+      if other.is_a? RunbyTime
+        total_seconds <=> other.total_seconds
+      elsif other.is_a? String
+        return 0 if @time_s == other
+        total_seconds <=> RunbyTime.parse(other).total_seconds
+      end
+    end
+
+    def almost_equals?(other_time, tolerance_time = '00:01')
+      other_time = RunbyTime.new(other_time) if other_time.is_a?(String)
+      tolerance = RunbyTime.new(tolerance_time)
+      self >= (other_time - tolerance) && self <= (other_time + tolerance)
+    end
+
+    private
+
+    # @param [RunbyTimeParser::TimeParts] parts
+    def init_from_parts(parts)
+      @time_s = parts.format
+      @hours_part = parts[:hours]
+      @minutes_part = parts[:minutes]
+      @seconds_part = parts[:seconds]
+    end
+  end
+end

data/lib/runby_pace/runby_time_parser.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Runby
+  # Helper class which parses strings and returns new RunbyTime(s)
+  class RunbyTimeParser
+    def self.parse(str)
+      time = str.to_s.strip.chomp
+      if time_string?(time)
+        parts = TimeParts.new(time.split(':').reverse)
+      elsif integer?(time)
+        parts = extract_minutes_from_integer time
+      elsif decimal?(time)
+        parts = extract_minutes_from_decimal time
+      else
+        raise 'Invalid time format'
+      end
+      RunbyTime.new(parts)
+    end
+
+    def self.decimal?(str)
+      str.match?(/^\d+[,. ]\d+$/)
+    end
+
+    def self.integer?(str)
+      str.match?(/^\d+$/)
+    end
+
+    def self.time_string?(str)
+      str.match?(/^\d?\d(:\d\d)+$/)
+    end
+
+    def self.extract_minutes_from_decimal(decimal_str)
+      decimal_parts = decimal_str.split(/[,. ]/)
+      minutes = decimal_parts[0].to_i
+      seconds = (decimal_parts[1].to_i / 10.0 * 60).to_i
+      TimeParts.new([seconds, minutes])
+    end
+
+    def self.extract_minutes_from_integer(integer_str)
+      TimeParts.new([0, integer_str.to_i])
+    end
+
+    # Encapsulates the parts of a time string
+    class TimeParts
+      def initialize(parts_array)
+        @keys = { seconds: 0, minutes: 1, hours: 2 }
+        @parts = Array.new(@keys.count, 0)
+        Range.new(0, parts_array.count - 1).each { |i| @parts[i] = parts_array[i] }
+        validate
+        freeze
+      end
+
+      def [](key)
+        i = @keys[key]
+        @parts[i].to_i
+      end
+
+      def format
+        time_f = +''
+        @parts.reverse_each do |part|
+          time_f << ':' << part.to_s.rjust(2, '0')
+        end
+        # Remove leading ':'
+        time_f.slice!(0)
+        # Remove leading '00:00...'
+        time_f.sub!(/^(?:00:)+(\d\d:\d\d)/, '\1') if time_f.length > 5
+        # If the time looks like 00:48, only show 0:48
+        time_f.slice!(0) if time_f.slice(0) == '0'
+        time_f
+      end
+
+      def validate
+        raise 'Hours must be less than 24' if self[:hours] > 23
+        raise 'Minutes must be less than 60 if hours are supplied' if self[:hours].positive? && self[:minutes] > 59
+        raise 'Minutes must be less than 99 if no hours are supplied' if self[:hours].zero? && self[:minutes] > 99
+        raise 'Seconds must be less than 60' if self[:seconds] > 59
+      end
+    end
+  end
+end

data/lib/runby_pace/speed.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Runby
+  # Represents a speed consisting of a distance and a unit of time in which that distance was covered
+  class Speed
+    include Comparable
+
+    attr_reader :distance
+
+    def self.new(distance_or_multiplier, units = :km)
+      return distance_or_multiplier if distance_or_multiplier.is_a? Speed
+      if distance_or_multiplier.is_a? String
+        parsed_speed = Speed.try_parse(distance_or_multiplier)
+        return parsed_speed[:speed] unless parsed_speed[:error]
+      end
+      super
+    end
+
+    def initialize(distance_or_multiplier, units = :km)
+      case distance_or_multiplier
+      when Distance
+        init_from_distance distance_or_multiplier
+      when String
+        # Already tried to parse it as a Speed string. Try parsing it as a Distance string.
+        init_from_distance_string distance_or_multiplier
+      when Numeric
+        init_from_multiplier(distance_or_multiplier, units)
+      else
+        raise "Unable to initialize Runby::Speed from #{distance_or_multiplier}"
+      end
+      freeze
+    end
+
+    def to_s(format: :short)
+      distance = @distance.to_s(format: format)
+      case format
+      when :short then "#{distance}/ph"
+      when :long then "#{distance} per hour"
+      else raise "Invalid string format #{format}"
+      end
+    end
+
+    def as_pace
+      time = Runby::RunbyTime.from_minutes(60.0 / @distance.multiplier)
+      Runby::Pace.new(time, @distance.uom)
+    end
+
+    # @param [String] str is either a long-form speed such as "7.5 miles per hour" or a short-form speed like "7.5mi/ph"
+    def self.parse(str)
+      str = str.to_s.strip.chomp
+      match = str.match(%r{^(?<distance>\d+(?:\.\d+)? ?[A-Za-z]+)(?: per hour|\/ph)$})
+      raise "Invalid speed format (#{str})" unless match
+      distance = Runby::Distance.new(match[:distance])
+      Speed.new distance
+    end
+
+    def self.try_parse(str)
+      speed = nil
+      error_message = nil
+      warning_message = nil
+      begin
+        speed = Speed.parse str
+      rescue StandardError => ex
+        error_message = "#{ex.message} (#{str})"
+      end
+      { speed: speed, error: error_message, warning: warning_message }
+    end
+
+    def <=>(other)
+      raise "Unable to compare Runby::Speed to #{other.class}(#{other})" unless [Speed, String].include? other.class
+      if other.is_a? String
+        return 0 if to_s == other || to_s(format: :long) == other
+        self <=> try_parse(other)[:speed]
+      end
+      @distance <=> other.distance
+    end
+
+    private
+
+    def init_from_distance(distance)
+      @distance = distance
+    end
+
+    def init_from_multiplier(multiplier, uom)
+      @distance = Distance.new(uom, multiplier)
+    end
+
+    def init_from_distance_string(str)
+      results = Distance.try_parse(str)
+      unless results[:error]
+        @distance = results[:distance]
+        return
+      end
+      raise "'#{str}' is not recognized as a Speed or a Distance"
+    end
+  end
+end

data/lib/runby_pace/speed_range.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'runby_range'
+
+module Runby
+  # Represents a range of speeds, from fast to slow.
+  class SpeedRange < RunbyRange
+    def initialize(fast, slow)
+      raise "Invalid fast speed value: #{fast}" unless fast.is_a?(Numeric) || fast.is_a?(Speed)
+      raise "Invalid slow speed value: #{slow}" unless slow.is_a?(Numeric) || slow.is_a?(Speed)
+      @fast = Runby::Speed.new(fast)
+      @slow = Runby::Speed.new(slow)
+      freeze
+    end
+
+    def as_pace_range
+      Runby::PaceRange.new @fast.as_pace, @slow.as_pace
+    end
+
+    def to_s(format: :short)
+      if @fast == @slow
+        @fast.to_s(format: format)
+      else
+        fast_multiplier = format('%g', @fast.distance.multiplier.round(2))
+        slow_multiplier = format('%g', @slow.distance.multiplier.round(2))
+        @fast.to_s(format: format).sub(fast_multiplier.to_s, "#{fast_multiplier}-#{slow_multiplier}")
+      end
+    end
+  end
+end

data/lib/runby_pace/utility/parameter_sanitizer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Runby
+  module Utility
+    # Helps sanitize method parameters. (See RSpec documentation for examples)
+    class ParameterSanitizer
+      attr_reader :parameter
+
+      def initialize(parameter)
+        @parameter = parameter
+      end
+
+      def self.sanitize(parameter)
+        ParameterSanitizer.new parameter
+      end
+
+      def as(type)
+        return @parameter if @parameter.is_a?(type)
+        raise "Unable to sanitize parameter of type #{type}. Missing 'parse' method." unless type.respond_to? :parse
+        type.parse(@parameter)
+      end
+    end
+  end
+
+  # Just a shortcut method
+  def self.sanitize(parameter)
+    Runby::Utility::ParameterSanitizer.sanitize(parameter)
+  end
+end