quantitative 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9fa0c537499409fa9faa3fbca76beca44d37205c04c8de1c01b3e681985c2dc
-  data.tar.gz: 3916820207b47d2d19b79332e41329c35080ce1456c4a2ed751863ea220b5289
+  metadata.gz: 72d65b65fdcbb81650fcce3233f3fbde9c99c4b9b9ace1ce3bbc3b8e565152f9
+  data.tar.gz: f687ab3c32e88ffc579a9f92ff428846f91e60ff166d3b4379963deb15a88425
 SHA512:
-  metadata.gz: e3bead0b7fc23208c62dd18bb8f701b684db20780ae793fab973ab07cea0740897026a66755a07b9857228e815bfc3679801171f2b5875f510a7c98781fd30cb
-  data.tar.gz: 8b07dbcbe1a86c507a31df950aef293ae018913964848a9298310fe71a7929924a5a7ced417cf5ef86e9282feb58bc9d16531bf6b77e0fa23cea28de7a761740
+  metadata.gz: 594d57a819ce8d561c064f685353d27ef4dfd1cb2e76e5cf07758bcedb1c501d2bc06859aff89cf6f4bc744e327ede1290e31b4d4ffb1daed99d614735eb0a76
+  data.tar.gz: 5fbfb29d1501a3562788abf83ef4fcb78bcb17fcfc030e7543b42f3c29c2a7a5c3c8fba187494d4655691e117e383af59bca428764f49fd7e41fcef911ef6d40

data/.rubocop.yml

@@ -3,6 +3,8 @@ inherit_gem:
 
 AllCops:
   TargetRubyVersion: 3.0
+  Exclude:
+    - 'spec/performance/*.rb'
 
 Style/AccessorGrouping:
   Enabled: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    quantitative (0.1.5)
+    quantitative (0.1.6)
       oj (~> 3.10)
 
 GEM

data/lib/quant/attributes.rb

@@ -1,10 +1,60 @@
 # frozen_string_literal: true
 
 module Quant
+  # {Quant::Attributes} is similar to an +attr_accessor+ definition.  It provides a simple DSL
+  # for defining attributes or properies on an {Quant::Indicators::IndicatorPoint} class.
+  #
+  # {Quant::Attributes} tracks all defined attributes from child to parent classes,
+  # allowing child classes to inherit their parent's attributes as well as redefine them.
+  #
+  # The exception on redefining is that a serialized key cannot be redefined.  Experience
+  # has proven that this leads to serialization surprises where what was written to a specific
+  # key is not what was expected!
+  #
+  # NOTE: The above design constraint could be improved with a force or overwrite option.
+  #
+  # If :default is an immediate value (Integer, Float, Boolean, etc.), it will be used as the
+  # initial value for the attribute.  If :default is a Symbol, it will send a message on
+  # current instance of the class get the default value.
+  #
+  # @example
+  #   class FooPoint < IndicatorPoint
+  #     # will not serialize to a key
+  #     attribute :bar
+  #     # serializes to "bzz" key
+  #     attribute :baz, key: "bzz"
+  #     # calls the random method on the instance for the default value
+  #     attribute :foobar, default: :random
+  #     # delegated to the tick's high_price method
+  #     attribute :high, default: :high_price
+  #     # calls the lambda bound to instance for default
+  #     attribute :low, default: -> { high_price - 5 }
+  #
+  #     def random
+  #       rand(100)
+  #     end
+  #   end
+  #
+  #   class BarPoint < FooPoint
+  #     attribute :bar, key: "brr"                 # redefines and sets the key for bar
+  #     attribute :qux, key: "qxx", default: 5.0   # serializes to "qxx" and defaults to 5.0
+  #   end
+  #
+  #   FooPoint.attributes
+  #   # => { bar: { key: nil, default: nil },
+  #          baz: { key: "bzz", default: nil } }
+  #
+  #   BarPoint.attributes
+  #   # => { bar: { key: "brr", default: nil },
+  #   #      baz: { key: "bzz", default: nil },
+  #   #      qux: { key: "qxx", default: nil } }
+  #
+  #   BarPoint.new.bar # => nil
+  #   BarPoint.new.qux # => 5.0
+  #   BarPoint.new.bar = 2.0 => 2.0
   module Attributes
-    # Tracks all defined attributes, allowing child classes to inherit their parent's attributes.
-    # The registry key is the class registering an attrbritute and is itself a hash of the attribute name
-    # and the attribute's key and default value.
+    # The +registry+ key is the class registering an attrbritute and is itself
+    # a hash of the attribute name and the attribute's key and default value.
     # Internal use only.
     #
     # @example
