indicator_hub 0.1.0

data/lib/indicator_hub/indicators/trix.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "../calculation_helpers"
+require_relative "ema"
+
+module IndicatorHub
+  module Indicators
+    # Triple Exponential Average (TRIX).
+    # TRIX is a momentum oscillator that shows the percent rate-of-change of a
+    # triple exponentially smoothed moving average.
+    class TRIX
+      # Calculates the Triple Exponential Average.
+      # @param data [Array<Numeric>] The input data points.
+      # @param period [Integer] The TRIX period (default: 15).
+      # @return [Array<Float, nil>] The calculated TRIX values.
+      def self.calculate(data, period: 15)
+        period = period.to_i
+
+        # EMA1 = EMA(price, n)
+        ema1 = EMA.calculate(data, period: period)
+
+        # Filter out nils for next EMA
+        ema1_filtered = ema1.compact
+        ema2 = EMA.calculate(ema1_filtered, period: period)
+
+        # EMA2 filtered
+        ema2_filtered = ema2.compact
+        ema3 = EMA.calculate(ema2_filtered, period: period)
+
+        # Now we need to align them back to the original data size
+        # ema1 has (period - 1) nils at the start
+        # ema2 has (period - 1) additional nils
+        # ema3 has (period - 1) additional nils
+        # Total nils at start of ema3 (aligned to data): 3 * (period - 1)
+
+        full_ema3 = Array.new(data.size, nil)
+        ema3_compact = ema3.compact
+
+        offset = 3 * (period - 1)
+        ema3_compact.each_with_index do |v, i|
+          full_ema3[offset + i] = v if offset + i < data.size
+        end
+
+        output = Array.new(data.size, nil)
+        (1...data.size).each do |i|
+          output[i] = (((full_ema3[i] - full_ema3[i - 1]) / full_ema3[i - 1].to_f) * 100.0) if full_ema3[i] && full_ema3[i - 1]
+        end
+
+        output
+      end
+    end
+  end
+end

data/lib/indicator_hub/indicators/tsi.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "../calculation_helpers"
+require_relative "ema"
+
+module IndicatorHub
+  module Indicators
+    # True Strength Index (TSI).
+    # TSI is a technical momentum oscillator used to identify trends and reversals.
+    class TSI
+      # Calculates the True Strength Index.
+      # @param data [Array<Numeric>] The input data points.
+      # @param fast_period [Integer] Fast EMA period (default: 13).
+      # @param slow_period [Integer] Slow EMA period (default: 25).
+      # @return [Array<Float, nil>] The calculated TSI values.
+      def self.calculate(data, fast_period: 13, slow_period: 25)
+        fast_period = fast_period.to_i
+        slow_period = slow_period.to_i
+
+        return [] if data.size < 2
+
+        # 1. Momentum and absolute momentum
+        momentum = []
+        abs_momentum = []
+
+        (1...data.size).each do |i|
+          m = data[i] - data[i - 1]
+          momentum << m
+          abs_momentum << m.abs
+        end
+
+        # 2. First EMA (slow_period)
+        ema1_m = EMA.calculate(momentum, period: slow_period)
+        ema1_abs_m = EMA.calculate(abs_momentum, period: slow_period)
+
+        # 3. Second EMA (fast_period)
+        ema1_m_filtered = ema1_m.compact
+        ema1_abs_m_filtered = ema1_abs_m.compact
+
+        ema2_m = EMA.calculate(ema1_m_filtered, period: fast_period)
+        ema2_abs_m = EMA.calculate(ema1_abs_m_filtered, period: fast_period)
+
+        # Align results back to original data size
+        # momentum size is (data.size - 1)
+        # ema1 has (slow_period - 1) nils
+        # ema2 has (fast_period - 1) additional nils
+        # total nils in ema2 relative to momentum: (slow_period - 1) + (fast_period - 1)
+        # relative to original data: 1 + (slow_period - 1) + (fast_period - 1) = slow_period + fast_period - 1
+
+        offset = slow_period + fast_period - 1
+        output = Array.new(data.size, nil)
+
+        ema2_m_compact = ema2_m.compact
+        ema2_abs_m_compact = ema2_abs_m.compact
+
+        ema2_m_compact.each_with_index do |v, i|
+          if offset + i < data.size
+            div = ema2_abs_m_compact[i]
+            output[offset + i] = div.zero? ? 0.0 : 100.0 * (v / div.to_f)
+          end
+        end
+
+        output
+      end
+    end
+  end
+end

