indicator_hub 0.1.0

data/lib/indicator_hub/calculation_helpers.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+# typed: true
+
+require "sorbet-runtime"
+
+module IndicatorHub
+  # Calculation helpers for technical analysis math.
+  # Provides common mathematical functions used in various indicator calculations.
+  module CalculationHelpers
+    extend T::Sig
+
+    # Sums up the given numerical data.
+    # @param data [Array<Numeric>] The input data array.
+    # @return [Float] The sum of all elements.
+    sig { params(data: T::Array[Numeric]).returns(Float) }
+    def self.sum(data)
+      data.sum(0.0)
+    end
+
+    # Calculates the arithmetic mean (average) of the data.
+    # @param data [Array<Numeric>] The input data array.
+    # @return [Float] The average of the elements.
+    sig { params(data: T::Array[Numeric]).returns(Float) }
+    def self.average(data)
+      return 0.0 if data.empty?
+
+      sum(data) / data.size.to_f
+    end
+
+    # @see average
+    sig { params(data: T::Array[Numeric]).returns(Float) }
+    def self.mean(data)
+      average(data)
+    end
+
+    # Calculates the sample variance of the data.
+    # @param data [Array<Numeric>] The input data array.
+    # @return [Float] The sample variance.
+    sig { params(data: T::Array[Numeric]).returns(Float) }
+    def self.sample_variance(data)
+      return 0.0 if data.size <= 1
+
+      m = mean(data)
+      sum_sq_diff = data.inject(0.0) { |accum, i| accum + ((i - m)**2) }
+      sum_sq_diff / (data.size - 1).to_f
+    end
+
+    # Calculates the standard deviation of the data.
+    # @param data [Array<Numeric>] The input data array.
+    # @return [Float] The standard deviation.
+    sig { params(data: T::Array[Numeric]).returns(Float) }
+    def self.standard_deviation(data)
+      Math.sqrt(sample_variance(data))
+    end
+
+    # Calculates the mean absolute deviation (MAD) of the data.
+    # @param data [Array<Numeric>] The input data array.
+    # @param mean [Float] The mean of the data.
+    # @return [Float] The MAD of the elements.
+    sig { params(data: T::Array[Numeric], mean: Float).returns(Float) }
+    def self.mean_absolute_deviation(data, mean)
+      return 0.0 if data.empty?
+
+      sum_abs_diff = data.inject(0.0) { |accum, i| accum + (i - mean).abs }
+      sum_abs_diff / data.size.to_f
+    end
+
+    # Wilder's Smoothing for RSI.
+    # @param prev_avg [Numeric] The previous average.
+    # @param current [Numeric] The current value.
+    # @param period [Integer] The smoothing period.
+    # @return [Float] The smoothed value.
+    sig { params(prev_avg: Numeric, current: Numeric, period: Integer).returns(Float) }
+    def self.wilder_smoothing(prev_avg, current, period)
+      ((prev_avg.to_f * (period - 1)) + current.to_f) / period.to_f
+    end
+
+    # Calculates the True Range (TR).
+    # @param current_high [Numeric] The high price of the current period.
+    # @param current_low [Numeric] The low price of the current period.
+    # @param previous_close [Numeric] The close price of the previous period.
+    # @return [Float] The calculated True Range.
+    sig { params(current_high: Numeric, current_low: Numeric, previous_close: Numeric).returns(Float) }
+    def self.true_range(current_high, current_low, previous_close)
+      [
+        (current_high.to_f - current_low.to_f),
+        (current_high.to_f - previous_close.to_f).abs,
+        (current_low.to_f - previous_close.to_f).abs
+      ].max.to_f
+    end
+
+    # Calculates the Typical Price.
+    # @param high [Numeric] The high price.
+    # @param low [Numeric] The low price.
+    # @param close [Numeric] The close price.
+    # @return [Float] (high + low + close) / 3.0
+    sig { params(high: Numeric, low: Numeric, close: Numeric).returns(Float) }
+    def self.typical_price(high, low, close)
+      (high.to_f + low.to_f + close.to_f) / 3.0
+    end
+
+    # Calculates the Exponential Moving Average (EMA).
+    # @param current_value [Numeric] The current data point.
+    # @param data [Array<Numeric>] Historical data (used for seed calculation).
+    # @param period [Integer] The EMA period.
+    # @param prev_value [Numeric, nil] The previous EMA value.
+    # @return [Float] The calculated EMA value.
+    sig { params(current_value: Numeric, data: T::Array[Numeric], period: Integer, prev_value: T.nilable(Numeric)).returns(Float) }
+    def self.ema(current_value, data, period, prev_value)
+      if prev_value.nil?
+        average(data)
+      else
+        ((current_value.to_f - prev_value.to_f) * (2.0 / (period + 1.0))) + prev_value.to_f
+      end
+    end
+
+    # Calculates the Weighted Moving Average (WMA) of the data.
+    # @param data [Array<Numeric>] The input data array.
+    # @return [Float] The WMA of the data.
+    sig { params(data: T::Array[Numeric]).returns(Float) }
+    def self.wma(data)
+      return 0.0 if data.empty?
+
+      divisor = (data.size * (data.size + 1) / 2.0)
+      sum = 0.0
+      data.each_with_index do |v, i|
+        sum += v.to_f * (i + 1) / divisor
+      end
+      sum
+    end
+
+    # Calculates the maximum value in a sliding window.
+    # @param data [Array<Numeric>] The input data array.
+    # @param period [Integer] The window period.
+    # @return [Array<Float, nil>]
+    sig { params(data: T::Array[Numeric], period: Integer).returns(T::Array[T.nilable(Float)]) }
+    def self.max(data, period)
+      output = []
+      window = []
+      data.each do |v|
+        window << v.to_f
+        if window.size == period
+          output << window.max
+          window.shift
+        else
+          output << nil
+        end
+      end
+      output
+    end
+
+    # Calculates the minimum value in a sliding window.
+    # @param data [Array<Numeric>] The input data array.
+    # @param period [Integer] The window period.
+    # @return [Array<Float, nil>]
+    sig { params(data: T::Array[Numeric], period: Integer).returns(T::Array[T.nilable(Float)]) }
+    def self.min(data, period)
+      output = []
+      window = []
+      data.each do |v|
+        window << v.to_f
+        if window.size == period
+          output << window.min
+          window.shift
+        else
+          output << nil
+        end
+      end
+      output
+    end
+
+    # Simple Moving Average for numeric arrays.
+    # @param data [Array<Numeric, nil>] The input data array.
+    # @param period [Integer] The window period.
+    # @return [Array<Float, nil>]
+    sig { params(data: T::Array[T.nilable(Numeric)], period: Integer).returns(T::Array[T.nilable(Float)]) }
+    def self.sma(data, period)
+      output = []
+      window = []
+      data.each do |v|
+        if v.nil?
+          output << nil
+          next
+        end
+        window << v.to_f
+        if window.size == period
+          output << average(window)
+          window.shift
+        else
+          output << nil
+        end
+      end
+      output
+    end
+  end
+end

