quantitative 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81321ddd563920c047db7eef1c0eaa922a582a5fc17f0c52ea49b4a629aa9010
-  data.tar.gz: d7e00ef24cf0dcf1aaf2cb015591058e37fbbf2d0771f8d950f6d7e38da662cc
+  metadata.gz: 19fe65cd5c50b0b503abaa0e7c5be3949a284cf5a2b537d79b9cbdd69448041d
+  data.tar.gz: fe03ed6b2ddef6609cee31547cd84c1eac948bb8d10efb8c24c316673c693a62
 SHA512:
-  metadata.gz: f79190f22f241256fe8a34c35ad8289c09253642a3f534ac8ee4b1fc3fc4cf5f092bbc6c263adb0bf9087067fb5772ad74ff8430f623b467e76973a7a0e95b16
-  data.tar.gz: fa39ccd339097b6d7f18b0e5e9707643be4c224d52b5a27b0adea8b292f626f48ee4c7058771ca4316674196506920fd202b671c40446235e9d121bd9b2ea22e
+  metadata.gz: 9ce1d965a8e68f6fae76143dfc619ed98c8a5af559e9f26c67dd7685e60bf9b4cfa3ecf5f43908f01597862cb6d6389cebd40cf5897afed560a9e54ed79ea91e
+  data.tar.gz: ee8527e43aa4670175d20a20c6037af11227071ff0fe738344c4b9b91d2391335d210a9e5b305153e78edc75ca9acb802b56b2502223107a84366ae40ba55b7f

data/.ruby-version

@@ -0,0 +1 @@
+3.3.0

data/.yardopts

@@ -0,0 +1,7 @@
+--protected
+--no-private
+lib/quant/**/*.rb
+-
+CODE_OF_CONDUCT.md
+DISCLAIMER.md
+LICENSE

data/Gemfile

@@ -11,4 +11,10 @@ gem "rspec", "~> 3.0"
 
 gem "rubocop", "~> 1.21"
 gem "rubocop-rspec"
-gem "relaxed-rubocop"
+gem "relaxed-rubocop"
+
+gem "debug"
+gem "guard-rspec", "~> 4.7"
+gem "yard", "~> 0.9"
+gem "benchmark-ips", "~> 2.9"
+

data/Gemfile.lock

@@ -1,13 +1,15 @@
 PATH
   remote: .
   specs:
-    quantitative (0.1.0)
+    quantitative (0.1.2)
       oj (~> 3.10)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
+    benchmark-ips (2.13.0)
+    bigdecimal (3.1.6)
     coderay (1.1.3)
     debug (1.8.0)
       irb (>= 1.5.0)
@@ -44,7 +46,8 @@ GEM
     notiffany (0.1.3)
       nenv (~> 0.1)
       shellany (~> 0.0)
-    oj (3.16.1)
+    oj (3.16.3)
+      bigdecimal (>= 3.0)
     parallel (1.24.0)
     parser (3.3.0.4)
       ast (~> 2.4.1)
@@ -112,6 +115,7 @@ PLATFORMS
   arm64-darwin-22
 
 DEPENDENCIES
+  benchmark-ips (~> 2.9)
   debug
   guard-rspec (~> 4.7)
   quantitative!

data/README.md

@@ -1,5 +1,7 @@
 # Quantitative
 
