runby_pace 0.2.50 → 0.2.50.111

data/lib/runby_pace/distance_unit.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Runby
+  # Represents the distance units (e.g. kilometers, miles) used in paces
+  #  including the human-readable description of each unit
+  #  and the factor used to convert it to kilometers.
+  class DistanceUnit
+    attr_reader :symbol, :description, :conversion_factor
+
+    def self.new(unit_of_measure)
+      return unit_of_measure if unit_of_measure.is_a? DistanceUnit
+      return DistanceUnit.parse(unit_of_measure) if unit_of_measure.is_a? String
+      super
+    end
+
+    def initialize(unit_of_measure)
+      raise "':#{unit_of_measure}' is an unknown unit of measure" unless DistanceUnit.known_uom? unit_of_measure
+      @symbol = unit_of_measure
+      @conversion_factor = UOM_DEFINITIONS[@symbol][:conversion_factor]
+      @description = UOM_DEFINITIONS[@symbol][:description]
+      freeze
+    end
+
+    def to_s(format: :long, pluralize: false)
+      case format
+      when :short then @symbol.to_s
+      when :long then pluralize ? description_plural : @description
+      else raise "Invalid string format #{format}"
+      end
+    end
+
+    def description_plural
+      UOM_DEFINITIONS[@symbol][:description_plural]
+    end
+
+    def self.parse(description)
+      return new description if description.is_a? Symbol
+      description = description.strip.chomp.downcase
+      found_uom = nil
+      UOM_DEFINITIONS.each do |uom, details|
+        if details[:synonyms].include? description
+          found_uom = uom
+          break
+        end
+      end
+      raise "Error parsing distance unit '#{description}'" unless found_uom
+      DistanceUnit.new found_uom
+    end
+
+    def self.try_parse(str)
+      uom, error_message = nil
+      begin
+        uom = parse str
+      rescue StandardError => ex
+        error_message = ex.message
+      end
+      { uom: uom, error: error_message }
+    end
+
+    def self.known_uom?(symbol)
+      UOM_DEFINITIONS.key?(symbol)
+    end
+
+    def ==(other)
+      if other.is_a? DistanceUnit
+        @symbol == other.symbol
+      elsif other.is_a? String
+        self == DistanceUnit.parse(other)
+      else
+        raise "Unable to compare DistanceUnit to #{other.class}(#{other})"
+      end
+    end
+
+    UOM_DEFINITIONS =
+      { km: { description: 'kilometer', description_plural: 'kilometers', conversion_factor: 1.0,
+              synonyms: %w[k km kms kilometer kilometers] },
+        m:  { description: 'meter', description_plural: 'meters', conversion_factor: 0.001,
+              synonyms: %w[m meter meters] },
+        mi: { description: 'mile', description_plural: 'miles', conversion_factor: 1.609344,
+              synonyms: %w[mi mile miles] },
+        ft: { description: 'foot', description_plural: 'feet', conversion_factor: 0.0003048,
+              synonyms: %w[ft foot feet] },
+        yd: { description: 'yard', description_plural: 'yards', conversion_factor: 1093.61,
+              synonyms: %w[y yd yds yard yards] },
+        # Fun distance unit of measures
+        marathon: { description: 'marathon', description_plural: 'marathons', conversion_factor: 42.1648128,
+                    synonyms: %w[marathon] } }.freeze
+  end
+end

data/lib/runby_pace/golden_pace_set.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Runby
+
+  # Maps a set of 5K race times with their pre-calculated pace recommendations.
+  # This is useful in testing as well as defining the fastest and slowest supported 5K times.
+  # GoldenPaceSet could conceivably be used to pre-compute a large number of recommended paces,
+  #  thus reducing runtime CPU overhead.
+  class GoldenPaceSet
+    include Enumerable
+
+    attr_reader :paces
+
+    # The fastest 5K time supported by RunbyPace
+    FASTEST_5K = :'14:00'
+
+    # The slowest 5K time supported by RunbyPace
+    SLOWEST_5K = :'42:00'
+
+    # @param [Hash] paces_hash is a hash mapping 5K time symbols to times, represented as strings.
+    # An example paces_hash is {'14:00':'4:00', '15:00':'4:55'}
+    def initialize(paces_hash)
+      @paces = {}
+      paces_hash.each { |five_k_time, recommended_pace| @paces[five_k_time.to_sym] = Pace.new(recommended_pace) }
+    end
+
+    def each
+      @paces.each do |h, v|
+        yield h, v
+      end
+    end
+
+    # Returns first/fastest recommended pace in the set
+    def first
+      @paces[FASTEST_5K]
+    end
+    alias fastest first
+
+    # Return the last/slowest recommended pace in the set
+    def last
+      @paces[SLOWEST_5K]
+    end
+    alias slowest last
+
+    # Creates and returns a new GoldenPaceSet with only two entries
+    def self.new_from_endpoints(fastest, slowest)
+      GoldenPaceSet.new(FASTEST_5K => fastest, SLOWEST_5K => slowest)
+    end
+  end
+end

