GeneratedGenerated from the built extension by scripts/generate_python_api_reference.py; CI fails if it is stale.

openquant.bars

Pure Python. Signatures are as written in the source; descriptions are the docstrings. All Python modules.

Functions

`bar_diagnostics`

bar_diagnostics(df: pl.DataFrame) -> dict[str, float]

Summarize the statistical properties of a bar series' close-to-close returns.

Useful for comparing bar types (AFML section 2.3 argues that activity-based bars have returns closer to IID normal than time bars). Simple returns are computed within each symbol after clean_ohlcv, then pooled across symbols in (symbol, ts) order; the lag-1 autocorrelations are taken over that pooled list, so with several symbols they include the pairs that straddle a symbol boundary.

Parameters

df : polars.DataFrame: Long OHLCV frame with columns ts, symbol, open, high, low, close and volume (or aliases accepted by clean_ohlcv).

Returns

dict[str, float]: n_bars (rows after cleaning), lag1_return_autocorr, lag1_sq_return_autocorr (lag-1 autocorrelation of squared returns, a volatility-clustering gauge) and return_std (sample standard deviation). With fewer than 3 returns, every entry but n_bars is 0.0; an autocorrelation is also 0.0 when either side has zero variance.

Raises

ValueError: If df lacks a required column.

`build_dollar_bars`

build_dollar_bars(
    df: pl.DataFrame,
    *,
    dollar_value_per_bar: float = 5000000.0,
) -> pl.DataFrame

Group an OHLCV frame into dollar bars per symbol (AFML section 2.3.1.4).

The input goes through openquant.data.clean_ohlcv first (column aliases resolved, rows with nulls dropped, duplicate (symbol, ts) keys removed) and is then processed one symbol at a time. Each input row is treated as one trade at its close price with its volume; the input open, high, low and adj_close are ignored, so the output high/low are the extremes of the input closes.

A bar closes when cumulative close * volume reaches dollar_value_per_bar; the row that crosses the threshold belongs to the bar it closes, so bars overshoot. A trailing partial bar is dropped.

Parameters

df : polars.DataFrame: Long OHLCV frame with columns ts, symbol, open, high, low, close and volume (or aliases accepted by clean_ohlcv).
dollar_value_per_bar : float, default 5_000_000.0: Cumulative traded value that closes a bar.

Returns

polars.DataFrame: Columns ts (time of the bar's last row), symbol, open, high, low, close, volume, adj_close (equal to close), start_ts (time of the bar's first row), n_obs (rows in the bar) and dollar_value (sum of close * volume), sorted by symbol then ts.

Raises

ValueError: If dollar_value_per_bar is not positive and finite, or df lacks a required column.

`build_tick_bars`

build_tick_bars(df: pl.DataFrame, *, ticks_per_bar: int = 50) -> pl.DataFrame

Group an OHLCV frame into tick bars of a fixed row count per symbol (AFML 2.3.1.2).

A bar closes once ticks_per_bar rows have accumulated; a trailing partial bar is dropped.

Parameters

df : polars.DataFrame: Long OHLCV frame with columns ts, symbol, open, high, low, close and volume (or aliases accepted by clean_ohlcv).
ticks_per_bar : int, default 50: Number of rows per bar.

Returns

polars.DataFrame: Columns ts (time of the bar's last row), symbol, open, high, low, close, volume, adj_close (equal to close), start_ts (time of the bar's first row), n_obs (rows in the bar) and dollar_value (sum of close * volume), sorted by symbol then ts.

Raises

ValueError: If ticks_per_bar <= 0, or df lacks a required column.

`build_time_bars`

build_time_bars(df: pl.DataFrame, *, interval: str = '1d') -> pl.DataFrame

Resample an OHLCV frame into time bars per symbol (AFML section 2.3.1.1).

A bar closes on the first row at least interval after the bar's first row, and that row belongs to the closing bar; bars are anchored to each bar's first row, not to the wall clock. A trailing partial bar is kept as a final, shorter bar.

Parameters

df : polars.DataFrame: Long OHLCV frame with columns ts, symbol, open, high, low, close and volume (or aliases accepted by clean_ohlcv).
interval : str, default "1d": Bar length: an integer followed by d, h, m or s (for example "4h", "15m"); case-insensitive.

Returns

polars.DataFrame: Columns ts (time of the bar's last row), symbol, open, high, low, close, volume, adj_close (equal to close), start_ts (time of the bar's first row), n_obs (rows in the bar) and dollar_value (sum of close * volume), sorted by symbol then ts.

Raises

ValueError: If interval does not have a supported form or is not positive, or df lacks a required column.

`build_volume_bars`

build_volume_bars(df: pl.DataFrame, *, volume_per_bar: float = 100000.0) -> pl.DataFrame

Group an OHLCV frame into volume bars per symbol (AFML section 2.3.1.3).

A bar closes when cumulative volume reaches volume_per_bar; the row that crosses the threshold belongs to the bar it closes, so bars overshoot. A trailing partial bar is dropped.

Parameters

df : polars.DataFrame: Long OHLCV frame with columns ts, symbol, open, high, low, close and volume (or aliases accepted by clean_ohlcv).
volume_per_bar : float, default 100_000.0: Cumulative volume that closes a bar.

Returns

polars.DataFrame: Columns ts (time of the bar's last row), symbol, open, high, low, close, volume, adj_close (equal to close), start_ts (time of the bar's first row), n_obs (rows in the bar) and dollar_value (sum of close * volume), sorted by symbol then ts.

Raises

ValueError: If volume_per_bar is not positive and finite, or df lacks a required column.