quantitative 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d68c387b70e811a933f804ccc410a9a7eb5382b40c01f806cd446d8d3f893ec
-  data.tar.gz: 4d19edc74c74e80ff5cd14bfe0906efad8ee7518ef15e17e7365faf9067b83cf
+  metadata.gz: 3f00aee096aa1bbed04ac495bfca0d468eccee92e84ca1cc5d0e7c868299489d
+  data.tar.gz: 2d06fc2b90c09ceb39e471360917895c99c64501b4c577e5a288fcea8134f658
 SHA512:
-  metadata.gz: '08c361a6745b972d50d47b6f73a4e455ae56e5a8a770b1c62ef2ca21e2893c4831e655be702c25c02f0af2edffb561b6db75a7ecc15b080c780442f0eeede8a7'
-  data.tar.gz: e29e29bd0bdaf461bbb9581dda8aac99c8dab99c947e31a133710aa62c2ee4a7aa078297cf2f1868a795d7384a834e3dd4a69d124f4017cdf8854b936349415f
+  metadata.gz: 62eea4fce9e5588ccd9dd4ba25bcc1369b82b3c79821394a5c2583a0a47216fa7cb06a45e533568b4e8cd69b57a69c72211dfbeb24c3cccbf6faf30739da8e97
+  data.tar.gz: 61da1a83ea015eb49b55c99ea6d539293756af1e2ac927006891e9167c2de046295d00204af29aa55300945600c80a2e65dae3d968667d598177bc33629989ef

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.6.0] — 2026-06-13
+
+### Added
+
+- **`Quant::Indicators::DominantCycles::SuppliedPeriod`** — generalization of the prior `HalfPeriod` slot. The class doc names four canonical supply modes (fixed / manual / configured / external) that consumers compose freely. The `compute` method stays no-op; whoever sets `point.period` controls the period that downstream indicators reading `adaptive_period` see. The substrate-driven external mode is the load-bearing pattern for tick-derived adaptive lookbacks (e.g., Fishy peak-count cycle period) where another process writes the period to a runtime store and the integration site reads + populates the point.
+- **`:supplied_period`** symbol registered alongside the other DC kinds; it is the new default for `Settings::Indicators#dominant_cycle_kind`.
+
+### Deprecated (removed in 0.9.0)
+
+- **`Quant::Indicators::DominantCycles::HalfPeriod`** → use `SuppliedPeriod`. The old constant remains as an alias and is marked via `Module#deprecate_constant`; each access emits a Ruby deprecation warning. The two are equivalent at runtime; the rename clarifies the underlying capability.
+- **`Quant::Indicators::DominantCycles::HalfPeriodPoint`** → use `SuppliedPeriodPoint`. Same alias + `deprecate_constant` treatment.
+- **`:half_period` dominant_cycle_kind symbol** → use `:supplied_period`. `Settings::Indicators#dominant_cycle_indicator_class` resolves the deprecated symbol to `SuppliedPeriod` and emits a one-time-per-instance warning via `warn`.
+
+The unrelated `Settings::Indicators#half_period` method (returns `(max_period + min_period) / 2`) and the point default symbol `:half_period` (which references that method, not the deprecated class) are NOT deprecated and continue to work unchanged.
+
+See `Quant::Indicators::DominantCycles::SuppliedPeriod` class doc §Migration for the upgrade path. Existing consumers see identical runtime behavior; only the names change.
+
+---
+
 ## [0.5.0] — 2026-05-22
 
 ### Changed (breaking)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    quantitative (0.5.0)
+    quantitative (0.6.0)
       csv
       oj (~> 3.10)
       zeitwerk (~> 2.6)

data/lib/quant/dominant_cycles_source.rb

@@ -6,8 +6,9 @@ module Quant
   #
   #    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}.
