quantitative 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3db79bcbb841511c94568e330f60dfb6b68178ae874c56b867c17c538510a01
-  data.tar.gz: c5da8745035d84023886dcc8fba53f0df473c404b979e084385f6d9a7e19d536
+  metadata.gz: bf0aa73684247efc7bc9750c27c856a094fa362d99c1eba73bd70457da8f3a97
+  data.tar.gz: 56dcaa82230328cb44149ceb957420484217e33c6f601ea135997391bfb95440
 SHA512:
-  metadata.gz: 23c01e976533a62eddd80d5a774c55d23c644f6b9902392277f8a3450849f46a8dd8ead5588d8cc798cbaa36cce6c7ca7404ed332d4b41d6707982fb8e85c7bc
-  data.tar.gz: 769c9951b5af3cef2f9a4b93c4a49bd13f33876daa18ba90cf78a00503bfea1e87d8fa4ece964e72f0e15dbc712ef857bf3fa102d438e982d308e00a4c376b9d
+  metadata.gz: b674a5e4408a69039cf2c7ad2378d065e3f88b409a7530108af1bfc5a186a02690cba8ffb1c8d40a87ad69368f302d9eec0211135beec7db6a9c51c4e1be46d3
+  data.tar.gz: e7d7693cd878ebe777f81ca0d90b4f305e645c8547aa9f420cccb4a4f9b53920211a2b7f49af146508756e6e38f5cc7e0c4b57f1c8abdd722f65bd3409abd02f

data/Gemfile.lock

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

data/lib/quant/errors.rb

@@ -10,6 +10,10 @@ module Quant
     # {Quant::Interval} with an invalid value.
     class InvalidInterval < Error; end
 
+    # {InvalidIndicatorSource} is raised when attempting to reference
+    # an indicator through a source that has not been prepared, yet.
+    class InvalidIndicatorSource < 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

data/lib/quant/indicators/dominant_cycle_indicators.rb

@@ -1,10 +1,49 @@
 module Quant
+  # Dominant Cycles measure the primary cycle within a given range.  By default, the library
+  # is wired to look for cycles between 10 and 48 bars.  These values can be adjusted by setting
+  # the `min_period` and `max_period` configuration values in {Quant::Config}.
+  #
+  #    Quant.configure_indicators(min_period: 8, max_period: 32)
+  #
+  # The default dominant cycle kind is the `half_period` filter.  This can be adjusted by setting
+  # the `dominant_cycle_kind` configuration value in {Quant::Config}.
+  #
+  #    Quant.configure_indicators(dominant_cycle_kind: :band_pass)
+  #
+  # The purpose of these indicators is to compute the dominant cycle and underpin the various
+  # indicators that would otherwise be setting an arbitrary lookback period.  This makes the
+  # indicators adaptive and auto-tuning to the market dynamics.  Or so the theory goes!
   class DominantCycleIndicators < IndicatorsProxy
+    # Auto-Correlation Reversals is a method of computing the dominant cycle
+    # by correlating the data stream with itself delayed by a lag.
     def acr; indicator(Indicators::DominantCycles::Acr) end
+
+    # The band-pass dominant cycle passes signals within a certain frequency
+    # range, and attenuates signals outside that range.
+    # The trend component of the signal is removed, leaving only the cyclical
+    # component.  Then we count number of iterations between zero crossings
+    # and this is the `period` of the dominant cycle.
     def band_pass; indicator(Indicators::DominantCycles::BandPass) end
+
+    # Homodyne means the signal is multiplied by itself. More precisely,
+    # we want to multiply the signal of the current bar with the complex
+    # value of the signal one bar ago
     def homodyne; indicator(Indicators::DominantCycles::Homodyne) end
 
+    # The Dual Differentiator algorithm computes the phase angle from the
+    # analytic signal as the arctangent of the ratio of the imaginary
+    # component to the real component. Further, the angular frequency
+    # is defined as the rate change of phase. We can use these facts to
+    # derive the cycle period.
     def differential; indicator(Indicators::DominantCycles::Differential) end
+
+    # The phase accumulation method of computing the dominant cycle measures
+    # the phase at each sample by taking the arctangent of the ratio of the
+    # quadrature component to the in-phase component.  The phase is then
+    # accumulated and the period is derived from the phase.
     def phase_accumulator; indicator(Indicators::DominantCycles::PhaseAccumulator) end
