sqa 0.0.24 → 0.0.31

data/docs/advanced/fpop.md

@@ -0,0 +1,153 @@
+# FPOP - Future Period of Performance
+
+## Overview
+
+Calculate future returns, risk metrics, and direction classification to evaluate trading opportunities.
+
+## Quick Start
+
+```ruby
+require 'sqa'
+
+stock = SQA::Stock.new(ticker: 'AAPL')
+prices = stock.df["adj_close_price"].to_a
+
+# Calculate FPL (Future Period Loss/Profit)
+fpl_data = SQA::FPOP.fpl(prices, fpop: 10)
+# => [[min_delta, max_delta], ...]
+
+# Comprehensive analysis
+analysis = SQA::FPOP.fpl_analysis(prices, fpop: 10)
+puts "Risk: #{analysis[:risk]}%"
+puts "Direction: #{analysis[:direction]}"  # :UP, :DOWN, :FLAT
+```
+
+## Methods
+
+### Basic FPL Calculation
+
+```ruby
+prices = [100, 102, 105, 103, 107, 110]
+fpl = SQA::FPOP.fpl(prices, fpop: 3)
+
+# For each point, calculates min/max change over next 3 periods
+# fpl[0] = [min(102,105,103) - 100, max(102,105,103) - 100]
+#        = [100-100, 105-100] = [0, 5]
+```
+
+### Comprehensive Analysis
+
+```ruby
+analysis = SQA::FPOP.fpl_analysis(prices, fpop: 10)
+
+# Returns hash with:
+# {
+#   fpl: [[min_delta, max_delta], ...],
+#   risk: 15.5,              # Max downside %
+#   reward: 25.2,            # Max upside %
+#   direction: :UP,          # Overall trend
+#   magnitude: 10.3,         # Average move size
+#   quality_score: 0.75      # Risk/reward ratio
+# }
+```
+
+### Quality Filtering
+
+```ruby
+filtered = SQA::FPOP.filter_by_quality(
+  analysis,
+  min_magnitude: 5.0,      # Minimum 5% move
+  max_risk: 25.0,          # Maximum 25% downside
+  directions: [:UP]         # Only upward moves
+)
+
+# Returns only high-quality opportunities
+```
+
+## Integration with Strategy Generator
+
+```ruby
+generator = SQA::StrategyGenerator.new(
+  stock: stock,
+  min_gain_percent: 10.0,
+  fpop: 10,                  # Use 10-period lookahead
+  max_fpl_risk: 20.0         # Filter by max acceptable risk
+)
+
+patterns = generator.discover_patterns
+# Only includes patterns with acceptable risk/reward
+```
+
+## DataFrame Methods
+
+```ruby
+# Convenient DataFrame extensions
+df = stock.df
+
+# Add FPL columns
+df_with_fpl = df.fpl(fpop: 10)
+
+# Add full analysis
+df_with_analysis = df.fpl_analysis(fpop: 10)
+
+# Now has columns: fpl_min, fpl_max, fpl_risk, fpl_direction, etc.
+```
+
+## Use Cases
+
+### 1. Opportunity Screening
+
+```ruby
+stocks = ['AAPL', 'GOOGL', 'MSFT']
+
+stocks.each do |ticker|
+  stock = SQA::Stock.new(ticker: ticker)
+  prices = stock.df["adj_close_price"].to_a
+  
+  analysis = SQA::FPOP.fpl_analysis(prices, fpop: 10)
+  
+  if analysis[:reward] > 15.0 && analysis[:risk] < 10.0
+    puts "#{ticker}: Good risk/reward (#{analysis[:reward]}/#{analysis[:risk]})"
+  end
+end
+```
+
+### 2. Entry Point Validation
+
+```ruby
+# Check if current point offers good risk/reward
+current_analysis = SQA::FPOP.fpl_analysis(prices, fpop: 10)
+
+if current_analysis[:direction] == :UP && 
+   current_analysis[:quality_score] > 0.7
+  puts "Strong buy opportunity"
+end
+```
+
+### 3. Stop Loss Calculation
+
+```ruby
+analysis = SQA::FPOP.fpl_analysis(prices, fpop: 10)
+
+# Set stop loss based on expected risk
+entry_price = prices.last
+stop_loss = entry_price * (1 - analysis[:risk] / 100)
+
+puts "Entry: $#{entry_price}"
+puts "Stop Loss: $#{stop_loss}"
+puts "Target: $#{entry_price * (1 + analysis[:reward] / 100)}"
+```
+
+## Parameters
+
+- `fpop`: Future periods to analyze (default: 10)
+- `min_magnitude`: Minimum move size to consider (%)
+- `max_risk`: Maximum acceptable downside (%)
+- `directions`: Filter by `:UP`, `:DOWN`, or `:FLAT`
+
+## Related
+
+- [Strategy Generator](strategy-generator.md) - Uses FPOP for pattern quality
+- [Risk Management](risk-management.md) - Position sizing based on risk
+- [Backtesting](backtesting.md) - Validate FPOP predictions
+