data/lib/indicator_hub/indicators/adi.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "../calculation_helpers"
+
+module IndicatorHub
+  module Indicators
+    # Accumulation/Distribution Index (ADI).
+    # ADI uses volume and price to assess whether a stock is being accumulated or distributed.
+    class ADI
+      # Calculates the Accumulation/Distribution Index.
+      # @param data [Array<Hash>] Array of OHLCV hashes.
+      # @return [Array<Float, nil>] The calculated ADI values.
+      def self.calculate(data)
+        ad = 0.0
+        output = []
+
+        data.each do |values|
+          high = values[:high]
+          low = values[:low]
+          close = values[:close]
+          volume = values[:volume]
+
+          clv = if high == low
+                  0.0
+                else
+                  ((close - low) - (high - close)) / (high - low).to_f
+                end
+
+          ad += (clv * volume)
+          output << ad
+        end
+
+        output
+      end
+    end
+  end
+end

data/lib/indicator_hub/indicators/adtv.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../calculation_helpers"
+
+module IndicatorHub
+  module Indicators
+    # Average Daily Trading Volume (ADTV).
+    # ADTV is the average number of shares traded within a day in a given stock.
+    class ADTV
+      # Calculates the Average Daily Trading Volume.
+      # @param data [Array<Hash>] Array of OHLCV hashes.
+      # @param period [Integer] The period for calculating the average (default: 20).
+      # @return [Array<Float, nil>] The calculated ADTV values.
+      def self.calculate(data, period: 20)
+        output = []
+        volumes = data.map { |v| v[:volume] }
+
+        (period - 1).upto(volumes.size - 1) do |i|
+          window = volumes[(i - period + 1)..i]
+          output << CalculationHelpers.average(window)
+        end
+
+        Array.new(data.size - output.size, nil) + output
+      end
+    end
+  end
+end

