sqa 0.0.31 → 0.0.37

data/lib/sqa/data_frame/data.rb

@@ -21,9 +21,21 @@ class SQA::DataFrame
   #   data = SQA::DataFrame::Data.new(json_data)
   #
   class Data
+    # @!attribute [rw] ticker
+    #   @return [String, nil] Stock ticker symbol (e.g., 'AAPL', 'MSFT')
+    # @!attribute [rw] name
+    #   @return [String, nil] Company name
+    # @!attribute [rw] exchange
+    #   @return [String, nil] Exchange where stock trades (e.g., 'NASDAQ', 'NYSE')
+    # @!attribute [rw] source
+    #   @return [Symbol] Data source (:alpha_vantage, :yahoo_finance)
+    # @!attribute [rw] indicators
+    #   @return [Hash] Technical indicators configuration and cached values
+    # @!attribute [rw] overview
+    #   @return [Hash] Company overview data from API
     attr_accessor :ticker, :name, :exchange, :source, :indicators, :overview
 
-    # Initialize stock metadata
+    # Initializes stock metadata.
     #
     # Can be called in two ways:
     #   1. With a hash: SQA::DataFrame::Data.new(hash) - for JSON deserialization

data/lib/sqa/data_frame.rb

@@ -10,21 +10,43 @@ require_relative 'data_frame/data'
 require_relative 'data_frame/yahoo_finance'
 require_relative 'data_frame/alpha_vantage'
 
+# High-performance DataFrame wrapper around Polars for time series data manipulation.
+# Provides convenience methods for stock market data while leveraging Polars' Rust-backed
+# performance for vectorized operations.
+#
+# @example Creating from CSV
+#   df = SQA::DataFrame.load(source: "path/to/data.csv")
+#
+# @example Creating from array of hashes
+#   data = [{ timestamp: "2024-01-01", close: 100.0 }, { timestamp: "2024-01-02", close: 101.5 }]
+#   df = SQA::DataFrame.from_aofh(data)
+#
+# @example Accessing data
+#   prices = df["adj_close_price"].to_a
+#   df.columns  # => ["timestamp", "open_price", "high_price", ...]
+#
 class SQA::DataFrame
   extend Forwardable
 
+  # @!attribute [rw] data
+  #   @return [Polars::DataFrame] The underlying Polars DataFrame
   attr_accessor :data
 
+  # Creates a new DataFrame instance.
+  #
+  # @param raw_data [Hash, Array, Polars::DataFrame, nil] Initial data for the DataFrame
+  # @param mapping [Hash] Column name mappings to apply (old_name => new_name)
+  # @param transformers [Hash] Column transformers to apply (column => lambda)
+  #
+  # @example With column mapping
+  #   df = SQA::DataFrame.new(data, mapping: { "Close" => "close_price" })
+  #
+  # @example With transformers
+  #   df = SQA::DataFrame.new(data, transformers: { "price" => ->(v) { v.to_f } })
+  #
   def initialize(raw_data = nil, mapping: {}, transformers: {})
     @data = Polars::DataFrame.new(raw_data || [])
 
-    debug_me{[
-      :raw_data,
-      :mapping,
-      :transformers,
-      '@data'
-    ]}
-
     # IMPORTANT: Rename columns FIRST, then apply transformers
     # Transformers expect renamed column names
     rename_columns!(mapping) unless mapping.empty?
@@ -32,6 +54,14 @@ class SQA::DataFrame
   end
 
 
+  # Applies transformer functions to specified columns in place.
+  #
+  # @param transformers [Hash{String, Symbol => Proc}] Column name to transformer mapping
+  # @return [void]
+  #
+  # @example
+  #   df.apply_transformers!({ "price" => ->(v) { v.to_f }, "volume" => ->(v) { v.to_i } })
+  #
   def apply_transformers!(transformers)
     transformers.each do |col, transformer|
       col_name = col.to_s
@@ -41,7 +71,14 @@ class SQA::DataFrame
     end
   end
 
