sqa 0.0.37 → 0.0.38

data/docs/api-reference/string.md

@@ -5,7 +5,7 @@
      Desc:  Monkey to the String class.
 
 !!! abstract "Source Information"
-    **Defined in:** `lib/patches/string.rb:10`
+    **Defined in:** [`lib/patches/string.rb:10`](https://github.com/madbomber/sqa/blob/main/lib/patches/string.rb#L10)
     
     **Inherits from:** `Object`
 
@@ -19,7 +19,7 @@ Convert CamelCase to camel_case
 
 
 ??? info "Source Location"
-    `lib/patches/string.rb:14`
+    [`lib/patches/string.rb:14`](https://github.com/madbomber/sqa/blob/main/lib/patches/string.rb#L14)
 
 ---
 
@@ -31,7 +31,7 @@ Convert CamelCase to camel_case
 
 
 ??? info "Source Location"
-    `lib/patches/string.rb:21`
+    [`lib/patches/string.rb:21`](https://github.com/madbomber/sqa/blob/main/lib/patches/string.rb#L21)
 
 ---
 
@@ -43,7 +43,7 @@ Convert CamelCase to camel_case
 
 
 ??? info "Source Location"
-    `lib/patches/string.rb:22`
+    [`lib/patches/string.rb:22`](https://github.com/madbomber/sqa/blob/main/lib/patches/string.rb#L22)
 
 ---
 
@@ -55,7 +55,7 @@ Convert CamelCase to camel_case
 
 
 ??? info "Source Location"
-    `lib/patches/string.rb:23`
+    [`lib/patches/string.rb:23`](https://github.com/madbomber/sqa/blob/main/lib/patches/string.rb#L23)
 
 ---
 
@@ -67,7 +67,7 @@ Convert CamelCase to camel_case
 
 
 ??? info "Source Location"
-    `lib/patches/string.rb:24`
+    [`lib/patches/string.rb:24`](https://github.com/madbomber/sqa/blob/main/lib/patches/string.rb#L24)
 
 ---
 
@@ -79,7 +79,7 @@ Convert camel_case to CamelCase
 
 
 ??? info "Source Location"
-    `lib/patches/string.rb:29`
+    [`lib/patches/string.rb:29`](https://github.com/madbomber/sqa/blob/main/lib/patches/string.rb#L29)
 
 ---
 
@@ -91,7 +91,7 @@ Convert camel_case to CamelCase
 
 
 ??? info "Source Location"
-    `lib/patches/string.rb:34`
+    [`lib/patches/string.rb:34`](https://github.com/madbomber/sqa/blob/main/lib/patches/string.rb#L34)
 
 ---
 
@@ -103,7 +103,7 @@ Convert camel_case to CamelCase
 
 
 ??? info "Source Location"
-    `lib/patches/string.rb:35`
+    [`lib/patches/string.rb:35`](https://github.com/madbomber/sqa/blob/main/lib/patches/string.rb#L35)
 
 ---
 
@@ -115,7 +115,7 @@ Convert "CamelCase" into CamelCase
 
 
 ??? info "Source Location"
-    `lib/patches/string.rb:40`
+    [`lib/patches/string.rb:40`](https://github.com/madbomber/sqa/blob/main/lib/patches/string.rb#L40)
 
 ---
 
@@ -127,7 +127,7 @@ Convert "CamelCase" into CamelCase
 
 
 ??? info "Source Location"
-    `lib/patches/string.rb:55`
+    [`lib/patches/string.rb:55`](https://github.com/madbomber/sqa/blob/main/lib/patches/string.rb#L55)
 
 ---
 

data/docs/file_formats.md

@@ -0,0 +1,250 @@
+# File Formats
+
+This document describes the CSV file formats used by SQA for data import and export.
+
+## Portfolio CSV Formats
+
+The `SQA::Portfolio` class supports two CSV file formats for different purposes: positions (holdings) and trade history.
+
+### Portfolio Positions CSV
+
+This format is used to save and load current portfolio holdings.
+
+**Methods:**
+- `portfolio.save_to_csv(filename)` - Save positions
+- `SQA::Portfolio.load_from_csv(filename)` - Load positions
+
+**Schema:**
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `ticker` | String | Stock ticker symbol (e.g., 'AAPL', 'MSFT') |
+| `shares` | Integer | Number of shares currently held |
+| `avg_cost` | Float | Average cost per share (cost basis) |
+| `total_cost` | Float | Total cost basis for the entire position |
+
+**Example File (`portfolio.csv`):**
+
+```csv
+ticker,shares,avg_cost,total_cost
+AAPL,100,150.0,15000.0
+MSFT,50,300.0,15000.0
+GOOG,25,120.0,3000.0
+```
+
+**Usage:**
+
+```ruby
+# Save current positions to CSV
+portfolio = SQA::Portfolio.new(initial_cash: 100_000)
+portfolio.buy('AAPL', shares: 100, price: 150.0)
+portfolio.buy('MSFT', shares: 50, price: 300.0)
+portfolio.save_to_csv('my_portfolio.csv')
+
+# Load positions from CSV
+loaded_portfolio = SQA::Portfolio.load_from_csv('my_portfolio.csv')
+loaded_portfolio.position('AAPL').shares  # => 100
+```
+
+**Notes:**
+- The CSV includes only current positions (open holdings)
+- Cash balance is NOT saved in the CSV (set via `initial_cash` parameter when loading)
+- Use this format for portfolio snapshots and position tracking
+
+---
+
+### Trade History CSV
+
+This format is used to export the complete log of all buy and sell transactions.
+
+**Methods:**
+- `portfolio.save_trades_to_csv(filename)` - Export trade history
+
+**Schema:**
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `date` | Date | Trade execution date (YYYY-MM-DD format) |
+| `ticker` | String | Stock ticker symbol |
+| `action` | Symbol | Trade type: `buy` or `sell` |
+| `shares` | Integer | Number of shares traded |
+| `price` | Float | Price per share at execution |
+| `total` | Float | Total transaction value (shares × price) |
+| `commission` | Float | Commission paid for the trade |
+
+**Example File (`trades.csv`):**
+
+```csv
+date,ticker,action,shares,price,total,commission
+2024-01-15,AAPL,buy,100,150.0,15000.0,1.0
+2024-01-20,MSFT,buy,50,300.0,15000.0,1.0
+2024-02-05,AAPL,sell,50,160.0,8000.0,1.0
+2024-02-15,GOOG,buy,25,120.0,3000.0,1.0
+2024-03-01,MSFT,sell,25,310.0,7750.0,1.0
+```
+
+**Usage:**
+
+```ruby
+# Execute some trades
+portfolio = SQA::Portfolio.new(initial_cash: 100_000, commission: 1.0)
+portfolio.buy('AAPL', shares: 100, price: 150.0, date: Date.parse('2024-01-15'))
+portfolio.buy('MSFT', shares: 50, price: 300.0, date: Date.parse('2024-01-20'))
+portfolio.sell('AAPL', shares: 50, price: 160.0, date: Date.parse('2024-02-05'))
+
+# Export complete trade history
+portfolio.save_trades_to_csv('trade_history.csv')
+```
+
+**Notes:**
+- This format is write-only (no corresponding `load_trades_from_csv()` method)
+- Use for audit trails, tax reporting, and performance analysis
+- Each row represents a single executed trade
+- The `total` column does NOT include commission (commission is tracked separately)
+
+---
+
+## Stock Data CSV Format
+
+Stock price and volume data is stored in CSV format with the following schema:
+
+**Schema:**
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `timestamp` | String | Date in YYYY-MM-DD format |
+| `open_price` | Float | Opening price |
+| `high_price` | Float | Highest price during the period |
+| `low_price` | Float | Lowest price during the period |
+| `close_price` | Float | Closing price |
+| `adj_close_price` | Float | Adjusted closing price (accounts for splits/dividends) |
+| `volume` | Integer | Trading volume |
+
+**Example File (`aapl.csv`):**
+
+```csv
+timestamp,open_price,high_price,low_price,close_price,adj_close_price,volume
+2023-01-03,130.28,130.90,124.17,125.07,124.38,112117500
+2023-01-04,126.89,128.66,125.08,126.36,125.66,89113600
+2023-01-05,127.13,127.77,124.76,125.02,124.33,80962700
+```
+
+**Location:**
+- Stock CSV files are stored in `~/sqa_data/` by default (configurable via `SQA::Config`)
+- File naming convention: `{ticker}.csv` (e.g., `aapl.csv`, `msft.csv`)
+
+**Data Ordering:**
+- **CRITICAL:** Data MUST be in ascending chronological order (oldest first, newest last)
+- This ordering is required for TA-Lib compatibility
+- Index [0] = oldest data point, Index [last] = newest data point
+
+**Usage:**
+
+```ruby
+# Stock data is automatically loaded/saved
+stock = SQA::Stock.new(ticker: 'AAPL')
+stock.df.to_csv('aapl_export.csv')  # Export to custom location
+
+# Load from custom CSV
+df = SQA::DataFrame.load(source: 'path/to/custom.csv')
+```
+
+**Notes:**
+- Data is automatically fetched from Alpha Vantage or Yahoo Finance on first load
+- Updates are appended and deduplicated using `concat_and_deduplicate!`
+- Use `adj_close_price` for calculations that need to account for corporate actions
+
+---
+
+## Stock Metadata JSON Format
+
+Stock metadata (company information) is stored in JSON format alongside CSV files.
+
+**Location:** `~/sqa_data/{ticker}.json`
+
+**Example File (`aapl.json`):**
+
+```json
+{
+  "ticker": "aapl",
+  "name": "Apple Inc.",
+  "exchange": "NASDAQ",
+  "source": "alpha_vantage",
+  "indicators": {},
+  "overview": {
+    "symbol": "AAPL",
+    "asset_type": "Common Stock",
+    "name": "Apple Inc.",
+    "exchange": "NASDAQ",
+    "currency": "USD",
+    "country": "USA",
+    "sector": "TECHNOLOGY",
+    "industry": "ELECTRONIC COMPUTERS",
+    "market_capitalization": 2500000000000,
+    "pe_ratio": 28.5,
+    "eps": 6.05,
+    "dividend_per_share": 0.92,
+    "dividend_yield": 0.0055
+  }
+}
+```
+
+**Usage:**
+
+```ruby
+stock = SQA::Stock.new(ticker: 'AAPL')
+stock.data.overview['market_capitalization']  # => 2500000000000
+stock.data.overview['pe_ratio']  # => 28.5
+```
+
+---
+
+## Configuration File Format
+
+SQA supports YAML and TOML configuration files.
+
+**Location:** `~/.sqa.yml` or `~/.sqa.toml`
+
+**Example YAML (`~/.sqa.yml`):**
+
+```yaml
+data_dir: ~/sqa_data
+lazy_update: false
+log_level: info
+plotting_library: gnuplot
+```
+
+**Example TOML (`~/.sqa.toml`):**
+
+```toml
+data_dir = "~/sqa_data"
+lazy_update = false
+log_level = "info"
+plotting_library = "gnuplot"
+```
+
+**Available Configuration Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `data_dir` | String | `~/sqa_data` | Directory for storing stock data files |
+| `lazy_update` | Boolean | `false` | If true, skip automatic data updates |
+| `log_level` | Symbol | `:info` | Logging level (`:debug`, `:info`, `:warn`, `:error`) |
+| `plotting_library` | Symbol | `:gnuplot` | Plotting library to use |
+
+**Usage:**
+
+```ruby
+# Load custom configuration
+config = SQA::Config.new(data_dir: '/path/to/data', lazy_update: true)
+SQA.init(config)
+```
+
+---
+
+## See Also
+
+- [API Reference - Portfolio](api-reference/sqa_portfolio.md)
+- [API Reference - Stock](api-reference/sqa_stock.md)
+- [API Reference - DataFrame](api-reference/sqa_dataframe.md)
+- [Data Frame Documentation](data_frame.md)

data/lib/sqa/backtest.rb

@@ -99,6 +99,38 @@ class SQA::Backtest
 
   # Run the backtest
   # @return [Results] Backtest results
+  #
+  # @example Run backtest with RSI strategy
+  #   stock = SQA::Stock.new(ticker: 'AAPL')
+  #   backtest = SQA::Backtest.new(
+  #     stock: stock,
+  #     strategy: SQA::Strategy::RSI,
+  #     initial_capital: 10_000,
+  #     commission: 1.0
+  #   )
+  #   results = backtest.run
+  #   puts results.summary
+  #   # => Total Return: 15.5%
+  #   #    Sharpe Ratio: 1.2
+  #   #    Max Drawdown: -8.3%
+  #   #    Win Rate: 65%
+  #
+  # @example Backtest with custom date range
+  #   backtest = SQA::Backtest.new(
+  #     stock: stock,
+  #     strategy: SQA::Strategy::MACD,
+  #     start_date: '2023-01-01',
+  #     end_date: '2023-12-31'
+  #   )
+  #   results = backtest.run
+  #   results.total_return  # => 0.155 (15.5%)
+  #
+  # @example Access equity curve for plotting
+  #   results = backtest.run
+  #   backtest.equity_curve.each do |point|
+  #     puts "#{point[:date]}: $#{point[:value]}"
+  #   end
+  #
   def run
     # Get data for the backtest period
     df = @stock.df.data

data/lib/sqa/data_frame.rb

@@ -132,6 +132,23 @@ class SQA::DataFrame
   #
   # NOTE: TA-Lib requires data in ascending (oldest-first) order. Using descending: true
   # will produce a warning and force ascending order to prevent silent calculation errors.
+  #
+  # @example Merge new data with deduplication
+  #   stock = SQA::Stock.new(ticker: 'AAPL')
+  #   df = stock.df
+  #   df.size  # => 252
+  #
+  #   # Fetch recent data (may have overlapping dates)
+  #   new_df = SQA::DataFrame::AlphaVantage.recent('AAPL', from_date: Date.today - 7)
+  #   df.concat_and_deduplicate!(new_df)
+  #   # Duplicates removed, data sorted ascending (oldest first)
+  #   df.size  # => 255 (only 3 new unique dates added)
+  #
+  # @example Maintains TA-Lib compatibility
+  #   df.concat_and_deduplicate!(new_df)  # Sorted ascending automatically
+  #   prices = df["adj_close_price"].to_a
+  #   rsi = SQAI.rsi(prices, period: 14)  # Works correctly with ascending data
+  #
   def concat_and_deduplicate!(other_df, sort_column: "timestamp", descending: false)
     # Enforce ascending order for TA-Lib compatibility
     if descending
@@ -184,6 +201,14 @@ class SQA::DataFrame
   #
   # @param path_to_file [String, Pathname] Path to output CSV file
   # @return [void]
+  #
+  # @example Save stock data to CSV
+  #   stock = SQA::Stock.new(ticker: 'AAPL')
+  #   stock.df.to_csv('aapl_prices.csv')
+  #
+  # @example Export with custom path
+  #   df.to_csv(Pathname.new('data/exports/prices.csv'))
+  #
   def to_csv(path_to_file)
     @data.write_csv(path_to_file)
   end

data/lib/sqa/portfolio.rb

@@ -52,6 +52,19 @@ class SQA::Portfolio
   # @param price [Float] Price per share
   # @param date [Date] Date of trade
   # @return [Trade] The executed trade
+  #
+  # @example Buy 10 shares of AAPL
+  #   portfolio = SQA::Portfolio.new(initial_cash: 10_000, commission: 1.0)
+  #   trade = portfolio.buy('AAPL', shares: 10, price: 150.0)
+  #   trade.action  # => :buy
+  #   trade.total   # => 1500.0
+  #   portfolio.cash  # => 8499.0 (10_000 - 1500 - 1.0 commission)
+  #
+  # @example Buy multiple stocks
+  #   portfolio.buy('AAPL', shares: 10, price: 150.0)
+  #   portfolio.buy('MSFT', shares: 5, price: 300.0)
+  #   portfolio.positions.size  # => 2
+  #
   def buy(ticker, shares:, price:, date: Date.today)
     raise BadParameterError, "Shares must be positive" if shares <= 0
     raise BadParameterError, "Price must be positive" if price <= 0
@@ -95,6 +108,19 @@ class SQA::Portfolio
   # @param price [Float] Price per share
   # @param date [Date] Date of trade
   # @return [Trade] The executed trade
+  #
+  # @example Sell entire position for profit
+  #   portfolio = SQA::Portfolio.new(initial_cash: 10_000, commission: 1.0)
+  #   portfolio.buy('AAPL', shares: 10, price: 150.0)
+  #   trade = portfolio.sell('AAPL', shares: 10, price: 160.0)
+  #   trade.total  # => 1600.0
+  #   portfolio.cash  # => 8498.0 + 1599.0 = 10097.0 (after commissions)
+  #
+  # @example Partial sale
+  #   portfolio.buy('AAPL', shares: 100, price: 150.0)
+  #   portfolio.sell('AAPL', shares: 50, price: 160.0)  # Sell half
+  #   portfolio.position('AAPL').shares  # => 50
+  #
   def sell(ticker, shares:, price:, date: Date.today)
     raise BadParameterError, "Shares must be positive" if shares <= 0
     raise BadParameterError, "Price must be positive" if price <= 0
@@ -145,6 +171,18 @@ class SQA::Portfolio
   # Calculate total portfolio value
   # @param current_prices [Hash] Hash of ticker => current_price
   # @return [Float] Total portfolio value (cash + positions)
+  #
+  # @example Calculate portfolio value with current prices
+  #   portfolio = SQA::Portfolio.new(initial_cash: 10_000)
+  #   portfolio.buy('AAPL', shares: 10, price: 150.0)
+  #   portfolio.buy('MSFT', shares: 5, price: 300.0)
+  #
+  #   current_prices = { 'AAPL' => 160.0, 'MSFT' => 310.0 }
+  #   portfolio.value(current_prices)  # => 10_000 - 1500 - 1500 + 1600 + 1550 = 10_150
+  #
+  # @example Without current prices (uses avg_cost)
+  #   portfolio.value  # Uses purchase prices if no current prices provided
+  #
   def value(current_prices = {})
     positions_value = @positions.sum do |ticker, pos|
       current_price = current_prices[ticker] || pos.avg_cost
@@ -186,6 +224,22 @@ class SQA::Portfolio
   # Get summary statistics
   # @param current_prices [Hash] Hash of ticker => current_price
   # @return [Hash] Summary statistics
+  #
+  # @example Get portfolio performance summary
+  #   portfolio = SQA::Portfolio.new(initial_cash: 10_000, commission: 1.0)
+  #   portfolio.buy('AAPL', shares: 10, price: 150.0)
+  #   portfolio.sell('AAPL', shares: 5, price: 160.0)
+  #
+  #   summary = portfolio.summary({ 'AAPL' => 165.0 })
+  #   summary[:initial_cash]        # => 10_000.0
+  #   summary[:current_cash]        # => 8798.0
+  #   summary[:positions_count]     # => 1
+  #   summary[:total_value]         # => 9623.0
+  #   summary[:profit_loss_percent] # => -3.77%
+  #   summary[:total_trades]        # => 2
+  #   summary[:buy_trades]          # => 1
+  #   summary[:sell_trades]         # => 1
+  #
   def summary(current_prices = {})
     {
       initial_cash: @initial_cash,

data/lib/sqa/stock.rb

@@ -131,6 +131,17 @@ class SQA::Stock
   # Silently handles errors since overview data is optional.
   #
   # @return [void]
+  #
+  # @example Update stock metadata from API
+  #   stock = SQA::Stock.new(ticker: 'AAPL')
+  #   stock.update  # Fetches latest company overview data
+  #   stock.data.overview['market_capitalization']  # => 2500000000000
+  #   stock.data.overview['pe_ratio']  # => 28.5
+  #
+  # @example Update is safe if API fails
+  #   stock.update  # No error raised if API is unavailable
+  #   # Warning logged but stock remains usable with cached data
+  #
   def update
     begin
       merge_overview

data/lib/sqa/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SQA
-  VERSION = '0.0.37'
+  VERSION = '0.0.38'
 end

data/mkdocs.yml

@@ -177,6 +177,7 @@ nav:
           - Overview: concepts/index.md
           - DataFrames: data_frame.md
           - Trading Strategies: strategy.md
+          - File Formats: file_formats.md
       - Technical Indicators:
           - Overview: indicators/index.md
           - Indicator Details: indicators.md

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sqa
 version: !ruby/object:Gem::Version
-  version: 0.0.37
+  version: 0.0.38
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -426,7 +426,6 @@ files:
 - data/talk_talk.json
 - develop_summary.md
 - docs/.gitignore
-- docs/IMPROVEMENT_PLAN.md
 - docs/advanced/backtesting.md
 - docs/advanced/ensemble.md
 - docs/advanced/fpop.md
@@ -507,6 +506,7 @@ files:
 - docs/data-sources/index.md
 - docs/data_frame.md
 - docs/factors_that_impact_price.md
+- docs/file_formats.md
 - docs/finviz.md
 - docs/fx_pro_bit.md
 - docs/genetic_programming.md