data/lib/indicator_hub/indicators/adx.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "../calculation_helpers"
+
+module IndicatorHub
+  module Indicators
+    # Average Directional Index (ADX).
+    # ADX is used to quantify trend strength. It is calculated based on the
+    # moving average of price range expansion over a given period of time.
+    class ADX
+      # Calculates the Average Directional Index.
+      # @param data [Array<Hash>] Array of OHLCV hashes.
+      # @param period [Integer] The period for ADX calculation (default: 14).
+      # @return [Array<Float, nil>] The calculated ADX values.
+      def self.calculate(data, period: 14)
+        output = []
+        plus_dm = []
+        minus_dm = []
+        tr = []
+
+        data.each_with_index do |val, i|
+          if i.zero?
+            plus_dm << 0.0
+            minus_dm << 0.0
+            tr << (val[:high] - val[:low])
+            next
+          end
+
+          prev = data[i - 1]
+          high_diff = val[:high] - prev[:high]
+          low_diff = prev[:low] - val[:low]
+
+          plus_dm << if high_diff > low_diff && high_diff.positive?
+                       high_diff
+                     else
+                       0.0
+                     end
+
+          minus_dm << if low_diff > high_diff && low_diff.positive?
+                        low_diff
+                      else
+                        0.0
+                      end
+
+          tr << CalculationHelpers.true_range(val[:high], val[:low], prev[:close])
+        end
+
+        smoothed_plus_dm = smooth(plus_dm, period)
+        smoothed_minus_dm = smooth(minus_dm, period)
+        smoothed_tr = smooth(tr, period)
+
+        dx_values = []
+        smoothed_plus_dm.each_with_index do |s_plus, i|
+          s_minus = smoothed_minus_dm[i]
+          s_tr = smoothed_tr[i]
+
+          plus_di = 100.0 * (s_plus / s_tr)
+          minus_di = 100.0 * (s_minus / s_tr)
+
+          dx = 100.0 * (plus_di - minus_di).abs / (plus_di + minus_di)
+          dx_values << dx
+        end
+
+        # ADX is SMA of DX for the first period, then smoothed
+        adx = 0.0
+        dx_values.each_with_index do |dx, i|
+          if i < period - 1
+            output << nil
+          elsif i == period - 1
+            adx = CalculationHelpers.average(dx_values[0..i])
+            output << adx
+          else
+            adx = ((adx * (period - 1)) + dx) / period.to_f
+            output << adx
+          end
+        end
+
+        # Prepend nil for the initial period where TR/DM are being calculated
+        Array.new(period - 1, nil) + output
+      end
+
+      def self.smooth(data, period)
+        smoothed = []
+        current_sum = 0.0
+
+        data.each_with_index do |val, i|
+          if i < period - 1
+            current_sum += val
+          elsif i == period - 1
+            current_sum += val
+            smoothed << current_sum
+          else
+            prev_smoothed = smoothed.last
+            new_smoothed = prev_smoothed - (prev_smoothed / period.to_f) + val
+            smoothed << new_smoothed
+          end
+        end
+        smoothed
+      end
+    end
+  end
+end

