foresight 0.1.0

data/lib/foresight/evaluation_report.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Foresight
+  EvaluationReport = Struct.new(:classes, :series, :excluded_series, :levels, keyword_init: true)
+  ClassSummary = Struct.new(:demand_class, :series_count, :excluded_origins, :zero_scale_origins, :held_out,
+                            :zero_held_out, :nonzero_held_out, :mae, :rmse, :mase,
+                            :scaled_pinball, :scaled_pinball_zero, :scaled_pinball_nonzero,
+                            :coverage, :lead_time_coverage, keyword_init: true)
+  SeriesEntry = Struct.new(:index, :demand_class, :backtest, keyword_init: true)
+
+  class EvaluationReport
+    DEMAND_CLASSES = %i[smooth erratic intermittent lumpy].freeze
+
+    class << self
+      def aggregate(entries, horizon:, levels:)
+        classes = DEMAND_CLASSES.to_h do |demand_class|
+          backtests = entries.select { |entry| entry.demand_class == demand_class }.map(&:backtest)
+          [demand_class, summary(demand_class, backtests, levels)]
+        end
+        new(classes: classes, series: entries, excluded_series: 0, levels: levels)
+      end
+
+      private
+
+      def summary(demand_class, backtests, levels)
+        held_out = backtests.sum(&:held_out)
+        origins = backtests.sum { |backtest| backtest.origins.size }
+        ClassSummary.new(demand_class: demand_class, series_count: backtests.size,
+                         excluded_origins: backtests.sum(&:excluded_origins),
+                         zero_scale_origins: backtests.sum(&:zero_scale_origins), held_out: held_out,
+                         zero_held_out: backtests.sum(&:zero_held_out),
+                         nonzero_held_out: backtests.sum(&:nonzero_held_out),
+                         mae: mean(backtests.map(&:mae)), rmse: mean(backtests.map(&:rmse)),
+                         mase: mean(backtests.map(&:mase)),
+                         scaled_pinball: level_means(backtests, levels, &:scaled_pinball),
+                         scaled_pinball_zero: level_means(backtests, levels, &:scaled_pinball_zero),
+                         scaled_pinball_nonzero: level_means(backtests, levels, &:scaled_pinball_nonzero),
+                         coverage: pooled(backtests, levels, held_out, &:covered),
+                         lead_time_coverage: pooled(backtests, levels, origins, &:lead_time_hits))
+      end
+
+      def level_means(backtests, levels)
+        levels.to_h { |level| [level, mean(backtests.map { |backtest| yield(backtest)[level] })] }
+      end
+
+      def pooled(backtests, levels, total)
+        levels.to_h { |level| [level, proportion(backtests.sum { |backtest| yield(backtest)[level] }, total)] }
+      end
+
+      def mean(values)
+        present = values.compact
+        return if present.empty?
+
+        present.inject(:+) / present.size
+      end
+
+      def proportion(count, total)
+        count.fdiv(total) if total.positive?
+      end
+    end
+  end
+end

