Indicators

`finml_core.metrics.indicators`

`bollinger_bands(prices, window=20, num_std=2.0)`

Calculates Bollinger Bands and derived volatility metrics (%B and Bandwidth).

Bollinger Bands consist of a middle band (SMA) and two outer bands calculated using the standard deviation of the price series.

Mathematical Formulas

\[ \text{MB}_t = \mu_{P,n} \]
\[ \text{UB}_t = \mu_{P,n} + (k \cdot \sigma_{P,n}) \]
\[ \text{LB}_t = \mu_{P,n} - (k \cdot \sigma_{P,n}) \]

Where

\(\mu_{P,n}\): The rolling mean (SMA) of price \(P\) over window \(n\).
\(\sigma_{P,n}\): The rolling standard deviation of price \(P\) over window \(n\).
\(k\): Standard deviation multiplier.

Parameters:

Name	Type	Description	Default
`prices`	`Series`	Time series of asset prices.	required
`window`	`int`	Moving average window size. Defaults to 20.	`20`
`num_std`	`float`	Number of standard deviations (k). Defaults to 2.0.	`2.0`

Returns:

Type	Description
`DataFrame`	A MultiIndex-compatible DataFrame containing: `bb_middle`: The Simple Moving Average (SMA). `bb_upper`: Upper volatility band. `bb_lower`: Lower volatility band. `bb_pct_b`: Price position relative to the bands (1.0 = Upper, 0.0 = Lower). `bb_width`: Normalized width of the bands, measuring relative volatility.

`macd(prices, fast=12, slow=26, signal=9)`

Calculates the Moving Average Convergence Divergence (MACD).

The MACD is a trend-following momentum indicator that shows the relationship between two exponential moving averages of an asset's price.

Mathematical Formulas:

\[ \text{MACD Line} = \text{EMA}_{fast}(P) - \text{EMA}_{slow}(P) \]
\[ \text{Signal Line} = \text{EMA}_{signal}(\text{MACD Line}) \]
\[ \text{Histogram} = \text{MACD Line} - \text{Signal Line} \]
\[ \text{Relative Hist} = \frac{\text{Histogram}}{P} \]

Parameters:

Name	Type	Description	Default
`prices`	`Series`	Time series of asset prices.	required
`fast`	`int`	Fast EMA span. Defaults to 12.	`12`
`slow`	`int`	Slow EMA span. Defaults to 26.	`26`
`signal`	`int`	Signal EMA span. Defaults to 9.	`9`

Returns:

Type	Description
`DataFrame`	A DataFrame containing: `macd_line`: The difference between fast and slow EMAs. `macd_signal`: EMA of the MACD line (smoothing). `macd_hist`: The distance between the MACD line and the signal line. `macd_rel_hist`: Price-normalized histogram (stationary feature for ML).

Notes

EMA Calculation: Uses Standard EMA (\(\alpha = 2/(N+1)\)).
'macd_rel_hist' is a custom metric: Histogram / Price. This normalizes the volatility relative to the asset price, useful for ML features.
Why adjust=False? This mimics the recursive formula used in most trading platforms: \(y_t = (1-\alpha)y_{t-1} + \alpha x_t\). Using adjust=True (pandas default) would calculate weights based on finite history, leading to values that diverge from standard market indicators.

`relative_volume(volume, window=20)`

Calculates Relative Volume (RVol).

RVol measures the current trading activity relative to its historical average. It is a key feature for identifying "smart money" institutional activity and confirming price breakouts.

Mathematical Formula

\[ \text{RVol}_t = \frac{V_t}{\frac{1}{n} \sum_{i=0}^{n-1} V_{t-i}} \]

Where

\(V_t\): Trading volume at time \(t\).
\(n\): Lookback window (moving average period).

Parameters:

Name	Type	Description	Default
`volume`	`Series`	Time series of trading volume.	required
`window`	`int`	Lookback window. Defaults to 20 (approx. 1 trading month).	`20`

Returns:

Type	Description
`Series`	A ratio indicating relative volume. Values > 1.0: High abnormal activity (Surge in interest). Values < 1.0: Low activity (Typical of consolidations).

Notes

Why 20 days? Represents approximately one trading month.
Stationarity: RVol is a stationary feature, making it highly suitable for Machine Learning models without further differencing.
Numerical Stability: Uses EPSILON (1e-6) replacement for zero moving averages to prevent inf values in low-liquidity assets.

`rsi(prices, period=14)`

Calculates the Relative Strength Index (RSI) using Wilder's Smoothing.

The RSI calculates a ratio of the recent upward price movements to the absolute price movements.

\[ RSI = 100 - \frac{100}{1 + RS} \]

Parameters:

Name	Type	Description	Default
`prices`	`Series`	Time series of asset prices.	required
`period`	`int`	The lookback period. Defaults to 14 (Standard industry value proposed by Wilder).	`14`

Returns:

Type	Description
`Series`	The RSI values (0-100).

Notes

This implementation uses Wilder's Smoothing (\(\alpha = 1/N\)), which is standard in technical analysis. This creates a recursive dependency, so early values may vary slightly depending on the data start point.

Why adjust=False? This mimics the recursive formula used in most trading platforms: \(y_t = (1-\alpha)y_{t-1} + \alpha x_t\). Using adjust=True (pandas default) would calculate weights based on finite history, leading to values that diverge from standard market indicators.