data/docs/advanced/index.md

@@ -0,0 +1,112 @@
+# Advanced Features
+
+Explore SQA's advanced capabilities for professional-grade analysis.
+
+## Power Tools for Serious Analysis
+
+SQA goes beyond basic technical analysis with powerful features for portfolio management, strategy optimization, and real-time trading.
+
+## Available Features
+
+### Portfolio Management
+Track positions, calculate P&L, manage commissions, and monitor portfolio performance.
+
+**Key Capabilities:**
+- Position tracking with share quantities
+- Commission and fee calculations
+- Realized and unrealized P&L
+- Portfolio value over time
+
+[Learn more →](portfolio.md)
+
+### Backtesting Framework
+Simulate trading strategies on historical data with comprehensive performance metrics.
+
+**Performance Metrics:**
+- Total return and annualized return
+- Sharpe ratio and Sortino ratio
+- Maximum drawdown
+- Win rate and profit factor
+
+[Learn more →](backtesting.md)
+
+### Strategy Generator
+Reverse-engineer profitable trades to discover patterns and generate new strategies.
+
+**Workflow:**
+1. Identify profitable entry/exit points
+2. Capture indicator states at those points
+3. Mine patterns from indicator combinations
+4. Generate executable strategies
+
+[Learn more →](strategy-generator.md)
+
+### Genetic Programming
+Evolve optimal strategy parameters using genetic algorithms.
+
+**Process:**
+- Define parameter space (genes)
+- Create random population
+- Evaluate fitness via backtesting
+- Evolve through selection, crossover, mutation
+
+[Learn more →](../genetic_programming.md)
+
+### Real-Time Streaming
+Process live price data with event callbacks and parallel strategy execution.
+
+**Features:**
+- Rolling window of recent data
+- On-the-fly indicator calculations
+- Multiple strategies in parallel
+- Customizable callbacks
+
+[Learn more →](streaming.md)
+
+### FPOP Analysis
+Future Period of Performance analysis for risk/reward calculations.
+
+**Capabilities:**
+- Calculate future returns
+- Direction classification
+- Risk/reward metrics
+- Performance attribution
+
+[Learn more →](fpop.md)
+
+## Example Workflow
+
+```mermaid
+graph LR
+    A[Historical Data] --> B[Strategy Generator]
+    B --> C[Discovered Patterns]
+    C --> D[Generated Strategies]
+    D --> E[Genetic Programming]
+    E --> F[Optimized Parameters]
+    F --> G[Backtest]
+    G --> H{Results Good?}
+    H -->|Yes| I[Live Stream]
+    H -->|No| D
+    I --> J[Portfolio Management]
+```
+
+## Use Cases
+
+### Quantitative Research
+- Pattern discovery in historical data
+- Parameter optimization
+- Strategy validation
+
+### Algorithmic Trading (Educational)
+- Real-time signal generation
+- Portfolio tracking
+- Performance monitoring
+
+### Risk Management
+- Drawdown analysis
+- Volatility tracking
+- Position sizing
+
+---
+
+**Remember**: These are powerful tools for education and research. Always test thoroughly before considering any real trading applications.