+  # The default dominant cycle kind is the `supplied_period` slot (formerly `half_period`; the old name
+  # is deprecated since 0.6.0 and removed in 0.9.0).  This can be adjusted by setting the
+  # `dominant_cycle_kind` configuration value in {Quant::Config}.
   #
   #    Quant.configure_indicators(dominant_cycle_kind: :band_pass)
   #

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

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Quant
+  module Indicators
+    module DominantCycles
+      # `SuppliedPeriod` — a dominant-cycle slot whose period is supplied
+      # by the caller rather than computed from price data. The `compute`
+      # method is intentionally a no-op; whatever sets `point.period` is
+      # the period that downstream indicators reading `adaptive_period`
+      # will see.
+      #
+      # Use this when you want a downstream indicator's lookback window
+      # to come from somewhere other than the indicator's own cycle
+      # detection — a fixed constant, an operator setting, a config
+      # value, or a separate runtime process. Four canonical modes,
+      # distinguished only by *who* sets the period and *when*:
+      #
+      # | Mode       | Period source                          | When set         | Example use case                          |
+      # |------------|----------------------------------------|------------------|-------------------------------------------|
+      # | Fixed      | Literal value at construction          | Once             | RSI(14), SMA(20) — classical lookbacks    |
+      # | Manual     | Operator-mutable runtime setting       | On every read    | Settings page, Pool config tuning         |
+      # | Configured | `Quant.config.indicators` symbol       | On every read    | Project-wide default lookback             |
+      # | External   | Substrate written by another process   | Per-tick by collector | Tick-derived adaptive period (Fishy peak-count) |
+      #
+      # ## Mode 1: Fixed
+      #
+      # Period is a literal value, set once at construction, never
+      # changes. The classical "RSI(14)" / "SMA(20)" shape.
+      #
+      #     Quant.config.indicators.dominant_cycle_kind = :supplied_period
+      #     indicator = MyIndicator.new(series: series)
+      #     indicator.dominant_cycle.p0.period = 14    # fixed lookback
+      #
+      # ## Mode 2: Manual (operator-tunable at runtime)
+      #
+      # Period is set from a value the operator changes via UI, config
+      # file reload, settings page, etc. The slot reads whatever value
+      # is current when the indicator runs.
+      #
+      #     point.period = pool.config.fetch(:lookback_window)
+      #
+      # When the operator updates `pool.config[:lookback_window]`, the
+      # next tick sees the new value. No re-instantiation needed.
+      #
+      # ## Mode 3: Configured (Quant.config-resolved default)
+      #
+      # Period defaults to a symbol (`:half_period`) that resolves
+      # through `Quant.config.indicators` at indicator construction
+      # time. This was the original `HalfPeriod` usage — the parent
+      # `Indicator#half_period` resolves to
+      # `(min_period + max_period) / 2` from the active config.
+      #
+      # The default symbol mechanism resolves once per indicator
+      # instance; if the operator mutates `Quant.config.indicators`
+      # after construction, existing indicator instances continue
+      # using the resolved-at-construction value. Construct a fresh
+      # indicator to pick up the new config (or use Mode 2 / 4 if
+      # you need true runtime tracking).
+      #
+      #     class SuppliedPeriodPoint < IndicatorPoint
+      #       attribute :period, default: :half_period
+      #     end
+      #
+      #     # consumer site — no explicit set; default symbol resolves:
+      #     indicator.dominant_cycle.p0.period     # => 18 (resolved from config)
+      #
+      # ## Mode 4: External (runtime-supplied by a separate process)
+      #
+      # Period is supplied per-tick by a separate producer writing to
+      # substrate. The integration site (collector, service, anywhere
+      # downstream of the producer) reads the substrate and sets
+      # `point.period` before consumers read `adaptive_period`.
+      #
+      # Example pattern: a producer computes a tick-stream peak-to-peak
+      # period and writes it to substrate. A consuming indicator's
+      # collector instance reads the substrate value and populates the
+      # supplied-period slot:
+      #
+      #     period_seconds = substrate.read(platform, listing).period_seconds
+      #     period_bars    = period_seconds / series.interval.to_seconds
+      #     indicator.dominant_cycle.p0.period = period_bars
+      #
+      # The substrate-driven external mode is the load-bearing pattern
+      # for tick-derived adaptive lookbacks — but the slot itself is
+      # mode-agnostic; consumers compose any of the four modes per
+      # their need.
+      #
+      # ## Why no-op `compute`?
+      #
+      # The `DominantCycle` framework's contract is that
+      # `Indicator#dominant_cycle_indicator_class.compute` runs once per
+      # tick, then consumers read `point.period`. `SuppliedPeriod`
+      # short-circuits that — `compute` runs (no-op), and `point.period`
+      # carries whatever the caller put there. This lets the polymorphic
+      # DC dispatch (`Indicator#dominant_cycle`) treat externally-driven
+      # period sources identically to algorithmically-computed ones.
+      #
+      # ## Default fallback
+      #
+      # When no caller sets `point.period`, the attribute default
+      # (`:half_period`) provides safe behavior: downstream indicators
+      # see the midpoint-of-min-max-period config value, which is what
+      # they got pre-rename with `HalfPeriod`. Backward-compatible.
+      #
+      # Note: the default symbol `:half_period` refers to the
+      # `Settings::Indicators#half_period` method (the `(max+min)/2`
+      # attribute), NOT the deprecated `HalfPeriod` class. The method
+      # is not deprecated and is unaffected by this rename.
+      #
+      # ## Migration from HalfPeriod (deprecated; removed in 0.9.0)
+      #
+      # Prior to 0.6.0 this class was named `HalfPeriod`. The old name
+      # was descriptive of one resolved value (the midpoint of min/max
+      # period in config) rather than the underlying capability (a slot
+      # whose period is supplied externally). The rename clarifies that
+      # the slot supports four equivalent modes — see table above.
+      #
+      # The old names continue to work through 0.8.x but emit Ruby
+      # deprecation warnings via `Module#deprecate_constant`:
+      #
+      #     HalfPeriod      = SuppliedPeriod       # deprecated; warns at access
+      #     HalfPeriodPoint = SuppliedPeriodPoint  # deprecated; warns at access
+      #
+      # The registry symbol `:half_period` continues to resolve to
+      # `SuppliedPeriod` for `Quant.config.indicators.dominant_cycle_kind`
+      # through 0.8.x; the resolver emits a one-time deprecation warning
+      # per `Quant::Settings::Indicators` instance when `:half_period`
+      # is the lookup key.
+      #
+      # **To migrate** (any 0.6.x or later):
+      #
+      #     # before:
+      #     Quant.config.indicators.dominant_cycle_kind = :half_period
+      #     point = Quant::Indicators::DominantCycles::HalfPeriodPoint.new(...)
+      #
+      #     # after:
+      #     Quant.config.indicators.dominant_cycle_kind = :supplied_period
+      #     point = Quant::Indicators::DominantCycles::SuppliedPeriodPoint.new(...)
+      #
+      # The point's `period` attribute default stays `:half_period` —
+      # that's the resolved-via-config symbol (Mode 3) and a sensible
+      # safe default; it is NOT the deprecated class name and is not
+      # affected by the rename. Existing consumers see identical
+      # runtime behavior.
+      #
+      # **Removal**: `HalfPeriod` / `HalfPeriodPoint` constants and the
+      # `:half_period` registry alias are scheduled for removal in
+      # quantitative 0.9.0. Migrate any time before then.
+      class SuppliedPeriodPoint < Quant::Indicators::IndicatorPoint
+        attribute :period, default: :half_period
+      end
+
+      class SuppliedPeriod < DominantCycle
+        register name: :supplied_period
+
+        def compute
+          # No-Op — `period` is supplied by the caller (see class doc
+          # for the four canonical supply modes).
+        end
+      end
+
+      # Deprecated aliases — removed in 0.9.0. See `SuppliedPeriod`
+      # class doc §Migration for the upgrade path.
+      HalfPeriodPoint = SuppliedPeriodPoint
+      HalfPeriod      = SuppliedPeriod
+
+      deprecate_constant :HalfPeriod
+      deprecate_constant :HalfPeriodPoint
+    end
+  end
+end

