📦 SQA::DataFrame¶

Description

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.

Source Information

Defined in: lib/sqa/data_frame.rb:28

Inherits from: Object

🏭 Class Methods¶

`.is_date?(value)`¶

Checks if a value appears to be a date string.

Parameters

Name	Type	Description
`value`	`Object`	Value to check

Returns

Type: Boolean

true if value matches YYYY-MM-DD format

Source Location

lib/sqa/data_frame.rb:246

`.load(source:, transformers: = {}, mapping: = {})`¶

Load a DataFrame from a file source This is the primary method for loading persisted DataFrames

Note: For cached CSV files, transformers and mapping should typically be empty since transformations were already applied when the data was first fetched. We only apply them if the CSV has old-format column names that need migration.

Parameters

Name	Type	Description
`source`	`String, Pathname`	Path to CSV file
`transformers`	`Hash`	Column transformations to apply (usually not needed for cached data)
`mapping`	`Hash`	Column name mappings (usually not needed for cached data)

Returns

Type: SQA::DataFrame

Loaded DataFrame

Source Location

lib/sqa/data_frame.rb:283

`.from_aofh(aofh, mapping: = {}, transformers: = {})`¶

Creates a DataFrame from an array of hashes.

Parameters

Name	Type	Description
`aofh`	`Array<Hash>`	Array of hash records
`mapping`	`Hash`	Column name mappings to apply
`transformers`	`Hash`	Column transformers to apply

Returns

Type: SQA::DataFrame

New DataFrame instance

Usage Examples

data = [{ "date" => "2024-01-01", "price" => 100.0 }]
df = SQA::DataFrame.from_aofh(data)

Source Location

lib/sqa/data_frame.rb:302

`.from_csv_file(source, mapping: = {}, transformers: = {})`¶

Creates a DataFrame from a CSV file.

Parameters

Name	Type	Description
`source`	`String, Pathname`	Path to CSV file
`mapping`	`Hash`	Column name mappings to apply
`transformers`	`Hash`	Column transformers to apply

Returns

Type: SQA::DataFrame

New DataFrame instance

Source Location

lib/sqa/data_frame.rb:324

`.from_json_file(source, mapping: = {}, transformers: = {})`¶

Creates a DataFrame from a JSON file.

Parameters

Name	Type	Description
`source`	`String, Pathname`	Path to JSON file containing array of objects
`mapping`	`Hash`	Column name mappings to apply
`transformers`	`Hash`	Column transformers to apply

Returns

Type: SQA::DataFrame

New DataFrame instance

Source Location

lib/sqa/data_frame.rb:335

`.generate_mapping(keys)`¶

Generates a mapping of original keys to underscored keys.

Parameters

Name	Type	Description
`keys`	`Array<String>`	Original key names

Returns

Type: Hash{String => Symbol}

Mapping from original to underscored keys

Source Location

lib/sqa/data_frame.rb:344

`.underscore_key(key)`¶

Converts a key string to underscored snake_case format.

Parameters

Name	Type	Description
`key`	`String`	Key to convert

Returns

Type: Symbol

Underscored key as symbol

Usage Examples

underscore_key("closePrice")  # => :close_price
underscore_key("Close Price") # => :close_price

Source Location

lib/sqa/data_frame.rb:359

`.sanitize_key()`¶

Converts a key string to underscored snake_case format.

Parameters

Name	Type	Description
`key`	`String`	Key to convert

Returns

Type: Symbol

Underscored key as symbol

Usage Examples

underscore_key("closePrice")  # => :close_price
underscore_key("Close Price") # => :close_price

Source Location

lib/sqa/data_frame.rb:371

`.normalize_keys(hash, adapter_mapping: = {})`¶

Normalizes all keys in a hash to snake_case format.

Parameters

Name	Type	Description
`hash`	`Hash`	Hash with keys to normalize
`adapter_mapping`	`Hash`	Optional pre-mapping to apply first

Returns

Type: Hash

Hash with normalized keys

Source Location

lib/sqa/data_frame.rb:378

`.rename(hash, mapping)`¶

Renames keys in a hash according to a mapping.

Parameters

Name	Type	Description
`hash`	`Hash`	Hash to modify
`mapping`	`Hash`	Old key to new key mapping