data/lib/runby_pace/pace.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Runby
+  # Represents a pace consisting of a distance and a time in which that distance was covered
+  class Pace
+    include Comparable
+
+    attr_reader :time, :distance
+
+    def self.new(time_or_pace, distance = '1K')
+      return time_or_pace if time_or_pace.is_a? Pace
+      super
+    end
+
+    def initialize(time_or_pace, distance = '1K')
+      case time_or_pace
+      when RunbyTime
+        init_from_time time_or_pace, distance
+      when String
+        init_from_string time_or_pace, distance
+      else
+        raise 'Invalid Time or Pace'
+      end
+      freeze
+    end
+
+    def convert_to(target_distance)
+      target_distance = Distance.new(target_distance) unless target_distance.is_a?(Distance)
+      return self if @distance == target_distance
+      conversion_factor = target_distance / @distance
+      Pace.new @time * conversion_factor, target_distance
+    end
+
+    def to_s(format: :short)
+      leading_one_regex = /^1 ?/
+      distance_s = @distance.to_s(format: format).gsub(leading_one_regex, '')
+      case format
+      when :short then "#{time} p/#{distance_s}"
+      when :long then "#{time} per #{distance_s}"
+      else raise "Invalid string format #{format}"
+      end
+    end
+
+    def as_speed
+      total_minutes = @time.total_minutes
+      multiplier = total_minutes.positive? ? (60 / total_minutes).round(2) : 0
+      distance = Runby::Distance.new(@distance.uom, multiplier)
+      Runby::Speed.new distance
+    end
+
+    def meters_per_minute
+      total_minutes = @time.total_minutes
+      return 0 unless total_minutes.positive?
+      @distance.meters / total_minutes
+    end
+
+    # @param [String] str is either a long-form pace such as "10:00 per mile" or a short-form pace like "10:00 p/mi"
+    def self.parse(str)
+      str = str.to_s.strip.chomp
+      match = str.match %r{^(?<time>[:\d]*) ?(?: per |p\/)(?<distance>(?:[\d.]+ ?)?\w+)$}
+      raise "Invalid pace format (#{str})" unless match
+      time = Runby::RunbyTime.new(match[:time])
+      distance = Runby::Distance.new(match[:distance])
+      Pace.new time, distance
+    end
+
+    def self.try_parse(str)
+      pace = nil
+      error_message = nil
+      warning_message = nil
+      begin
+        pace = Pace.parse str
+      rescue StandardError => ex
+        error_message = ex.message
+      end
+      { pace: pace, error: error_message, warning: warning_message }
+    end
+
+    def <=>(other)
+      raise "Unable to compare Runby::Pace to #{other.class}(#{other})" unless [Pace, RunbyTime, String].include? other.class
+      if other.is_a? Pace
+        meters_per_minute.round(2) <=> other.meters_per_minute.round(2)
+      elsif other.is_a? RunbyTime
+        @time <=> other
+      elsif other.is_a? String
+        return 0 if to_s == other || to_s(format: :long) == other
+        return 0 if @time == other
+        self <=> try_parse(other)[:pace]
+      end
+    end
+
+    def almost_equals?(other_pace, tolerance_time = '00:01')
+      if other_pace.is_a?(RunbyTime)
+        return almost_equals?(Pace.new(other_pace, @distance), tolerance_time)
+      end
+      if other_pace.is_a?(String)
+        return almost_equals?(Pace.new(other_pace, @distance), tolerance_time) if other_pace.match?(/^\d?\d:\d\d$/)
+        other_pace = Pace.parse(other_pace)
+      end
+      tolerance = RunbyTime.new(tolerance_time)
+      fast_end = (self - tolerance)
+      slow_end = (self + tolerance)
+      slow_end <= other_pace && other_pace <= fast_end
+    end
+
+    # @param [Pace, RunbyTime] other
+    def -(other)
+      if other.is_a?(Pace)
+        Pace.new(@time - other.convert_to(@distance).time, @distance)
+      elsif other.is_a?(RunbyTime)
+        Pace.new(@time - other, @distance)
+      end
+    end
+
+    # @param [Pace, RunbyTime] other
+    def +(other)
+      if other.is_a?(Pace)
+        Pace.new(@time + other.convert_to(@distance).time, @distance)
+      elsif other.is_a?(RunbyTime)
+        Pace.new(@time + other, @distance)
+      end
+    end
+
+    def distance_covered_over_time(time)
+      time = Runby.sanitize(time).as(RunbyTime)
+      if time.total_minutes.zero? || @distance.multiplier.zero?
+        return Runby::Distance.new(@distance.uom, 0)
+      end
+      divisor = @time.total_minutes / time.total_minutes / @distance.multiplier
+      distance_covered = Runby::Distance.new(@distance.uom, 1 / divisor)
+      distance_covered
+    end
+
+    private
+
+    def init_from_string(string, distance = '1K')
+      pace = Pace.try_parse(string)
+      if pace[:pace]
+        @time = pace[:pace].time
+        @distance = pace[:pace].distance
+        return
+      end
+      @time = Runby::RunbyTime.new string
+      @distance = Runby::Distance.new distance
+    end
+
+    def init_from_time(time, distance)
+      @time = time
+      @distance = Runby::Distance.new distance
+    end
+  end
+end