@@ -47,9 +97,18 @@ module Quant
     end
 
     module InstanceMethods
-      def initialize(...)
-        initialize_attributes
-        super(...)
+      # Makes some assumptions about the class's initialization having a +tick+ keyword argument.
+      #
+      # The challenge here is that we prepend this module to the class, and we are
+      # initializing attributes before the owning class gets the opportunity to initialize
+      # variables that we wanted to depend on with being able to define a default
+      # value that could set default values from a +tick+ method.
+      #
+      # Ok for now.  May need to be more flexible in the future.  Alternative strategy could be
+      # to lazy eval the default value the first time it is accessed.
+      def initialize(*args, **kwargs)
+        initialize_attributes(tick: kwargs[:tick])
+        super(*args, **kwargs)
       end
 
       # Iterates over all defined attributes in a child => parent hierarchy,
@@ -65,17 +124,42 @@ module Quant
         end
       end
 
+      # The default value can be one of the following:
+      # - A symbol that is a method on the instance responds to
+      # - A symbol that is a method that the instance's tick responds to
+      # - A Proc that is bound to the instance
+      # - An immediate value (Integer, Float, Boolean, etc.)
+      def default_value_for(entry, new_tick)
+        # let's not assume tick is always available/implemented
+        # can get from instance or from initializer passed here as `new_tick`
+        current_tick = new_tick
+        current_tick ||= tick if respond_to?(:tick)
+
+        if entry[:default].is_a?(Symbol) && respond_to?(entry[:default])
+          send(entry[:default])
+
+        elsif entry[:default].is_a?(Symbol) && current_tick&.respond_to?(entry[:default])
+          current_tick.send(entry[:default])
+
+        elsif entry[:default].is_a?(Proc)
+          instance_exec(&entry[:default])
+
+        else
+          entry[:default]
+        end
+      end
+
       # Initializes the defined attributes with default values and
       # defines accessor methods for each attribute.
       # If a child class redefines a parent's attribute, the child's
       # definition will be used.
-      def initialize_attributes
+      def initialize_attributes(tick:)
         each_attribute do |name, entry|
           # use the child's definition, skipping the parent's
           next if respond_to?(name)
 
           ivar_name = "@#{name}"
-          instance_variable_set(ivar_name, entry[:default])
+          instance_variable_set(ivar_name, default_value_for(entry, tick))
           define_singleton_method(name) { instance_variable_get(ivar_name) }
           define_singleton_method("#{name}=") { |value| instance_variable_set(ivar_name, value) }
         end

data/lib/quant/indicators/indicator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Quant
   class Indicators
     class Indicator
@@ -27,6 +29,10 @@ module Quant
         @points.keys
       end
 
+      def [](index)
+        values[index]
+      end
+
       def values
         @points.values
       end
@@ -59,7 +65,7 @@ module Quant
       end
 
       def inspect
-        "#<#{self.class.name} symbol=#{series.symbol} source=#{source} #{points.size} ticks>"
+        "#<#{self.class.name} symbol=#{series.symbol} source=#{source} #{ticks.size} ticks>"
       end
 
       def compute
@@ -168,4 +174,4 @@ module Quant
       # end
     end
   end
-end
+end

data/lib/quant/indicators/indicator_point.rb

@@ -5,7 +5,7 @@ module Quant
     class IndicatorPoint
       include Quant::Attributes
 
-      attribute :tick
+      attr_reader :tick
       attribute :source, key: "src"
       attribute :input, key: "in"
 

data/lib/quant/indicators/ma.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Quant
   class Indicators
     class MaPoint < IndicatorPoint

data/lib/quant/indicators/ping.rb

@@ -1,5 +1,11 @@
+# frozen_string_literal: true
+
 module Quant
   class Indicators
+    # A simple point used primarily to test the indicator system in unit tests.
+    # It has a simple computation that just sets the pong value to the input value
+    # and increments the compute_count by 1 each time compute is called.
+    # Sometimes you just gotta play ping pong to win.
     class PingPoint < IndicatorPoint
       attribute :pong
       attribute :compute_count, default: 0

data/lib/quant/indicators_proxy.rb

@@ -1,6 +1,17 @@
 # frozen_string_literal: true
 
 module Quant
+  # The {Quant::IndicatorsProxy} class is responsible for lazily loading indicators
+  # so that not all indicators are always engaged and computing their values.
+  # If the indicator is never accessed, it's never computed, saving valuable
+  # processing CPU cycles.
+  #
+  # Indicators are generally built around the concept of a source input value and
+  # that source is designated by the source parameter when instantiating the
+  # {Quant::IndicatorsProxy} class.
+  #
+  # By design, the {Quant::Indicator} class holds the {Quant::Ticks::Tick} instance
+  # alongside the indicator's computed values for that tick.
   class IndicatorsProxy
     attr_reader :series, :source, :indicators
 