data/lib/quant/settings/indicators.rb

@@ -14,15 +14,19 @@ module Quant
     # 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:
-    # * +:half_period+  - the half_period is the dominant cycle and is not adaptive
+    # The dominant cycle kind is the kind of dominant cycle to use in the indicator.  The default is +:supplied_period+
+    # which means the period is supplied by the caller (defaulting to the half_period config value).  It is not
+    # adaptive when configured this way.  The other kinds are adaptive and are computed from the series data.
+    # The choices are:
+    # * +:supplied_period+ - The period is supplied externally by the caller; not adaptive (see SuppliedPeriod doc
+    #   for the four canonical supply modes: fixed, manual, configured, external). Default.
     # * +: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.
     # * +:differential+ - The dominant cycle is computed from the differential discriminator.
     # * +:phase_accumulator+ - The dominant cycle is computed from the phase accumulator.
+    # * +:half_period+ - **Deprecated** alias for +:supplied_period+; removed in 0.9.0. Resolver emits a
+    #   one-time warning per Settings::Indicators instance when this symbol is used.
     #
     # All of the above are adaptive and are computed from the series data and are described in John Ehlers' books
     # and published papers.
@@ -89,7 +93,17 @@ module Quant
       def dominant_cycle_indicator_class
         return @dominant_cycle_indicator_class if @dominant_cycle_indicator_class
 