Returns

Type: Hash

Modified hash

Source Location

lib/sqa/data_frame.rb:389

`.aofh_to_hofa(aofh, mapping: = {}, transformers: = {})`¶

Converts array of hashes to hash of arrays format.

Parameters

Name	Type	Description
`aofh`	`Array<Hash>`	Array of hash records
`mapping`	`Hash`	Column name mappings (unused, for API compatibility)
`transformers`	`Hash`	Column transformers (unused, for API compatibility)

Returns

Type: Hash{String => Array}

Hash with column names as keys and arrays as values

Source Location

lib/sqa/data_frame.rb:400

🔨 Instance Methods¶

`#data()`¶

Returns

Type: Polars::DataFrame

The underlying Polars DataFrame

Source Location

lib/sqa/data_frame.rb:33

`#data=(value)`¶

Sets the attribute data

Parameters

Name	Type	Description
`value`	`Any`	the value to set the attribute data to.

Source Location

lib/sqa/data_frame.rb:33

`#initialize(raw_data = nil, mapping: = {}, transformers: = {})`¶

Creates a new DataFrame instance.

Parameters

Name	Type	Description
`raw_data`	`Hash, Array, Polars::DataFrame, nil`	Initial data for the DataFrame
`mapping`	`Hash`	Column name mappings to apply (old_name => new_name)
`transformers`	`Hash`	Column transformers to apply (column => lambda)

Returns

Type: DataFrame

a new instance of DataFrame

Usage Examples

df = SQA::DataFrame.new(data, mapping: { "Close" => "close_price" })

df = SQA::DataFrame.new(data, transformers: { "price" => ->(v) { v.to_f } })

Source Location

lib/sqa/data_frame.rb:47

`#apply_transformers!(transformers)`¶

Applies transformer functions to specified columns in place.

Parameters

Name	Type	Description
`transformers`	`Hash{String, Symbol => Proc}`	Column name to transformer mapping

Returns

Type: void

Usage Examples

df.apply_transformers!({ "price" => ->(v) { v.to_f }, "volume" => ->(v) { v.to_i } })

Source Location

lib/sqa/data_frame.rb:65

`#rename_columns!(mapping)`¶

Renames columns according to the provided mapping in place.

Parameters

Name	Type	Description
`mapping`	`Hash{String, Symbol => String}`	Old column name to new column name mapping

Returns

Type: void

Usage Examples

df.rename_columns!({ "open" => "open_price", "close" => "close_price" })

Source Location

lib/sqa/data_frame.rb:82

`#append!(other_df)`¶

Appends another DataFrame to this one in place.

Parameters

Name	Type	Description
`other_df`	`SQA::DataFrame`	DataFrame to append

Returns

Type: void

Usage Examples

df1.append!(df2)

Source Location

lib/sqa/data_frame.rb:107

`#concat!()`¶

Appends another DataFrame to this one in place.

Parameters

Name	Type	Description
`other_df`	`SQA::DataFrame`	DataFrame to append

Returns

Type: void

Usage Examples

df1.append!(df2)

Source Location

lib/sqa/data_frame.rb:124

`#concat_and_deduplicate!(other_df, sort_column: = "timestamp", descending: = false)`¶

Concatenate another DataFrame, remove duplicates, and sort This is the preferred method for updating CSV data to prevent duplicates

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.

Parameters

Name	Type	Description
`other_df`	`SQA::DataFrame`	DataFrame to append
`sort_column`	`String`	Column to use for deduplication and sorting (default: "timestamp")
`descending`	`Boolean`	Sort order - false for ascending (oldest first, TA-Lib compatible), true for descending

Usage Examples

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)

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

Source Location

lib/sqa/data_frame.rb:135

`#columns()`¶

Returns the column names of the DataFrame.

Returns

Type: Array<String>

List of column names

Source Location

lib/sqa/data_frame.rb:159

`#keys()`¶