data/lib/indicator_hub/indicators/uo.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "../calculation_helpers"
+
+module IndicatorHub
+  module Indicators
+    # Ultimate Oscillator (UO).
+    # UO is a technical indicator that combines price action over three
+    # different timeframes into a single momentum oscillator.
+    class UO
+      # Calculates the Ultimate Oscillator.
+      # @param data [Array<Hash>] Array of OHLCV hashes.
+      # @param short_period [Integer] Short period (default: 7).
+      # @param medium_period [Integer] Medium period (default: 14).
+      # @param long_period [Integer] Long period (default: 28).
+      # @param short_weight [Float] Short period weight (default: 4.0).
+      # @param medium_weight [Float] Medium period weight (default: 2.0).
+      # @param long_weight [Float] Long period weight (default: 1.0).
+      # @return [Array<Float, nil>] The calculated UO values.
+      def self.calculate(data, short_period: 7, medium_period: 14, long_period: 28,
+                         short_weight: 4.0, medium_weight: 2.0, long_weight: 1.0)
+        short_period = short_period.to_i
+        medium_period = medium_period.to_i
+        long_period = long_period.to_i
+
+        return [] if data.size < 2
+
+        bp = []
+        tr = []
+
+        (1...data.size).each do |i|
+          v = data[i]
+          prev_close = data[i - 1][:close]
+
+          min_low_p_close = [v[:low], prev_close].min
+          max_high_p_close = [v[:high], prev_close].max
+
+          bp << (v[:close] - min_low_p_close)
+          tr << (max_high_p_close - min_low_p_close)
+        end
+
+        sum_weights = short_weight + medium_weight + long_weight
+        output = Array.new(data.size, nil)
+
+        # We need long_period elements in bp/tr to start
+        # bp/tr have size data.size - 1
+        ((long_period - 1)...bp.size).each do |i|
+          avg7 = sum_last(bp, i, short_period) / sum_last(tr, i, short_period).to_f
+          avg14 = sum_last(bp, i, medium_period) / sum_last(tr, i, medium_period).to_f
+          avg28 = sum_last(bp, i, long_period) / sum_last(tr, i, long_period).to_f
+
+          uo = 100.0 * ((short_weight * avg7) + (medium_weight * avg14) + (long_weight * avg28)) / sum_weights
+          output[i + 1] = uo
+        end
+
+        output
+      end
+
+      def self.sum_last(array, index, period)
+        start = index - period + 1
+        sum = 0.0
+        (start..index).each { |j| sum += array[j] }
+        sum
+      end
+    end
+  end
+end

data/lib/indicator_hub/indicators/vi.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "../calculation_helpers"
+
+module IndicatorHub
+  module Indicators
+    # Vortex Indicator (VI).
+    # VI is a technical indicator consisting of two lines that identify
+    # positive and negative trend movement.
+    class VI
+      # Calculates the Vortex Indicator.
+      # @param data [Array<Hash>] Array of OHLCV hashes.
+      # @param period [Integer] The VI period (default: 14).
+      # @return [Array<Hash>] The calculated VI values { plus_vi: Float, minus_vi: Float }.
+      def self.calculate(data, period: 14)
+        output = []
+        pos_vms = []
+        neg_vms = []
+        trs = []
+
+        data.each_with_index do |val, i|
+          if i.zero?
+            output << { plus_vi: nil, minus_vi: nil }
+            next
+          end
+
+          prev = data[i - 1]
+          pos_vm = (val[:high] - prev[:low]).abs
+          neg_vm = (val[:low] - prev[:high]).abs
+          tr = CalculationHelpers.true_range(val[:high], val[:low], prev[:close])
+
+          pos_vms << pos_vm
+          neg_vms << neg_vm
+          trs << tr
+
+          if pos_vms.size >= period
+            sum_pos = CalculationHelpers.sum(pos_vms.last(period))
+            sum_neg = CalculationHelpers.sum(neg_vms.last(period))
+            sum_tr = CalculationHelpers.sum(trs.last(period))
+
+            output << {
+              plus_vi: (sum_pos / sum_tr.to_f),
+              minus_vi: (sum_neg / sum_tr.to_f)
+            }
+          else
+            output << { plus_vi: nil, minus_vi: nil }
+          end
+        end
+
+        output
+      end
+    end
+  end
+end