data/lib/runby_pace/{pace_data.rb → pace_calculator.rb}

@@ -1,7 +1,8 @@
-module RunbyPace
-
-  class PaceData
+# frozen_string_literal: true
 
+module Runby
+  # Encapsulates the algorithms used to calculate target paces.
+  class PaceCalculator
     # The number of data points plotted on our line of 5K times.
     #  We take 5K times from 14:00 to 42:00 with a sample rate
     #  of 30 seconds, and out pops 57.
@@ -26,26 +27,41 @@ module RunbyPace
     #  until it matches that of the data. (See #curve_minutes)
     attr_reader :midpoint_radius_divisor
 
-    def initialize(fastest_pace_km, slowest_pace_km, midpoint_radius_divisor)
-      @fastest_pace_km = RunbyPace::PaceTime.new(fastest_pace_km)
-      @slowest_pace_km = RunbyPace::PaceTime.new(slowest_pace_km)
+    def initialize(golden_pace_set, midpoint_radius_divisor)
+      @fastest_pace_km = golden_pace_set.fastest
+      @slowest_pace_km = golden_pace_set.slowest
       @midpoint_radius_divisor = midpoint_radius_divisor
     end
 
     # Calculate the slope of the line between the fastest and slowest paces
     def slope
-      (@slowest_pace_km.total_minutes - @fastest_pace_km.total_minutes) / (DATA_POINTS_COUNT - 1)
+      (@slowest_pace_km.time.total_minutes - @fastest_pace_km.time.total_minutes) / (DATA_POINTS_COUNT - 1)
     end
 
     # Calculate the prescribed pace for the given 5K time
-    def calc(five_k_time)
-      five_k_time = RunbyPace::PaceTime.new(five_k_time)
-      x2 = ((five_k_time.total_minutes * 2) - (MIDPOINT_X - 1)) - 1
-      RunbyPace::PaceTime.from_minutes(slope * x2 + @fastest_pace_km.total_minutes + curve_minutes(x2))
+    # @return [Pace]
+    def calc(five_k_time, distance_units = :km)
+      five_k_time = Runby.sanitize(five_k_time).as(RunbyTime)
+      distance_units = Runby.sanitize(distance_units).as(DistanceUnit)
+
+      minutes_per_unit = calculate_minutes_per_unit(distance_units, five_k_time)
+      build_pace minutes_per_unit, distance_units
     end
 
     private
 
+    def build_pace(minutes_per_unit, distance_units)
+      time = RunbyTime.from_minutes(minutes_per_unit)
+      distance = Distance.new distance_units, 1
+      Pace.new time, distance
+    end
+
+    def calculate_minutes_per_unit(distance_units, five_k_time)
+      x2 = ((five_k_time.total_minutes * 2) - (MIDPOINT_X - 1)) - 1
+      minutes_per_km = slope * x2 + @fastest_pace_km.time.total_minutes + curve_minutes(x2)
+      minutes_per_km * distance_units.conversion_factor
+    end
+
     # Since the paces for each 5K time do not progress in a straight line
     #  when plotted on a graph, but rather a curve with its highest point near
     #  the center, we must add some seconds to the calculated time depending on
@@ -55,12 +71,12 @@ module RunbyPace
     # The default curve radius is the same as the midpoint of the X axis,
     #  forming a circle. Use #midpoint_radius_divisor to reduce it's size.
     def curve_minutes(x_axis)
