finmlkit.feature.core.volatility module

Implements various volatility estimators.

finmlkit.feature.core.volatility.atr(high: ndarray[tuple[int, ...], dtype[float64]], low: ndarray[tuple[int, ...], dtype[float64]], close: ndarray[tuple[int, ...], dtype[float64]], window: int, ema_based: bool = False, normalize: bool = False) → ndarray[tuple[int, ...], dtype[float64]]

Calculate Average True Range (ATR).

ATR is a measure of market volatility showing how much an asset price moves, on average, during a given time period. ATR can be calculated using either a simple moving average or an exponential moving average method.

Parameters:

• high – np.array, high prices

• low – np.array, low prices

• close – np.array, close prices

• window – int, lookback period

• ema_based – bool, if True uses EMA calculation, if False uses SMA calculation

• normalize – bool, if True normalizes ATR by mid price (avg of high and low)

Returns:

np.array, ATR values

finmlkit.feature.core.volatility.bollinger_percent_b(close: ndarray[tuple[int, ...], dtype[float64]], window: int, num_std: float) → ndarray[tuple[int, ...], dtype[float64]]

Calculate Bollinger Percent B indicator.

Bollinger Percent B shows where the price is in relation to the Bollinger Bands. Values range typically between 0 and 1, where: - Values above 1 indicate price is above the upper band - Values below 0 indicate price is below the lower band - Value of 0.5 indicates price is at the middle band (SMA)

Parameters:

• close – Array of close prices

• window – Lookback window for calculations

• num_std – Number of standard deviations for bands

Returns:

Array of Bollinger Percent B values

finmlkit.feature.core.volatility.ewms(y: ndarray[tuple[int, ...], dtype[float64]], span: int) → ndarray[tuple[int, ...], dtype[float64]]

Calculates the Exponentially Weighted Moving Standard Deviation (EWM_STD) of a one-dimensional numpy array. Equivalent to pandas.Series.ewm(…).std() with adjust=True and bias=False.

Parameters:

• y – A one-dimensional numpy array of floats.

• span – The decay window, or ‘span’.

Returns:

The EWM standard deviation vector, same length and shape as y.

Note

This function adjusts for small sample sizes by dividing by the cumulative weight minus the sum of squared weights divided by the cumulative weight, matching the behavior of adjust=True and bias=False in pandas.

finmlkit.feature.core.volatility.ewmst(timestamps: ndarray[tuple[int, ...], dtype[int64]], y: ndarray[tuple[int, ...], dtype[float64]], half_life: float, sigma_floor: float = 1e-12) → ndarray[tuple[int, ...], dtype[float64]]

Unbiased time-decay EWMA std-dev (adjust=True, bias=False semantics).

Maintains:

V = sum of weights V2 = sum of squared weights Sy = EWMA sum of y Syy = EWMA sum of y^2

Then

mean_t = Sy / V ewma_y2 = Syy / V var_raw = ewma_y2 - mean_t^2 denom = V - V2 / V var_t = var_raw * (V / denom) σ_t = sqrt(max(var_t, 0))

finmlkit.feature.core.volatility.ewmst_mean0(timestamps: ndarray[tuple[int, ...], dtype[int64]], y: ndarray[tuple[int, ...], dtype[float64]], half_life: float, sigma_floor: float = 1e-12) → ndarray[tuple[int, ...], dtype[float64]]

Unbiased EWMA std-dev with time-decay half-life fo a zero-mean series)

σ_t² = U_t / V_t with

U_t = α_t * y_t² + (1-α_t) * U_{t-1} V_t = α_t + (1-α_t) * V_{t-1}

where α_t = 1 - exp(-Δt / half_life), Δt in seconds and y_t is your return at timestamp[t].

Parameters:

• timestamps – 1D array of event times in nanoseconds.

• y – 1D array of floats (e.g. lagged returns).

• half_life – Decay half-life in seconds.

• sigma_floor – Minimum σ to enforce stability.

Returns:

EWMA standard deviation array.

finmlkit.feature.core.volatility.parkinson_range(high: ndarray[tuple[int, ...], dtype[float64]], low: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[float64]]

finmlkit.feature.core.volatility.realized_vol(r: ndarray[tuple[int, ...], dtype[float64]], window: int, is_sample: bool) → ndarray[tuple[int, ...], dtype[float64]]

Calculate realized volatility from return input using Numba.

Parameters:

• r – np.array of returns

• window – int, number of samples for volatility calculation

• is_sample – bool, if True uses (n-1) divisor for sample standard deviation, else uses n for population

Returns:

np.array, realized volatility values

finmlkit.feature.core.volatility.rolling_variance_nb(series: ndarray[tuple[int, ...], dtype[float64]], window: int, ddof: int = 1, min_periods: int = 1) → ndarray[tuple[int, ...], dtype[float64]]

Calculate rolling variance of a series with NaN handling.

Parameters:

• series – Input array

• window – Window size for rolling calculation

• ddof – Delta degrees of freedom (1 for sample variance, 0 for population variance)

• min_periods – Minimum number of valid observations required to calculate result

Returns:

Array of rolling variances, same length as input series

finmlkit.feature.core.volatility.true_range(high: ndarray[tuple[int, ...], dtype[_ScalarType_co]], low: ndarray[tuple[int, ...], dtype[_ScalarType_co]], close: ndarray[tuple[int, ...], dtype[_ScalarType_co]]) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Calculate True Range using Numba.

Parameters:

• high – np.array, high prices

• low – np.array, low prices

• close – np.array, close prices

Returns:

np.array, True Range values

finmlkit.feature.core.volatility.variance_ratio_1_4_core(price: ndarray[tuple[int, ...], dtype[float64]], window: int, ddof: int, ret_type: str) → ndarray[tuple[int, ...], dtype[float64]]

Calculate the variance ratio: var(1-bar return) / var(4×1-bar return).

This ratio helps detect microstructure noise vs trending. Values closer to 0.25 suggest a random walk (efficient market), while values significantly different from 0.25 suggest either mean-reversion (<0.25) or momentum/trending (>0.25).

Parameters:

• price – Input price array

• window – Window size for variance calculation

• ddof – Delta degrees of freedom for variance

• ret_type – Type of returns to use: “simple” or “log”

Returns:

Array of variance ratios, same length as input price