optrade.utils

---

optrade.utils.directories

clean_up_file(file_path)

Removes a file from the filesystem.

Parameters:

file_path (str) – Path to the file to be removed

Returns:

None

Return type:

None

clean_up_dir(dir_path)

Remove a directory and all its contents (files and subdirectories).

Parameters:

dir_path (str) – Path to the directory to be removed

Return type:

None

set_contract_dir(SCRIPT_DIR, root='AAPL', start_date='20231107', end_date='20241114', contract_stride=5, interval_min=1, right='C', target_tte=30, tte_tolerance=(25, 35), moneyness='OTM', strike_band=0.05, volatility_scaled=True, volatility_scalar=1.0, hist_vol=None, save_dir=None, dev_mode=False)

Sets up the directory structure for saving historical contract data.

Parameters:

• SCRIPT_DIR (Path) – Path to the script directory

• root (str) – Root symbol of the contract

• start_date (str) – Start date of the contract data

• end_date (str) – End date of the contract data

• contract_stride (int) – Number of days between contracts

• interval_min (int) – Interval in minutes for the contract data

• right (str) – Right of the contract (C for call, P for put)

• target_tte (int) – Target time-to-expiration in days

• tte_tolerance (Tuple[int, int]) – Lower and upper bounds for time-to-expiration

• moneyness (str) – Moneyness of the contract (OTM, ATM, or ITM)

• strike_band (float) – Band around the ATM strike price to define ITM and OTM

• volatility_scaled (bool) – Whether to scale the strike price bands by historical volatility

• volatility_scalar (float) – Scalar to multiply the historical volatility by

• hist_vol (Optional[float]) – Historical volatility of the underlying

• save_dir (Optional[str]) – Directory to save the contract data

• dev_mode (bool) – Whether to use development mode

Returns:

Path – Path to the contract directory

Return type:

Path

optrade.utils.error_handlers

exception DataValidationError(message, error_code, real_start_date=None, real_end_date=None, verbose=True, warning=False)

Bases: Exception

Parameters:

• message (str)

• error_code (int)

• real_start_date (str | None)

• real_end_date (str | None)

• verbose (bool)

• warning (bool)

__init__(message, error_code, real_start_date=None, real_end_date=None, verbose=True, warning=False)

Parameters:

• message (str)

• error_code (int)

• real_start_date (str | None)

• real_end_date (str | None)

• verbose (bool)

• warning (bool)

optrade.utils.market_metrics

get_historical_vol(stock_data, volatility_type='period', verbose=False)

Calculate historical volatility using intraday data from regular trading hours (9:30AM-3:59PM). Uses mid prices ((bid+ask)/2) for return calculations to avoid bid-ask bounce. Properly accounts for overnight return removal between trading days.

Parameters:

• stock_data (DataFrame) – DataFrame with datetime column in format “YYYY-MM-DD HH:MM:SS” Must be sorted and contain regular intervals during trading hours

• volatility_type (str) – Type of volatility to calculate. Options: “daily”, “period”, “annualized”.

• verbose (bool)

Returns:

Volatility value based on the specified type

Return type:

float

get_train_historical_vol(root, start_date, end_date, interval_min, volatility_window, volatility_type)

Get historical volatility for a stock over a given time period.

Parameters:

• root (str) – Underlying stock symbol

• start_date (str) – Start date for the total dataset in YYYYMMDD format

• end_date (str) – End date for the total dataset in YYYYMMDD format

• interval_min (int) – Interval in minutes for the underlying stock data

• volatility_window (float) – Proportion of total days to use for historical volatility calculation

• volatility_type (str) – Type of historical volatility to use. Options: “daily”, “period”, “annualized”.

Returns:

Historical volatility value based on the specified type.

Return type:

float

get_previous_trading_day(date, n_days=1)

Returns the timestamp of the n-th previous NYSE trading day before date.

Parameters:

• date (Timestamp) – A pd.Timestamp

• n_days (int) – How many trading days to go back

Returns:

pd.Timestamp of the previous trading day

Return type:

Timestamp

get_rolling_volatility(reference_df, root, interval_min=20, return_type='log', time_col='datetime', dev_mode=False)

Computes realized volatility over a lookback window ending at each timestamp in reference_df[time_col], with diagnostics for missing data.

Parameters:

• reference_df (DataFrame)

• root (str)

• interval_min (int)

• return_type (str)

• time_col (str)

• dev_mode (bool)

Return type:

Series

optrade.utils.misc

format_time_dynamic(seconds)

fill_open_zeros(group)

Fills any zero values in the ‘mid_price’ column with the first non-zero value that occurs before 9:35 AM within each group of data.

Parameters:

group (DataFrame)

Return type:

DataFrame

generate_random_id(length=10)

Parameters:

length (int)

datetime_to_tensor(datetime_array, unit='s')

Convert various datetime formats to PyTorch tensor of timestamps.

Parameters:

• datetime_array (str | datetime64) – array-like of datetime values (can be strings, datetime objects, or datetime64)

• unit (str) – time unit for conversion (‘s’ for seconds, ‘ms’ for milliseconds, etc.)

Returns:

PyTorch tensor of integer timestamps in the specified unit

Return type:

Tensor

tensor_to_datetime(timestamp_tensor, unit='s', batch_mode=False)

Convert PyTorch tensor of timestamps back to numpy datetime64 array. :param timestamp_tensor: PyTorch tensor of integer timestamps :param unit: time unit used in conversion (‘s’ for seconds, ‘ms’ for milliseconds,

‘us’ for microseconds, ‘ns’ for nanoseconds)

Parameters:

• batch_mode (bool) – If True, handles tensor as batched (2D) data