data/lib/indicator_hub/indicators/volume_oscillator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "../calculation_helpers"
+
+module IndicatorHub
+  module Indicators
+    # Volume Oscillator.
+    # Volume Oscillator measures the difference between a fast and slow volume
+    # moving average.
+    class VolumeOscillator
+      # Calculates the Volume Oscillator.
+      # @param data [Array<Numeric, Hash>] Array of volumes or OHLCV hashes.
+      # @param short_period [Integer] Short SMA period (default: 20).
+      # @param long_period [Integer] Long SMA period (default: 60).
+      # @return [Array<Float, nil>] The calculated Volume Oscillator values.
+      def self.calculate(data, short_period: 20, long_period: 60)
+        # Handle OHLC data by extracting volume
+        numeric_data = if data.is_a?(Array) && data.first.is_a?(Hash)
+                         data.map { |d| d[:volume] }
+                       else
+                         data
+                       end
+
+        Validation.validate_numeric_data(numeric_data)
+
+        output = []
+        short_period_values = []
+        long_period_values = []
+
+        numeric_data.each do |v|
+          short_period_values << v
+          long_period_values << v
+
+          short_period_values.shift if short_period_values.size > short_period
+          long_period_values.shift if long_period_values.size > long_period
+
+          if long_period_values.size == long_period
+            short_sma = CalculationHelpers.average(short_period_values)
+            long_sma = CalculationHelpers.average(long_period_values)
+
+            vo = if long_sma.zero?
+                   0.0
+                 else
+                   ((short_sma - long_sma) / long_sma.to_f) * 100.0
+                 end
+            output << vo.round(2)
+          else
+            output << nil
+          end
+        end
+        output
+      end
+    end
+  end
+end

data/lib/indicator_hub/indicators/vpt.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "../calculation_helpers"
+
+module IndicatorHub
+  module Indicators
+    # Volume-Price Trend (VPT).
+    # VPT is a technical indicator that combines price and volume to confirm
+    # the strength of a price trend or signal its reversal.
+    class VPT
+      # Calculates the Volume-Price Trend.
+      # @param data [Array<Hash>] Array of OHLCV hashes.
+      # @return [Array<Float, nil>] The calculated VPT values.
+      def self.calculate(data)
+        output = []
+        prev_vpt = 0.0
+
+        data.each_with_index do |val, i|
+          if i.zero?
+            output << nil
+            next
+          end
+
+          prev = data[i - 1]
+          # VPT = prev_vpt + (volume * (close - prev_close) / prev_close)
+          vpt = prev_vpt + (val[:volume] * (val[:close] - prev[:close]) / prev[:close].to_f)
+          output << vpt
+          prev_vpt = vpt
+        end
+
+        output
+      end
+    end
+  end
+end

data/lib/indicator_hub/indicators/vwap.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "../calculation_helpers"
+
+module IndicatorHub
+  module Indicators
+    # Volume Weighted Average Price (VWAP).
+    # VWAP is a technical analysis indicator used on intraday charts that resets
+    # at the start of every new trading session.
+    class VWAP
+      # Calculates the Volume Weighted Average Price.
+      # @param data [Array<Hash>] Array of OHLCV hashes.
+      # @return [Array<Float, nil>] The calculated VWAP values.
+      def self.calculate(data)
+        # Expects array of hashes with :high, :low, :close, :volume
+        output = []
+        cumm_volume = 0.0
+        cumm_volume_x_typical_price = 0.0
+
+        data.each do |v|
+          tp = CalculationHelpers.typical_price(v[:high], v[:low], v[:close])
+          vol = v[:volume].to_f
+          cumm_volume_x_typical_price += vol * tp
+          cumm_volume += vol
+
+          vwap = cumm_volume.positive? ? (cumm_volume_x_typical_price / cumm_volume) : 0.0
+          output << vwap
+        end
+        output
+      end
+    end
+  end
+end

