sqa 0.0.24 → 0.0.31

data/docs/getting-started/index.md

@@ -0,0 +1,123 @@
+# Getting Started with SQA
+
+Welcome to SQA! This guide will help you get up and running with stock market technical analysis in just a few minutes.
+
+## What You'll Learn
+
+In this section, you'll learn how to:
+
+- Install SQA and its dependencies
+- Configure your environment for data access
+- Run your first analysis
+- Use the interactive console
+- Understand the basic workflow
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- **Ruby 3.2+** installed on your system
+- **TA-Lib C library** (for technical indicators)
+- **(Optional) Alpha Vantage API key** for live data access
+
+## Quick Navigation
+
+<div class="grid cards" markdown>
+
+-   :material-download:{ .lg .middle } __Installation__
+
+    ---
+
+    Install SQA and set up TA-Lib for technical analysis
+
+    [:octicons-arrow-right-24: Installation Guide](installation.md)
+
+-   :material-rocket-launch:{ .lg .middle } __Quick Start__
+
+    ---
+
+    Get your first analysis running in minutes
+
+    [:octicons-arrow-right-24: Quick Start Guide](quick-start.md)
+
+-   :material-cog:{ .lg .middle } __Configuration__
+
+    ---
+
+    Configure data sources and customize settings
+
+    [:octicons-arrow-right-24: Configuration](configuration.md)
+
+-   :material-console:{ .lg .middle } __Console Usage__
+
+    ---
+
+    Interactive exploration with sqa-console
+
+    [:octicons-arrow-right-24: Console Guide](console-usage.md)
+
+</div>
+
+## Typical Workflow
+
+Here's the typical workflow when using SQA:
+
+```mermaid
+graph LR
+    A[Install SQA] --> B[Configure API Keys]
+    B --> C[Load Stock Data]
+    C --> D[Calculate Indicators]
+    D --> E[Apply Strategies]
+    E --> F{Analysis Type}
+    F -->|Backtest| G[Run Backtest]
+    F -->|Live| H[Stream Real-Time]
+    F -->|Research| I[Explore in Console]
+    G --> J[Review Results]
+    H --> J
+    I --> J
+```
+
+## What's Next?
+
+Once you've completed the getting started guides, you can explore:
+
+- **[Core Concepts](../concepts/index.md)** - Deep dive into SQA's architecture
+- **[Technical Indicators](../indicators/index.md)** - Learn about the 150+ indicators
+- **[Trading Strategies](../strategies/index.md)** - Explore built-in and custom strategies
+- **[Advanced Features](../advanced/index.md)** - Portfolio management, backtesting, and more
+
+## Need Help?
+
+If you run into issues:
+
+1. Check the [Troubleshooting](#troubleshooting) section below
+2. Review the [Requirements](../requirements.md) page
+3. Visit our [GitHub Issues](https://github.com/madbomber/sqa/issues)
+
+## Troubleshooting
+
+### Common Issues
+
+**Ruby Version Too Old**
+```bash
+ruby --version  # Should be 3.2 or higher
+rbenv install 3.3.6  # Or rvm install ruby-3.3.6
+```
+
+**TA-Lib Not Found**
+```bash
+# See the Installation guide for TA-Lib setup
+# Quick check:
+ls /usr/local/lib/libta_lib.*
+```
+
+**API Key Issues**
+```bash
+# Set your Alpha Vantage API key
+export AV_API_KEY="your_key_here"
+# Or add to ~/.bashrc for persistence
+```
+
+---
+
+Ready to install? Let's get started with the **[Installation Guide](installation.md)**!

data/docs/getting-started/installation.md

@@ -0,0 +1,229 @@
+# Installation Guide
+
+This guide walks you through installing SQA and all its dependencies.
+
+## System Requirements
+
+- **Ruby**: 3.2 or higher
+- **Operating System**: Linux, macOS, or Windows (with WSL)
+- **Disk Space**: ~100MB for gem and dependencies
+- **Internet**: Required for downloading stock data
+
+## Step 1: Install TA-Lib
+
+SQA requires the TA-Lib C library for technical analysis calculations.
+
+### Linux (Ubuntu/Debian)
+
+```bash
+# Download and extract TA-Lib source
+cd /tmp
+wget http://prdownloads.sourceforge.net/ta-lib/ta-lib-0.4.0-src.tar.gz
+tar -xzf ta-lib-0.4.0-src.tar.gz
+
+# Compile and install
+cd ta-lib
+./configure --prefix=/usr/local
+make
+sudo make install
+
+# Create symlink for compatibility
+cd /usr/local/lib
+sudo ln -s libta_lib.so libta-lib.so
+sudo ldconfig
+
+# Set library path (add to ~/.bashrc for persistence)
+export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
+```
+
+### macOS
+
+```bash
+# Using Homebrew
+brew install ta-lib
+```
+
+### Verify Installation
+
+```bash
+# Check that TA-Lib is installed
+ls -la /usr/local/lib/libta_lib.*
+
+# Should show files like:
+# libta_lib.a
+# libta_lib.so
+# libta_lib.so.0
+# libta_lib.so.0.0.0
+```
+
+## Step 2: Install SQA Gem
+
+### From RubyGems (Recommended)
+
+```bash
+gem install sqa
+```
+
+### From Source
+
+```bash
+# Clone the repository
+git clone https://github.com/madbomber/sqa.git
+cd sqa
+
+# Install dependencies
+bundle install
+
+# Install the gem locally
+rake install
+```
+
+## Step 3: Verify Installation
+
+Test that SQA is installed correctly:
+
+```bash
+# Launch the SQA console
+sqa-console
+
+# In the console, try:
+SQA::VERSION  # Should display the version number
+SQAI.methods.grep(/^[a-z]/).sort  # List available indicators
+```
+
+Expected output:
+```ruby
+=> "0.0.31"  # Version number
+
+=> [:acos, :ad, :add, :adosc, :adx, :adxr, ...]  # 150+ indicators
+```
+
+## Step 4: Configure API Access (Optional)
+
+To download live stock data, you'll need an Alpha Vantage API key.
+
+### Get API Key
+
+1. Visit [Alpha Vantage](https://www.alphavantage.co/support/#api-key)
+2. Sign up for a free API key
+3. Copy your API key
+
+### Set Environment Variable
+
+```bash
+# Temporary (current session)
+export AV_API_KEY="your_api_key_here"
+
+# Permanent (add to ~/.bashrc or ~/.zshrc)
+echo 'export AV_API_KEY="your_api_key_here"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### Alternative: Configuration File
+
+Create `~/.sqa.yml`:
+
+```yaml
+data_dir: ~/sqa_data
+debug: false
+verbose: false
+```
+
+The API key is read from environment variables, not the config file.
+
+## Troubleshooting
+
+### TA-Lib Not Found
+
+**Error**: `cannot load such file -- sqa/tai (LoadError)`
+
+**Solution**: Make sure TA-Lib is installed and `LD_LIBRARY_PATH` is set:
+
+```bash
+export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
+```
+
+### Permission Denied During Installation
+
+**Error**: `Permission denied @ dir_s_mkdir`
+
+**Solution**: Use `sudo` for system-wide installation:
+
+```bash
+sudo gem install sqa
+```
+
+Or install to user directory:
+
+```bash
+gem install --user-install sqa
+```
+
+### Ruby Version Too Old
+
+**Error**: `Required Ruby version is >= 3.2.0`
+
+**Solution**: Update Ruby using rbenv or rvm:
+
+```bash
+# Using rbenv
+rbenv install 3.3.6
+rbenv global 3.3.6
+
+# Using rvm
+rvm install 3.3.6
+rvm use 3.3.6 --default
+```
+
+### Bundle Install Fails
+
+**Error**: Various dependency errors
+
+**Solution**: Update bundler and try again:
+
+```bash
+gem update --system
+gem install bundler
+bundle install
+```
+
+## Next Steps
+
+Now that you have SQA installed:
+
+1. **[Quick Start Guide](quick-start.md)** - Run your first analysis
+2. **[Configuration](configuration.md)** - Customize your setup
+3. **[Console Usage](console-usage.md)** - Explore interactively
+
+## Additional Dependencies
+
+SQA automatically installs these dependencies:
+
+- `polars-df` - High-performance DataFrames
+- `sqa-tai` - TA-Lib wrapper for indicators
+- `faraday` - HTTP client for API calls
+- `hashie` - Enhanced hash objects
+- `tty-table` - Terminal table formatting
+- `kbs` - Knowledge-based strategy framework
+- `toml-rb` - TOML configuration support
+
+For development, you may also want:
+
+- `amazing_print` - Pretty printing
+- `debug_me` - Debugging utilities
+- `minitest` - Testing framework
+- `simplecov` - Code coverage
+
+## Supported Platforms
+
+SQA has been tested on:
+
+- ✅ Ubuntu 20.04+
+- ✅ Debian 11+
+- ✅ macOS 12+ (Monterey and later)
+- ✅ Fedora 35+
+- ⚠️ Windows (via WSL recommended)
+
+---
+
+Having issues? Check our [GitHub Issues](https://github.com/madbomber/sqa/issues) or create a new one.

data/docs/getting-started/quick-start.md

@@ -0,0 +1,244 @@
+# Quick Start Guide
+
+Get up and running with SQA in just a few minutes!
+
+## Your First Analysis (5 Minutes)
+
+### 1. Create a Simple Script
+
+Create a file called `my_first_analysis.rb`:
+
+```ruby
+require 'sqa'
+
+# Initialize SQA
+SQA.init
+
+# Load Apple stock data
+puts "Loading AAPL data..."
+stock = SQA::Stock.new(ticker: 'AAPL')
+
+# Display basic information
+puts "\n#{stock}"
+puts "Data points: #{stock.df.height}"
+puts "Date range: #{stock.df['timestamp'].first} to #{stock.df['timestamp'].last}"
+
+# Get closing prices
+prices = stock.df["adj_close_price"].to_a
+puts "\nCurrent price: $#{prices.last}"
+
+# Calculate RSI (Relative Strength Index)
+rsi_values = SQAI.rsi(prices, period: 14)
+current_rsi = rsi_values.last.round(2)
+
+puts "Current RSI: #{current_rsi}"
+puts "Market condition: #{current_rsi < 30 ? 'Oversold' : current_rsi > 70 ? 'Overbought' : 'Neutral'}"
+
+# Calculate Simple Moving Average
+sma_20 = SQAI.sma(prices, period: 20)
+sma_50 = SQAI.sma(prices, period: 50)
+
+puts "\n20-day SMA: $#{sma_20.last.round(2)}"
+puts "50-day SMA: $#{sma_50.last.round(2)}"
+puts "Trend: #{sma_20.last > sma_50.last ? 'Bullish' : 'Bearish'}"
+```
+
+### 2. Run the Script
+
+```bash
+ruby my_first_analysis.rb
+```
+
+Expected output:
+```
+Loading AAPL data...
+
+aapl with 1258 data points from 2019-11-09 to 2024-11-08
+Data points: 1258
+Date range: 2019-11-09 to 2024-11-08
+
+Current price: $226.96
+Current RSI: 48.23
+Market condition: Neutral
+
+20-day SMA: $225.45
+50-day SMA: $218.32
+Trend: Bullish
+```
+
+## Backtest a Strategy (10 Minutes)
+
+Let's backtest a simple RSI trading strategy:
+
+```ruby
+require 'sqa'
+
+SQA.init
+
+# Load stock data
+stock = SQA::Stock.new(ticker: 'AAPL')
+
+# Create and run backtest
+backtest = SQA::Backtest.new(
+  stock: stock,
+  strategy: SQA::Strategy::RSI,
+  initial_cash: 10_000.0,
+  commission: 1.0  # $1 per trade
+)
+
+puts "Running backtest for RSI strategy..."
+results = backtest.run
+
+# Display results
+puts "\n=== Backtest Results ==="
+puts "Total Return: #{results.total_return.round(2)}%"
+puts "Sharpe Ratio: #{results.sharpe_ratio.round(2)}"
+puts "Max Drawdown: #{results.max_drawdown.round(2)}%"
+puts "Win Rate: #{results.win_rate.round(2)}%"
+puts "\nTotal Trades: #{results.total_trades}"
+puts "Winning Trades: #{results.winning_trades}"
+puts "Losing Trades: #{results.losing_trades}"
+puts "\nFinal Portfolio Value: $#{results.final_value.round(2)}"
+```
+
+## Use Multiple Indicators (15 Minutes)
+
+Combine several indicators for better analysis:
+
+```ruby
+require 'sqa'
+
+SQA.init
+
+stock = SQA::Stock.new(ticker: 'MSFT')
+prices = stock.df["adj_close_price"].to_a
+volumes = stock.df["volume"].to_a
+
+# Calculate multiple indicators
+puts "Calculating indicators..."
+
+# Trend indicators
+sma_20 = SQAI.sma(prices, period: 20)
+ema_12 = SQAI.ema(prices, period: 12)
+ema_26 = SQAI.ema(prices, period: 26)
+
+# Momentum indicators
+rsi = SQAI.rsi(prices, period: 14)
+macd_line, signal_line, histogram = SQAI.macd(
+  prices,
+  fast_period: 12,
+  slow_period: 26,
+  signal_period: 9
+)
+
+# Volatility indicators
+upper, middle, lower = SQAI.bbands(prices, period: 20)
+
+# Display current values
+puts "\n=== Technical Analysis for MSFT ==="
+puts "Price: $#{prices.last.round(2)}"
+puts "\nTrend:"
+puts "  SMA(20): $#{sma_20.last.round(2)}"
+puts "  EMA(12): $#{ema_12.last.round(2)}"
+puts "  EMA(26): $#{ema_26.last.round(2)}"
+
+puts "\nMomentum:"
+puts "  RSI: #{rsi.last.round(2)}"
+puts "  MACD: #{macd_line.last.round(2)}"
+puts "  Signal: #{signal_line.last.round(2)}"
+
+puts "\nVolatility (Bollinger Bands):"
+puts "  Upper: $#{upper.last.round(2)}"
+puts "  Middle: $#{middle.last.round(2)}"
+puts "  Lower: $#{lower.last.round(2)}"
+
+# Generate trading signal
+signal = case
+  when rsi.last < 30 && prices.last < lower.last
+    "STRONG BUY"
+  when rsi.last < 40 && macd_line.last > signal_line.last
+    "BUY"
+  when rsi.last > 70 && prices.last > upper.last
+    "STRONG SELL"
+  when rsi.last > 60 && macd_line.last < signal_line.last
+    "SELL"
+  else
+    "HOLD"
+  end
+
+puts "\nRecommended Action: #{signal}"
+```
+
+## Explore Interactively
+
+Use the `sqa-console` for interactive exploration:
+
+```bash
+sqa-console
+```
+
+Try these commands in the console:
+
+```ruby
+# Load a stock
+stock = SQA::Stock.new(ticker: 'GOOGL')
+
+# Explore the dataframe
+stock.df.head(10)
+
+# Get column names
+stock.df.columns
+
+# Calculate any indicator
+prices = stock.df["adj_close_price"].to_a
+SQAI.sma(prices, period: 50)
+
+# List all available indicators
+SQAI.methods.grep(/^[a-z]/).sort
+
+# Try different strategies
+SQA::Strategy.descendants  # List all strategy classes
+```
+
+## Next Steps
+
+Now that you've run your first analyses:
+
+1. **[Configuration Guide](configuration.md)** - Customize data sources and settings
+2. **[Core Concepts](../concepts/index.md)** - Understand SQA's architecture
+3. **[Trading Strategies](../strategies/index.md)** - Explore built-in strategies
+4. **[Advanced Features](../advanced/index.md)** - Portfolio management, streaming, etc.
+
+## Common Patterns
+
+### Load Historical Data
+
+```ruby
+stock = SQA::Stock.new(ticker: 'TSLA')
+prices = stock.df["adj_close_price"].to_a
+```
+
+### Calculate Indicator
+
+```ruby
+values = SQAI.indicator_name(prices, period: 14)
+```
+
+### Apply Strategy
+
+```ruby
+require 'ostruct'
+vector = OpenStruct.new(prices: prices, rsi: rsi_values)
+signal = SQA::Strategy::RSI.trade(vector)
+```
+
+### Run Backtest
+
+```ruby
+backtest = SQA::Backtest.new(stock: stock, strategy: SQA::Strategy::MACD)
+results = backtest.run
+```
+
+---
+
+**Tip**: Keep the [Technical Indicators Reference](../indicators/index.md) handy as you explore!

data/docs/i_gotta_an_idea.md

@@ -0,0 +1,22 @@
+## In Idea
+
+... based upon my prior work with sports outcome predictions and sensor net architecture.
+
+### Conceptual Framework for Financial Technical Analysis and Future Position Prediction
+
+#### Abstract
+
+This paper proposes a novel approach to financial technical analysis and the prediction of future market positions by drawing upon a methodology previously applied in the assessment of professional football games. The core idea involves the development and application of a numerical rating system, similar to one created in the 1980s for evaluating the performance of football teams by analyzing the strengths and weaknesses of their offensive, defensive, and special teams' statistics. The aim of this approach is to extend the principles of this rating system to the evaluation of companies by examining their financial fundamentals and technical analysis metrics.
+
+#### Introduction
+
+In the realm of sports analytics, the creation of a power rating system transformed the evaluation of professional football games by quantifying the performance of teams based on a comprehensive analysis of their statistics. This methodology involved a comparative analysis between the offensive capabilities of one team against the defensive competencies of their opponents, in addition to assessing the performance of special teams. The derived power rating was instrumental in predicting the likelihood of a team to "cover the points" in a game, essentially forecasting game outcomes with a higher degree of accuracy.
+
+The proposed study seeks to adapt this successful analytical framework to the financial domain, specifically to the assessment of company performance and market position prediction. The adaptation involves considering company financial fundamentals and technical analysis indicators as analogous to the offensive, defensive, and special teams' statistics in football.
+
+#### Methodology
+
+The methodology encompasses the conceptualization of financial fundamental and technical analysis indicators as individual "sensors," each attributed with a distinct reliability weight. This is inspired by prior work on sensor networks, where each sensor's input was weighted according to its reliability. Through historical analysis within 15-day windows, weights will be assigned to each "sensor" (i.e., financial indicator), determining its influence on buy, sell, or hold decisions.
+
+The study will explore multiple combinations of these weighted sensors to establish a comprehensive set of indicators. These indicators will cover various trading horizons, specifically 15, 30, 45, 60, 90, 120, 180, 240, and 360 trading days. The intent is to produce a versatile suite of both short-term and long-term indicators that can guide investment decisions.
+