+
+    # Static, arbitrarily set period.
+    def half_period; indicator(Indicators::DominantCycles::HalfPeriod) end
   end
 end

data/lib/quant/indicators/dominant_cycles/acr.rb

@@ -22,20 +22,20 @@ module Quant
         attribute :reversal, default: false
       end
 
-      # Auto-Correlation Reversals
+      # Auto-Correlation Reversals is a method of computing the dominant cycle
+      # by correlating the data stream with itself delayed by a lag.
+      # Construction of the autocorrelation periodogram starts with the
+      # autocorrelation function using the minimum three bars of averaging.
+      # The cyclic information is extracted using a discrete Fourier transform
+      # (DFT) of the autocorrelation results.
       class Acr < DominantCycle
-        def average_length
-          3 # AvgLength
-        end
-
-        def bandwidth
-          deg2rad(370)
-        end
+        BANDWIDTH_DEGREES = 370
+        BANDWIDTH_RADIANS = BANDWIDTH_DEGREES * Math::PI / 180.0
 
         def compute_auto_correlations
           (min_period..max_period).each do |period|
             corr = Statistics::Correlation.new
-            average_length.times do |lookback_period|
+            micro_period.times do |lookback_period|
               corr.add(p(lookback_period).filter, p(period + lookback_period).filter)
             end
             p0.corr[period] = corr.coefficient
@@ -46,8 +46,8 @@ module Quant
           p0.maxpwr = 0.995 * p1.maxpwr
 
           (min_period..max_period).each do |period|
-            (average_length..max_period).each do |n|
-              radians = bandwidth * n / period
+            (micro_period..max_period).each do |n|
+              radians = BANDWIDTH_RADIANS * n / period
               p0.cospart[period] += p0.corr[n] * Math.cos(radians)
               p0.sinpart[period] += p0.corr[n] * Math.sin(radians)
             end
@@ -98,4 +98,4 @@ module Quant
       end
     end
   end
-end
+end

data/lib/quant/indicators/dominant_cycles/band_pass.rb

@@ -14,6 +14,11 @@ module Quant
         attribute :direction, default: :flat
       end
 
+      # The band-pass dominant cycle passes signals within a certain frequency
+      # range, and attenuates signals outside that range.
+      # The trend component of the signal is revoved, leaving only the cyclical
+      # component.  Then we count number of iterations between zero crossings
+      # and this is the `period` of the dominant cycle.
       class BandPass < DominantCycle
         def bandwidth
           0.75

data/lib/quant/indicators/dominant_cycles/differential.rb

@@ -1,9 +1,11 @@
 module Quant
   class Indicators
     class DominantCycles
-      # The Dual Differentiator algorithm computes the phase angle from the analytic signal as the arctangent of
-      # the ratio of the imaginary component to the real compo- nent. Further, the angular frequency is defined
-      # as the rate change of phase. We can use these facts to derive the cycle period.
+      # The Dual Differentiator algorithm computes the phase angle from the
+      # analytic signal as the arctangent of the ratio of the imaginary
+      # component to the real component. Further, the angular frequency
+      # is defined as the rate change of phase. We can use these facts to
+      # derive the cycle period.
       class Differential < DominantCycle
         def compute_period
           p0.ddd = (p0.q2 * (p0.i2 - p1.i2)) - (p0.i2 * (p0.q2 - p1.q2))

data/lib/quant/indicators/dominant_cycles/dominant_cycle.rb

@@ -2,6 +2,20 @@ require_relative "../indicator"
 
 module Quant
   class Indicators
+    # Dominant Cycles measure the primary cycle within a given range.  By default, the library
+    # is wired to look for cycles between 10 and 48 bars.  These values can be adjusted by setting
+    # the `min_period` and `max_period` configuration values in {Quant::Config}.
+    #
+    #    Quant.configure_indicators(min_period: 8, max_period: 32)
+    #
+    # The default dominant cycle kind is the `half_period` filter.  This can be adjusted by setting
+    # the `dominant_cycle_kind` configuration value in {Quant::Config}.
+    #
+    #    Quant.configure_indicators(dominant_cycle_kind: :band_pass)
+    #
+    # The purpose of these indicators is to compute the dominant cycle and underpin the various
+    # indicators that would otherwise be setting an arbitrary lookback period.  This makes the
+    # indicators adaptive and auto-tuning to the market dynamics.  Or so the theory goes!
     class DominantCycles
       class DominantCyclePoint < Quant::Indicators::IndicatorPoint
         attribute :smooth, default: 0.0
