sqa 0.0.24 → 0.0.31

data/lib/sqa/ensemble.rb

@@ -0,0 +1,359 @@
+# lib/sqa/ensemble.rb
+# frozen_string_literal: true
+
+module SQA
+  ##
+  # Ensemble - Combine multiple trading strategies
+  #
+  # Provides methods for:
+  # - Majority voting
+  # - Weighted voting based on past performance
+  # - Meta-learning (strategy selection)
+  # - Strategy rotation based on market conditions
+  # - Confidence-based aggregation
+  #
+  # @example Simple majority voting
+  #   ensemble = SQA::Ensemble.new(
+  #     strategies: [SQA::Strategy::RSI, SQA::Strategy::MACD, SQA::Strategy::Bollinger]
+  #   )
+  #   signal = ensemble.vote(vector)
+  #   # => :buy (if 2 out of 3 say :buy)
+  #
+  class Ensemble
+    attr_accessor :strategies, :weights, :performance_history
+
+    ##
+    # Initialize ensemble
+    #
+    # @param strategies [Array<Class>] Array of strategy classes
+    # @param voting_method [Symbol] :majority, :weighted, :unanimous, :confidence
+    # @param weights [Array<Float>] Optional weights for weighted voting
+    #
+    def initialize(strategies:, voting_method: :majority, weights: nil)
+      @strategies = strategies
+      @voting_method = voting_method
+      @weights = weights || Array.new(strategies.size, 1.0 / strategies.size)
+      @performance_history = Hash.new { |h, k| h[k] = [] }
+      @confidence_scores = Hash.new(0.5)
+    end
+
+    ##
+    # Generate ensemble signal
+    #
+    # @param vector [OpenStruct] Market data vector
+    # @return [Symbol] :buy, :sell, or :hold
+    #
+    def signal(vector)
+      case @voting_method
+      when :majority
+        majority_vote(vector)
+      when :weighted
+        weighted_vote(vector)
+      when :unanimous
+        unanimous_vote(vector)
+      when :confidence
+        confidence_vote(vector)
+      else
+        majority_vote(vector)
+      end
+    end
+
+    ##
+    # Majority voting
+    #
+    # @param vector [OpenStruct] Market data
+    # @return [Symbol] Signal with most votes
+    #
+    def majority_vote(vector)
+      votes = collect_votes(vector)
+
+      # Count votes
+      vote_counts = { buy: 0, sell: 0, hold: 0 }
+      votes.each { |v| vote_counts[v] += 1 }
+
+      # Return signal with most votes
+      vote_counts.max_by { |_signal, count| count }.first
+    end
+
+    ##
+    # Weighted voting based on strategy performance
+    #
+    # @param vector [OpenStruct] Market data
+    # @return [Symbol] Weighted signal
+    #
+    def weighted_vote(vector)
+      votes = collect_votes(vector)
+
+      # Weighted scores
+      scores = { buy: 0.0, sell: 0.0, hold: 0.0 }
+
+      votes.each_with_index do |vote, idx|
+        scores[vote] += @weights[idx]
+      end
+
+      # Return signal with highest weighted score
+      scores.max_by { |_signal, score| score }.first
+    end
+
+    ##
+    # Unanimous voting (all strategies must agree)
+    #
+    # @param vector [OpenStruct] Market data
+    # @return [Symbol] :buy/:sell only if unanimous, otherwise :hold
+    #
+    def unanimous_vote(vector)
+      votes = collect_votes(vector)
+
+      # All must agree
+      if votes.all? { |v| v == :buy }
+        :buy
+      elsif votes.all? { |v| v == :sell }
+        :sell
+      else
+        :hold
+      end
+    end
+
+    ##
+    # Confidence-based voting
+    #
+    # Weight votes by strategy confidence scores.
+    #
+    # @param vector [OpenStruct] Market data
+    # @return [Symbol] Signal weighted by confidence
+    #
+    def confidence_vote(vector)
+      votes = collect_votes(vector)
+
+      scores = { buy: 0.0, sell: 0.0, hold: 0.0 }
+
+      votes.each_with_index do |vote, idx|
+        strategy_class = @strategies[idx]
+        confidence = @confidence_scores[strategy_class] || 0.5
+        scores[vote] += confidence
+      end
+
+      scores.max_by { |_signal, score| score }.first
+    end
+
+    ##
+    # Update strategy weights based on performance
+    #
+    # Adjust weights to favor better-performing strategies.
+    #
+    # @param strategy_index [Integer] Index of strategy
+    # @param performance [Float] Performance metric (e.g., return)
+    #
+    def update_weight(strategy_index, performance)
+      @performance_history[@strategies[strategy_index]] << performance
+
+      # Recalculate weights based on recent performance
+      recalculate_weights
+    end
+
+    ##
+    # Update confidence score for strategy
+    #
+    # @param strategy_class [Class] Strategy class
+    # @param correct [Boolean] Was the prediction correct?
+    #
+    def update_confidence(strategy_class, correct)
+      current = @confidence_scores[strategy_class]
+
+      # Exponential moving average of correctness
+      alpha = 0.1
+      @confidence_scores[strategy_class] = if correct
+                                             current + alpha * (1.0 - current)
+                                           else
+                                             current - alpha * current
+                                           end
+    end
+
+    ##
+    # Select best strategy for current market conditions
+    #
+    # Meta-learning approach: choose the strategy most likely to succeed.
+    #
+    # @param market_regime [Symbol] Current market regime (:bull, :bear, :sideways)
+    # @param volatility [Symbol] Volatility regime (:low, :medium, :high)
+    # @return [Class] Best strategy class for conditions
+    #
+    def select_strategy(market_regime:, volatility: :medium)
+      # Strategy performance by market condition
+      # This could be learned from historical data
+      strategy_preferences = {
+        bull: {
+          low: SQA::Strategy::EMA,
+          medium: SQA::Strategy::MACD,
+          high: SQA::Strategy::Bollinger
+        },
+        bear: {
+          low: SQA::Strategy::RSI,
+          medium: SQA::Strategy::RSI,
+          high: SQA::Strategy::Bollinger
+        },
+        sideways: {
+          low: SQA::Strategy::MR,
+          medium: SQA::Strategy::MR,
+          high: SQA::Strategy::Bollinger
+        }
+      }
+
+      # Return preferred strategy or fall back to best performer
+      strategy_preferences.dig(market_regime, volatility) ||
+        best_performing_strategy
+    end
+
+    ##
+    # Rotate strategies based on market conditions
+    #
+    # @param stock [SQA::Stock] Stock object
+    # @return [Class] Strategy to use
+    #
+    def rotate(stock)
+      regime_data = SQA::MarketRegime.detect(stock)
+
+      select_strategy(
+        market_regime: regime_data[:type],
+        volatility: regime_data[:volatility]
+      )
+    end
+
+    ##
+    # Get ensemble statistics
+    #
+    # @return [Hash] Performance statistics
+    #
+    def statistics
+      {
+        num_strategies: @strategies.size,
+        weights: @weights,
+        confidence_scores: @confidence_scores,
+        best_strategy: best_performing_strategy,
+        worst_strategy: worst_performing_strategy,
+        performance_history: @performance_history
+      }
+    end
+
+    ##
+    # Backtest ensemble vs individual strategies
+    #
+    # @param stock [SQA::Stock] Stock to backtest
+    # @param initial_capital [Float] Starting capital
+    # @return [Hash] Comparison results
+    #
+    def backtest_comparison(stock, initial_capital: 10_000)
+      results = {}
+
+      # Backtest ensemble
+      ensemble_backtest = SQA::Backtest.new(
+        stock: stock,
+        strategy: self,
+        initial_capital: initial_capital
+      )
+      results[:ensemble] = ensemble_backtest.run
+
+      # Backtest each individual strategy
+      @strategies.each do |strategy_class|
+        individual_backtest = SQA::Backtest.new(
+          stock: stock,
+          strategy: strategy_class,
+          initial_capital: initial_capital
+        )
+        results[strategy_class.name] = individual_backtest.run
+      end
+
+      results
+    end
+
+    ##
+    # Make ensemble compatible with Backtest (acts like a strategy)
+    #
+    # @param vector [OpenStruct] Market data
+    # @return [Symbol] Trading signal
+    #
+    def self.trade(vector)
+      # This won't work for class method, use instance instead
+      raise NotImplementedError, "Use ensemble instance, not class"
+    end
+
+    ##
+    # Instance method for compatibility
+    #
+    def trade(vector)
+      signal(vector)
+    end
+
+    private
+
+    ##
+    # Collect votes from all strategies
+    #
+    def collect_votes(vector)
+      @strategies.map do |strategy_class|
+        begin
+          strategy_class.trade(vector)
+        rescue StandardError => e
+          # If strategy fails, default to :hold
+          :hold
+        end
+      end
+    end
+
+    ##
+    # Recalculate weights based on performance history
+    #
+    def recalculate_weights
+      # Use recent performance (last 10 trades)
+      recent_performance = @strategies.map do |strategy_class|
+        history = @performance_history[strategy_class]
+        recent = history.last(10)
+        recent.empty? ? 0.0 : recent.sum / recent.size.to_f
+      end
+
+      # Convert to positive values (shift if negative)
+      min_perf = recent_performance.min
+      if min_perf < 0
+        recent_performance = recent_performance.map { |p| p - min_perf + 0.01 }
+      end
+
+      # Normalize to sum to 1.0
+      total = recent_performance.sum
+      @weights = if total.zero?
+                   Array.new(@strategies.size, 1.0 / @strategies.size)
+                 else
+                   recent_performance.map { |p| p / total }
+                 end
+    end
+
+    ##
+    # Find best performing strategy
+    #
+    def best_performing_strategy
+      return @strategies.first if @performance_history.empty?
+
+      avg_performance = @strategies.map do |strategy_class|
+        history = @performance_history[strategy_class]
+        avg = history.empty? ? 0.0 : history.sum / history.size.to_f
+        [strategy_class, avg]
+      end
+
+      avg_performance.max_by { |_strategy, avg| avg }&.first || @strategies.first
+    end
+
+    ##
+    # Find worst performing strategy
+    #
+    def worst_performing_strategy
+      return @strategies.first if @performance_history.empty?
+
+      avg_performance = @strategies.map do |strategy_class|
+        history = @performance_history[strategy_class]
+        avg = history.empty? ? 0.0 : history.sum / history.size.to_f
+        [strategy_class, avg]
+      end
+
+      avg_performance.min_by { |_strategy, avg| avg }&.first || @strategies.first
+    end
+  end
+end