data/docs/advanced/multi-timeframe.md

@@ -0,0 +1,67 @@
+# Multi-Timeframe Analysis
+
+Analyze multiple timeframes simultaneously for better trade timing.
+
+## Setup
+
+```ruby
+mta = SQA::MultiTimeframe.new(stock: stock)
+```
+
+## Trend Alignment
+
+```ruby
+alignment = mta.trend_alignment
+
+# {
+#   daily: :up,
+#   weekly: :up,
+#   monthly: :up,
+#   aligned: true,
+#   direction: :bullish
+# }
+
+if alignment[:aligned] && alignment[:direction] == :bullish
+  puts "Strong uptrend across all timeframes"
+end
+```
+
+## Multi-Timeframe Signal
+
+```ruby
+# Higher timeframe = trend, lower timeframe = timing
+signal = mta.signal(
+  strategy_class: SQA::Strategy::RSI,
+  higher_timeframe: :weekly,   # Trend filter
+  lower_timeframe: :daily      # Entry timing
+)
+
+# Only takes trades aligned with higher timeframe trend
+```
+
+## Support/Resistance
+
+```ruby
+# Find levels that appear across multiple timeframes
+levels = mta.support_resistance(tolerance: 0.02)
+
+levels.each do |level|
+  puts "Strong level at #{level[:price]}"
+  puts "  Appears in: #{level[:timeframes].join(', ')}"
+end
+```
+
+## Divergence Detection
+
+```ruby
+# Price makes new high but indicator doesn't (bearish)
+divergence = mta.detect_divergence(
+  indicator: :rsi,
+  lookback: 20
+)
+
+if divergence[:type] == :bearish
+  puts "Bearish divergence detected - potential reversal"
+end
+```
+

data/docs/advanced/pattern-matcher.md

@@ -0,0 +1,75 @@
+# Pattern Matcher
+
+Pattern recognition and similarity search for forecasting.
+
+## Find Similar Patterns
+
+```ruby
+matcher = SQA::PatternMatcher.new(stock: stock)
+
+# Find historical patterns similar to current
+similar = matcher.find_similar(
+  lookback: 10,           # 10-period pattern
+  num_matches: 5,          # Find 5 best matches
+  method: :euclidean      # Distance metric
+)
+
+similar.each do |match|
+  puts "Distance: #{match[:distance]}"
+  puts "Future return: #{match[:future_return]}%"
+end
+```
+
+## Distance Methods
+
+- `:euclidean` - Standard distance
+- `:dtw` - Dynamic Time Warping (handles compression/stretching)
+- `:correlation` - Correlation-based similarity
+
+## Forecasting
+
+```ruby
+forecast = matcher.forecast(
+  lookback: 10,
+  forecast_periods: 5,
+  method: :dtw
+)
+
+puts "Forecast price: #{forecast[:forecast_price]}"
+puts "Expected return: #{forecast[:forecast_return]}%"
+puts "95% CI: #{forecast[:confidence_interval_95]}"
+```
+
+## Chart Pattern Detection
+
+```ruby
+# Detect double top/bottom
+patterns = matcher.detect_chart_pattern(:double_top)
+
+# Detect head & shoulders
+patterns = matcher.detect_chart_pattern(:head_and_shoulders)
+
+# Detect triangles
+patterns = matcher.detect_chart_pattern(:triangle)
+
+patterns.each do |pattern|
+  puts "#{pattern[:type]} at index #{pattern[:index]}"
+  puts "Confidence: #{pattern[:confidence]}"
+end
+```
+
+## Pattern Clustering
+
+```ruby
+# Group similar patterns
+clusters = matcher.cluster_patterns(
+  num_clusters: 5,
+  lookback: 10
+)
+
+clusters.each_with_index do |cluster, i|
+  puts "Cluster #{i}: #{cluster.size} patterns"
+  puts "  Avg future return: #{cluster[:avg_return]}%"
+end
+```
+

