foresight 0.1.0

data/lib/foresight/series.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Foresight
+  class Series
+    LARGEST_VALUE = 10**15
+
+    attr_reader :values, :exact, :keys, :frequency
+
+    class << self
+      def parse(input, keys_required:)
+        case input
+        when Array
+          exact = input.dup
+          check_values(exact, nil)
+          new(exact)
+        when Hash
+          parse_keyed(input, keys_required)
+        else
+          raise InputError,
+                "series must be a Hash with Date or Time keys or an Array of numbers, got #{class_of(input)}"
+        end
+      end
+
+      def describe(supplied)
+        Object === supplied && supplied.respond_to?(:inspect) ? supplied.inspect : "#<#{class_of(supplied)}>"
+      end
+
+      private
+
+      def parse_keyed(input, keys_required)
+        check_keys(input.keys)
+        pairs = input.sort_by { |key, _| key }
+        keys = pairs.map(&:first)
+        exact = pairs.map(&:last)
+        check_values(exact, keys)
+        if keys.size >= 2
+          new(exact, keys, Frequency.detect(keys))
+        elsif keys_required
+          raise InputError, "a keyed series needs at least two keys to determine its frequency, got #{keys.size}"
+        else
+          new(exact, keys)
+        end
+      end
+
+      def check_keys(keys)
+        date_keys = date?(keys.first)
+        index = keys.index { |key| date_keys ? !date?(key) : !time?(key) }
+        return unless index
+
+        raise InputError, "series keys must be all Date values or all Time values, got #{key_text(keys[index])}"
+      end
+
+      def check_values(exact, keys)
+        index = exact.index { |value| !finite_real?(value) }
+        raise InputError, "series value #{observation(exact, keys, index)} is not a finite real number" if index
+
+        index = exact.index(&:negative?)
+        raise InputError, "series value #{observation(exact, keys, index)} is negative" if index
+
+        index = exact.index { |value| value > LARGEST_VALUE }
+        raise InputError, "series value #{observation(exact, keys, index)} is greater than 1e15" if index
+      end
+
+      def observation(exact, keys, index)
+        location = keys ? "key #{key_text(keys[index])}" : "position #{index}"
+        "#{describe(exact[index])} at #{location}"
+      end
+
+      def finite_real?(value)
+        Numeric === value && value.real? && value.finite?
+      end
+
+      def date?(key)
+        Date === key && !(DateTime === key)
+      end
+
+      def time?(key)
+        Time === key || (Object === key && key.is_a?(Time))
+      end
+
+      def key_text(key)
+        date?(key) ? key.to_s : describe(key)
+      end
+
+      def class_of(supplied)
+        Kernel.instance_method(:class).bind_call(supplied)
+      end
+    end
+
+    def initialize(exact, keys = nil, frequency = nil)
+      @exact = exact
+      @values = exact.map(&:to_f)
+      @keys = keys
+      @frequency = frequency
+    end
+
+    def size
+      values.size
+    end
+
+    def label(index)
+      keys ? keys[index] : index
+    end
+
+    def prefix(length)
+      Series.new(exact.first(length))
+    end
+
+    def future_keys(count)
+      (1..count).map { |period| frequency.advance(keys.last, period) }
+    end
+  end
+end

data/lib/foresight/ses.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Foresight
+  class SES
+    attr_reader :alpha, :residuals
+
+    def self.minimum_history(_options)
+      1
+    end
+
+    def initialize(values, _options)
+      @alpha = Smoothing.golden_section(values, 0.01, 0.99)
+      @forecast, fitted = Smoothing.run(values, alpha)
+      @residuals = (1...values.size).map { |index| values[index] - fitted[index] }
+    end
+
+    def forecast(horizon)
+      Array.new(horizon, @forecast)
+    end
+
+    def step_factors(horizon)
+      Array.new(horizon) { |index| 1 + index * alpha * alpha }
+    end
+
+    def total_factor(horizon)
+      (0...horizon).sum { |index| (1 + index * alpha)**2 }
+    end
+  end
+end

data/lib/foresight/simulator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Foresight
+  class Simulator
+    def initialize(probability:, sizes:, horizon:, paths:, seed:)
+      @probability = probability
+      @sizes = sizes
+      @horizon = horizon
+      @paths = paths
+      @seed = seed
+    end
+
+    def totals
+      return Array.new(@paths, 0.0) if @sizes.empty?
+
+      rng = Random.new(@seed)
+      Array.new(@paths) do
+        total = 0.0
+        @horizon.times { total += @sizes[rng.rand(@sizes.size)] if rng.rand < @probability }
+        total
+      end
+    end
+  end
+end