data/lib/foresight/forecaster.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Foresight
+  class Forecaster
+    SMOOTH_MODELS = %i[naive seasonal_naive ses].freeze
+
+    def initialize(options)
+      @options = options
+      @horizon = options[:count]
+    end
+
+    def call(series)
+      check_model_history(series.size)
+      classification = classify(series.exact)
+      name = @options[:model] || Selector.model_for(classification)
+      model_class = MODELS.fetch(name)
+      kind = strategy_kind(name)
+      check_strategy_history(kind, model_class, series.size)
+      keys = series.future_keys(@horizon) if series.keys
+      model = model_class.new(series.values, @options)
+      forecast = model.forecast(@horizon)
+      strategy = quantile_strategy(kind, model, series.values, forecast)
+      Result.new(forecast: keyed(forecast, keys),
+                 quantiles: strategy.quantiles.transform_values { |steps| keyed(steps, keys) },
+                 lead_time_quantiles: strategy.lead_time_quantiles, model: name,
+                 demand_class: classification&.demand_class, reason: Selector.reason(classification, @options[:model]),
+                 strategy: @options[:strategy], levels: @options[:levels])
+    end
+
+    private
+
+    def check_model_history(size)
+      model_class = MODELS[@options[:model]]
+      return SeasonalNaive.check_history(size, @options) if model_class == SeasonalNaive
+
+      required = model_class ? model_class.minimum_history(@options) : Selector::MINIMUM_HISTORY
+      return if size >= required
+
+      component = model_class ? model_class.name.split("::").last : "automatic model selection"
+      raise InputError, "#{component} requires at least #{required} observations, got #{size}"
+    end
+
+    def classify(exact)
+      return Classifier.call(exact) unless exact.all?(&:zero?)
+      return if @options[:model]
+
+      raise InputError, "automatic selection requires at least one non-zero observation; specify a model instead"
+    end
+
+    def strategy_kind(name)
+      return :conformal if @options[:strategy] == :conformal
+
+      SMOOTH_MODELS.include?(name) ? :gaussian : :compound
+    end
+
+    def check_strategy_history(kind, model_class, size)
+      required = case kind
+                 when :gaussian then GaussianStrategy.minimum_history(model_class, @options)
+                 when :compound then CompoundStrategy.minimum_history(model_class, @options)
+                 else ConformalStrategy.minimum_history(model_class, @options, @horizon)
+                 end
+      return if size >= required
+
+      raise InputError, "#{kind} quantiles need at least #{required} observations, got #{size}"
+    end
+
+    def quantile_strategy(kind, model, values, forecast)
+      levels = @options[:levels]
+      case kind
+      when :gaussian then GaussianStrategy.new(model, horizon: @horizon, levels: levels)
+      when :compound
+        CompoundStrategy.new(model, horizon: @horizon, levels: levels, paths: @options[:paths], seed: @options[:seed])
+      else ConformalStrategy.new(model.class, values, @options, horizon: @horizon, levels: levels, point: forecast)
+      end
+    end
+
+    def keyed(steps, keys)
+      keys ? keys.zip(steps).to_h : steps
+    end
+  end
+end

data/lib/foresight/frequency.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Foresight
+  class Frequency
+    DATE_UNITS = %i[day week month year].freeze
+
+    attr_reader :unit, :seconds
+
+    class << self
+      def detect(keys)
+        frequency = implied_by(keys[0], keys[1])
+        keys.each_cons(2) do |earlier, later|
+          next if frequency&.follows?(earlier, later)
+
+          raise InputError, "keys #{key_text(earlier)} and #{key_text(later)} do not follow the series frequency; " \
+                            "every period must be present, with a value of zero for periods without demand"
+        end
+        frequency
+      end
+
+      private
+
+      def implied_by(earlier, later)
+        if Date === earlier
+          DATE_UNITS.map { |unit| new(unit) }.find { |frequency| frequency.follows?(earlier, later) }
+        elsif later.to_r > earlier.to_r
+          new(:second, later.to_r - earlier.to_r)
+        end
+      end
+
+      def key_text(key)
+        Date === key ? key.to_s : key.inspect
+      end
+    end
+
+    def initialize(unit, seconds = nil)
+      @unit = unit
+      @seconds = seconds
+    end
+
+    def follows?(earlier, later)
+      case unit
+      when :day then later - earlier == 1
+      when :week then later - earlier == 7
+      when :month then later.day == earlier.day && month_index(later) == month_index(earlier) + 1
+      when :year then later.month == earlier.month && later.day == earlier.day && later.year == earlier.year + 1
+      else later.to_r - earlier.to_r == seconds
+      end
+    end
+
+    def advance(key, periods)
+      case unit
+      when :day then key + periods
+      when :week then key + 7 * periods
+      when :month then month_after(key, periods)
+      when :year then key >> (12 * periods)
+      else time_after(key, periods)
+      end
+    end
+
+    private
+
+    def month_index(date)
+      12 * date.year + date.month
+    end
+
+    def month_after(key, periods)
+      date = key >> periods
+      return date if date.day == key.day
+
+      raise InputError, "cannot key monthly forecasts after #{key}: #{date.strftime("%Y-%m")} has no day #{key.day}"
+    end
+
+    def time_after(key, periods)
+      time = key + periods * seconds
+      Time === key ? key.class.at(time) : time
+    end
+  end
+end