data/docs/advanced/portfolio-optimizer.md

@@ -0,0 +1,79 @@
+# Portfolio Optimizer
+
+Multi-objective portfolio optimization for optimal asset allocation and rebalancing.
+
+## Maximum Sharpe Portfolio
+
+```ruby
+# Get returns for multiple stocks
+returns_matrix = ['AAPL', 'GOOGL', 'MSFT'].map do |ticker|
+  stock = SQA::Stock.new(ticker: ticker)
+  prices = stock.df["adj_close_price"].to_a
+  prices.each_cons(2).map { |a, b| (b - a) / a }
+end
+
+# Find optimal weights
+result = SQA::PortfolioOptimizer.maximum_sharpe(returns_matrix)
+
+puts "Optimal Weights:"
+puts "  AAPL: #{(result[:weights][0] * 100).round(2)}%"
+puts "  GOOGL: #{(result[:weights][1] * 100).round(2)}%"
+puts "  MSFT: #{(result[:weights][2] * 100).round(2)}%"
+puts "\nExpected Sharpe: #{result[:sharpe].round(2)}"
+```
+
+## Minimum Variance Portfolio
+
+```ruby
+result = SQA::PortfolioOptimizer.minimum_variance(returns_matrix)
+# Lowest risk allocation
+```
+
+## Risk Parity
+
+```ruby
+result = SQA::PortfolioOptimizer.risk_parity(returns_matrix)
+# Equal risk contribution from each asset
+```
+
+## Efficient Frontier
+
+```ruby
+frontier = SQA::PortfolioOptimizer.efficient_frontier(
+  returns_matrix,
+  num_portfolios: 50
+)
+
+frontier.each do |portfolio|
+  puts "Return: #{portfolio[:return]}, Risk: #{portfolio[:volatility]}"
+end
+```
+
+## Multi-Objective Optimization
+
+```ruby
+result = SQA::PortfolioOptimizer.multi_objective(
+  returns_matrix,
+  objectives: {
+    maximize_return: 0.4,
+    minimize_volatility: 0.3,
+    minimize_drawdown: 0.3
+  }
+)
+```
+
+## Rebalancing
+
+```ruby
+current_weights = [0.5, 0.3, 0.2]
+target_weights = [0.4, 0.4, 0.2]
+
+trades = SQA::PortfolioOptimizer.rebalance(
+  current_weights: current_weights,
+  target_weights: target_weights,
+  portfolio_value: 10_000
+)
+
+# trades => [{ ticker: 'AAPL', shares: -5, value: -750 }, ...]
+```
+

data/docs/advanced/portfolio.md