data/lib/foresight/smoothing.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Foresight
+  # Follows ses_sse, ses_forecast and golden_section_ses in statsforecast src/ses.cpp, operation by operation
+  module Smoothing
+    class << self
+      def sse(values, alpha)
+        return 0.0 if values.size < 2
+
+        complement = 1.0 - alpha
+        forecast = values[0]
+        sum = 0.0
+        (1...values.size).each do |index|
+          forecast = alpha * values[index - 1] + complement * forecast
+          error = values[index] - forecast
+          sum += error * error
+        end
+        sum
+      end
+
+      def run(values, alpha)
+        return [values[0], []] if values.size == 1
+
+        complement = 1.0 - alpha
+        level = values[0]
+        fitted = []
+        (1...values.size).each do |index|
+          level = alpha * values[index - 1] + complement * level
+          fitted[index] = level
+        end
+        [alpha * values.last + complement * level, fitted]
+      end
+
+      def golden_section(values, lower, upper)
+        golden_ratio = (Math.sqrt(5.0) + 1.0) / 2.0
+        left = upper - (upper - lower) / golden_ratio
+        right = lower + (upper - lower) / golden_ratio
+        left_sum = sse(values, left)
+        right_sum = sse(values, right)
+        while (upper - lower).abs >= 1e-12
+          if left_sum < right_sum
+            upper, right, right_sum = right, left, left_sum
+            left = upper - (upper - lower) / golden_ratio
+            left_sum = sse(values, left)
+          elsif right_sum < left_sum
+            lower, left, left_sum = left, right, right_sum
+            right = lower + (upper - lower) / golden_ratio
+            right_sum = sse(values, right)
+          else
+            break
+          end
+        end
+        (upper + lower) / 2.0
+      end
+    end
+  end
+end

data/lib/foresight/tsb.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Foresight
+  class TSB
+    attr_reader :probability, :sizes
+
+    def self.minimum_history(_options)
+      1
+    end
+
+    def initialize(values, options)
+      @forecast = 0.0
+      @probability = 0.0
+      sizes = values.reject(&:zero?)
+      @sizes = sizes.sort
+      return if sizes.empty?
+
+      occurrences = values.map { |value| value.zero? ? 0.0 : 1.0 }
+      occurrence = Smoothing.run(occurrences, options[:alpha_p].to_f).first
+      size = Smoothing.run(sizes, options[:alpha_d].to_f).first
+      @forecast = occurrence * size
+      @probability = occurrence.clamp(0.0, 1.0)
+    end
+
+    def forecast(horizon)
+      Array.new(horizon, @forecast)
+    end
+  end
+end

data/lib/foresight/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Foresight
+  VERSION = "0.1.0"
+end

data/lib/foresight.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "foresight/version"
+require_relative "foresight/input_error"
+require_relative "foresight/frequency"
+require_relative "foresight/series"
+require_relative "foresight/options"
+require_relative "foresight/classifier"
+require_relative "foresight/selector"
+require_relative "foresight/normal"
+require_relative "foresight/empirical_quantile"
+require_relative "foresight/smoothing"
+require_relative "foresight/naive"
+require_relative "foresight/seasonal_naive"
+require_relative "foresight/ses"
+require_relative "foresight/croston_classic"
+require_relative "foresight/croston_sba"
+require_relative "foresight/tsb"
+require_relative "foresight/gaussian_strategy"
+require_relative "foresight/compound_strategy"
+require_relative "foresight/simulator"
+require_relative "foresight/conformal_strategy"
+require_relative "foresight/forecaster"
+require_relative "foresight/result"
+require_relative "foresight/metrics"
+require_relative "foresight/backtester"
+require_relative "foresight/evaluation_report"
+
+module Foresight
+  DEFAULT_COUNT   = 10
+  DEFAULT_LEVELS  = [0.5, 0.8, 0.9, 0.95].freeze
+  DEFAULT_SEED    = 0
+  DEFAULT_PATHS   = 10_000
+  DEFAULT_WINDOWS = 2
+  MODELS = { naive: Naive, seasonal_naive: SeasonalNaive, ses: SES,
+             croston_classic: CrostonClassic, croston_sba: CrostonSBA, tsb: TSB }.freeze
+
+  def self.forecast(series, **options)
+    forecaster = Forecaster.new(Options.forecast(options))
+    forecaster.call(Series.parse(series, keys_required: true))
+  end
+
+  def self.classify(series)
+    Classifier.call(Series.parse(series, keys_required: false).exact)
+  end
+
+  def self.backtest(series, **options)
+    Backtester.new(**options).run(series)
+  end
+
+  def self.evaluate(collection, **options)
+    Backtester.new(**options).evaluate(collection)
+  end
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: foresight
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ojus Chugh
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/foresight.rb
+- lib/foresight/backtester.rb
+- lib/foresight/classifier.rb
+- lib/foresight/compound_strategy.rb
+- lib/foresight/conformal_strategy.rb
+- lib/foresight/croston_classic.rb
+- lib/foresight/croston_sba.rb
+- lib/foresight/empirical_quantile.rb
+- lib/foresight/evaluation_report.rb
+- lib/foresight/forecaster.rb
+- lib/foresight/frequency.rb
+- lib/foresight/gaussian_strategy.rb
+- lib/foresight/input_error.rb
+- lib/foresight/metrics.rb
+- lib/foresight/naive.rb
+- lib/foresight/normal.rb
+- lib/foresight/options.rb
+- lib/foresight/result.rb
+- lib/foresight/seasonal_naive.rb
+- lib/foresight/selector.rb
+- lib/foresight/series.rb
+- lib/foresight/ses.rb
+- lib/foresight/simulator.rb
+- lib/foresight/smoothing.rb
+- lib/foresight/tsb.rb
+- lib/foresight/version.rb
+homepage: https://github.com/ojuschugh1/foresight
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/ojuschugh1/foresight
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Probabilistic demand forecasting for smooth and intermittent series
+test_files: []