data/lib/indicator_hub/indicators/ao.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "../calculation_helpers"
+
+module IndicatorHub
+  module Indicators
+    # Awesome Oscillator (AO).
+    # AO is used to measure market momentum. It calculates the difference
+    # between a 34-period and 5-period Simple Moving Average of the bar's midpoints.
+    class AO
+      # Calculates the Awesome Oscillator.
+      # @param data [Array<Hash>] Array of OHLCV hashes.
+      # @param short_period [Integer] The short SMA period (default: 5).
+      # @param long_period [Integer] The long SMA period (default: 34).
+      # @return [Array<Float, nil>] The calculated AO values.
+      def self.calculate(data, short_period: 5, long_period: 34)
+        midpoints = data.map { |v| (v[:high] + v[:low]) / 2.0 }
+        output = []
+
+        midpoints.each_with_index do |_, i|
+          if i < long_period - 1
+            output << nil
+            next
+          end
+
+          short_window = midpoints[(i - short_period + 1)..i]
+          long_window = midpoints[(i - long_period + 1)..i]
+
+          short_sma = CalculationHelpers.average(short_window)
+          long_sma = CalculationHelpers.average(long_window)
+
+          output << (short_sma - long_sma)
+        end
+
+        output
+      end
+    end
+  end
+end

data/lib/indicator_hub/indicators/atr.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../calculation_helpers"
+
+module IndicatorHub
+  module Indicators
+    # Average True Range (ATR).
+    # ATR is a volatility indicator that shows how much an asset moves, on average, during a given time frame.
+    class ATR
+      # Calculates the Average True Range.
+      # @param data [Array<Hash>] Array of OHLCV hashes.
+      # @param period [Integer] The period for ATR (default: 14).
+      # @return [Array<Float, nil>] The calculated ATR values.
+      def self.calculate(data, period: 14)
+        output = []
+        tr_values = []
+        prev_close = nil
+        current_atr = nil
+
+        data.each_with_index do |v, i|
+          tr = if i.zero?
+                 v[:high] - v[:low]
+               else
+                 CalculationHelpers.true_range(v[:high], v[:low], prev_close)
+               end
+
+          tr_values << tr
+          prev_close = v[:close]
+
+          if tr_values.size < period
+            output << nil
+          elsif tr_values.size == period
+            current_atr = CalculationHelpers.average(tr_values)
+            output << current_atr
+          else
+            current_atr = CalculationHelpers.wilder_smoothing(current_atr, tr, period)
+            output << current_atr
+          end
+        end
+
+        output
+      end
+    end
+  end
+end

data/lib/indicator_hub/indicators/base_indicator.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "../validation"
+require_relative "../series"
+require_relative "../calculation_helpers"
+
+module IndicatorHub
+  module Indicators
+    # Abstract base class for all technical analysis indicators.
+    # Implements common initialization, data normalization, and validation logic.
+    class BaseIndicator
+      # @return [Series] The normalized series data.
+      attr_reader :data
+      # @return [Hash] The configuration options for the indicator.
+      attr_reader :options
+
+      # Initializes a new indicator instance.
+      # @param data [Array, Series] The input data series.
+      # @param options [Hash] Configuration options (e.g., period, field).
+      def initialize(data, options = {})
+        @data = data.is_a?(Series) ? data : Series.new(data)
+        @options = options
+        validate!
+      end
+
+      # Abstract method to be implemented by concrete indicator classes.
+      # @raise [NotImplementedError] if not overridden.
+      def calculate
+        raise NotImplementedError, "#{self.class} must implement #calculate"
+      end
+
+      # Returns the data normalized as a simple numeric array.
+      # @return [Array<Float>]
+      def numeric_data
+        data.to_a(field: options[:field] || :close)
+      end
+
+      # Returns the data normalized as an OHLCV hash array.
+      # @return [Array<Hash>]
+      def ohlc_data
+        data.to_ohlc
+      end
+
+      # Defines the list of valid option keys for this indicator.
+      # @return [Array<Symbol>]
+      def self.valid_options
+        [:field]
+      end
+
+      # Defines the minimum number of data points required for calculation.
+      # @param options [Hash] The current indicator options.
+      # @return [Integer]
+      def self.min_data_size(_options)
+        1
+      end
+
+      private
+
+      # Validates options, numeric integrity, and minimum data length.
+      # @raise [Validation::Error] if validation fails.
+      def validate!
+        Validation.validate_options(options, self.class.valid_options)
+        Validation.validate_numeric_data(numeric_data)
+        Validation.validate_length(numeric_data, self.class.min_data_size(options))
+      end
+    end
+  end
+end