@@ -10,14 +21,41 @@ module Quant
       @indicators = {}
     end
 
+    # Instantiates the indicator class and stores it in the indicators hash.  Once
+    # prepared, the indicator becomes active and all ticks pushed into the series
+    # are sent to the indicator for processing.
     def indicator(indicator_class)
       indicators[indicator_class] ||= indicator_class.new(series: series, source: source)
     end
 
+    # Adds the tick to all active indicators, triggering them to compute
+    # new values against the latest tick.
+    #
+    # NOTE:  Dominant cycle indicators must be computed first as many
+    # indicators are adaptive and require the dominant cycle period.
+    # The IndicatorsProxy class is not responsible for enforcing
+    # this order of events.
     def <<(tick)
       indicators.each_value { |indicator| indicator << tick }
     end
 
+    # Attaches a given Indicator class and defines the method for
+    # accessing it using the given name.  Indicators take care of
+    # computing their values when first attached to a populated
+    # series.
+    #
+    # The indicators shipped with the library are all wired into the framework, thus
+    # this method should be used for custom indicators not shipped with the library.
+    #
+    # @param name [Symbol] The name of the method to define for accessing the indicator.
+    # @param indicator_class [Class] The class of the indicator to attach.
+    # @example
+    #   series.indicators.oc2.attach(name: :foo, indicator_class: Indicators::Foo)
+    def attach(name:, indicator_class:)
+      define_singleton_method(name) { indicator(indicator_class) }
+    end
+
     def ma; indicator(Indicators::Ma) end
+    def ping; indicator(Indicators::Ping) end
   end
 end

data/lib/quant/mixins/moving_averages.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Quant
+  module Mixins
+    module MovingAverages
+      using Quant
+
+      # Computes the Weighted Moving Average (WMA) of the series, using the four most recent data points.
+      #
+      # @param source [Symbol] the source of the data points to be used in the calculation.
+      # @return [Float] the weighted average of the series.
+      # @raise [ArgumentError] if the source is not a Symbol.
+      # @example
+      #   p0.wma = weighted_average(:close_price)
+      def weighted_moving_average(source)
+        raise ArgumentError, "source must be a Symbol" unless source.is_a?(Symbol)
+
+        [4.0 * p0.send(source),
+         3.0 * p1.send(source),
+         2.0 * p2.send(source),
+               p3.send(source)].sum / 10.0
+      end
+      alias wma weighted_moving_average
+
+      # Computes the Weighted Moving Average (WMA) of the series, using the seven most recent data points.
+      #
+      # @param source [Symbol] the source of the data points to be used in the calculation.
+      # @return [Float] the weighted average of the series.
+      # @raise [ArgumentError] if the source is not a Symbol.
+      # @example
+      #   p0.wma = weighted_average(:close_price)
+      def extended_weighted_moving_average(source)
+        raise ArgumentError, "source must be a Symbol" unless source.is_a?(Symbol)
+
+        [7.0 * p0.send(source),
+         6.0 * p1.send(source),
+         5.0 * p2.send(source),
+         4.0 * p3.send(source),
+         3.0 * p(4).send(source),
+         2.0 * p(5).send(source),
+               p(6).send(source)].sum / 28.0
+      end
+      alias ewma extended_weighted_moving_average
+
+      # Computes the Simple Moving Average (SMA) of the given period.
+      #
+      # @param source [Symbol] the source of the data points to be used in the calculation.
+      # @param period [Integer] the number of elements to compute the SMA over.
+      # @return [Float] the simple moving average of the period.
+      def simple_moving_average(source, period:)
+        raise ArgumentError, "source must be a Symbol" unless source.is_a?(Symbol)
+
+        values.last(period).map { |value| value.send(source) }.mean
+      end
+      alias sma simple_moving_average
+
+      # Computes the Exponential Moving Average (EMA) of the given period.
+      #
+      # The EMA computation is optimized to compute using just the last two
+      # indicator data points and is expected to be called in each indicator's
+      # `#compute` method for each iteration on the series.
+      #
+      # @param source [Symbol] the source of the data points to be used in the calculation.
+      # @param previous [Symbol] the previous EMA value.
+      # @param period [Integer] the number of elements to compute the EMA over.
+      # @return [Float] the exponential moving average of the period.
+      # @raise [ArgumentError] if the source is not a Symbol.
+      # @example
+      #   def compute
+      #     p0.ema = exponential_moving_average(:close_price, period: 3)
+      #   end
+      #
+      #   def compute
+      #     p0.ema = exponential_moving_average(:close_price, previous: :ema, period: 3)
+      #   end
+      def exponential_moving_average(source, previous: :ema, period:)
+        raise ArgumentError, "source must be a Symbol" unless source.is_a?(Symbol)
+        raise ArgumentError, "previous must be a Symbol" unless previous.is_a?(Symbol)
+
+        alpha = 2.0 / (period + 1)
+        p0.send(source) * alpha + p1.send(previous) * (1.0 - alpha)
+      end
+      alias ema exponential_moving_average
+    end
+  end
+end