-      return 0 if @midpoint_radius_divisor == 0
+      return 0 if @midpoint_radius_divisor.zero?
       midpoint_reduction = x_axis
       midpoint = MIDPOINT_X
       if midpoint_reduction > midpoint
         midpoint_reduction = midpoint - (midpoint_reduction - midpoint)
-        midpoint_reduction = 0 if midpoint_reduction < 0
+        midpoint_reduction = 0 if midpoint_reduction.negative?
       end
       # TODO: Use an actual curve instead of a triangle to calculate the number of minutes to add.
       midpoint_reduction / @midpoint_radius_divisor / 60

data/lib/runby_pace/pace_range.rb

@@ -1,15 +1,33 @@
-module RunbyPace
+# frozen_string_literal: true
 
-  class PaceRange
-    attr_reader :fast, :slow
+require_relative 'runby_range'
 
-    def initialize(fast, slow)
-      @fast = RunbyPace::PaceTime.new(fast)
-      @slow = RunbyPace::PaceTime.new(slow)
+module Runby
+  # Represents a range of paces, from fast to slow.
+  class PaceRange < RunbyRange
+    def initialize(fast, slow, distance_units = :km)
+      if fast.is_a?(Pace) && slow.is_a?(Pace)
+        @fast = fast
+        @slow = slow
+      else
+        # Hopefully 'fast' and 'slow' are parseable as a RunbyTime
+        distance = Distance.new distance_units, 1
+        @fast = Pace.new(fast, distance)
+        @slow = Pace.new(slow, distance)
+      end
+      freeze
     end
 
-    def to_s
-      "#{@fast}-#{@slow}"
+    def as_speed_range
+      SpeedRange.new @fast.as_speed, @slow.as_speed
+    end
+
+    def to_s(format: :short)
+      if @fast == @slow
+        @fast.to_s(format: format)
+      else
+        @fast.to_s(format: format).sub(@fast.time.to_s, "#{@fast.time}-#{@slow.time}")
+      end
     end
   end
-end
+end

data/lib/runby_pace/run_math.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Runby
+  # An assortment of mathematical functions related to running.
+  class RunMath
+    def self.predict_race_time(race1_distance, race1_time, target_distance)
+      race1_distance = Runby.sanitize(race1_distance).as(Distance)
+      race1_time = Runby.sanitize(race1_time).as(RunbyTime)
+      target_distance = Runby.sanitize(target_distance).as(Distance)
+
+      race1_time * (target_distance / race1_distance)**1.06
+    end
+  end
+end

data/lib/runby_pace/run_type.rb

@@ -1,18 +1,26 @@
-module RunbyPace
+# frozen_string_literal: true
 
+module Runby
+  # Base class for all run types
   class RunType
     def description
       'No description'
     end
 
-    def pace(five_k_time)
+    def explanation
+      'No explanation'
     end
+
+    def lookup_pace(five_k_time, distance_units = :km) end
   end
 
+  # Extends RunTypes with additional methods.
+  # Since RunTypes is autogenerated in all_run_types.g.rb, we needed a safe way of adding behavior to it
+  #  without complicating the codegen.
   module RunTypes
+    # Returns an initialized run type, given the name of an existing run type
     def self.new_from_name(run_type_name)
-      Object::const_get("RunbyPace::RunTypes::#{run_type_name}").new
+      Object.const_get("Runby::RunTypes::#{run_type_name}").new
     end
   end
-
 end

data/lib/runby_pace/run_types/all_run_types.g.rb

@@ -1,12 +1,14 @@
-# This file is automatically generated by a rake task
-
-module RunbyPace
-
-  module RunTypes
-
-    def self.all
-      %w(EasyRun LongRun)
-    end
-
-  end
-end
+# This file is automatically generated by a rake task
+
+module Runby
+  # Encapsulates data and behavior relating to all run types.
+  module RunTypes
+    def self.all
+      %w[DistanceRun EasyRun FastTempoRun FiveKilometerRaceRun LongRun MileRaceRun SlowTempoRun TempoRun TenKilometerRaceRun]
+    end
+
+    def self.all_classes
+      [DistanceRun, EasyRun, FastTempoRun, FiveKilometerRaceRun, LongRun, MileRaceRun, SlowTempoRun, TempoRun, TenKilometerRaceRun]
+    end
+  end
+end

data/lib/runby_pace/run_types/all_run_types.template

@@ -1,12 +1,14 @@
 # This file is automatically generated by a rake task
 
-module RunbyPace
-
+module Runby
+  # Encapsulates data and behavior relating to all run types.
   module RunTypes
-
     def self.all
