quantitative 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 266a7aa51d29b809224fa76091d26c52d58f6e42959aeeb4ca5ffb6376828773
-  data.tar.gz: 5b3ac92706338a77a098e5dee72f3ecf57f2c4032f946533225e6061d07082d5
+  metadata.gz: 72d65b65fdcbb81650fcce3233f3fbde9c99c4b9b9ace1ce3bbc3b8e565152f9
+  data.tar.gz: f687ab3c32e88ffc579a9f92ff428846f91e60ff166d3b4379963deb15a88425
 SHA512:
-  metadata.gz: 624d6945e690d51b5afef5ebc7939eb3f444fd7d4d79a31e73df5a42e0f6c351f8d4ac451a455a657c96a07448a0c724ba1481156d2e859ca720c8994328547a
-  data.tar.gz: 51b9fd16424fe1fd1b48c72f350c89cfb9e26e0a082eb750ae864c436b51eeab2142c64744deee93b91aaafe119354f19a4159ecda84b066d75f1d242945a9a2
+  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.4)
+    quantitative (0.1.6)
       oj (~> 3.10)
 
 GEM

data/lib/quant/asset.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "asset_class"
+
+module Quant
+  # A {Quant::Asset} is a representation of a financial instrument such as a stock, option, future, or currency.
+  # It is used to represent the instrument that is being traded, analyzed, or managed.
+  #
+  # Not all data sources have a rich set of attributes for their assets or securities.  The {Quant::Asset} is designed
+  # to be flexible and to support a wide variety of data sources and use-cases.  The most common use-cases are supported
+  # while allowing for additional attributes to be added via the +meta+ attribute, which is tyipically just a Hash,
+  # but can be any object that can hold useful information about the asset such as currency formatting, precision, etc.
+  # @example
+  #   asset = Quant::Asset.new(symbol: "AAPL", name: "Apple Inc.", asset_class: :stock, exchange: "NASDAQ")
+  #   asset.symbol # => "AAPL"
+  #   asset.name # => "Apple Inc."
+  #   asset.stock? # => true
+  #   asset.option? # => false
+  #   asset.future? # => false
+  #   asset.currency? # => false
+  #   asset.exchange # => "NASDAQ"
+  #
+  #   # Can serialize two ways:
+  #   asset.to_h # => { "s" => "AAPL" }
+  #   asset.to_h(full: true) # => { "s" => "AAPL", "n" => "Apple Inc.", "sc" => "stock", "x" => "NASDAQ" }
+  class Asset
+    attr_reader :symbol, :name, :asset_class, :id, :exchange, :source, :meta, :created_at, :updated_at
+
+    def initialize(
+      symbol:,
+      name: nil,
+      id: nil,
+      active: true,
+      tradeable: true,
+      exchange: nil,
+      source: nil,
+      asset_class: nil,
+      created_at: Quant.current_time,
+      updated_at: Quant.current_time,
+      meta: {}
+    )
+      raise ArgumentError, "symbol is required" unless symbol
+
+      @symbol = symbol.to_s.upcase
+      @name = name
+      @id = id
+      @tradeable = tradeable
+      @active = active
+      @exchange = exchange
+      @source = source
+      @asset_class = AssetClass.new(asset_class)
+      @created_at = created_at
+      @updated_at = updated_at
+      @meta = meta
+    end
+
+    def active?
+      !!@active
+    end
+
+    def tradeable?
+      !!@tradeable
+    end
+
+    AssetClass::CLASSES.each do |class_name|
+      define_method("#{class_name}?") do
+        asset_class == class_name
+      end
+    end
+
+    def to_h(full: false)
+      return { "s" => symbol } unless full
+
+      { "s" => symbol,
+        "n" => name,
+        "id" => id,
+        "t" => tradeable?,
+        "a" => active?,
+        "x" => exchange,
+        "sc" => asset_class.to_s,
+        "src" => source.to_s }
+    end
+
+    def to_json(*args, full: false)
+      Oj.dump(to_h(full: full), *args)
+    end
+  end
+end

data/lib/quant/{security_class.rb → asset_class.rb}

@@ -24,7 +24,7 @@ module Quant
   # real estate. Investors can buy shares in a REIT, which provides them with a share of the
   # income produced by the real estate.
 
-  # Cryptocurrencies: Digital or virtual currencies that use cryptography for security and operate on
+  # Cryptocurrencies: Digital or virtual currencies that use cryptography for asset and operate on
   # decentralized networks, typically based on blockchain technology. Examples include Bitcoin, Ethereum, and Ripple.
 
   # Preferred Stock: A type of stock that has priority over common stock in terms of dividend