-
+  # Renames columns according to the provided mapping in place.
+  #
+  # @param mapping [Hash{String, Symbol => String}] Old column name to new column name mapping
+  # @return [void]
+  #
+  # @example
+  #   df.rename_columns!({ "open" => "open_price", "close" => "close_price" })
+  #
   def rename_columns!(mapping)
     # Normalize mapping keys to strings for consistent lookup
     # mapping can have string or symbol keys, columns are always strings
@@ -58,6 +95,15 @@ class SQA::DataFrame
   end
 
 
+  # Appends another DataFrame to this one in place.
+  #
+  # @param other_df [SQA::DataFrame] DataFrame to append
+  # @return [void]
+  # @raise [RuntimeError] If the resulting row count doesn't match expected
+  #
+  # @example
+  #   df1.append!(df2)
+  #
   def append!(other_df)
     self_row_count = @data.shape[0]
     other_row_count = other_df.data.shape[0]
@@ -77,32 +123,83 @@ class SQA::DataFrame
   end
   alias concat! append!
 
+  # Concatenate another DataFrame, remove duplicates, and sort
+  # This is the preferred method for updating CSV data to prevent duplicates
+  #
+  # @param other_df [SQA::DataFrame] DataFrame to append
+  # @param sort_column [String] Column to use for deduplication and sorting (default: "timestamp")
+  # @param descending [Boolean] Sort order - false for ascending (oldest first, TA-Lib compatible), true for descending
+  #
+  # 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.
+  def concat_and_deduplicate!(other_df, sort_column: "timestamp", descending: false)
+    # Enforce ascending order for TA-Lib compatibility
+    if descending
+      warn "[SQA WARNING] TA-Lib requires ascending (oldest-first) order. Forcing descending: false"
+      descending = false
+    end
+
+    # Concatenate the dataframes
+    @data = if @data.shape[0] == 0
+              other_df.data
+            else
+              @data.vstack(other_df.data)
+            end
+
+    # Remove duplicates based on sort_column, keeping first occurrence
+    @data = @data.unique(subset: [sort_column], keep: "first")
+
+    # Sort by the specified column (Polars uses 'reverse' for descending)
+    @data = @data.sort(sort_column, reverse: descending)
+  end
+
+  # Returns the column names of the DataFrame.
+  #
+  # @return [Array<String>] List of column names
   def columns
     @data.columns
   end
 
-
+  # Returns the column names of the DataFrame.
+  # Alias for {#columns}.
+  #
+  # @return [Array<String>] List of column names
   def keys
     @data.columns
   end
   alias vectors keys
 
+  # Converts the DataFrame to a Ruby Hash.
+  #
+  # @return [Hash{Symbol => Array}] Hash with column names as keys and column data as arrays
+  #
+  # @example
+  #   df.to_h  # => { timestamp: ["2024-01-01", ...], close_price: [100.0, ...] }
+  #
   def to_h
     @data.columns.map { |col| [col.to_sym, @data[col].to_a] }.to_h
   end
 
-
+  # Writes the DataFrame to a CSV file.
+  #
+  # @param path_to_file [String, Pathname] Path to output CSV file
+  # @return [void]
   def to_csv(path_to_file)
     @data.write_csv(path_to_file)
   end
 
-
+  # Returns the number of rows in the DataFrame.
+  #
+  # @return [Integer] Row count
   def size
     @data.height
   end
   alias nrows size
   alias length size
 
+  # Returns the number of columns in the DataFrame.
+  #
+  # @return [Integer] Column count
   def ncols
     @data.width
   end
@@ -142,23 +239,31 @@ class SQA::DataFrame
   end
 
 
+  # Checks if a value appears to be a date string.
+  #
+  # @param value [Object] Value to check
+  # @return [Boolean] true if value matches YYYY-MM-DD format
   def self.is_date?(value)
     value.is_a?(String) && !/\d{4}-\d{2}-\d{2}/.match(value).nil?
   end
 