data/lib/indicator_hub/indicators/wilders_smoothing.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module IndicatorHub
+  module Indicators
+    # Wilder's Smoothing.
+    # Wilder's Smoothing is a type of exponential moving average used in
+    # technical indicators like RSI and ATR.
+    class WildersSmoothing
+      include CalculationHelpers
+
+      # Calculates Wilder's Smoothing.
+      # @param prices [Array<Numeric>] Array of prices.
+      # @param period [Integer] The smoothing period (default: 14).
+      # @return [Array<Float, nil>] The calculated Wilder's Smoothing values.
+      def self.calculate(prices, period: 14)
+        return Array.new(prices.length, nil) if prices.length < period
+
+        results = Array.new(period - 1, nil)
+
+        # First Wilder's is a simple average of the first 'period' values
+        initial_sma = prices.first(period).sum.to_f / period
+        results << initial_sma.round(4)
+
+        wilders = initial_sma
+        alpha = 1.0 / period
+
+        prices.drop(period).each do |price|
+          wilders = ((price - wilders) * alpha) + wilders
+          results << wilders.round(4)
+        end
+
+        results
+      end
+    end
+  end
+end

data/lib/indicator_hub/indicators/wma.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "../calculation_helpers"
+
+module IndicatorHub
+  module Indicators
+    # Weighted Moving Average (WMA).
+    # WMA is a moving average that assigns more weight to recent data points
+    # and less weight to past data points.
+    class WMA
+      # Calculates the Weighted Moving Average.
+      # @param data [Array<Numeric>] The input data points.
+      # @param period [Integer] The WMA period (default: 20).
+      # @return [Array<Float, nil>] The calculated WMA values.
+      def self.calculate(data, period: 20)
+        period = period.to_i
+        Validation.validate_numeric_data(data)
+        return Array.new(data.size, nil) if data.size < period
+
+        output = []
+        period_values = []
+
+        data.each do |v|
+          period_values << v
+          if period_values.size == period
+            output << CalculationHelpers.wma(period_values)
+            period_values.shift
+          else
+            output << nil
+          end
+        end
+        output
+      end
+    end
+  end
+end

data/lib/indicator_hub/indicators/wr.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "../calculation_helpers"
+
+module IndicatorHub
+  module Indicators
+    # Williams %R (WR).
+    # WR is a momentum indicator that measures overbought and oversold levels.
+    class WR
+      # Calculates the Williams %R.
+      # @param data [Array<Hash>] Array of OHLCV hashes.
+      # @param period [Integer] The WR period (default: 14).
+      # @return [Array<Float, nil>] The calculated Williams %R values.
+      def self.calculate(data, period: 14)
+        output = []
+
+        data.each_with_index do |val, i|
+          if i < period - 1
+            output << nil
+            next
+          end
+
+          slice = data[(i - period + 1)..i]
+          highest_high = slice.map { |d| d[:high] }.max
+          lowest_low = slice.map { |d| d[:low] }.min
+
+          # WR = (highest_high - close) / (highest_high - lowest_low) * -100
+          wr = (highest_high - val[:close]) / (highest_high - lowest_low).to_f * -100
+          output << wr
+        end
+
+        output
+      end
+    end
+  end
+end