data/lib/sqa/fpop.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+# SQA::FPOP - Future Period of Performance Analysis
+#
+# This module provides utilities for analyzing potential future price movements
+# from any given point in a price series. It calculates the range of possible
+# outcomes (min/max deltas) during a future period, along with risk metrics
+# and directional classification.
+#
+# Key Concepts:
+# - FPL (Future Period Loss/Profit): Min and max percentage change during fpop
+# - Risk: Volatility range (max_delta - min_delta)
+# - Direction: Classification of movement (UP/DOWN/UNCERTAIN/FLAT)
+# - Magnitude: Average expected movement
+#
+# Example:
+#   prices = [100, 102, 98, 105, 110, 115, 120]
+#
+#   # Get raw FPL data
+#   fpl_data = SQA::FPOP.fpl(prices, fpop: 3)
+#   # => [[-2.0, 10.0], [-4.9, 17.6], ...]
+#
+#   # Get detailed analysis
+#   analysis = SQA::FPOP.fpl_analysis(prices, fpop: 3)
+#   # => [{min_delta: -2.0, max_delta: 10.0, risk: 12.0, direction: :UNCERTAIN, ...}, ...]
+
+module SQA
+  module FPOP
+    class << self
+      # Calculate Future Period Loss/Profit for each point in price series
+      #
+      # For each price point, looks ahead fpop periods and calculates:
+      # - Minimum percentage change (worst loss)
+      # - Maximum percentage change (best gain)
+      #
+      # @param price [Array<Numeric>] Array of prices
+      # @param fpop [Integer] Future Period of Performance (days to look ahead)
+      # @return [Array<Array<Float, Float>>] Array of [min_delta, max_delta] pairs
+      #
+      # @example
+      #   SQA::FPOP.fpl([100, 105, 95, 110], fpop: 2)
+      #   # => [[-5.0, 5.0], [-9.52, 4.76], [15.79, 15.79]]
+      #
+      def fpl(price, fpop: 14)
+        validate_fpl_inputs(price, fpop)
+
+        price_floats = price.map(&:to_f)
+        result = []
+
+        price_floats.each_with_index do |current_price, index|
+          future_prices = price_floats[(index + 1)..(index + fpop)]
+          break if future_prices.nil? || future_prices.empty?
+
+          deltas = future_prices.map { |p| ((p - current_price) / current_price) * 100.0 }
+          result << [deltas.min, deltas.max]
+        end
+
+        result
+      end
+
+      # Perform comprehensive FPL analysis with risk metrics and classification
+      #
+      # @param price [Array<Numeric>] Array of prices
+      # @param fpop [Integer] Future Period of Performance
+      # @return [Array<Hash>] Array of analysis hashes containing:
+      #   - :min_delta - Worst percentage loss during fpop
+      #   - :max_delta - Best percentage gain during fpop
+      #   - :risk - Volatility range (max - min)
+      #   - :direction - Movement classification (:UP, :DOWN, :UNCERTAIN, :FLAT)
+      #   - :magnitude - Average expected movement
+      #   - :interpretation - Human-readable summary
+      #
+      # @example
+      #   analysis = SQA::FPOP.fpl_analysis([100, 110, 120], fpop: 2)
+      #   analysis.first
+      #   # => {
+      #   #   min_delta: 10.0,
+      #   #   max_delta: 20.0,
+      #   #   risk: 10.0,
+      #   #   direction: :UP,
+      #   #   magnitude: 15.0,
+      #   #   interpretation: "UP: 15.0% (±5.0% risk)"
+      #   # }
+      #
+      def fpl_analysis(price, fpop: 14)
+        validate_fpl_inputs(price, fpop)
+
+        fpl_results = fpl(price, fpop: fpop)
+
+        fpl_results.map do |min_delta, max_delta|
+          {
+            min_delta: min_delta,
+            max_delta: max_delta,
+            risk: (max_delta - min_delta).abs,
+            direction: determine_direction(min_delta, max_delta),
+            magnitude: calculate_magnitude(min_delta, max_delta),
+            interpretation: build_interpretation(min_delta, max_delta)
+          }
+        end
+      end
+
+      # Determine directional bias from min/max deltas
+      #
+      # @param min_delta [Float] Minimum percentage change
+      # @param max_delta [Float] Maximum percentage change
+      # @return [Symbol] :UP, :DOWN, :UNCERTAIN, or :FLAT
+      #
+      def determine_direction(min_delta, max_delta)
+        if min_delta > 0 && max_delta > 0
+          :UP
+        elsif min_delta < 0 && max_delta < 0
+          :DOWN
+        elsif min_delta < 0 && max_delta > 0
+          :UNCERTAIN
+        else
+          :FLAT
+        end
+      end
+
+      # Calculate average expected movement (magnitude)
+      #
+      # @param min_delta [Float] Minimum percentage change
+      # @param max_delta [Float] Maximum percentage change
+      # @return [Float] Average of min and max deltas
+      #
+      def calculate_magnitude(min_delta, max_delta)
+        (min_delta + max_delta) / 2.0
+      end
+
+      # Build human-readable interpretation string
+      #
+      # @param min_delta [Float] Minimum percentage change
+      # @param max_delta [Float] Maximum percentage change
+      # @return [String] Formatted interpretation
+      #
+      def build_interpretation(min_delta, max_delta)
+        direction = determine_direction(min_delta, max_delta)
+        magnitude = calculate_magnitude(min_delta, max_delta)
+        risk = (max_delta - min_delta).abs
+
+        "#{direction}: #{magnitude.round(2)}% (±#{(risk / 2).round(2)}% risk)"
+      end
+
+      # Filter FPL analysis results by criteria
+      #
+      # Useful for finding high-quality trading opportunities
+      #
+      # @param analysis [Array<Hash>] FPL analysis results
+      # @param min_magnitude [Float] Minimum average movement (default: nil)
+      # @param max_risk [Float] Maximum acceptable risk (default: nil)
+      # @param directions [Array<Symbol>] Acceptable directions (default: [:UP, :DOWN, :UNCERTAIN, :FLAT])
+      # @return [Array<Integer>] Indices of points that meet criteria
+      #
+      # @example Find low-risk bullish opportunities
+      #   analysis = SQA::FPOP.fpl_analysis(prices, fpop: 10)
+      #   indices = SQA::FPOP.filter_by_quality(
+      #     analysis,
+      #     min_magnitude: 5.0,
+      #     max_risk: 10.0,
+      #     directions: [:UP]
+      #   )
+      #
+      def filter_by_quality(analysis, min_magnitude: nil, max_risk: nil, directions: [:UP, :DOWN, :UNCERTAIN, :FLAT])
+        indices = []
+
+        analysis.each_with_index do |result, idx|
+          next if min_magnitude && result[:magnitude] < min_magnitude
+          next if max_risk && result[:risk] > max_risk
+          next unless directions.include?(result[:direction])
+
+          indices << idx
+        end
+
+        indices
+      end
+
+      # Calculate risk-reward ratio for each analysis point
+      #
+      # @param analysis [Array<Hash>] FPL analysis results
+      # @return [Array<Float>] Risk-reward ratios (magnitude / risk)
+      #
+      def risk_reward_ratios(analysis)
+        analysis.map do |result|
+          result[:risk] > 0 ? result[:magnitude].abs / result[:risk] : 0.0
+        end
+      end
+
+      private
+
+      # Validate FPL input parameters
+      def validate_fpl_inputs(price, fpop)
+        raise ArgumentError, "price must be an Array" unless price.is_a?(Array)
+        raise ArgumentError, "price cannot be empty" if price.empty?
+        raise ArgumentError, "fpop must be a positive integer" unless fpop.is_a?(Integer) && fpop > 0
+        raise ArgumentError, "prices must not contain zero or negative values" if price.any? { |p| p <= 0 }
+      end
+    end
+  end
+end