Skip to content

Utilities

Volatility-adjusted log returns and adjusted log-price helpers.

tinycta.util

Volatility adjustment and price normalization helpers (Polars expressions).

This module provides expression-level building blocks used to standardize log returns by an exponentially weighted volatility estimate and to integrate those standardized returns into adjusted log-price series. These are designed for use within Polars pipelines (e.g., DataFrame.with_columns) and operate column-wise.

Functions: - vol_adj: Standardize log returns using EWMA volatility and clip extremes. - adj_log_prices: Cumulative sum (integration) of standardized, clipped returns.

adj_log_prices(x, vola, clip, min_samples=1)

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

Uses vol_adj to standardize/clamp log returns and then integrates them via cumulative sum. The resulting series behaves like a standardized price- like process with roughly unit volatility.

Parameters:

Name Type Description Default
x Expr

Polars expression of the price series to transform.

 required
vola int

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

 required
clip float

Symmetric clipping threshold applied after standardization.

 required
min_samples int

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

 1

Returns:

Type Description
Expr

pl.Expr: Adjusted-log-price series obtained by cumulative sum of standardized returns.
Source code in src/tinycta/util.py 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def adj_log_prices(x: pl.Expr, vola: int, clip: float, min_samples: int = 1) -> pl.Expr:
    """Integrate clipped, volatility-adjusted log returns to adjusted log prices.

    Uses ``vol_adj`` to standardize/clamp log returns and then integrates them
    via cumulative sum. The resulting series behaves like a standardized price-
    like process with roughly unit volatility.

    Args:
        x: Polars expression of the price series to transform.
        vola: EWMA lookback (span-equivalent) used to estimate volatility.
        clip: Symmetric clipping threshold applied after standardization.
        min_samples: Minimum samples required by EWM to emit non-null values.

    Returns:
        pl.Expr: Adjusted-log-price series obtained by cumulative sum of
            standardized returns.
    """
    return vol_adj(x, vola=vola, clip=clip, min_samples=min_samples).cum_sum()

vol_adj(x, vola, clip, min_samples=1)

Compute clipped, volatility-adjusted log returns per column.

Parameters:

Name Type Description Default
x Expr

Price series to transform.

 required
vola int

EWMA lookback (span-equivalent) for std.

 required
clip float

Symmetric clipping threshold applied after standardization.

 required
min_samples int

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

 1

Returns:

Type Description
Expr

pl.Expr: Standardized and clipped log returns.
Source code in src/tinycta/util.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
def vol_adj(x: pl.Expr, vola: int, clip: float, min_samples: int = 1) -> pl.Expr:
    """Compute clipped, volatility-adjusted log returns per column.

    Args:
        x: Price series to transform.
        vola: EWMA lookback (span-equivalent) for std.
        clip: Symmetric clipping threshold applied after standardization.
        min_samples: Minimum samples required by EWM to yield non-null values.

    Returns:
        pl.Expr: Standardized and clipped log returns.
    """
    log_returns = x.log().diff()
    vol = log_returns.ewm_std(com=vola - 1, adjust=True, min_samples=min_samples)
    return (log_returns / vol).clip(-clip, clip)