-        base_class_name = dominant_cycle_kind.to_s.split("_").map(&:capitalize).join
+        resolved_kind = Settings::DEPRECATED_DOMINANT_CYCLE_KIND_ALIASES[dominant_cycle_kind] || dominant_cycle_kind
+        if resolved_kind != dominant_cycle_kind
+          @dc_kind_deprecation_warned ||= begin
+            warn "[DEPRECATION] dominant_cycle_kind: :#{dominant_cycle_kind} is renamed to " \
+                 ":#{resolved_kind} (scheduled for removal in quantitative 0.9.0). " \
+                 "See Quant::Indicators::DominantCycles::SuppliedPeriod doc §Migration."
+            true
+          end
+        end
+
+        base_class_name = resolved_kind.to_s.split("_").map(&:capitalize).join
         class_name = "Quant::Indicators::DominantCycles::#{base_class_name}"
 
         @dominant_cycle_indicator_class = Object.const_get(class_name)

data/lib/quant/settings.rb

@@ -23,14 +23,23 @@ module Quant
     ).freeze
 
     DOMINANT_CYCLE_KINDS = %i(
-      half_period
+      supplied_period
       band_pass
       auto_correlation_reversal
       homodyne
       differential
       phase_accumulator
+      half_period
     ).freeze
 
+    # Deprecated `dominant_cycle_kind` symbols that resolve to current
+    # symbols via `Settings::Indicators#dominant_cycle_indicator_class`.
+    # Each access emits a one-time-per-instance deprecation warning.
+    # Removed in 0.9.0.
+    DEPRECATED_DOMINANT_CYCLE_KIND_ALIASES = {
+      half_period: :supplied_period
+    }.freeze
+
     # ---- Risk Management Ratio Settings ----
     #   Risk    Reward    Breakeven Win Rate %
     #     50         1            98%

data/lib/quant/version.rb

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

data/quantitative.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "lib/quant/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "quantitative"
+  spec.version = Quant::VERSION
+  spec.authors = ["Michael Lang"]
+  spec.email = ["mwlang@cybrains.net"]
+
+  spec.summary = "Quantitative and statistical tools written for Ruby for trading and finance."
+  spec.description = spec.summary
+  spec.homepage = "https://github.com/mwlang/quantitative"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.3"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_dependency "csv"
+  spec.add_dependency "oj", "~> 3.10"
+  spec.add_dependency "zeitwerk", "~> 2.6"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: quantitative
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Michael Lang
@@ -87,9 +87,9 @@ 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/dominant_cycles/supplied_period.rb
 - lib/quant/indicators/ema.rb
 - lib/quant/indicators/frama.rb
 - lib/quant/indicators/indicator.rb
@@ -149,6 +149,7 @@ files:
 - lib/quant/version.rb
 - lib/quantitative.rb
 - possibilities.png
+- quantitative.gemspec
 homepage: https://github.com/mwlang/quantitative
 licenses:
 - MIT

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

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-module Quant
-  module Indicators
-    module 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
-        register name: :half_period
-
-        def compute
-          # No-Op
-        end
-      end
-    end
-  end
-end