-
+  # Delegates unknown methods to the underlying Polars DataFrame.
+  # This allows direct access to Polars methods like filter, select, etc.
+  #
+  # @param method_name [Symbol] Method name being called
+  # @param args [Array] Method arguments
+  # @param block [Proc] Optional block
+  # @return [Object] Result from Polars DataFrame method
   def method_missing(method_name, *args, &block)
-    if @data.respond_to?(method_name)
-      self.class.send(:define_method, method_name) do |*method_args, &method_block|
-        @data.send(method_name, *method_args, &method_block)
-      end
-      send(method_name, *args, &block)
-    else
-      super
-    end
+    return super unless @data.respond_to?(method_name)
+    @data.send(method_name, *args, &block)
   end
 
-
+  # Checks if the DataFrame responds to a method.
+  #
+  # @param method_name [Symbol] Method name to check
+  # @param include_private [Boolean] Include private methods
+  # @return [Boolean] true if method is available
   def respond_to_missing?(method_name, include_private = false)
     @data.respond_to?(method_name) || super
   end
@@ -183,45 +288,74 @@ class SQA::DataFrame
       new(df, mapping: mapping, transformers: transformers)
     end
 
+    # Creates a DataFrame from an array of hashes.
+    #
+    # @param aofh [Array<Hash>] Array of hash records
+    # @param mapping [Hash] Column name mappings to apply
+    # @param transformers [Hash] Column transformers to apply
+    # @return [SQA::DataFrame] New DataFrame instance
+    #
+    # @example
+    #   data = [{ "date" => "2024-01-01", "price" => 100.0 }]
+    #   df = SQA::DataFrame.from_aofh(data)
+    #
     def from_aofh(aofh, mapping: {}, transformers: {})
+      return new({}, mapping: mapping, transformers: transformers) if aofh.empty?
+
+      # Sanitize keys to strings and convert to hash of arrays (Polars-compatible format)
       aoh_sanitized = aofh.map { |entry| entry.transform_keys(&:to_s) }
       columns = aoh_sanitized.first.keys
-      data = aoh_sanitized.map(&:values)
-      df = Polars::DataFrame.new(
-        data,
-        columns: columns
-      )
-      new(df)
-    end
 
-
-    def from_csv_file(source, mapping: {}, transformers: {})
-      debug_me do
-        %i[
-          source
-          mapping
-          transformers
-        ]
+      # Convert array-of-hashes to hash-of-arrays for Polars
+      hofa = columns.each_with_object({}) do |col, hash|
+        hash[col] = aoh_sanitized.map { |row| row[col] }
       end
 
-      df = Polars.read_csv(source)
+      df = Polars::DataFrame.new(hofa)
       new(df, mapping: mapping, transformers: transformers)
     end
 
+    # Creates a DataFrame from a CSV file.
+    #
+    # @param source [String, Pathname] Path to CSV file
+    # @param mapping [Hash] Column name mappings to apply
+    # @param transformers [Hash] Column transformers to apply
+    # @return [SQA::DataFrame] New DataFrame instance
+    def from_csv_file(source, mapping: {}, transformers: {})
+      df = Polars.read_csv(source)
+      new(df, mapping: mapping, transformers: transformers)
+    end
 
+    # Creates a DataFrame from a JSON file.
+    #
+    # @param source [String, Pathname] Path to JSON file containing array of objects
+    # @param mapping [Hash] Column name mappings to apply
+    # @param transformers [Hash] Column transformers to apply
+    # @return [SQA::DataFrame] New DataFrame instance
     def from_json_file(source, mapping: {}, transformers: {})
       aofh = JSON.parse(File.read(source)).map { |entry| entry.transform_keys(&:to_s) }
       from_aofh(aofh, mapping: mapping, transformers: transformers)
     end
 
-
+    # Generates a mapping of original keys to underscored keys.
+    #
+    # @param keys [Array<String>] Original key names
+    # @return [Hash{String => Symbol}] Mapping from original to underscored keys
     def generate_mapping(keys)
       keys.each_with_object({}) do |key, hash|
         hash[key.to_s] = underscore_key(key.to_s)
       end
     end
 
