Coverage for src/tinycta/util.py: 100%

1"""Volatility adjustment and price normalization helpers (Polars expressions). 

2 

3This module provides expression-level building blocks used to standardize 

4log returns by an exponentially weighted volatility estimate and to integrate 

5those standardized returns into adjusted log-price series. These are designed 

6for use within Polars pipelines (e.g., DataFrame.with_columns) and operate 

7column-wise. 

8 

9Functions: 

10- vol_adj: Standardize log returns using EWMA volatility and clip extremes. 

11- adj_log_prices: Cumulative sum (integration) of standardized, clipped returns. 

12""" 

13 

14import polars as pl 

15 

16 

17def vol_adj(x: pl.Expr, vola: int, clip: float, min_samples: int = 1) -> pl.Expr: 

18 """Compute clipped, volatility-adjusted log returns per column. 

19 

20 Args: 

21 x: Price series to transform. 

22 vola: EWMA lookback (span-equivalent) for std. 

23 clip: Symmetric clipping threshold applied after standardization. 

24 min_samples: Minimum samples required by EWM to yield non-null values. 

25 

26 Returns: 

27 pl.Expr: Standardized and clipped log returns. 

28 """ 

29 log_returns = x.log().diff() 

30 vol = log_returns.ewm_std(com=vola - 1, adjust=True, min_samples=min_samples) 

31 return (log_returns / vol).clip(-clip, clip) 

32 

33 

34def adj_log_prices(x: pl.Expr, vola: int, clip: float, min_samples: int = 1) -> pl.Expr: 

35 """Integrate clipped, volatility-adjusted log returns to adjusted log prices. 

36 

37 Uses ``vol_adj`` to standardize/clamp log returns and then integrates them 

38 via cumulative sum. The resulting series behaves like a standardized price- 

39 like process with roughly unit volatility. 

40 

41 Args: 

42 x: Polars expression of the price series to transform. 

43 vola: EWMA lookback (span-equivalent) used to estimate volatility. 

44 clip: Symmetric clipping threshold applied after standardization. 

45 min_samples: Minimum samples required by EWM to emit non-null values. 

46 

47 Returns: 

48 pl.Expr: Adjusted-log-price series obtained by cumulative sum of 

49 standardized returns. 

50 """ 

51 return vol_adj(x, vola=vola, clip=clip, min_samples=min_samples).cum_sum()