data/lib/foresight/gaussian_strategy.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Foresight
+  class GaussianStrategy
+    def self.minimum_history(model_class, options)
+      model_class.minimum_history(options) + 1
+    end
+
+    def initialize(model, horizon:, levels:)
+      residuals = model.residuals
+      variance = residuals.sum { |residual| residual * residual } / residuals.size
+      @sigma = Math.sqrt(variance)
+      @forecast = model.forecast(horizon)
+      @step_factors = model.step_factors(horizon)
+      @total_factor = model.total_factor(horizon)
+      @deviates = deviates(levels)
+    end
+
+    def quantiles
+      @deviates.transform_values do |deviate|
+        @forecast.zip(@step_factors).map { |value, factor| [0.0, value + deviate * @sigma * Math.sqrt(factor)].max }
+      end
+    end
+
+    def lead_time_quantiles
+      total = @forecast.sum
+      @deviates.transform_values { |deviate| [0.0, total + deviate * @sigma * Math.sqrt(@total_factor)].max }
+    end
+
+    private
+
+    def deviates(levels)
+      largest = -Float::INFINITY
+      levels.to_h do |level|
+        # The running maximum absorbs last-bit disagreements between the two AS 241 approximations
+        largest = [largest, Normal.quantile(level)].max
+        [level, largest]
+      end
+    end
+  end
+end

data/lib/foresight/input_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Foresight
+  class InputError < StandardError
+  end
+end

data/lib/foresight/metrics.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Foresight
+  module Metrics
+    class << self
+      def scale(history)
+        total = history.each_cons(2).inject(0.0) { |sum, (earlier, later)| sum + (later - earlier).abs }
+        total / (history.size - 1)
+      end
+
+      def mae(actual, forecast)
+        total = actual.zip(forecast).inject(0.0) { |sum, (value, predicted)| sum + (value - predicted).abs }
+        total / actual.size
+      end
+
+      def rmse(actual, forecast)
+        total = actual.zip(forecast).inject(0.0) do |sum, (value, predicted)|
+          error = value - predicted
+          sum + error * error
+        end
+        Math.sqrt(total / actual.size)
+      end
+
+      def pinball(level, quantile, actual)
+        level = level.to_f
+        actual >= quantile ? level * (actual - quantile) : (1 - level) * (quantile - actual)
+      end
+    end
+  end
+end

data/lib/foresight/naive.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Foresight
+  class Naive
+    attr_reader :residuals
+
+    def self.minimum_history(_options)
+      1
+    end
+
+    def initialize(values, _options)
+      @forecast = values.last
+      @residuals = (1...values.size).map { |index| values[index] - values[index - 1] }
+    end
+
+    def forecast(horizon)
+      Array.new(horizon, @forecast)
+    end
+
+    def step_factors(horizon)
+      (1..horizon).to_a
+    end
+
+    def total_factor(horizon)
+      horizon * (horizon + 1) * (2 * horizon + 1) / 6
+    end
+  end
+end