@@ -40,7 +40,7 @@ module Quant
 
   # Foreign Exchange (Forex): The market where currencies are traded. Investors can buy and sell currencies to
   # profit from changes in exchange rates.
-  class SecurityClass
+  class AssetClass
     CLASSES = %i(
       bond
       commodity
@@ -57,31 +57,31 @@ module Quant
       treasury_note
     ).freeze
 
-    attr_reader :security_class
+    attr_reader :asset_class
 
     def initialize(name)
-      return if @security_class = from_standard(name)
+      return if @asset_class = from_standard(name)
 
-      @security_class = from_alternate(name.to_s.downcase.to_sym) unless name.nil?
-      raise_unknown_security_class_error(name) unless security_class
+      @asset_class = from_alternate(name.to_s.downcase.to_sym) unless name.nil?
+      raise_unknown_asset_class_error(name) unless asset_class
     end
 
     CLASSES.each do |class_name|
       define_method("#{class_name}?") do
-        security_class == class_name
+        asset_class == class_name
       end
     end
 
-    def raise_unknown_security_class_error(name)
-      raise SecurityClassError, "Unknown security class: #{name.inspect}"
+    def raise_unknown_asset_class_error(name)
+      raise Errors::AssetClassError, "Unknown asset class: #{name.inspect}"
     end
 
     def to_s
-      security_class.to_s
+      asset_class.to_s
     end
 
     def to_h
-      { "sc" => security_class }
+      { "sc" => asset_class }
     end
 
     def to_json(*args)
@@ -90,9 +90,9 @@ module Quant
 
     def ==(other)
       case other
-      when String then from_alternate(other.to_sym) == security_class
-      when Symbol then from_alternate(other) == security_class
-      when SecurityClass then other.security_class == security_class
+      when String then from_alternate(other.to_sym) == asset_class
+      when Symbol then from_alternate(other) == asset_class
+      when AssetClass then other.asset_class == asset_class
       else
         false
       end

data/lib/quant/attributes.rb