data/lib/indicator_hub/series.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+# typed: true
+
+require "sorbet-runtime"
+
+module IndicatorHub
+  # Data structure for handling OHLCV and series data.
+  # Provides normalization and sorting capabilities for financial time series data.
+  class Series
+    extend T::Sig
+
+    # @return [Array<T.any(Hash, Numeric)>] The raw input data
+    sig { returns(T::Array[T.any(T::Hash[T.untyped, T.untyped], Numeric)]) }
+    attr_reader :data
+
+    # Initializes a new Series object.
+    #
+    # @param data [Array<T.any(Hash, Numeric)>] The input data, either an array of numbers or hashes
+    sig { params(data: T.any(T::Array[T.any(T::Hash[T.untyped, T.untyped], Numeric)], T::Hash[T.untyped, T.untyped], Numeric)).void }
+    def initialize(data)
+      @data = Array(data)
+    end
+
+    # Normalizes input data into an array of floats.
+    #
+    # @param field [Symbol, String] The field to extract from the hash data (default: :close)
+    # @return [Array<Float>] An array of floating point numbers extracted from the data
+    sig { params(field: T.any(Symbol, String)).returns(T::Array[Float]) }
+    def to_a(field: :close)
+      data.map do |v|
+        if v.is_a?(Numeric)
+          v.to_f
+        elsif v.is_a?(Hash)
+          (v[field] || v[field.to_sym] || v[field.to_s] || 0.0).to_f
+        else
+          0.0
+        end
+      end
+    end
+
+    # Normalizes input data into an array of OHLCV hashes.
+    #
+    # @return [Array<Hash{Symbol => Float}>] An array of hashes containing open, high, low, close, and volume
+    sig { returns(T::Array[T::Hash[Symbol, Float]]) }
+    def to_ohlc
+      data.map do |v|
+        if v.is_a?(Hash)
+          {
+            open: (v[:open] || v["open"] || 0.0).to_f,
+            high: (v[:high] || v["high"] || 0.0).to_f,
+            low: (v[:low] || v["low"] || 0.0).to_f,
+            close: (v[:close] || v["close"] || 0.0).to_f,
+            volume: (v[:volume] || v["volume"] || 0.0).to_f
+          }
+        elsif v.is_a?(Numeric)
+          {
+            open: v.to_f,
+            high: v.to_f,
+            low: v.to_f,
+            close: v.to_f,
+            volume: 0.0
+          }
+        else
+          { open: 0.0, high: 0.0, low: 0.0, close: 0.0, volume: 0.0 }
+        end
+      end
+    end
+
+    # Returns chronologically sorted data if it has date or time fields.
+    #
+    # @return [Array<T.any(Hash, Numeric)>] The sorted data
+    sig { returns(T::Array[T.any(T::Hash[T.untyped, T.untyped], Numeric)]) }
+    def sorted_data
+      return data unless data.first.is_a?(Hash) && (data.first[:date] || data.first["date"] || data.first[:date_time] || data.first["date_time"])
+
+      data.sort_by { |v| v[:date] || v["date"] || v[:date_time] || v["date_time"] }
+    end
+  end
+end

data/lib/indicator_hub/talib_adapter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module IndicatorHub
+  # Optional adapter for high-performance TA-Lib calculations
+  class TALibAdapter
+    def self.available?
+      @available ||= begin
+        require "talib_ffi"
+        true
+      rescue LoadError
+        false
+      end
+    end
+
+    def self.sma(_data, _period)
+      return nil unless available?
+
+      # Example: TALib.sma(data, period) - exact method depends on talib_ffi API
+      # For now, this is a placeholder to show where TA-Lib logic would go
+      nil
+    end
+  end
+end

data/lib/indicator_hub/validation.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+# typed: true
+
+require "sorbet-runtime"
+
+module IndicatorHub
+  # Robust validation for technical analysis data and options.
+  module Validation
+    extend T::Sig
+
+    # Error class for validation failures.
+    class Error < StandardError; end
+
+    # Validates that the provided options are within the allowed set.
+    # @param options [Hash] The options to validate.
+    # @param valid_options [Array<Symbol>] The list of allowed option keys.
+    # @raise [Validation::Error] if an invalid option is found.
+    sig { params(options: T::Hash[Symbol, T.untyped], valid_options: T::Array[Symbol]).void }
+    def self.validate_options(options, valid_options)
+      raise Error, "Options must be a hash." unless options.is_a?(Hash)
+
+      invalid_keys = options.keys - valid_options
+      return if invalid_keys.empty?
+
+      raise Error, "Invalid options: #{invalid_keys.join(", ")}. Valid options are: #{valid_options.join(", ")}"
+    end
+
+    # Validates that all data points in the numeric array are numbers.
+    # @param data [Array<Numeric>] The data to validate.
+    # @raise [Validation::Error] if non-numeric data is found.
+    sig { params(data: T::Array[T.untyped]).void }
+    def self.validate_numeric_data(data)
+      return if data.all?(Numeric)
+
+      raise Error, "Invalid Data. Input must be numeric."
+    end
+
+    # Validates that the data set meets the minimum required length.
+    # @param data [Array] The data to validate.
+    # @param required_size [Integer] The minimum length required.
+    # @raise [Validation::Error] if the data is too short.
+    sig { params(data: T::Array[T.untyped], required_size: Integer).void }
+    def self.validate_length(data, required_size)
+      return unless data.size < required_size
+
+      raise Error, "Not enough data. Expected at least #{required_size}, got #{data.size}."
+    end
+  end
+end

data/lib/indicator_hub/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module IndicatorHub
+  # The current version of the IndicatorHub gem.
+  VERSION = "0.1.0"
+end