data/lib/indicator_hub/indicators/bb.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "../calculation_helpers"
+
+module IndicatorHub
+  module Indicators
+    # Bollinger Bands (BB).
+    # Bollinger Bands are a type of statistical chart characterizing the prices
+    # and volatility over time of a financial instrument or commodity.
+    class BB
+      # Calculates the Bollinger Bands.
+      # @param data [Array<Numeric>] The input data points.
+      # @param period [Integer] The SMA period for the middle band (default: 20).
+      # @param standard_deviations [Numeric] The number of standard deviations for the bands (default: 2).
+      # @return [Array<Hash, nil>] The calculated Bollinger Bands (upper, middle, lower).
+      def self.calculate(data, period: 20, standard_deviations: 2)
+        return [] if data.size < period
+
+        period_values = []
+        output = []
+
+        data.each do |v|
+          period_values << v
+          if period_values.size == period
+            mb = CalculationHelpers.average(period_values)
+            sd = CalculationHelpers.standard_deviation(period_values)
+            ub = mb + (standard_deviations * sd)
+            lb = mb - (standard_deviations * sd)
+
+            output << {
+              upper: ub,
+              middle: mb,
+              lower: lb
+            }
+            period_values.shift
+          else
+            output << nil
+          end
+        end
+        output
+      end
+    end
+  end
+end

data/lib/indicator_hub/indicators/cci.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "../calculation_helpers"
+
+module IndicatorHub
+  module Indicators
+    # Commodity Channel Index (CCI).
+    # CCI measures the current price level relative to an average price level over a given period of time.
+    class CCI
+      # Calculates the Commodity Channel Index.
+      # @param data [Array<Hash>] Array of OHLCV hashes.
+      # @param period [Integer] The period for CCI (default: 20).
+      # @param constant [Float] The constant used for scaling (default: 0.015).
+      # @return [Array<Float, nil>] The calculated CCI values.
+      def self.calculate(data, period: 20, constant: 0.015)
+        tp_values = data.map { |v| (v[:high] + v[:low] + v[:close]) / 3.0 }
+        output = []
+
+        tp_values.each_with_index do |tp, i|
+          if i < period - 1
+            output << nil
+            next
+          end
+
+          window = tp_values[(i - period + 1)..i]
+          sma = CalculationHelpers.average(window)
+          mad = CalculationHelpers.mean_absolute_deviation(window, sma)
+
+          if mad.zero?
+            output << 0.0
+          else
+            cci = (tp - sma) / (constant * mad)
+            output << cci
+          end
+        end
+
+        output
+      end
+    end
+  end
+end

data/lib/indicator_hub/indicators/cmf.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "../calculation_helpers"
+
+module IndicatorHub
+  module Indicators
+    # Chaikin Money Flow (CMF).
+    # CMF measures the amount of Money Flow Volume over a specific period.
+    class CMF
+      # Calculates the Chaikin Money Flow.
+      # @param data [Array<Hash>] Array of OHLCV hashes.
+      # @param period [Integer] The period for CMF (default: 20).
+      # @return [Array<Float, nil>] The calculated CMF values.
+      def self.calculate(data, period: 20)
+        period = period.to_i
+        return Array.new(data.size, nil) if data.size < period
+
+        output = []
+        period_volumes = []
+        period_mf_volumes = []
+
+        data.each do |v|
+          high = v[:high]
+          low = v[:low]
+          close = v[:close]
+          volume = v[:volume]
+
+          multiplier = if high == low
+                         0.0
+                       else
+                         ((close - low) - (high - close)) / (high - low).to_f
+                       end
+          mf_volume = multiplier * volume
+
+          period_volumes << volume
+          period_mf_volumes << mf_volume
+
+          if period_volumes.size == period
+            volume_sum = CalculationHelpers.sum(period_volumes)
+            mf_volume_sum = CalculationHelpers.sum(period_mf_volumes)
+
+            output << (volume_sum.zero? ? 0.0 : mf_volume_sum / volume_sum.to_f)
+
+            period_volumes.shift
+            period_mf_volumes.shift
+          else
+            output << nil
+          end
+        end
+        output
+      end
+    end
+  end
+end