-
+    # Converts a key string to underscored snake_case format.
+    #
+    # @param key [String] Key to convert
+    # @return [Symbol] Underscored key as symbol
+    #
+    # @example
+    #   underscore_key("closePrice")  # => :close_price
+    #   underscore_key("Close Price") # => :close_price
+    #
     def underscore_key(key)
       key.to_s
          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
@@ -236,19 +370,33 @@ class SQA::DataFrame
 
     alias sanitize_key underscore_key
 
+    # Normalizes all keys in a hash to snake_case format.
+    #
+    # @param hash [Hash] Hash with keys to normalize
+    # @param adapter_mapping [Hash] Optional pre-mapping to apply first
+    # @return [Hash] Hash with normalized keys
     def normalize_keys(hash, adapter_mapping: {})
       hash = rename(hash, adapter_mapping) unless adapter_mapping.empty?
       mapping = generate_mapping(hash.keys)
       rename(hash, mapping)
     end
 
-
+    # Renames keys in a hash according to a mapping.
+    #
+    # @param hash [Hash] Hash to modify
+    # @param mapping [Hash] Old key to new key mapping
+    # @return [Hash] Modified hash
     def rename(hash, mapping)
       mapping.each { |old_key, new_key| hash[new_key] = hash.delete(old_key) if hash.key?(old_key) }
       hash
     end
 
-
+    # Converts array of hashes to hash of arrays format.
+    #
+    # @param aofh [Array<Hash>] Array of hash records
+    # @param mapping [Hash] Column name mappings (unused, for API compatibility)
+    # @param transformers [Hash] Column transformers (unused, for API compatibility)
+    # @return [Hash{String => Array}] Hash with column names as keys and arrays as values
     def aofh_to_hofa(aofh, mapping: {}, transformers: {})
       hofa = Hash.new { |h, k| h[k.downcase] = [] }
       aofh.each { |entry| entry.each { |key, value| hofa[key.to_s.downcase] << value } }

data/lib/sqa/errors.rb

@@ -1,30 +1,92 @@
 # lib/sqa/errors.rb
+#
+# SQA Exception Classes
+# All custom exceptions inherit from StandardError or RuntimeError
+# to ensure they can be caught by generic rescue blocks.
 
-# raised when a method is still in TODO state
+module SQA
+  # Raised when unable to fetch data from a data source (API, file, etc.).
+  # Wraps the original exception for debugging purposes.
+  #
+  # @example Raising with original error
+  #   begin
+  #     response = api.fetch(ticker)
+  #   rescue Faraday::Error => e
+  #     raise SQA::DataFetchError.new("Failed to fetch #{ticker}", original: e)
+  #   end
+  #
+  # @example Accessing original error
+  #   begin
+  #     stock = SQA::Stock.new(ticker: 'INVALID')
+  #   rescue SQA::DataFetchError => e
+  #     puts e.message
+  #     puts e.original_error.class if e.original_error
+  #   end
+  #
+  class DataFetchError < StandardError
+    # @return [Exception, nil] The original exception that caused this error
+    attr_reader :original_error
+
+    # Creates a new DataFetchError.
+    #
+    # @param message [String] Error message describing the fetch failure
+    # @param original [Exception, nil] The original exception that was caught
+    def initialize(message, original: nil)
+      @original_error = original
+      super(message)
+    end
+  end
+
+  # Raised when SQA configuration is invalid or missing.
+  # Common causes include missing API keys or invalid data directories.
+  #
+  # @example
+  #   raise SQA::ConfigurationError, "API key not set"
+  #
+  class ConfigurationError < StandardError; end
+
+  # Raised when a method parameter is invalid.
+  # Inherits from ArgumentError for semantic clarity.
+  #
+  # @example
+  #   raise SQA::BadParameterError, "Expected a Class or Method"
+  #
+  class BadParameterError < ArgumentError; end
+end
+
+# Global alias for backward compatibility.
+# @deprecated Use SQA::BadParameterError instead
+BadParameterError = SQA::BadParameterError
+
+# Raised when an external API returns an error response.
+# Automatically logs the error using debug_me before raising.
+#
+# @example
+#   ApiError.raise("Rate limit exceeded")
+#
 class ApiError < RuntimeError