Returns the column names of the DataFrame. Alias for {#columns}.

Returns

Type: Array<String>

List of column names

Source Location

lib/sqa/data_frame.rb:167

`#vectors()`¶

Returns the column names of the DataFrame. Alias for {#columns}.

Returns

Type: Array<String>

List of column names

Source Location

lib/sqa/data_frame.rb:170

`#to_h()`¶

Converts the DataFrame to a Ruby Hash.

Returns

Type: Hash{Symbol => Array}

Hash with column names as keys and column data as arrays

Usage Examples

df.to_h  # => { timestamp: ["2024-01-01", ...], close_price: [100.0, ...] }

Source Location

lib/sqa/data_frame.rb:179

`#to_csv(path_to_file)`¶

Writes the DataFrame to a CSV file.

Parameters

Name	Type	Description
`path_to_file`	`String, Pathname`	Path to output CSV file

Returns

Type: void

Usage Examples

stock = SQA::Stock.new(ticker: 'AAPL')
stock.df.to_csv('aapl_prices.csv')

df.to_csv(Pathname.new('data/exports/prices.csv'))

Source Location

lib/sqa/data_frame.rb:187

`#size()`¶

Returns the number of rows in the DataFrame.

Returns

Type: Integer

Row count

Source Location

lib/sqa/data_frame.rb:194

`#nrows()`¶

Returns the number of rows in the DataFrame.

Returns

Type: Integer

Row count

Source Location

lib/sqa/data_frame.rb:197

`#length()`¶

Returns the number of rows in the DataFrame.

Returns

Type: Integer

Row count

Source Location

lib/sqa/data_frame.rb:198

`#ncols()`¶

Returns the number of columns in the DataFrame.

Returns

Type: Integer

Column count

Source Location

lib/sqa/data_frame.rb:203

`#fpl(column: = 'adj_close_price', fpop: = 14)`¶

FPL Analysis - Calculate Future Period Loss/Profit

Parameters

Name	Type	Description
`column`	`String, Symbol`	Column name containing prices (default: "adj_close_price")
`fpop`	`Integer`	Future Period of Performance (days to look ahead)

Returns

Type: Array<Array<Float, Float>>

Array of [min_delta, max_delta] pairs

Usage Examples

stock = SQA::Stock.new(ticker: 'AAPL')
fpl_data = stock.df.fpl(fpop: 10)

Source Location

lib/sqa/data_frame.rb:218

`#fpl_analysis(column: = 'adj_close_price', fpop: = 14)`¶

FPL Analysis with risk metrics and classification

Parameters

Name	Type	Description
`column`	`String, Symbol`	Column name containing prices (default: "adj_close_price")
`fpop`	`Integer`	Future Period of Performance

Returns

Type: Array<Hash>

Array of analysis hashes

Usage Examples

analysis = stock.df.fpl_analysis(fpop: 10)
analysis.first[:direction]  # => :UP, :DOWN, :UNCERTAIN, or :FLAT
analysis.first[:magnitude]  # => Average expected movement percentage
analysis.first[:risk]       # => Volatility range

Source Location

lib/sqa/data_frame.rb:236

`#method_missing(method_name, *args, &block)`¶

Delegates unknown methods to the underlying Polars DataFrame. This allows direct access to Polars methods like filter, select, etc.

Parameters

Name	Type	Description
`method_name`	`Symbol`	Method name being called
`args`	`Array`	Method arguments
`block`	`Proc`	Optional block

Returns

Type: Object

Result from Polars DataFrame method

Source Location

lib/sqa/data_frame.rb:257

`#respond_to_missing?(method_name, include_private = false)`¶

Checks if the DataFrame responds to a method.

Parameters

Name	Type	Description
`method_name`	`Symbol`	Method name to check
`include_private`	`Boolean`	Include private methods

Returns

Type: Boolean

true if method is available

Source Location

lib/sqa/data_frame.rb:267

📦 SQA::DataFrame¶

🏭 Class Methods¶

`.is_date?(value)`¶

`.load(source:, transformers: = {}, mapping: = {})`¶

`.from_aofh(aofh, mapping: = {}, transformers: = {})`¶

`.from_csv_file(source, mapping: = {}, transformers: = {})`¶

`.from_json_file(source, mapping: = {}, transformers: = {})`¶

`.generate_mapping(keys)`¶

`.underscore_key(key)`¶

`.sanitize_key()`¶

`.normalize_keys(hash, adapter_mapping: = {})`¶

`.rename(hash, mapping)`¶

`.aofh_to_hofa(aofh, mapping: = {}, transformers: = {})`¶

🔨 Instance Methods¶

`#data()`¶

`#data=(value)`¶

`#initialize(raw_data = nil, mapping: = {}, transformers: = {})`¶

`#apply_transformers!(transformers)`¶

`#rename_columns!(mapping)`¶

`#append!(other_df)`¶

`#concat!()`¶

`#concat_and_deduplicate!(other_df, sort_column: = "timestamp", descending: = false)`¶

`#columns()`¶

`#keys()`¶

`#vectors()`¶

`#to_h()`¶

`#to_csv(path_to_file)`¶

`#size()`¶

`#nrows()`¶

`#length()`¶

`#ncols()`¶

`#fpl(column: = 'adj_close_price', fpop: = 14)`¶

`#fpl_analysis(column: = 'adj_close_price', fpop: = 14)`¶

`#method_missing(method_name, *args, &block)`¶

`#respond_to_missing?(method_name, include_private = false)`¶

📝 Attributes¶

🔄 `data` read/write¶

📦 SQA::DataFrame¶

🏭 Class Methods¶

.is_date?(value)¶

.load(source:, transformers: = {}, mapping: = {})¶

.from_aofh(aofh, mapping: = {}, transformers: = {})¶

.from_csv_file(source, mapping: = {}, transformers: = {})¶

.from_json_file(source, mapping: = {}, transformers: = {})¶

.generate_mapping(keys)¶

.underscore_key(key)¶

.sanitize_key()¶

.normalize_keys(hash, adapter_mapping: = {})¶

.rename(hash, mapping)¶

.aofh_to_hofa(aofh, mapping: = {}, transformers: = {})¶

🔨 Instance Methods¶

#data()¶

#data=(value)¶

#initialize(raw_data = nil, mapping: = {}, transformers: = {})¶

#apply_transformers!(transformers)¶

#rename_columns!(mapping)¶

#append!(other_df)¶

#concat!()¶

#concat_and_deduplicate!(other_df, sort_column: = "timestamp", descending: = false)¶

#columns()¶

#keys()¶

#vectors()¶

#to_h()¶

#to_csv(path_to_file)¶

#size()¶

#nrows()¶

#length()¶

#ncols()¶

#fpl(column: = 'adj_close_price', fpop: = 14)¶

#fpl_analysis(column: = 'adj_close_price', fpop: = 14)¶

#method_missing(method_name, *args, &block)¶

#respond_to_missing?(method_name, include_private = false)¶

📝 Attributes¶

🔄 data read/write¶

`.is_date?(value)`¶

`.load(source:, transformers: = {}, mapping: = {})`¶

`.from_aofh(aofh, mapping: = {}, transformers: = {})`¶

`.from_csv_file(source, mapping: = {}, transformers: = {})`¶

`.from_json_file(source, mapping: = {}, transformers: = {})`¶

`.generate_mapping(keys)`¶

`.underscore_key(key)`¶

`.sanitize_key()`¶

`.normalize_keys(hash, adapter_mapping: = {})`¶

`.rename(hash, mapping)`¶

`.aofh_to_hofa(aofh, mapping: = {}, transformers: = {})`¶

`#data()`¶

`#data=(value)`¶

`#initialize(raw_data = nil, mapping: = {}, transformers: = {})`¶

`#apply_transformers!(transformers)`¶

`#rename_columns!(mapping)`¶

`#append!(other_df)`¶

`#concat!()`¶

`#concat_and_deduplicate!(other_df, sort_column: = "timestamp", descending: = false)`¶

`#columns()`¶

`#keys()`¶

`#vectors()`¶

`#to_h()`¶

`#to_csv(path_to_file)`¶

`#size()`¶

`#nrows()`¶

`#length()`¶

`#ncols()`¶

`#fpl(column: = 'adj_close_price', fpop: = 14)`¶

`#fpl_analysis(column: = 'adj_close_price', fpop: = 14)`¶

`#method_missing(method_name, *args, &block)`¶

`#respond_to_missing?(method_name, include_private = false)`¶

🔄 `data` read/write¶