@@ -39,6 +53,8 @@ module Quant
           p0.inst_period = p0.inst_period.clamp(min_period, max_period)
         end
 
+        attr_reader :points
+
         # constrain magnitude of change in phase
         def constrain_period_magnitude_change
           p0.inst_period = [1.5 * p1.inst_period, p0.inst_period].min

data/lib/quant/indicators/dominant_cycles/half_period.rb

@@ -0,0 +1,21 @@
+require_relative "dominant_cycle"
+
+module Quant
+  class Indicators
+    class DominantCycles
+      # This dominant cycle indicator is based on the half period
+      # that is the midpoint of the `min_period` and `max_period`
+      # configured in the `Quant.config.indicators` object.
+      # Effectively providing a static, arbitrarily set period.
+      class HalfPeriodPoint < Quant::Indicators::IndicatorPoint
+        attribute :period, default: :half_period
+      end
+
+      class HalfPeriod < DominantCycle
+        def compute
+          # No-Op
+        end
+      end
+    end
+  end
+end

data/lib/quant/indicators/dominant_cycles/homodyne.rb

@@ -4,8 +4,9 @@ require_relative "dominant_cycle"
 module Quant
   class Indicators
     class DominantCycles
-      # Homodyne means the signal is multiplied by itself. More precisely, we want to multiply the signal
-      # of the current bar with the complex value of the signal one bar ago
+      # Homodyne means the signal is multiplied by itself. More precisely,
+      # we want to multiply the signal of the current bar with the complex
+      # value of the signal one bar ago
       class Homodyne < DominantCycle
         def compute_period
           p0.re = (p0.i2 * p1.i2) + (p0.q2 * p1.q2)

data/lib/quant/indicators/dominant_cycles/phase_accumulator.rb

@@ -8,7 +8,7 @@ module Quant
       # at each sample by taking the arctangent of the ratio of the quadrature
       # component to the in-phase component. A delta phase is generated by
       # taking the difference of the phase between successive samples.
-      # At each sam- ple we can then look backwards, adding up the delta
+      # At each sample we can then look backwards, adding up the delta
       # phases.  When the sum of the delta phases reaches 360 degrees,
       # we must have passed through one full cycle, on average.  The process
       # is repeated for each new sample.

data/lib/quant/indicators/indicator.rb

@@ -19,6 +19,7 @@ module Quant
         @series = series
         @source = source
         @points = {}
+        series.new_indicator(self)
         series.each { |tick| self << tick }
       end
 
@@ -46,6 +47,14 @@ module Quant
         Quant.config.indicators.pivot_kind
       end
 
+      def dominant_cycle
+        series.indicators[source].dominant_cycle
+      end
+
+      def dc_period
+        dominant_cycle.points[t0].period
+      end
+
       def ticks
         @points.keys
       end

data/lib/quant/indicators_proxy.rb

@@ -13,12 +13,21 @@ module Quant
   # 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
+    attr_reader :series, :source, :dominant_cycle, :indicators
 
     def initialize(series:, source:)
       @series = series
       @source = source
       @indicators = {}
+      @dominant_cycle = dominant_cycle_indicator
+    end
+
+    def dominant_cycle_indicator
+      kind = Quant.config.indicators.dominant_cycle_kind.to_s
+      base_class_name = kind.split("_").map(&:capitalize).join
+      class_name = "Quant::Indicators::DominantCycles::#{base_class_name}"
+      indicator_class = Object.const_get(class_name)
+      indicator_class.new(series:, source:)
     end
 
     # Instantiates the indicator class and stores it in the indicators hash.  Once
@@ -36,6 +45,7 @@ module Quant
     # The IndicatorsProxy class is not responsible for enforcing
     # this order of events.
     def <<(tick)
+      dominant_cycle << tick
       indicators.each_value { |indicator| indicator << tick }
     end
 

data/lib/quant/indicators_sources.rb

@@ -7,6 +7,16 @@ module Quant
       @indicator_sources = {}
     end
 
+    def new_indicator(indicator)
+      @indicator_sources[indicator.source] ||= Indicators.new(series: @series, source: indicator.source)
+    end
+
+    def [](source)
+      return @indicator_sources[source] if @indicator_sources.key?(source)
+
+      raise Quant::Errors::InvalidIndicatorSource, "Invalid source, #{source.inspect}."
+    end
+
     def <<(tick)
       @indicator_sources.each_value { |indicator| indicator << tick }
     end