data/lib/foresight/normal.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Foresight
+  # Wichura (1988), Algorithm AS 241, Applied Statistics 37(3), 477-484
+  module Normal
+    CENTRAL_NUMERATOR = [
+      3.38713_28727_96366_6080, 1.33141_66789_17843_7745e+2, 1.97159_09503_06551_4427e+3,
+      1.37316_93765_50946_1125e+4, 4.59219_53931_54987_1457e+4, 6.72657_70927_00870_0853e+4,
+      3.34305_75583_58812_8105e+4, 2.50908_09287_30122_6727e+3
+    ].freeze
+    CENTRAL_DENOMINATOR = [
+      1.0, 4.23133_30701_60091_1252e+1, 6.87187_00749_20579_0830e+2, 5.39419_60214_24751_1077e+3,
+      2.12137_94301_58659_5867e+4, 3.93078_95800_09271_0610e+4, 2.87290_85735_72194_2674e+4,
+      5.22649_52788_52854_5610e+3
+    ].freeze
+    INTERMEDIATE_NUMERATOR = [
+      1.42343_71107_49683_57734, 4.63033_78461_56545_29590, 5.76949_72214_60691_40550,
+      3.64784_83247_63204_60504, 1.27045_82524_52368_38258, 2.41780_72517_74506_11770e-1,
+      2.27238_44989_26918_45833e-2, 7.74545_01427_83414_07640e-4
+    ].freeze
+    INTERMEDIATE_DENOMINATOR = [
+      1.0, 2.05319_16266_37758_82187, 1.67638_48301_83803_84940, 6.89767_33498_51000_04550e-1,
+      1.48103_97642_74800_74590e-1, 1.51986_66563_61645_71966e-2, 5.47593_80849_95344_94600e-4,
+      1.05075_00716_44416_84324e-9
+    ].freeze
+    TAIL_NUMERATOR = [
+      6.65790_46435_01103_77720, 5.46378_49111_64114_36990, 1.78482_65399_17291_33580,
+      2.96560_57182_85048_91230e-1, 2.65321_89526_57612_30930e-2, 1.24266_09473_88078_43860e-3,
+      2.71155_55687_43487_57815e-5, 2.01033_43992_92288_13265e-7
+    ].freeze
+    TAIL_DENOMINATOR = [
+      1.0, 5.99832_20655_58879_37690e-1, 1.36929_88092_27358_05310e-1, 1.48753_61290_85061_48525e-2,
+      7.86869_13114_56132_59100e-4, 1.84631_83175_10054_68180e-5, 1.42151_17583_16445_88870e-7,
+      2.04426_31033_89939_78564e-15
+    ].freeze
+
+    class << self
+      def quantile(level)
+        level = level.to_f.clamp(Float::MIN, 1.0 - Float::EPSILON / 2)
+        offset = level - 0.5
+        if offset.abs <= 0.425
+          return offset * ratio(CENTRAL_NUMERATOR, CENTRAL_DENOMINATOR, 0.180625 - offset * offset)
+        end
+
+        depth = Math.sqrt(-Math.log(offset < 0 ? level : 1.0 - level))
+        deviate = if depth <= 5.0
+                    ratio(INTERMEDIATE_NUMERATOR, INTERMEDIATE_DENOMINATOR, depth - 1.6)
+                  else
+                    ratio(TAIL_NUMERATOR, TAIL_DENOMINATOR, depth - 5.0)
+                  end
+        offset < 0 ? -deviate : deviate
+      end
+
+      private
+
+      def ratio(numerator, denominator, argument)
+        polynomial(numerator, argument) / polynomial(denominator, argument)
+      end
+
+      def polynomial(coefficients, argument)
+        coefficients.reverse_each.inject { |sum, coefficient| sum * argument + coefficient }
+      end
+    end
+  end
+end

data/lib/foresight/options.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Foresight
+  module Options
+    FORECAST = %i[count model levels strategy seed season_length paths windows alpha alpha_d alpha_p].freeze
+    BACKTEST = %i[horizon origins step model levels strategy seed season_length paths windows
+                  alpha alpha_d alpha_p].freeze
+    STRATEGIES = %i[distribution conformal].freeze
+    SMOOTHING = %i[alpha alpha_d alpha_p].freeze
+    INTEGERS_AT_LEAST = { 0 => "a non-negative Integer", 1 => "a positive Integer",
+                          2 => "an Integer of at least 2" }.freeze
+
+    class << self
+      def forecast(raw)
+        check_names(raw, FORECAST)
+        supplied = raw.compact
+        { count: integer(supplied, :count, DEFAULT_COUNT, 1), **shared(supplied) }.freeze
+      end
+
+      def backtest(raw)
+        check_names(raw, BACKTEST)
+        supplied = raw.compact
+        horizon = required(supplied, :horizon)
+        origins = required(supplied, :origins)
+        { horizon: horizon, origins: origins, step: integer(supplied, :step, horizon, 1), **shared(supplied) }.freeze
+      end
+
+      private
+
+      def shared(supplied)
+        {
+          model: model(supplied),
+          levels: levels(supplied),
+          strategy: strategy(supplied),
+          seed: integer(supplied, :seed, DEFAULT_SEED, 0),
+          season_length: season_length(supplied),
+          paths: integer(supplied, :paths, DEFAULT_PATHS, 1),
+          windows: integer(supplied, :windows, DEFAULT_WINDOWS, 2),
+          **SMOOTHING.to_h { |name| [name, smoothing(supplied, name)] }
+        }
+      end
+
+      def required(supplied, name)
+        raise InputError, "#{name} is required" unless supplied.key?(name)
+
+        integer(supplied, name, nil, 1)
+      end
+
+      def check_names(raw, accepted)
+        names = raw.keys
+        index = names.index { |name| !accepted.include?(name) }
+        return unless index
+
+        raise InputError, "unknown option #{Series.describe(names[index])}; accepted options are #{list(accepted)}"
+      end
+
+      def integer(supplied, name, default, minimum)
+        value = supplied.fetch(name, default)
+        return value if Integer === value && value >= minimum
+
+        raise invalid(name, value, INTEGERS_AT_LEAST.fetch(minimum))
+      end
+
+      def model(supplied)
+        model = supplied[:model]
+        return model if [nil, *MODELS.keys].include?(model)
+
+        raise InputError, "model #{Series.describe(model)} is not provided; accepted values are #{list(MODELS.keys)}"
+      end
+
+      def levels(supplied)
+        levels = supplied.fetch(:levels, DEFAULT_LEVELS)
+        unless Array === levels && !levels.empty?
+          raise InputError, "levels must be a non-empty Array of numbers strictly between 0 and 1"
+        end
+
+        index = levels.index { |level| !between_zero_and_one?(level) }
+        raise InputError, "quantile level #{Series.describe(levels[index])} must be strictly between 0 and 1" if index
+
+        distinct = []
+        levels.each { |level| distinct << level unless distinct.include?(level) }
+        distinct.sort.freeze
+      end
+
+      def strategy(supplied)
+        strategy = supplied.fetch(:strategy, :distribution)
+        return strategy if STRATEGIES.include?(strategy)
+
+        raise invalid(:strategy, strategy, STRATEGIES.map(&:inspect).join(" or "))
+      end
+
+      def season_length(supplied)
+        if supplied[:model] == :seasonal_naive
+          season_length = supplied[:season_length]
+          return season_length if Integer === season_length && season_length >= 1
+
+          description = supplied.key?(:season_length) ? Series.describe(season_length) : "none"
+          raise InputError, "SeasonalNaive requires a positive Integer season_length, got #{description}"
+        end
+        integer(supplied, :season_length, nil, 1) if supplied.key?(:season_length)
+      end
+
+      def smoothing(supplied, name)
+        alpha = supplied.fetch(name, 0.1)
+        return alpha if between_zero_and_one?(alpha)
+
+        raise invalid(name, alpha, "a finite real number strictly between 0 and 1")
+      end
+
+      def between_zero_and_one?(number)
+        Numeric === number && number.real? && number.finite? && number > 0 && number < 1
+      end
+
+      def invalid(name, value, accepted)
+        InputError.new("#{name} must be #{accepted}, got #{Series.describe(value)}")
+      end
+
+      def list(names)
+        names.map(&:inspect).join(", ")
+      end
+    end
+  end
+end