data/lib/quant/mixins/super_smoother.rb

@@ -66,9 +66,8 @@ module Quant
         p3 = points[-4] || p2
 
         v0 = source.is_a?(Symbol) ? p0.send(source) : source
-        return v0 if [p0 == p3]
+        return v0 if p0 == p3
 
-        debugger if points.size > 4
         a1 = Math.exp(-Math::PI / ssperiod)
         b1 = 2 * a1 * Math.cos(Math::PI * Math.sqrt(3) / ssperiod)
         c1 = a1**2

data/lib/quant/refinements/array.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Quant
   module Refinements
     # Refinements for the standard Ruby {Quant::Array} class.
@@ -32,7 +34,6 @@ module Quant
     #   The refined behavior generally only exists within the library's scope, but if you call `using Quant` in your
     #   own code, you may encounter the changed behavior unexpectedly.
     module Array
-
       # Overrides the standard +<<+ method to track the +maximum+ and +minimum+ values
       # while also respecting the +max_size+ setting.
       def <<(value)
@@ -109,7 +110,7 @@ module Quant
         subset = last(n)
         return 0.0 if subset.empty?
 
-        sum = subset.sum / subset.size.to_f
+        subset.sum / subset.size.to_f
       end
 
       # Computes the Exponential Moving Average (EMA) of the array.  When +n+ is specified,
@@ -175,7 +176,7 @@ module Quant
       # @param n [Integer] the number of elements to compute the Standard Deviation over.
       # @return [Float]
       def stddev(reference_value, n: size)
-        variance(reference_value, n: n) ** 0.5
+        variance(reference_value, n: n)**0.5
       end
 
       def variance(reference_value, n: size)

data/lib/quant/settings.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Quant
   module Settings
     MAX_PERIOD = 48

data/lib/quant/ticks/ohlc.rb

@@ -89,7 +89,7 @@ module Quant
       # This method is useful for comparing the volatility of different assets.
       # @return [Float]
       def daily_price_change_ratio
-        @price_change ||= ((open_price - close_price) / oc2).abs
+        @daily_price_change_ratio ||= ((open_price - close_price) / oc2).abs
       end
 
       # Set the #green? property to true when the close_price is greater than or equal to the open_price.

data/lib/quant/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Quant
-  VERSION = "0.1.5"
+  VERSION = "0.1.6"
 end

data/lib/quantitative.rb

@@ -14,4 +14,4 @@ Dir.glob(File.join(quant_folder, "*.rb")).each { |fn| require fn }
 # require sub-folders and their sub-folders
 %w(refinements mixins settings ticks indicators).each do |sub_folder|
   Dir.glob(File.join(quant_folder, sub_folder, "**/*.rb")).each { |fn| require fn }
-end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: quantitative
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Michael Lang
@@ -62,10 +62,10 @@ files:
 - lib/quant/mixins/fisher_transform.rb
 - lib/quant/mixins/high_pass_filter.rb
 - lib/quant/mixins/hilbert_transform.rb
+- lib/quant/mixins/moving_averages.rb
 - lib/quant/mixins/stochastic.rb
 - lib/quant/mixins/super_smoother.rb
 - lib/quant/mixins/trig.rb
-- lib/quant/mixins/weighted_average.rb
 - lib/quant/refinements/array.rb
 - lib/quant/series.rb
 - lib/quant/settings.rb

data/lib/quant/mixins/weighted_average.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-module Quant
-  module Mixins
-    module WeightedAverage
-      def weighted_average(source)
-        value = source.is_a?(Symbol) ? p0.send(source) : source
-        [4.0 * value,
-         3.0 * p1.send(source),
-         2.0 * p2.send(source),
-         p3.send(source),].sum / 10.0
-      end
-
-      def extended_weighted_average(source)
-        value = source.is_a?(Symbol) ? p0.send(source) : source
-        [7.0 * value,
-         6.0 * p1.send(source),
-         5.0 * p2.send(source),
-         4.0 * p3.send(source),
-         3.0 * prev(4).send(source),
-         2.0 * prev(5).send(source),
-         prev(6).send(source),].sum / 28.0
-      end
-    end
-  end
-end