Indicators Engine

Indicators Engine (src/indicators.py)

This page documents the core engine that powers indicators-cli.

Responsibilities

• Fetch market data (Yahoo Finance via yfinance)
• Convert and normalize data into a Polars workflow
• Compute indicators (rolling windows + EWMs)
• Write output files concurrently
• Print phase timings (source / calculation / write)

Key functions (mental model)

source_data(...)

Fetches market history for one or more tickers and returns a list of packages:

• data: Polars LazyFrame with standardized columns
• ticker: the ticker symbol
• period: the requested period

Behavior notes:

• Pulls combined history, then selects per-ticker columns
• Skips tickers with no data (detected via missing close column)

See Source Data Deep Dive for MultiIndex handling and return packages.

calculate_indicators(...)

Takes a LazyFrame, selects window sizes based on defaults + optional config override, lowercases columns, then adds indicator columns:

• sma
• ema
• macd, signal_line, macd_hist
• rsi
• bb_lower, bb_upper
• roc
• ATR (uppercase)
• obv
• K, D (uppercase)

Returns a package like:

• data: collected Polars DataFrame
• ticker, period

Window selection uses defaults[family][period][time_frame] (see Config Resolution).

collect(..., engine=engine) is documented in Polars Engine.

write_output(...)

Constructs the output path and writes to the chosen format using Polars writers.

See Write Output Deep Dive for path rules and edge cases.

run_main(...)

Orchestrates:

1. Parse ticker/period/timeframe/config inputs
2. Source data
3. Calculate indicators
4. Write outputs
5. Print phase timings

Implementation gotchas

• Output column names include uppercase ATR, K, D (see Indicators (Overview))
• Timeframe may be a string or a dict (when loaded from JSON); config lookup must still key by interval string per period when applicable (see Config Resolution)

Related pages:

• Pipeline
• Schema Normalization
• Output Writing
• Data Shape Invariants