+  # Raises an ApiError with debug logging.
+  #
+  # @param why [String] The error message from the API
+  # @raise [ApiError] Always raises after logging
   def self.raise(why)
-    puts "="*64
-    puts "== API Error"
-    puts why
-    puts
-    puts "Callback trace:"
-    puts caller
-    puts "="*64
+    debug_me {"API Error: #{why}"}
     super
   end
 end
 
-# raised when a method is still in TODO state
+# Raised when a feature is not yet implemented.
+# Automatically logs using debug_me before raising.
+#
+# @example
+#   NotImplemented.raise
+#
 class NotImplemented < RuntimeError
+  # Raises a NotImplemented error with debug logging.
+  #
+  # @raise [NotImplemented] Always raises after logging
   def self.raise
-    puts "="*64
-    puts "== Not Yet Implemented"
-    puts "Callback trace:"
-    puts caller
-    puts "="*64
+    debug_me {"Not Yet Implemented"}
     super
   end
 end
-
-# raised when an API contract is broken
-class BadParameterError < ArgumentError; end

data/lib/sqa/indicator.rb

@@ -1,8 +1,21 @@
 # lib/sqa/indicator.rb
 # frozen_string_literal: true
 
-require 'sqa/tai'
+# Try to load TA-Lib indicators, but make them optional
+# This allows the library to work without TA-Lib installed for basic data loading
+begin
+  require 'sqa/tai'
 
-# Use SQA::TAI directly for all technical analysis indicators
-# SQAI is a shortcut alias for SQA::TAI
-SQAI = SQA::TAI
+  # Use SQA::TAI directly for all technical analysis indicators
+  # SQAI is a shortcut alias for SQA::TAI
+  SQAI = SQA::TAI
+rescue LoadError, Fiddle::DLError => e
+  # TA-Lib not available - define a stub that gives helpful errors
+  warn "Warning: TA-Lib not available (#{e.class}: #{e.message}). Technical indicators will not work." if $VERBOSE
+
+  module SQAI
+    def self.method_missing(method, *args, &block)
+      raise "Technical indicators require TA-Lib to be installed. Please install libta-lib system library. Visit: http://ta-lib.org/hdr_dw.html"
+    end
+  end
+end

data/lib/sqa/init.rb

@@ -1,12 +1,35 @@
 # sqa/lib/sqa/init.rb
 
+# SQA (Simple Qualitative Analysis) - Ruby library for stock market technical analysis.
+# Provides high-performance data structures, trading strategies, and integrates with
+# the sqa-tai gem for 150+ technical indicators.
+#
+# @example Basic usage
+#   require 'sqa'
+#   SQA.init
+#   stock = SQA::Stock.new(ticker: 'AAPL')
+#   prices = stock.df["adj_close_price"].to_a
+#
+# @example With configuration
+#   SQA.init
+#   SQA.config.data_dir = "~/my_data"
+#   SQA.config.lazy_update = true
+#
 module SQA
 	class << self
-		@@config = nil
-		@@av_api_key = ENV['AV_API_KEY'] || ENV['ALPHAVANTAGE_API_KEY']
+		# @!attribute [w] config
+		#   @return [SQA::Config] Configuration instance
+		attr_writer :config
 
-		# Initializes the SQA modules
-		# returns the configuration
+		# Initializes the SQA library.
+		# Should be called once at application startup.
+		#
+		# @param argv [Array<String>, String] Command line arguments (default: ARGV)
+		# @return [SQA::Config] The configuration instance
+		#
+		# @example
+		#   SQA.init
+		#   SQA.init("--debug --verbose")
 		#
 		def init(argv=ARGV)
 			if argv.is_a? String
@@ -15,10 +38,10 @@ module SQA
 
 
 			# Ran at SQA::Config elaboration time
