quantitative 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81321ddd563920c047db7eef1c0eaa922a582a5fc17f0c52ea49b4a629aa9010
-  data.tar.gz: d7e00ef24cf0dcf1aaf2cb015591058e37fbbf2d0771f8d950f6d7e38da662cc
+  metadata.gz: 7b99f939e67992ff9a3659ef69ef8ff4bd5897baba1d269c491a7db7d1717c85
+  data.tar.gz: e9f456c34e16ed0c44b4b23f6e274ed44cce4ca6ad7fe654602dbd73afc281bc
 SHA512:
-  metadata.gz: f79190f22f241256fe8a34c35ad8289c09253642a3f534ac8ee4b1fc3fc4cf5f092bbc6c263adb0bf9087067fb5772ad74ff8430f623b467e76973a7a0e95b16
-  data.tar.gz: fa39ccd339097b6d7f18b0e5e9707643be4c224d52b5a27b0adea8b292f626f48ee4c7058771ca4316674196506920fd202b671c40446235e9d121bd9b2ea22e
+  metadata.gz: 4fca7722561f54543b92a7b50700eed4cb706b9bfca65405a8a101908b6ae49b547bcdd2cd13c4656c94a30ad817225118c22c905e47076c88f8feff85947bc4
+  data.tar.gz: 78b256560d7aec2ee19833618bd19e89f6c87ae718ad966b1d18caa18e08727b37d1232b169bce1fbc0b4ca4bac951e956fd4efefaa27450d533769f68d8ac23

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.1)
       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/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/refinements/array.rb

@@ -0,0 +1,195 @@
+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.
+      #
+      # @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.
+      # 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.
+      # 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.
+      # 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.
+      #
+      # @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

@@ -59,7 +59,7 @@ module Quant
                      green: false,
                      doji: nil)
 
-        super(price: close_price, timestamp: close_timestamp, interval:, trades:)
+        super(price: close_price, timestamp: close_timestamp, interval: interval, trades: trades)
         @open_timestamp = extract_time(open_timestamp)
         @open_price = open_price.to_f
         @high_price = high_price.to_f

data/lib/quant/version.rb

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

data/lib/quantitative.rb

@@ -11,7 +11,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.1
 platform: ruby
 authors:
 - Michael Lang
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-11 00:00:00.000000000 Z
+date: 2024-02-12 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,6 +55,7 @@ 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
@@ -142,7 +89,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.