• timestamp_tensor (Tensor)

• unit (str)

Returns:

numpy array of datetime64 values

Return type:

ndarray

run_test()

optrade.utils.stock_categories

class ThreeFactorLevel(value)

Bases: str, Enum

An enumeration.

LOW = 'low'

MEDIUM = 'medium'

HIGH = 'high'

class FiveFactorLevel(value)

Bases: str, Enum

An enumeration.

VERY_LOW = 'very_low'

LOW = 'low'

MEDIUM = 'medium'

HIGH = 'high'

VERY_HIGH = 'very_high'

class SectorType(value)

Bases: str, Enum

An enumeration.

TECH = 'technology'

HEALTHCARE = 'healthcare'

FINANCIAL = 'financial'

CONSUMER_CYCLICAL = 'consumer_cyclical'

CONSUMER_DEFENSIVE = 'consumer_defensive'

INDUSTRIAL = 'industrial'

ENERGY = 'energy'

MATERIALS = 'materials'

UTILITIES = 'utilities'

REAL_ESTATE = 'real_estate'

COMMUNICATION = 'communication'

class IndustryType(value)

Bases: str, Enum

An enumeration.

SEMICONDUCTOR = 'semiconductor'

SOFTWARE_APPLICATION = 'software_application'

SOFTWARE_INFRASTRUCTURE = 'software_infrastructure'

ELECTRONIC_COMPONENTS = 'electronic_components'

COMPUTER_HARDWARE = 'computer_hardware'

CONSUMER_ELECTRONICS = 'consumer_electronics'

BIOTECHNOLOGY = 'biotechnology'

PHARMACEUTICAL_MANUFACTURERS = 'pharmaceutical_manufacturers'

MEDICAL_DEVICES = 'medical_devices'

MEDICAL_CARE_FACILITIES = 'medical_care_facilities'

HEALTH_INFORMATION_SERVICES = 'health_information_services'

BANKS_REGIONAL = 'banks_regional'

BANKS_DIVERSIFIED = 'banks_diversified'

INSURANCE_PROPERTY_CASUALTY = 'insurance_property_casualty'

INSURANCE_LIFE = 'insurance_life'

ASSET_MANAGEMENT = 'asset_management'

CAPITAL_MARKETS = 'capital_markets'

AUTO_MANUFACTURERS = 'auto_manufacturers'

AUTO_PARTS = 'auto_parts'

APPAREL_RETAIL = 'apparel_retail'

DEPARTMENT_STORES = 'department_stores'

RESTAURANTS = 'restaurants'

LODGING = 'lodging'

TRAVEL_SERVICES = 'travel_services'

GROCERY_STORES = 'grocery_stores'

DISCOUNT_STORES = 'discount_stores'

HOUSEHOLD_PRODUCTS = 'household_products'

BEVERAGES_NON_ALCOHOLIC = 'beverages_non_alcoholic'

BEVERAGES_ALCOHOLIC = 'beverages_alcoholic'

TOBACCO = 'tobacco'

AEROSPACE_DEFENSE = 'aerospace_defense'

FARM_HEAVY_MACHINERY = 'farm_heavy_machinery'

ENGINEERING_CONSTRUCTION = 'engineering_construction'

TOOLS_ACCESSORIES = 'tools_accessories'

BUSINESS_EQUIPMENT = 'business_equipment'

OIL_GAS_INTEGRATED = 'oil_gas_integrated'

OIL_GAS_EXPLORATION_PRODUCTION = 'oil_gas_exploration_production'

OIL_GAS_REFINING_MARKETING = 'oil_gas_refining_marketing'

OIL_GAS_EQUIPMENT_SERVICES = 'oil_gas_equipment_services'

CHEMICALS = 'chemicals'

SPECIALTY_CHEMICALS = 'specialty_chemicals'

STEEL = 'steel'

BUILDING_MATERIALS = 'building_materials'

PAPER_PAPER_PRODUCTS = 'paper_paper_products'

UTILITIES_REGULATED_ELECTRIC = 'utilities_regulated_electric'

UTILITIES_REGULATED_GAS = 'utilities_regulated_gas'

UTILITIES_RENEWABLE = 'utilities_renewable'

UTILITIES_DIVERSIFIED = 'utilities_diversified'

REIT_RESIDENTIAL = 'reit_residential'

REIT_RETAIL = 'reit_retail'

REIT_OFFICE = 'reit_office'

REIT_HEALTHCARE = 'reit_healthcare'

REIT_INDUSTRIAL = 'reit_industrial'

REAL_ESTATE_SERVICES = 'real_estate_services'

TELECOM_SERVICES = 'telecom_services'

ENTERTAINMENT = 'entertainment'

ADVERTISING_AGENCIES = 'advertising_agencies'

ELECTRONIC_GAMING_MULTIMEDIA = 'electronic_gaming_multimedia'

INTERNET_CONTENT_INFORMATION = 'internet_content_information'

optrade.utils.train

class EarlyStopping(patience=7, verbose=True, delta=0, path='checkpoint.pt')

Bases: object

Early stops the training if validation loss doesn’t improve after a given patience.

Github:

https://github.com/Bjarten/early-stopping-pytorch/blob/master/pytorchtools.py

__init__(patience=7, verbose=True, delta=0, path='checkpoint.pt')

Parameters:

• patience (int) – How long to wait after last time validation loss improved. Default: 7

• verbose (bool) – If True, prints a message for each validation loss improvement. Default: False

• path (str) – Path for the checkpoint to be saved to. Default: ‘checkpoint.pt’

Return type:

None

save_checkpoint(val_loss, model)

Parameters:

• val_loss (float)

• model (Module)

Return type:

None

Module contents