data/lib/quant/series.rb

@@ -101,6 +101,20 @@ module Quant
       "#<#{self.class.name} symbol=#{symbol} interval=#{interval} ticks=#{ticks.size}>"
     end
 
+    # When the first indicator is instantiated, it will also lead to instantiating
+    # the dominant cycle indicator.  The `new_indicator_lock` prevents reentrant calls
+    # to the `new_indicator` method with infinite recursion.
+    def new_indicator(indicator)
+      return if @new_indicator_lock
+
+      begin
+        @new_indicator_lock = true
+        indicators.new_indicator(indicator)
+      ensure
+        @new_indicator_lock = false
+      end
+    end
+
     def <<(tick)
       tick = Ticks::Spot.new(price: tick) if tick.is_a?(Numeric)
       indicators << tick unless tick.series?

data/lib/quant/settings/indicators.rb

@@ -8,14 +8,16 @@ module Quant
     # papers and books on the subject of technical analysis by John Ehlers where he variously suggests
     # a minimum period of 8 or 10 and a max period of 48.
     #
-    # The half period is the average of the max_period and min_period.
+    # The half period is the average of the max_period and min_period.  It is read-only and always computed
+    # relative to `min_period` and `max_period`.
+    #
     # The micro period comes from Ehler's writings on Swami charts and auto-correlation computations, which
     # is a period of 3 bars.  It is useful enough in various indicators to be its own setting.
     #
     # The dominant cycle kind is the kind of dominant cycle to use in the indicator.  The default is +:settings+
     # which means the dominant cycle is whatever the +max_period+ is set to.  It is not adaptive when configured
     # this way.  The other kinds are adaptive and are computed from the series data.  The choices are:
-    # * +:settings+  - the max_period is the dominant cycle and is not adaptive
+    # * +:half_period+  - the half_period is the dominant cycle and is not adaptive
     # * +:band_pass+ - The zero crossings of the band pass filter are used to compute the dominant cycle
     # * +:auto_correlation_reversal+ - The dominant cycle is computed from the auto-correlation of the series.
     # * +:homodyne+ - The dominant cycle is computed from the homodyne discriminator.
@@ -48,8 +50,8 @@ module Quant
         new
       end
 
-      attr_accessor :max_period, :min_period, :half_period, :micro_period
-      attr_accessor :dominant_cycle_kind, :pivot_kind
+      attr_reader :max_period, :min_period, :half_period
+      attr_accessor :micro_period, :dominant_cycle_kind, :pivot_kind
 
       def initialize(**settings)
         @max_period = settings[:max_period] || Settings::MAX_PERIOD
@@ -64,14 +66,22 @@ module Quant
       def apply_settings(**settings)
         @max_period = settings.fetch(:max_period, @max_period)
         @min_period = settings.fetch(:min_period, @min_period)
-        @half_period = settings.fetch(:half_period, @half_period || compute_half_period)
+        compute_half_period
         @micro_period = settings.fetch(:micro_period, @micro_period)
         @dominant_cycle_kind = settings.fetch(:dominant_cycle_kind, @dominant_cycle_kind)
         @pivot_kind = settings.fetch(:pivot_kind, @pivot_kind)
       end
 
+      def max_period=(value)
+        (@max_period = value).tap { compute_half_period }
+      end
+
+      def min_period=(value)
+        (@min_period = value).tap { compute_half_period }
+      end
+
       def compute_half_period
-        (max_period + min_period) / 2
+        @half_period = (max_period + min_period) / 2
       end
     end
   end

data/lib/quant/settings.rb

@@ -23,7 +23,7 @@ module Quant
     ).freeze
 
     DOMINANT_CYCLE_KINDS = %i(
-      settings
+      half_period
       band_pass
       auto_correlation_reversal
       homodyne

data/lib/quant/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quantitative
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Michael Lang
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-11 00:00:00.000000000 Z
+date: 2024-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oj
@@ -56,6 +56,7 @@ files:
 - lib/quant/indicators/dominant_cycles/band_pass.rb
 - lib/quant/indicators/dominant_cycles/differential.rb
 - lib/quant/indicators/dominant_cycles/dominant_cycle.rb
+- lib/quant/indicators/dominant_cycles/half_period.rb
 - lib/quant/indicators/dominant_cycles/homodyne.rb
 - lib/quant/indicators/dominant_cycles/phase_accumulator.rb
 - lib/quant/indicators/indicator.rb