data/lib/foresight/result.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Foresight
+  Result = Struct.new(:forecast, :quantiles, :lead_time_quantiles, :model, :demand_class,
+                      :reason, :strategy, :levels, keyword_init: true)
+end

data/lib/foresight/seasonal_naive.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Foresight
+  class SeasonalNaive
+    attr_reader :residuals
+
+    def self.minimum_history(options)
+      options[:season_length]
+    end
+
+    def self.check_history(size, options)
+      required = minimum_history(options)
+      return if size >= required
+
+      raise InputError, "SeasonalNaive requires at least #{required} observations (its season_length), got #{size}"
+    end
+
+    def initialize(values, options)
+      SeasonalNaive.check_history(values.size, options)
+      season_length = options[:season_length]
+      @season = values.last(season_length)
+      @residuals = (season_length...values.size).map { |index| values[index] - values[index - season_length] }
+    end
+
+    def forecast(horizon)
+      Array.new(horizon) { |index| @season[index % @season.size] }
+    end
+
+    def step_factors(horizon)
+      Array.new(horizon) { |index| 1 + index / @season.size }
+    end
+
+    def total_factor(horizon)
+      (1..[@season.size, horizon].min).sum do |period|
+        seasons = (horizon - period) / @season.size + 1
+        seasons * (seasons + 1) * (2 * seasons + 1) / 6
+      end
+    end
+  end
+end

data/lib/foresight/selector.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Foresight
+  module Selector
+    RULE = { smooth: :ses, erratic: :croston_sba, intermittent: :croston_sba, lumpy: :croston_sba }.freeze
+    MINIMUM_HISTORY = 1
+
+    class << self
+      def model_for(classification)
+        RULE.fetch(classification.demand_class)
+      end
+
+      def reason(classification, model)
+        return "#{model} was specified by the caller" if model
+
+        format("auto-selected %s for %s demand (ADI %.2f, CV squared %.2f)", model_for(classification),
+               classification.demand_class, classification.adi.to_r, classification.cv_squared.to_r)
+      end
+    end
+  end
+end