@@ -0,0 +1,166 @@
+# Portfolio Management
+
+## Overview
+
+The Portfolio class tracks positions, calculates P&L, manages commissions, and monitors portfolio performance over time.
+
+## Creating a Portfolio
+
+```ruby
+require 'sqa'
+
+portfolio = SQA::Portfolio.new(
+  initial_cash: 10_000,    # Starting capital
+  commission: 1.0           # Commission per trade
+)
+```
+
+## Basic Operations
+
+### Buy Stock
+
+```ruby
+portfolio.buy('AAPL', shares: 10, price: 150.0)
+# Deducts: (10 × $150) + $1 commission = $1,501
+
+puts portfolio.cash  # => 8,499.0
+puts portfolio.positions['AAPL']  # => 10 shares
+```
+
+### Sell Stock
+
+```ruby
+portfolio.sell('AAPL', shares: 5, price: 160.0)
+# Adds: (5 × $160) - $1 commission = $799
+
+puts portfolio.cash  # => 9,298.0
+puts portfolio.positions['AAPL']  # => 5 shares
+```
+
+### Calculate Portfolio Value
+
+```ruby
+current_prices = {
+  'AAPL' => 165.0,
+  'GOOGL' => 2800.0
+}
+
+total_value = portfolio.value(current_prices)
+# Cash + (positions × current prices)
+```
+
+## Complete Example
+
+```ruby
+# Initialize
+portfolio = SQA::Portfolio.new(initial_cash: 10_000)
+
+# Buy multiple stocks
+portfolio.buy('AAPL', shares: 10, price: 150.0)
+portfolio.buy('GOOGL', shares: 2, price: 2750.0)
+
+# Check positions
+puts "Positions: #{portfolio.positions}"
+# => {"AAPL"=>10, "GOOGL"=>2}
+
+# Calculate current value
+prices = { 'AAPL' => 160.0, 'GOOGL' => 2800.0 }
+puts "Portfolio Value: $#{portfolio.value(prices)}"
+
+# Sell some shares
+portfolio.sell('AAPL', shares: 5, price: 160.0)
+
+# View trade history
+portfolio.trades.each do |trade|
+  puts "#{trade.action} #{trade.shares} #{trade.ticker} @ $#{trade.price}"
+end
+```
+
+## P&L Tracking
+
+### Realized P&L
+Profit/loss from closed positions (sold shares).
+
+```ruby
+# Buy 10 shares @ $150
+portfolio.buy('AAPL', shares: 10, price: 150.0)
+
+# Sell 5 shares @ $160
+portfolio.sell('AAPL', shares: 5, price: 160.0)
+
+# Realized P&L: (160 - 150) × 5 = $50
+# (minus 2 × $1 commission = $48)
+```
+
+### Unrealized P&L
+Paper profit/loss on open positions.
+
+```ruby
+# Still holding 5 shares bought @ $150
+# Current price: $165
+
+unrealized_pnl = (165.0 - 150.0) * 5  # => $75
+```
+
+## Portfolio Methods
+
+| Method | Description |
+|--------|-------------|
+| `buy(ticker, shares:, price:)` | Purchase shares |
+| `sell(ticker, shares:, price:)` | Sell shares |
+| `value(current_prices)` | Calculate total portfolio value |
+| `positions` | Hash of ticker → share count |
+| `trades` | Array of all trades |
+| `cash` | Available cash balance |
+
+## Usage with Backtesting
+
+```ruby
+backtest = SQA::Backtest.new(
+  stock: stock,
+  strategy: SQA::Strategy::RSI,
+  initial_cash: 10_000,
+  commission: 1.0
+)
+
+results = backtest.run
+
+puts "Final Value: $#{results.portfolio_value}"
+puts "Total Return: #{results.total_return}%"
+puts "Total Trades: #{results.num_trades}"
+```
+
+## Advanced Features
+
+### Position Sizing
+
+```ruby
+# Risk-based position sizing
+risk_per_trade = portfolio.cash * 0.02  # 2% risk
+shares = (risk_per_trade / stop_loss_distance).to_i
+
+portfolio.buy('AAPL', shares: shares, price: current_price)
+```
+
+### Diversification Check
+
+```ruby
+def check_diversification(portfolio, prices)
+  total_value = portfolio.value(prices)
+  
+  portfolio.positions.each do |ticker, shares|
+    position_value = shares * prices[ticker]
+    percentage = (position_value / total_value) * 100
+    
+    puts "#{ticker}: #{percentage.round(2)}%"
+    warn "⚠️  #{ticker} exceeds 20%" if percentage > 20
+  end
+end
+```
+
+## Related
+
+- [Backtesting](backtesting.md) - Test strategies with portfolio tracking
+- [Risk Management](risk-management.md) - Position sizing and risk metrics
+- [Portfolio Optimizer](portfolio-optimizer.md) - Optimal asset allocation
+