-      %w(__RUN_TYPES__)
+      %w[__RUN_TYPE_NAMES__]
     end
 
+    def self.all_classes
+      [__RUN_TYPES__]
+    end
   end
 end

data/lib/runby_pace/run_types/distance_run.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Runby
+  module RunTypes
+    # Defines the venerable "distance run", the backbone of any distance running program.
+    #  Most of your runs should be at this pace. Harder than an "easy run" but still conversational.
+    class DistanceRun < RunType
+      attr_reader :slow_pace_calculator, :fast_pace_calculator
+
+      def description
+        'Distance Run'
+      end
+
+      def explanation
+        'Most of your weekly training should be comprised of Distance Runs. They are faster than easy runs, but you should still be able to carry on a conversation.'
+      end
+
+      def initialize
+        @fast_pace_calculator = PaceCalculator.new(GoldenPaces.fast, 3.675)
+        @slow_pace_calculator = PaceCalculator.new(GoldenPaces.slow, 2.175)
+      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:44',
+                            '15:00': '03:58',
+                            '20:00': '05:09',
+                            '25:00': '06:18',
+                            '30:00': '07:24',
+                            '35:00': '08:29',
+                            '40:00': '09:33',
+                            '42:00': '09:58')
+        end
+
+        def self.slow
+          GoldenPaceSet.new('14:00': '04:17',
+                            '15:00': '04:33',
+                            '20:00': '05:53',
+                            '25:00': '07:09',
+                            '30:00': '08:23',
+                            '35:00': '09:33',
+                            '40:00': '10:42',
+                            '42:00': '11:10')
+        end
+      end
+    end
+  end
+end

data/lib/runby_pace/run_types/easy_run.rb

@@ -1,31 +1,52 @@
-module RunbyPace
+# frozen_string_literal: true
 
+module Runby
   module RunTypes
-
+    # An easy run is basically a jog. It should be conversational.
     class EasyRun < RunType
-      attr_reader :slow_pace_data, :fast_pace_data
+      attr_reader :slow_pace_calculator, :fast_pace_calculator
 
       def description
         'Easy Run'
       end
 
+      def explanation
+        'Also called a recovery run, the easy run is harder than jogging, but you should still be able to carry on a conversation.'
+      end
+
       def initialize
-        @fast_pace_data = PaceData.new(GoldenPaces::fast[:'14:00'], GoldenPaces::fast[:'42:00'], 1.99)
-        @slow_pace_data = PaceData.new(GoldenPaces::slow[:'14:00'], GoldenPaces::slow[:'42:00'], 1.35)
+        @fast_pace_calculator = PaceCalculator.new(GoldenPaces.fast, 1.99)
+        @slow_pace_calculator = PaceCalculator.new(GoldenPaces.slow, 1.35)
       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:17', '15:00': '04:33', '20:00': '05:53', '25:00': '07:09', '30:00': '08:23', '35:00': '09:33', '40:00': '10:41', '42:00': '11:08'}
+          GoldenPaceSet.new('14:00': '04:17',
+                            '15:00': '04:33',
+                            '20:00': '05:53',
+                            '25:00': '07:09',
+                            '30:00': '08:23',
+                            '35:00': '09:33',
+                            '40:00': '10:41',
+                            '42:00': '11:08')
         end
+
         def self.slow
-          { '14:00': '05:01', '15:00': '05:20', '20:00': '06:51', '25:00': '08:17', '30:00': '09:38', '35:00': '10:56', '40:00': '12:10', '42:00': '12:39'}
+          GoldenPaceSet.new('14:00': '05:01',
+                            '15:00': '05:20',
+                            '20:00': '06:51',
+                            '25:00': '08:17',
+                            '30:00': '09:38',
+                            '35:00': '10:56',
+                            '40:00': '12:10',
+                            '42:00': '12:39')
         end
       end
     end

data/lib/runby_pace/run_types/fast_tempo_run.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+require_relative 'tempo_run'
+
+module Runby
+  module RunTypes
+    # The "fast tempo" pace roughly equates to your half-marathon pace.
+    #  It's a pace you could maintain for about an hour, if pressed.
+    class FastTempoRun < TempoRun
+      def description
+        'Fast Tempo Run'
+      end
+
+      def explanation
+        'The fast tempo run is an interval workout of 15-25 minutes per repetition. The pace roughly corresponds to that of your half-marathon race pace.'
+      end
+
+      def lookup_pace(five_k_time, distance_units = :km)
+        fast = @fast_pace_calculator.calc(five_k_time, distance_units)
+        PaceRange.new(fast, fast)
+      end
+    end
+  end
+end