-			# @@config = Config.new
+			# @config = Config.new
 
 			if defined? CLI
-				CLI.run!    # TODO: how to parse a fake argv?  (argv)
+				CLI.run!    # CLI handles its own argument parsing
 			else
 				# There are no real command line parameters
 				# because the sqa gem is being required within
@@ -30,29 +53,61 @@ module SQA
 			config
 		end
 
+		# Returns the Alpha Vantage API key.
+		# Reads from AV_API_KEY or ALPHAVANTAGE_API_KEY environment variables.
+		#
+		# @return [String] The API key
+		# @raise [SQA::ConfigurationError] If no API key is set
 		def av_api_key
-			@@av_api_key || raise('Alpha Vantage API key not set. Set AV_API_KEY or ALPHAVANTAGE_API_KEY environment variable.')
+			@av_api_key ||= ENV['AV_API_KEY'] || ENV['ALPHAVANTAGE_API_KEY']
+			@av_api_key || raise(SQA::ConfigurationError, 'Alpha Vantage API key not set. Set AV_API_KEY or ALPHAVANTAGE_API_KEY environment variable.')
 		end
 
-		# Legacy accessor for backward compatibility
+		# Sets the Alpha Vantage API key.
+		#
+		# @param key [String] The API key to set
+		# @return [String] The key that was set
+		def av_api_key=(key)
+			@av_api_key = key
+		end
+
+		# Legacy accessor for backward compatibility with SQA.av.key usage.
+		#
+		# @return [SQA] Self, to allow SQA.av.key calls
 		def av
 			self
 		end
 
-		# For compatibility with old SQA.av.key usage
+		# Returns the API key for compatibility with old SQA.av.key usage.
+		#
+		# @return [String] The API key
+		# @raise [SQA::ConfigurationError] If no API key is set
 		def key
 			av_api_key
 		end
 
-		def debug?() 						= @@config.debug?
-		def verbose?() 					= @@config.verbose?
+		# Returns whether debug mode is enabled.
+		# @return [Boolean] true if debug mode is on
+		def debug?() 						= @config&.debug?
+
+		# Returns whether verbose mode is enabled.
+		# @return [Boolean] true if verbose mode is on
+		def verbose?() 					= @config&.verbose?
 
+		# Expands ~ to user's home directory in filepath.
+		#
+		# @param filepath [String] Path potentially containing ~
+		# @return [String] Path with ~ expanded
 		def homify(filepath) 		= filepath.gsub(/^~/, Nenv.home)
+
+		# Returns the data directory as a Pathname.
+		#
+		# @return [Pathname] Data directory path
 		def data_dir() 					= Pathname.new(config.data_dir)
-		def config()            = @@config
 
-		def config=(an_object)
-			@@config = an_object
-		end
+		# Returns the current configuration.
+		#
+		# @return [SQA::Config] Configuration instance
+		def config()            = @config
 	end
 end

data/lib/sqa/pattern_matcher.rb

@@ -214,13 +214,13 @@ module SQA
     def pattern_quality(pattern)
       return nil if pattern.size < 3
 
-      # Trend strength
-      first = pattern.first
-      last = pattern.last
+      # Trend strength (convert to float to avoid integer division)
+      first = pattern.first.to_f
+      last = pattern.last.to_f
       trend = (last - first) / first
 
       # Volatility
-      returns = pattern.each_cons(2).map { |a, b| (b - a) / a }
+      returns = pattern.each_cons(2).map { |a, b| (b - a).to_f / a }
       volatility = standard_deviation(returns)
 
       # Smoothness (how linear is the trend?)

data/lib/sqa/portfolio.rb

@@ -5,7 +5,7 @@ require 'date'
 require 'csv'
 
 class SQA::Portfolio
-  attr_accessor :positions, :trades, :cash, :initial_cash
+  attr_accessor :positions, :trades, :cash, :initial_cash, :commission
 
   # Represents a single position in the portfolio
   Position = Struct.new(:ticker, :shares, :avg_cost, :total_cost) do