+[![Gem Version](https://badge.fury.io/rb/quantitative.svg)](https://badge.fury.io/rb/quantitative)
+
 STATUS: ALPHA - very early stages!  The framework is very much a work in progress and I am rapidly introducing new things and changing existing things around.
 
 Quantitative is a statistical and quantitative library for Ruby 3.x for trading stocks, cryptocurrency, and forex.  It provides a number of classes and modules for working with time-series data, financial data, and other quantitative data.  It is designed to be fast, efficient, and easy to use.

data/lib/quant/errors.rb

@@ -4,4 +4,5 @@ module Quant
   class Error < StandardError; end
   class InvalidInterval < Error; end
   class InvalidResolution < Error; end
+  class ArrayMaxSizeError < Error; end
 end

data/lib/quant/interval.rb

@@ -167,7 +167,13 @@ module Quant
     alias seconds duration
 
     def ==(other)
-      interval == other&.interval
+      if other.is_a? String
+        interval.to_s == other
+      elsif other.is_a? Symbol
+        interval == MAPPINGS[other]&.fetch(:interval, nil)
+      else
+        interval == other&.interval
+      end
     end
 
     def ticks_per_minute

data/lib/quant/refinements/array.rb

@@ -0,0 +1,196 @@
+module Quant
+  module Refinements
+    # Refinements for the standard Ruby +Array+ class.
+    # These refinements add statistical methods to the Array class as well as some optimizations that greatly
+    # speed up some of the computations performed by the various indicators.
+    #
+    # In addtion to the statistical methods, the refinements also add a +max_size!+ method to the Array class, which
+    # allows us to bound the array to a maximum number of elements, which is useful for indicators that are computing
+    # averages or sums over a fixed number of lookback ticks.
+    #
+    # There are some various performance benchmarks in the spec/performance directory that show the performance
+    # improvements of using these refinements.
+    #
+    # Keep in mind that within this library, we're generally concerned with adding to the tail of the arrays and
+    # rarely with removing or popping, so there's few optimizations or protections for those operations in
+    # conjunction with the +max_size+ setting.  The +max_size+ has also been designed to be set only once, to avoid
+    # adding additional complexity to the code that is unnecessary until a use-case presents itself.
+    #
+    # Usage: Call +using Quant+ in the file or scope where you want to use these refinements.  It does not matter
+    # if the arrays were instantiated outside the scope of the refinement, the refinements will still be applied.
+    #
+    # @example
+    #   using Quant
+    #
+    #   array = [1, 2, 3, 4, 5]
+    #   array.mean => 3.0
+    #   another_array.max_size!(3).push(1, 2, 3, 4, 5, 6) => [4, 5, 6]
+    #
+    # @note The behavior of out of bound indexes into the Array deviates from standard Ruby and always returns an element.
+    #   If an array only has three elements and 4 or more are requested for +n+, the method constrains itself to
+    #   the size of the array. This is an intentional design decision, but it may be a gotcha if you're not expecting it.
+    #   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)
+        push(value)
+      end
+
+      # Overrides the standard +push+ method to track the +maximum+ and +minimum+ values
+      # while also respecting the +max_size+ setting.
+      def push(*objects)
+        Array(objects).each do |object|
+          super(object)
+          if @max_size && size > @max_size
+            voted_off = shift
+            @minimum = min if voted_off == @minimum
+            @maximum = max if voted_off == @maximum
+          else
+            @maximum = object if @maximum.nil? || object > @maximum
+            @minimum = object if @minimum.nil? || object < @minimum
+          end
+        end
+        self
+      end
+
+      # Returns the maximum element value in the array.  It is an optimized version of the standard +max+ method.
+      def maximum
+        @maximum || max
+      end
+
+      # Returns the minimum element value in the array.  It is an optimized version of the standard +min+ method.
+      def minimum
+        @minimum || min
+      end
+
+      # Treats the tail of the array as starting at zero and counting up.  Does not overflow the head of the array.
+      # That is, if the +Array+ has 5 elements, prev(10) would return the first element in the array.
+      #
+      # @example
+      #   series = [1, 2, 3, 4]
+      #   series.prev(0) # => series[-1] => series[3] => 4
+      #   series.prev(1) # => series[-2] => series[3] => 3
+      #   series.prev(2) # => series[-3] => series[2] => 2
+      #   series.prev(3) # => series[-4] => series[1] => 1
+      #   series.prev(4) # => series[-4] => series[0] => 1 (no out of bounds!)
+      #
+      # Useful for when translating TradingView or MQ4 indicators to Ruby where those programs' indexing starts at 0
+      # for most recent bar and counts up to the oldest bar.
+      def prev(index)
+        raise ArgumentError, "index must be positive" if index < 0
+
+        self[[size - (index + 1), 0].max]
+      end
+
+      # Sets the maximum size of the array.  When the size of the array exceeds the
+      # +max_size+, the first element is removed from the array.
+      # This setting modifies :<< and :push methods.
+      def max_size!(max_size)
+        # These guards are maybe not necessary, but they are here until a use-case is found.
+        # My concern lies with indicators that are built specifically against the +max_size+ of a given array.
+        raise Quant::ArrayMaxSizeError, 'cannot set max_size to nil.' unless max_size
+        raise Quant::ArrayMaxSizeError, 'can only max_size! once.' if @max_size
+        raise Quant::ArrayMaxSizeError, "size of Array #{size} exceeds max_size #{max_size}." if size > max_size
+
+        @max_size = max_size
+        self
+      end
+
+      # Computes the mean of the array.  When +n+ is specified, the mean is computed over
+      # the last +n+ elements, otherwise it is computed over the entire array.
+      #
+      # @param n [Integer] the number of elements to compute the mean over
+      # @return [Float]
+      def mean(n: size)
+        subset = last(n)
+        return 0.0 if subset.empty?
+
+        sum = subset.sum / subset.size.to_f
+      end
+
+      # Computes the Exponential Moving Average (EMA) of the array.  When +n+ is specified,
+      # the EMA is computed over the last +n+ elements, otherwise it is computed over the entire array.
+      # An Array of EMA's is returned, with the first entry always the first value in the subset.
+      #
+      # @params n [Integer] the number of elements to compute the EMA over.
+      # @return [Array<Float>]
+      def ema(n: size)
+        subset = last(n)
+        return [] if subset.empty?
+
+        alpha = 2.0 / (subset.size + 1)
+        naught_alpha = (1.0 - alpha)
+        pvalue = subset[0]
+        subset.map do |value|
+          pvalue = (alpha * value) + (naught_alpha * pvalue)
+        end
+      end
+
+      # Computes the Simple Moving Average (SMA) of the array.  When +n+ is specified,
+      # the SMA is computed over the last +n+ elements, otherwise it is computed over the entire array.
+      # An Array of SMA's is returned, with the first entry always the first value in the subset.
+      #
+      # @param n [Integer] the number of elements to compute the SMA over
+      # @return [Array<Float>]
+      def sma(n: size)
+        subset = last(n)
+        return [] if subset.empty?
+
+        pvalue = subset[0]
+        subset.map do |value|
+          pvalue = (pvalue + value) / 2.0
+        end
+      end
+
+      # Computes the Weighted Moving Average (WMA) of the array.  When +n+ is specified,
+      # the WMA is computed over the last +n+ elements, otherwise it is computed over the entire array.
+      # An Array of WMA's is returned, with the first entry always the first value in the subset.
+      #
+      # @param n [Integer] the number of elements to compute the WMA over
+      # @return [Array<Float>]
+      def wma(n: size)
+        subset = last(n)
+        return [] if subset.empty?
+
+        # ensures we return not more than number of elements in full array,
+        # yet have enough values to compute each iteration
+        max_size = [size, n].min
+        while subset.size <= max_size + 2
+          subset.unshift(subset[0])
+        end
+
+        subset.each_cons(4).map do |v1, v2, v3, v4|
+          (4.0 * v4 + 3.0 * v3 + 2.0 * v2 + v1) / 10.0
+        end
+      end
+
+      # Computes the Standard Deviation of the array.  When +n+ is specified,
+      # the Standard Deviation is computed over the last +n+ elements,
+      # otherwise it is computed over the entire array.
+      #
+      # @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
+      end
+
+      def variance(reference_value, n: size)
+        subset = last(n)
+        return 0.0 if subset.empty?
+
+        subset.empty? ? 0.0 : subset.map{ |v| (v - reference_value)**2 }.mean
+      end
+    end
+  end
+
+  refine Array do
+    import_methods Quant::Refinements::Array
+
+    alias std_dev stddev
+    alias standard_deviation stddev
+    alias var variance
+  end
+end

data/lib/quant/ticks/ohlc.rb

@@ -1,125 +1,98 @@
-require_relative 'value'
+# frozen_string_literal: true
+
+require_relative "tick"
 
 module Quant
   module Ticks
-    # serialized keys
-    # ot: open timestamp
-    # ct: close timestamp
-    # iv: interval
-
-    # o: open price
-    # h: high price
-    # l: low price
-    # c: close price
-
-    # bv: base volume
-    # tv: target volume
-    # ct: close timestamp
-
-    # t: trades
-    # g: green
-    # j: doji
-    class OHLC < Value
-      def self.from(hash)
-        new \
-          open_timestamp: hash["ot"],
-          close_timestamp: hash["ct"],
-          interval: hash["iv"],
-
-          open_price: hash["o"],
-          high_price: hash["h"],
-          low_price: hash["l"],
-          close_price: hash["c"],
-
-          base_volume: hash["bv"],
-          target_volume: hash["tv"],
-
-          trades: hash["t"],
-          green: hash["g"],
-          doji: hash["j"]
-      end
-
-      def self.from_json(json)
-        from Oj.load(json)
-      end
-
-      def initialize(open_timestamp:,
-                     close_timestamp:,
-                     interval: nil,
-
-                     open_price:,
-                     high_price:,
-                     low_price:,
-                     close_price:,
-
-                     base_volume: 0.0,
-                     target_volume: 0.0,
-
-                     trades: 0,
-                     green: false,
-                     doji: nil)
-
-        super(price: close_price, timestamp: close_timestamp, interval:, trades:)
+    class OHLC < Tick
+      include TimeMethods
+
+      attr_reader :interval, :series
+      attr_reader :close_timestamp, :open_timestamp
+      attr_reader :open_price, :high_price, :low_price, :close_price
+      attr_reader :base_volume, :target_volume, :trades
+      attr_reader :green, :doji
+
+      def initialize(
+        open_timestamp:,
+        close_timestamp:,
+
+        open_price:,
+        high_price:,
+        low_price:,
+        close_price:,
+
+        interval: nil,
+
+        volume: nil,
+        base_volume: nil,
+        target_volume: nil,
+
+        trades: nil,
+        green: nil,
+        doji: nil
+      )
         @open_timestamp = extract_time(open_timestamp)
+        @close_timestamp = extract_time(close_timestamp)
+
         @open_price = open_price.to_f
         @high_price = high_price.to_f
         @low_price = low_price.to_f
+        @close_price = close_price.to_f
+
+        @interval = Interval[interval]
 
-        @base_volume = base_volume.to_i
-        @target_volume = target_volume.to_i
+        @base_volume = (volume || base_volume).to_i
+        @target_volume = (target_volume || @base_volume).to_i
+        @trades = trades.to_i
 
         @green = green.nil? ? compute_green : green
         @doji = doji.nil? ? compute_doji : doji
+        super()
       end
 
+      alias price close_price
+      alias timestamp close_timestamp
+      alias volume base_volume
+
       def hl2; ((high_price + low_price) / 2.0) end
       def oc2; ((open_price + close_price) / 2.0) end
       def hlc3; ((high_price + low_price + close_price) / 3.0) end
       def ohlc4; ((open_price + high_price + low_price + close_price) / 4.0) end
 
+      # The corresponding? method helps determine that the other tick's timestamp is the same as this tick's timestamp,
+      # which is useful when aligning ticks between two separate series where one starts or ends at a different time,
+      # or when there may be gaps in the data between the two series.
       def corresponding?(other)
         [open_timestamp, close_timestamp] == [other.open_timestamp, other.close_timestamp]
       end
 
-      # percent change from open to close
-      def delta
-        ((open_price / close_price) - 1.0) * 100
+      # Returns the percent daily price change from open_price to close_price, ranging from 0.0 to 1.0.
+      # A positive value means the price increased, and a negative value means the price decreased.
+      # A value of 0.0 means no change.
+      # @return [Float]
+      def daily_price_change
+        ((open_price / close_price) - 1.0)
+      rescue ZeroDivisionError
+        0.0
       end
 
-      def to_h
-        { "ot" => open_timestamp,
-          "ct" => close_timestamp,
-          "iv" => interval.to_s,
-
-          "o" => open_price,
-          "h" => high_price,
-          "l" => low_price,
-          "c" => close_price,
-
-          "bv" => base_volume,
-          "tv" => target_volume,
-
-          "t" => trades,
-          "g" => green,
-          "j" => doji }
-      end
-
-      def as_price(value)
-        series.nil? ? value : series.as_price(value)
-      end
-
-      def to_s
-        ots = interval.daily? ? open_timestamp.strftime('%Y-%m-%d') : open_timestamp.strftime('%Y-%m-%d %H:%M:%S')
-        cts = interval.daily? ? close_timestamp.strftime('%Y-%m-%d') : close_timestamp.strftime('%Y-%m-%d %H:%M:%S')
-        "#{ots}: o: #{as_price(open_price)}, h: #{as_price(high_price)}, l: #{as_price(low_price)}, c: #{as_price(close_price)} :#{cts}"
+      # Calculates the absolute change from the open_price to the close_price, divided by the average of the
+      # open_price and close_price. This method will give a value between 0 and 2, where 0 means no change,
+      # 1 means the price doubled, and 2 means the price went to zero.
+      # 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
       end
 
+      # Set the #green? property to true when the close_price is greater than or equal to the open_price.
       def compute_green
         close_price >= open_price
       end
 
       def green?
-        close_price > open_price
+        @green
       end
 
       def red?
@@ -130,10 +103,10 @@ module Quant
         @doji
       end
 
-      def price_change
-        @price_change ||= ((open_price - close_price) / oc2).abs
-      end
-
+      # Computes a doji candlestick pattern.  A doji is a candlestick pattern that occurs when the open and close
+      # are the same or very close to the same.  The high and low are also very close to the same.  The doji pattern
+      # is a sign of indecision in the market. It is a sign that the market is not sure which way to go.
+      # @return [Boolean]
       def compute_doji
         body_bottom, body_top = [open_price, close_price].sort
 

data/lib/quant/ticks/serializers/ohlc.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Quant
+  module Ticks
+    module Serializers
+      class OHLC < Tick
+        # Returns a +Quant::Ticks::Tick+ from a valid JSON +String+.
+        # @param json [String]
+        # @param tick_class [Quant::Ticks::Tick]
+        # @return [Quant::Ticks::Tick]
+        # @example
+        #  json =
+        #  Quant::Ticks::Serializers::Tick.from_json(json, tick_class: Quant::Ticks::Spot)
+        def self.from_json(json, tick_class:)
+          hash = Oj.load(json)
+          from(hash, tick_class: tick_class)
+        end
+
+        # Returns a +Hash+ of the Spot tick's key properties
+        #
+        # Serialized Keys:
+        #
+        # - ot: open timestamp
+        # - ct: close timestamp
+        # - iv: interval
+        # - o: open price
+        # - h: high price
+        # - l: low price
+        # - c: close price
+        # - bv: base volume
+        # - tv: target volume
+        # - t: trades
+        # - g: green
+        # - j: doji
+        #
+        # @param tick [Quant::Ticks::Tick]
+        # @return [Hash]
+        # @example
+        #  Quant::Ticks::Serializers::Tick.to_h(tick)
+        #  # => { "ot" => [Time], "ct" => [Time], "iv" => "1m", "o" => 1.0, "h" => 2.0,
+        #  #      "l" => 0.5, "c" => 1.5, "bv" => 6.0, "tv" => 5.0, "t" => 1, "g" => true, "j" => true }
+        def self.to_h(tick)
+          { "ot" => tick.open_timestamp,
+            "ct" => tick.close_timestamp,
+            "iv" => tick.interval.to_s,
+
+            "o" => tick.open_price,
+            "h" => tick.high_price,
+            "l" => tick.low_price,
+            "c" => tick.close_price,
+
+            "bv" => tick.base_volume,
+            "tv" => tick.target_volume,
+
+            "t" => tick.trades,
+            "g" => tick.green,
+            "j" => tick.doji }
+        end
+
+        def self.from(hash, tick_class:)
+          tick_class.new \
+            open_timestamp: hash["ot"],
+            close_timestamp: hash["ct"],
+            interval: hash["iv"],
+
+            open_price: hash["o"],
+            high_price: hash["h"],
+            low_price: hash["l"],
+            close_price: hash["c"],
+
+            base_volume: hash["bv"],
+            target_volume: hash["tv"],
+
+            trades: hash["t"],
+            green: hash["g"],
+            doji: hash["j"]
+        end
+      end
+    end
+  end
+end

data/lib/quant/ticks/serializers/spot.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Quant
+  module Ticks
+    module Serializers
+      class Spot < Tick
+        # Returns a +Quant::Ticks::Tick+ from a valid JSON +String+.
+        # @param json [String]
+        # @param tick_class [Quant::Ticks::Tick]
+        # @return [Quant::Ticks::Tick]
+        # @example
+        #  json = "{\"ct\":\"2024-01-15 03:12:23 UTC\", \"cp\":5.0, \"iv\":\"1d\", \"bv\":0.0, \"tv\":0.0, \"t\":0}"
+        #  Quant::Ticks::Serializers::Tick.from_json(json, tick_class: Quant::Ticks::Spot)
+        def self.from_json(json, tick_class:)
+          hash = Oj.load(json)
+          from(hash, tick_class: tick_class)
+        end
+
+        # Returns a +Hash+ of the Spot tick's key properties
+        #
+        # Serialized Keys:
+        #
+        # - ct: close timestamp
+        # - iv: interval
+        # - cp: close price
+        # - bv: base volume
+        # - tv: target volume
+        # - t: trades
+        #
+        # @param tick [Quant::Ticks::Tick]
+        # @return [Hash]
+        # @example
+        #  Quant::Ticks::Serializers::Tick.to_h(tick)
+        #  # => { "ct" => "2024-02-13 03:12:23 UTC", "cp" => 5.0, "iv" => "1d", "bv" => 0.0, "tv" => 0.0, "t" => 0 }
+        def self.to_h(tick)
+          { "ct" => tick.close_timestamp,
+            "cp" => tick.close_price,
+            "iv" => tick.interval.to_s,
+            "bv" => tick.base_volume,
+            "tv" => tick.target_volume,
+            "t" => tick.trades }
+        end
+
+        def self.from(hash, tick_class:)
+          tick_class.new(
+            close_timestamp: hash["ct"],
+            close_price: hash["cp"],
+            interval: hash["iv"],
+            base_volume: hash["bv"],
+            target_volume: hash["tv"],
+            trades: hash["t"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/quant/ticks/serializers/tick.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Quant
+  module Ticks
+    module Serializers
+      # The +Tick+ class serializes and deserializes +Tick+ objects to and from various formats.
+      # These classes are wired into the Tick classes and are used to convert +Tick+ objects to and from
+      # Ruby hashes, JSON strings, and CSV strings.  They're not typically used directly, but are extracted
+      # to make it easier to provide custom serialization and deserialization for +Tick+ objects not shipped
+      # with the library.
+      # @abstract
+      class Tick
+        # Returns a +String+ that is a valid CSV row
+        # @param tick [Quant::Ticks::Tick]
+        # @param headers [Boolean]
+        # @return [String]
+        # @example
+        #  Quant::Ticks::Serializers::Tick.to_csv(tick)
+        #  # => "1d,9999,5.0\n"
+        # @example
+        #  Quant::Ticks::Serializers::Tick.to_csv(tick, headers: true)
+        #  # => "iv,ct,cp\n1d,9999,5.0\n"
+        def self.to_csv(tick, headers: false)
+          hash = to_h(tick)
+          row = CSV::Row.new(hash.keys, hash.values)
+          return row.to_csv unless headers
+
+          header_row = CSV::Row.new(hash.keys, hash.keys)
+          header_row.to_csv << row.to_csv
+        end
+
+        # Returns a +String+ that is a valid JSON representation of the tick's key properties.
+        # @param tick [Quant::Ticks::Tick]
+        # @return [String]
+        # @example
+        #  Quant::Ticks::Serializers::Tick.to_json(tick)
+        #  # => "{\"iv\":\"1d\",\"ct\":9999,\"cp\":5.0}"
+        def self.to_json(tick)
+          Oj.dump to_h(tick)
+        end
+
+        # Returns a Ruby +Hash+ comprised of the tick's key properties.
+        # @param tick [Quant::Ticks::Tick]
+        # @return [Hash]
+        # @example
+        #  Quant::Ticks::Serializers::Tick.to_h(tick)
+        #  # => { "iv" => "1d", "ct" => 9999, "cp" => 5.0 }
+        def self.to_h(instance)
+          raise NotImplementedError
+        end
+
+        # Returns a +Quant::Ticks::Tick+ from a Ruby +Hash+.
+        # @param hash [Hash]
+        # @param tick_class [Quant::Ticks::Tick]
+        # @return [Quant::Ticks::Tick]
+        # @example
+        #  hash = { "ct" => 2024-01-15 03:12:23 UTC", "cp" => 5.0, "iv" => "1d", "bv" => 0.0, "tv" => 0.0, "t" => 0}
+        #  Quant::Ticks::Serializers::Tick.from(hash, tick_class: Quant::Ticks::Spot)
+        def self.from(hash, tick_class:)
+          raise NotImplementedError
+        end
+
+        # Returns a +Quant::Ticks::Tick+ from a valid JSON +String+.
+        # @param json [String]
+        # @param tick_class [Quant::Ticks::Tick]
+        # @return [Quant::Ticks::Tick]
+        # @example
+        #  json = "{\"ct\":\"2024-01-15 03:12:23 UTC\", \"cp\":5.0, \"iv\":\"1d\", \"bv\":0.0, \"tv\":0.0, \"t\":0}"
+        #  Quant::Ticks::Serializers::Tick.from_json(json, tick_class: Quant::Ticks::Spot)
+        def self.from_json(json, tick_class:)
+          hash = Oj.load(json)
+          from(hash, tick_class: tick_class)
+        end
+      end
+    end
+  end
+end

data/lib/quant/ticks/spot.rb

@@ -1,32 +1,78 @@
 # frozen_string_literal: true
 
+require_relative "tick"
+
 module Quant
   module Ticks
-    class Spot < Value
-      def self.from(hash)
-        new(close_timestamp: hash["ct"], close_price: hash["c"], base_volume: hash["bv"], target_volume: hash["tv"])
-      end
+    # A +Spot+ is a single price point in time.  It is the most basic form of a +Tick+ and is usually used to represent
+    # a continuously streaming tick that just has a single price point at a given point in time.
+    # @example
+    #   spot = Quant::Ticks::Spot.new(price: 100.0, timestamp: Time.now)
+    #   spot.price # => 100.0
+    #   spot.timestamp # => 2018-01-01 12:00:00 UTC
+    #
+    # @example
+    #   spot = Quant::Ticks::Spot.from({ "p" => 100.0, "t" => "2018-01-01 12:00:00 UTC", "bv" => 1000 })
+    #   spot.price # => 100.0
+    #   spot.timestamp # => 2018-01-01 12:00:00 UTC
+    #   spot.volume # => 1000
+    class Spot < Tick
+      include TimeMethods
+
+      attr_reader :interval, :series
+      attr_reader :close_timestamp, :open_timestamp
+      attr_reader :open_price, :high_price, :low_price, :close_price
+      attr_reader :base_volume, :target_volume, :trades
+
+      def initialize(
+        price: nil,
+        timestamp: nil,
+        close_price: nil,
+        close_timestamp: nil,
+        volume: nil,
+        interval: nil,
+        base_volume: nil,
+        target_volume: nil,
+        trades: nil
+      )
+        raise ArgumentError, "Must supply a spot price as either :price or :close_price" unless price || close_price
+
+        @close_price = (close_price || price).to_f
 
-      def self.from_json(json)
-        from Oj.load(json)
+        @interval = Interval[interval]
+
+        @close_timestamp = extract_time(timestamp || close_timestamp || Quant.current_time)
+        @open_timestamp = @close_timestamp
+
+        @base_volume = (volume || base_volume).to_i
+        @target_volume = (target_volume || @base_volume).to_i
+
+        @trades = trades.to_i
+        super()
       end
 
-      def initialize(close_timestamp:, close_price:, interval: nil, base_volume: 0.0, target_volume: 0.0, trades: 0)
-        super(price: close_price, timestamp: close_timestamp, interval: interval, volume: base_volume, trades: trades)
-        @target_volume = target_volume.to_i
+      alias timestamp close_timestamp
+      alias price close_price
+      alias oc2 close_price
+      alias hl2 close_price
+      alias hlc3 close_price
+      alias ohlc4 close_price
+      alias delta close_price
+      alias volume base_volume
+
+      def ==(other)
+        [close_price, close_timestamp] == [other.close_price, other.close_timestamp]
       end
 
+      # The corresponding? method helps determine that the other tick's timestamp is the same as this tick's timestamp,
+      # which is useful when aligning ticks between two separate series where one starts or ends at a different time,
+      # or when there may be gaps in the data between the two series.
       def corresponding?(other)
         close_timestamp == other.close_timestamp
       end
 
-      def to_h
-        { "ct" => close_timestamp,
-          "c" => close_price,
-          "iv" => interval.to_s,
-          "bv" => base_volume,
-          "tv" => target_volume,
-          "t" => trades }
+      def inspect
+        "#<#{self.class.name} cp=#{close_price.to_f} ct=#{close_timestamp.strftime("%Y-%m-%d")} iv=#{interval.to_s} v=#{volume}>"
       end
     end
   end

data/lib/quant/ticks/tick.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Quant
+  module Ticks
+    # +Tick+ is the abstract ancestor for all Ticks and holds the logic for interacting with series and indicators.
+    # The public interface is devoid of properties around price, volume, and timestamp, etc.  Descendant classes
+    # are responsible for defining the properties and how they are represented.
+    #
+    # The +Tick+ class is designed to be immutable and is intended to be used as a value object.  This means that
+    # once a +Tick+ is created, it cannot be changed.  This is important for the integrity of the series and
+    # indicators that depend on the ticks within the series.
+    #
+    # When a tick is added to a series, it is locked into the series and ownership cannot be changed.  This is important
+    # for the integrity of the series and indicators that depend on the ticks within the series.  This is a key design
+    # to being able to being able to not only compute indicators on the ticks just once, but also avoid recomputing
+    # indicators when series are limited/sliced/filtered into subsets of the original series.
+    #
+    # Ticks can be serialized to and from Ruby Hash, JSON strings, and CSV strings.
+    class Tick
+      # Returns a +Tick+ from a Ruby +Hash+.  The default serializer is used to generate the +Tick+.
+      # @param hash [Hash]
+      # @param serializer_class [Class] The serializer class to use for the conversion.
+      # @return [Quant::Ticks::Tick]
+      # @example
+      #   hash = { "timestamp" => "2018-01-01 12:00:00 UTC", "price" => 100.0, "volume" => 1000 }
+      #   Quant::Ticks::Tick.from(hash)
+      #   # => #<Quant::Ticks::Spot:0x00007f9e3b8b3e08 @timestamp=2018-01-01 12:00:00 UTC, @price=100.0, @volume=1000>
+      def self.from(hash, serializer_class: default_serializer_class)
+        serializer_class.from(hash, tick_class: self)
+      end
+
+      # Returns a +Tick+ from a JSON string.  The default serializer is used to generate the +Tick+.
+      # @param json [String]
+      # @param serializer_class [Class] The serializer class to use for the conversion.
+      # @return [Quant::Ticks::Tick]
+      # @example
+      #   json = "{\"timestamp\":\"2018-01-01 12:00:00 UTC\",\"price\":100.0,\"volume\":1000}"
+      #   Quant::Ticks::Tick.from_json(json)
+      #   # => #<Quant::Ticks::Spot:0x00007f9e3b8b3e08 @timestamp=2018-01-01 12:00:00 UTC, @price=100.0, @volume=1000>
+      def self.from_json(json, serializer_class: default_serializer_class)
+        serializer_class.from_json(json, tick_class: self)
+      end
+
+      attr_reader :series
+
+      def initialize
+        # Set the series by appending to the series or calling #assign_series method
+        @series = nil
+      end
+
+      # Ticks always belong to the first series they're assigned so we can easily spin off
+      # sub-sets or new series with the same ticks while allowing each series to have
+      # its own state and full control over the ticks within its series
+      def assign_series(new_series)
+        assign_series!(new_series) if @series.nil?
+        self
+      end
+
+      # Ticks always belong to the first series they're assigned so we can easily spin off
+      # sub-sets or new series with the same ticks.  However, if you need to reassign the
+      # series, you can use this method to force the change of series ownership.
+      #
+      # The series interval is also assigned to the tick if it is not already set.
+      def assign_series!(new_series)
+        @series = new_series
+        @interval = new_series.interval if @interval.nil?
+        self
+      end
+
+      # Returns a Ruby hash for the Tick.  The default serializer is used to generate the hash.
+      #
+      # @param serializer_class [Class] the serializer class to use for the conversion.
+      # @example
+      #   tick.to_h
+      #   # => { timestamp: "2018-01-01 12:00:00 UTC", price: 100.0, volume: 1000 }
+      def to_h(serializer_class: default_serializer_class)
+        serializer_class.to_h(self)
+      end
+
+      # Returns a JSON string for the Tick.  The default serializer is used to generate the JSON string.
+      #
+      # @param serializer_class [Class] the serializer class to use for the conversion.
+      # @example
+      #   tick.to_json
+      #   # => "{\"timestamp\":\"2018-01-01 12:00:00 UTC\",\"price\":100.0,\"volume\":1000}"
+      def to_json(serializer_class: default_serializer_class)
+        serializer_class.to_json(self)
+      end
+
+      # Returns a CSV row as a String for the Tick.  The default serializer is used to generate the CSV string.
+      # If headers is true, two lines returned separated by newline.
+      # The first line is the header row and the second line is the data row.
+      #
+      # @param serializer_class [Class] the serializer class to use for the conversion.
+      # @example
+      #   tick.to_csv(headers: true)
+      #   # => "timestamp,price,volume\n2018-01-01 12:00:00 UTC,100.0,1000\n"
+      def to_csv(serializer_class: default_serializer_class, headers: false)
+        serializer_class.to_csv(self, headers: headers)
+      end
+
+      # Reflects the serializer class from the tick's class name.
+      # @note internal use only.
+      def self.default_serializer_class
+        Object.const_get "Quant::Ticks::Serializers::#{name.split("::").last}"
+      end
+
+      # Reflects the serializer class from the tick's class name.
+      # @note internal use only.
+      def default_serializer_class
+        self.class.default_serializer_class
+      end
+    end
+  end
+end

data/lib/quant/version.rb

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

data/lib/quantitative.rb

@@ -3,6 +3,7 @@
 require "time"
 require "date"
 require "oj"
+require "csv"
 
 lib_folder = File.expand_path(File.join(File.dirname(__FILE__)))
 quant_folder = File.join(lib_folder, "quant")
@@ -11,7 +12,6 @@ quant_folder = File.join(lib_folder, "quant")
 Dir.glob(File.join(quant_folder, "*.rb")).each { |fn| require fn }
 
 # require sub-folders and their sub-folders
-%w(ticks).each do |sub_folder|
-  Dir.glob(File.join(quant_folder, sub_folder, "*.rb")).each { |fn| require fn }
+%w(refinements ticks).each do |sub_folder|
   Dir.glob(File.join(quant_folder, sub_folder, "**/*.rb")).each { |fn| require fn }
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quantitative
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Michael Lang
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-11 00:00:00.000000000 Z
+date: 2024-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oj
@@ -24,62 +24,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.10'
-- !ruby/object:Gem::Dependency
-  name: debug
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: guard-rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '4.7'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '4.7'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.2'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.2'
-- !ruby/object:Gem::Dependency
-  name: yard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.9'
 description: Quantitative and statistical tools written for Ruby 3.x for trading and
   finance.
 email:
@@ -90,12 +34,14 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
+- ".ruby-version"
+- ".yardopts"
 - CODE_OF_CONDUCT.md
-- DISCLAIMER.txt
+- DISCLAIMER.md
 - Gemfile
 - Gemfile.lock
 - Guardfile
-- LICENSE.txt
+- LICENSE
 - README.md
 - Rakefile
 - lib/quant/errors.rb
@@ -109,12 +55,14 @@ files:
 - lib/quant/mixins/super_smoother.rb
 - lib/quant/mixins/trig.rb
 - lib/quant/mixins/weighted_average.rb
+- lib/quant/refinements/array.rb
 - lib/quant/ticks/core.rb
-- lib/quant/ticks/indicator_points.rb
 - lib/quant/ticks/ohlc.rb
-- lib/quant/ticks/serializers/value.rb
+- lib/quant/ticks/serializers/ohlc.rb
+- lib/quant/ticks/serializers/spot.rb
+- lib/quant/ticks/serializers/tick.rb
 - lib/quant/ticks/spot.rb
-- lib/quant/ticks/value.rb
+- lib/quant/ticks/tick.rb
 - lib/quant/time_methods.rb
 - lib/quant/time_period.rb
 - lib/quant/version.rb
@@ -142,7 +90,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.5.5
 signing_key:
 specification_version: 4
 summary: Quantitative and statistical tools written for Ruby 3.x for trading and finance.

data/lib/quant/ticks/indicator_points.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-module Quant
-  module Ticks
-    class IndicatorPoints
-      attr_reader :points
-
-      def initialize(tick:)
-        @tick = tick
-        @points = {}
-      end
-
-      def [](indicator)
-        points[indicator]
-      end
-
-      def []=(indicator, point)
-        points[indicator] = point
-      end
-    end
-  end
-end

data/lib/quant/ticks/serializers/value.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-module Quant
-  module Ticks
-    module Serializers
-      module Value
-        module_function
-
-        def to_h(instance)
-          { "iv" => instance.interval.to_s,
-            "ct" => instance.close_timestamp.to_i,
-            "cp" => instance.close_price,
-            "bv" => instance.base_volume,
-            "tv" => instance.target_volume }
-        end
-
-        def to_json(instance)
-          Oj.dump to_h(instance)
-        end
-      end
-    end
-  end
-end

data/lib/quant/ticks/value.rb

@@ -1,88 +0,0 @@
-# frozen_string_literal: true
-
-module Quant
-  module Ticks
-    # Value ticks are the most basic ticks and are used to represent a single price point (no open, high, low, close, etc.)
-    # and a single timestamp.  Usually, these are best used in streaming data where ticks are flowing in every second or whatever
-    # interval that's appropriate for the data source.
-    # Often indicators and charts still want a universal public interface (i.e. open_price, high_price, volume, etc.), so we add
-    # those methods here and inherit and redefine upstream as appropriate.
-    #
-    # For Value ticks:
-    # * The +price+ given is set for all *_price fields.
-    # * The +volume+ is set for both base and target volume.
-    # * The +timestamp+ is set for both open and close timestamps.
-    class Value
-      include TimeMethods
-
-      attr_reader :interval, :series
-      attr_reader :close_timestamp, :open_timestamp
-      attr_reader :open_price, :high_price, :low_price, :close_price
-      attr_reader :base_volume, :target_volume, :trades
-      attr_reader :green, :doji
-
-      def initialize(price:, timestamp: Quant.current_time, interval: nil, volume: 0, trades: 0)
-        @interval = Interval[interval]
-
-        @close_timestamp = extract_time(timestamp)
-        @open_timestamp = @close_timestamp
-
-        @close_price = price.to_f
-        @open_price = close_price
-        @high_price = close_price
-        @low_price = close_price
-
-        @base_volume = volume.to_i
-        @target_volume = volume.to_i
-        @trades = trades.to_i
-
-        # Set the series by appending to the series
-        @series = nil
-      end
-
-      alias oc2 close_price
-      alias hl2 close_price
-      alias hlc3 close_price
-      alias ohlc4 close_price
-      alias delta close_price
-      alias volume base_volume
-
-      def corresponding?(other)
-        close_timestamp == other.close_timestamp
-      end
-
-      def ==(other)
-        to_h == other.to_h
-      end
-
-      # ticks are immutable across series so we can easily initialize sub-sets or new series
-      # with the same ticks while allowing each series to have its own state and full
-      # control over the ticks within its series
-      def assign_series(new_series)
-        assign_series!(new_series) if @series.nil?
-
-        # dup.tap do |new_tick|
-        #   # new_tick.instance_variable_set(:@series, new_series)
-        #   new_tick.instance_variable_set(:@indicators, indicators)
-        # end
-      end
-
-      def assign_series!(new_series)
-        @series = new_series
-        self
-      end
-
-      def inspect
-        "#<#{self.class.name} iv=#{interval} ct=#{close_timestamp.strftime("%Y-%m-%d")} o=#{open_price} c=#{close_price} v=#{volume}>"
-      end
-
-      def to_h
-        Quant::Ticks::Serializers::Value.to_h(self)
-      end
-
-      def to_json(*_args)
-        Quant::Ticks::Serializers::Value.to_json(self)
-      end
-    end
-  end
-end