@@ -0,0 +1,218 @@
+# 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
+    # 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
+    #   { Quant::Indicators::IndicatorPoint => {
+    #       tick: { key: nil, default: nil },
+    #       source: { key: "src", default: nil },
+    #       input: { key: "in", default: nil }
+    #     },
+    #     Quant::Indicators::PingPoint => {
+    #       pong: { key: nil, default: nil },
+    #       compute_count: { key: nil, default: 0 }
+    #     }
+    #   }
+    # @return [Hash] The registry of all defined attributes.
+    def self.registry
+      @registry ||= {}
+    end
+
+    # Removes the given class from the registry. Useful for testing.
+    def self.deregister(klass)
+      registry.delete(klass)
+    end
+
+    # Registers an attribute for a class in the registry.
+    # Internal use only.
+    #
+    # @param klass [Class] The class registering the attribute
+    # @param name [Symbol] The name of the attribute
+    # @param key [String] The key to use when serializing the attribute
+    # @param default [Object] The default value for the attribute
+    def self.register(klass, name, key, default)
+      # Disallow redefining or replacing a key as it is easy to miss the overwrite
+      # and leads to serialization surprises.
+      if key && registry.values.flat_map(&:values).map{ |entry| entry[:key] }.include?(key)
+        raise Errors::DuplicateAttributesKeyError, "Attribute Key #{key} already defined!"
+      end
+
+      registry[klass] ||= {}
+      registry[klass][name] = { key: key, default: default }
+    end
+
+    module InstanceMethods
+      # 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,
+      # and yields the name and entry for each.
+      def each_attribute(&block)
+        klass = self.class
+        loop do
+          attributes = Attributes.registry[klass]
+          break if attributes.nil?
+
+          attributes.each{ |name, entry| block.call(name, entry) }
+          klass = klass.superclass
+        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(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, 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
+      end
+
+      # Serializes keys that have been defined as serializeable attributes
+      # Key values that are nil are removed from the hash
+      # @return [Hash] The serialized attributes as a Ruby Hash.
+      def to_h
+        {}.tap do |key_values|
+          each_attribute do |name, entry|
+            next unless entry[:key]
+
+            ivar_name = "@#{name}"
+            value = instance_variable_get(ivar_name)
+
+            key_values[entry[:key]] = value if value
+          end
+        end
+      end
+
+      # Serializes keys that have been defined as serializeable attributes
+      # Key values that are nil are removed from the hash
+      # @return [String] The serialized attributes as a JSON string.
+      def to_json(*args)
+        Oj.dump(to_h, *args)
+      end
+    end
+
+    module ClassMethods
+      # Define an +attribute+ for the class that can optionally be serialized.
+      # Works much like an attr_accessor does, but also manages serialization for
+      # #to_h and #to_json methods.
+      #
+      # An +attribute+ will result in a same-named instance on the class when
+      # it is instantiated and it will set a default value if one is provided.
+      #
+      # @param name [Symbol] The name of the attribute and it's accessor methods
+      # @param key [String] The key to use when serializing the attribute
+      # @param default [Object] The default value for the attribute
+      #
+      # @examples
+      #   attribute :tick                 # will not serialize to a key
+      #   attribute :source, key: "src"   # serializes to "src" key
+      #   attribute :input, key: "in"     # serializes to "in" key
+      def attribute(name, key: nil, default: nil)
+        Attributes.register(self, name, key, default)
+      end
+    end
+
+    def self.included(base) # :nodoc:
+      base.extend(ClassMethods)
+      base.prepend(InstanceMethods)
+    end
+  end
+end

data/lib/quant/errors.rb

@@ -1,9 +1,34 @@
 # frozen_string_literal: true
 
 module Quant
-  class Error < StandardError; end
-  class InvalidInterval < Error; end
-  class InvalidResolution < Error; end
-  class ArrayMaxSizeError < Error; end
-  class SecurityClassError < Error; end
+  module Errors
+    # {Error} is the base class for all errors in the Quant gem.
+    # It is a subclass of the Ruby {StandardError}.
+    class Error < StandardError; end
+
+    # {InvalidInterval} is raised when attempting to instantiate an
+    # {Quant::Interval} with an invalid value.
+    class InvalidInterval < Error; end
+
+    # {InvalidResolution} is raised when attempting to instantiate
+    # an {Quant::Resolution} with a resolution value that has not been defined.
+    class InvalidResolution < Error; end
+
+    # {ArrayMaxSizeError} is raised when attempting to set the +max_size+ on
+    # the refined {Array} class to an invalid value or when attempting to
+    # redefine the +max_size+ on the refined {Array} class.
+    class ArrayMaxSizeError < Error; end
+
+    # {AssetClassError} is raised when attempting to instantiate a
+    # {Quant::Asset} with an attribute that is not a valid {Quant::Asset} attribute.
+    class AssetClassError < Error; end
+
+    # {DuplicateAttributesKeyError} is raised when attempting to define an
+    # attribute with a key that has already been defined.
+    class DuplicateAttributesKeyError < Error; end
+
+    # {DuplicateAttributesNameError} is raised when attempting to define an
+    # attribute with a name that has already been defined.
+    class DuplicateAttributesNameError < Error; end
+  end
 end

data/lib/quant/indicators/indicator.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module Quant
   class Indicators
     class Indicator
-      # include Enumerable
+      include Enumerable
 
       # # include Mixins::TrendMethods
       # include Mixins::Trig
@@ -14,57 +16,107 @@ module Quant
       # include Mixins::Direction
       # include Mixins::Filters
 
-      # def inspect
-      #   "#<#{self.class.name} #{symbol} #{interval} #{points.size} points>"
-      # end
+      attr_reader :source, :series
 
-      # def compute
-      #   raise NotImplementedError
-      # end
+      def initialize(series:, source:)
+        @series = series
+        @source = source
+        @points = {}
+        series.each { |tick| self << tick }
+      end
 
-      # def [](index)
-      #   points[index]
-      # end
+      def ticks
+        @points.keys
+      end
 
-      # def after_append
-      #   # NoOp
-      # end
+      def [](index)
+        values[index]
+      end
 
-      # def points_class
-      #   "Quant::Indicators::#{indicator_name}Point".constantize
-      # end
+      def values
+        @points.values
+      end
 
-      # def indicator_name
-      #   self.class.name.demodulize
-      # end
+      def size
+        @points.size
+      end
 
-      # def warmed_up?
-      #   true
-      # end
+      attr_reader :p0, :p1, :p2, :p3
+      attr_reader :t0, :t1, :t2, :t3
 
-      # def initial_max_size
-      #   value = [series.size, series.max_size].max
-      #   value.zero? ? settings.initial_max_size : value
-      # end
+      def <<(tick)
+        @t0 = tick
+        @p0 = points_class.new(tick: tick, source: source)
+        @points[tick] = @p0
 
-      attr_reader :series #, :settings, :max_size, :points, :dc_period
-      # delegate :p0, :p1, :p2, :p3, :prev, :iteration, to: :points
-      # delegate :each, :size, :[], :last, :first, to: :points
-      # delegate :oc2, :high_price, :low_price, :open_price, :close_price, :volume, to: :p0
+        @p1 = values[-2] || @p0
+        @p2 = values[-3] || @p1
+        @p3 = values[-4] || @p2
 
-      def initialize(series:) # settings: Settings::Indicators.defaults, cloning: false)
-        @series = series
-        # @settings = settings
-        # @max_size = initial_max_size
-        # @points = Points.new(indicator: self)
-        # return if cloning
-
-        # after_initialization
-        # parent_series.each { |ohlc| append ohlc }
-        # @points_for_cache = {}
-        # @dc_period = nil
+        @t1 = ticks[-2] || @t0
+        @t2 = ticks[-3] || @t1
+        @t3 = ticks[-4] || @t2
+
+        compute
+      end
+
+      def each(&block)
+        @points.each_value(&block)
+      end
+
+      def inspect
+        "#<#{self.class.name} symbol=#{series.symbol} source=#{source} #{ticks.size} ticks>"
       end
 
+      def compute
+        raise NotImplementedError
+      end
+
+      def indicator_name
+        self.class.name.split("::").last
+      end
+
+      def points_class
+        Object.const_get "Quant::Indicators::#{indicator_name}Point"
+      end
+
+      # p(0) => values[-1]
+      # p(1) => values[-2]
+      # p(2) => values[-3]
+      # p(3) => values[-4]
+      def p(offset)
+        raise ArgumentError, "offset must be a positive value" if offset < 0
+
+        index = offset + 1
+        values[[-index, -size].max]
+      end
+
+      # t(0) => ticks[-1]
+      # t(1) => ticks[-2]
+      # t(2) => ticks[-3]
+      # t(3) => ticks[-4]
+      def t(offset)
+        raise ArgumentError, "offset must be a positive value" if offset < 0
+
+        index = offset + 1
+        ticks[[-index, -size].max]
+      end
+
+      # The input is the value derived from the source for the indicator
+      # for the current tick.
+      # For example, if the source is :oc2, then the input is the
+      # value of the current tick's (open + close) / 2
+      # @return [Numeric]
+      def input
+        t0.send(source)
+      end
+
+      # def warmed_up?
+      #   true
+      # end
+
+      # attr_reader :dc_period
+
       # def points_for(series:)
       #   @points_for_cache[series] ||= self.class.new(series:, settings:, cloning: true).tap do |indicator|
       #     series.ticks.each { |tick| indicator.points.push(tick.indicators[self]) }
@@ -77,10 +129,6 @@ module Quant
       #   series.ticks.empty? ? series : series.ticks.first.series
       # end
 
-      # def after_initialization
-      #   # NoOp
-      # end
-
       # # Returns the last point of the current indicator rather than the entire series
       # # This is used for indicators that depend on dominant cycle or other indicators
       # # to compute their data points.
@@ -103,13 +151,6 @@ module Quant
       #   raise 'Dominant Cycle Indicators cannot use the thing they compute!'
       # end
 
-      # # Sets the dominant cycle period for the current indicator's point
-      # # @dc_period gets set before each #compute call.
-      # def update_dc_period
-      #   ensure_not_dominant_cycler_indicator
-      #   @dc_period = current_dominant_cycle.period
-      # end
-
       # # Returns the dominant cycle point for the current indicator's point
       # def current_dominant_cycle
       #   dominant_cycle_indicator[current_point]
@@ -133,4 +174,4 @@ module Quant
       # end
     end
   end
-end
+end

data/lib/quant/indicators/indicator_point.rb

@@ -3,33 +3,21 @@
 module Quant
   class Indicators
     class IndicatorPoint
-      extend Forwardable
+      include Quant::Attributes
 
-      attr_reader :tick, :source
+      attr_reader :tick
+      attribute :source, key: "src"
+      attribute :input, key: "in"
 
       def initialize(tick:, source:)
         @tick = tick
-        @source = @tick.send(source)
+        @source = source
+        @input = @tick.send(source)
+        initialize_data_points
       end
 
-      def volume
-        @tick.base_volume
-      end
-
-      def timestamp
-        @tick.close_timestamp
-      end
-
-      def initialize_data_points(indicator:)
-        # NoOp
-      end
-
-      def to_h
-        raise NotImplementedError
-      end
-
-      def to_json(*args)
-        Oj.dump(to_h, *args)
+      def initialize_data_points
+        # No-Op - Override in subclass if needed.
       end
     end
   end