polars-anta 0.3.1

Institutional-Grade Alpha Research, Market Microstructure, Quantitative Feature Engineering & Vectorized Backtesting in Polars

Auditable mathematical expressions. Cross-sectional factor analytics and microstructure modeling. An intuitive dual .anta / .ta interface. Zero-C deployment with Rust-accelerated performance.

An open-source quantitative research engine for market microstructure estimation, cross-sectional alpha discovery, statistical factor evaluation, technical feature engineering, and loop-free vectorized backtesting. Purpose-built for quantitative researchers, institutional prop trading desks, index futures & derivatives strategists, and systematic portfolio managers who demand both sub-second execution speed and 100% mathematical transparency.

Documentation • Quick start • API Reference • Learning Resources • Examples • Report an issue

What is polars-anta?

polars-anta (Alpha & Numerical Technical Analysis) is an institutional-grade Python library for quantitative feature engineering, market microstructure analysis, cross-sectional alpha research, statistical signal validation, and vectorized portfolio backtesting powered natively by Polars.

Unlike traditional technical analysis packages designed around single-asset retail charting, polars-anta is architected from the ground up for buy-side research workflows: unifying formulaic alpha primitives (WorldQuant 101), liquidity and price-impact estimators (Amihud, Kyle's $\lambda$, Roll, Corwin-Schultz), closed-form rolling OLS regressions, cross-sectional standardization/neutralization, Alphalens-style Rank IC evaluation, and transaction-cost-aware vectorized backtesting inside Polars' multi-threaded Rust query engine.

Why Institutional & Quantitative Research Teams Choose polars-anta

• End-to-end alpha research lifecycle — move seamlessly from raw OHLCV integrity auditing and multi-timeframe resampling to microstructure extraction, cross-sectional factor neutralization, IC/quantile decay analysis, and vectorized backtesting in one unified Arrow/Polars pipeline.
• 100% Auditable white-box mathematics — Risk Committees and Quantitative Researchers can inspect clean, closed-form algebraic Polars expressions (pl.Expr) directly in Python rather than trusting opaque C/Cython black-box binaries.
• Rust-accelerated panel execution — computations compile directly into Polars' multi-threaded Rust query planner and SIMD kernels, achieving up to 112.4x speedups over Pandas without GIL contention.
• Zero-C enterprise compliance — installs deterministically via pip install polars-anta across air-gapped institutional Linux clusters, Docker research containers, Windows workstations, and macOS without gcc, msvc, or external C headers.
• Built for Index Futures & Multi-Asset Universes — evaluate intraday signals on single-instrument futures (e.g., VN30F1M, CME E-mini, Crypto Perpetuals) or scale cross-sectional alphas across thousands of equities simultaneously via .over("symbol") and .over("timestamp").

The Institutional Research Pipeline:

Raw Market Data → Data Validation & Resampling → Microstructure & Alpha Expressions (.anta / .ta) → Cross-Sectional Neutralization → Rank IC & Quantile Validation → Cost-Aware Vectorized Backtest

Institutional Use Cases & Target Desks

1. Index Futures & Intraday Derivatives Desks (VN30F1M, CME E-Mini, Perpetual Futures) Aggregate tick/minute feeds into information-driven bars (resample_volume_bars, resample_dollar_bars, resample_imbalance_bars), stitch continuous roll series (stitch_futures_roll), track intraday session_vwap z-scores, measure order flow toxicity (vpin, ofi) and carry (futures_basis, oi_regime), and backtest with next-bar open/VWAP execution (execution_price="open"), session flatten masks (flat_mask), and round-trip MAE/MFE excursion ledgers (bt.trades()).
2. Cross-Sectional Statistical Arbitrage & Equity Factor Research Construct, winsorize (cs_winsorize via Quantile/Z-Score/MAD), standardize (cs_zscore), sector-neutralize (neutralize), and Gram-Schmidt OLS residualize (orthogonalize) WorldQuant 101 Formulaic Alphas across thousands of tickers, then validate with Newey-West HAC $t$-statistics (ic_summary), multi-horizon Alpha Half-Life (ic_decay), and Deflated Sharpe Ratios (deflated_sharpe_ratio).
3. Quantitative Machine Learning (AFML) Feature Stores Transform non-stationary prices via Fixed-Window Fractional Differentiation (frac_diff), generate dynamic path-dependent labels (triple_barrier_labels with Meta-Labeling and trend_scanning_labels), and feed zero-copy Apache Arrow tensors directly into LightGBM, XGBoost, CatBoost, or PyTorch.

Quick start

1. Install

polars-anta is available on PyPI with zero C compiler requirements:

python -m pip install polars-anta

To upgrade to the latest release:

python -m pip install --upgrade polars-anta

Or using uv:

uv add polars-anta

2. Verify your installation

Importing polars_anta automatically registers both .anta and .ta namespaces on Polars Expr, DataFrame, and LazyFrame objects:

import polars as pl
import polars_anta as pa

df = pl.DataFrame({"close": [100.0, 102.0, 101.5, 104.0, 106.5, 105.0, 108.0]})
out = df.with_columns(
    pl.col("close").anta.ema(period=3).round(2).alias("ema_3"),
    pl.col("close").anta.rsi(period=3).round(2).alias("rsi_3"),
)
print(out.tail(3))
# shape: (3, 3)
# ┌───────┬────────┬───────┐
# │ close ┆ ema_3  ┆ rsi_3 │
# │ ---   ┆ ---    ┆ ---   │
# │ f64   ┆ f64    ┆ f64   │
# ╞═══════╪════════╪═══════╡
# │ 106.5 ┆ 104.59 ┆ 88.14 │
# │ 105.0 ┆ 104.80 ┆ 62.61 │
# │ 108.0 ┆ 106.40 ┆ 80.52 │
# └───────┴────────┴───────┘

3. Explore quantitative workflows

Start with our ready-to-run example scripts or 1-click Google Colab notebooks, or explore the five institutional workflows below:

A. Intraday Derivatives, Information Bars, Roll Stitching & Microstructure

# 1. Stitch continuous futures contracts (backward/ratio/panama) & sample Volume/Imbalance bars:
cont_df = raw_contracts.anta.stitch_futures_roll(method="backward")
vol_bars = cont_df.anta.resample_volume_bars(volume_threshold=5_000)

# 2. Extract Session-Anchored VWAP, Order Flow Toxicity (VPIN, OFI), Carry & OI Regimes:
deriv_features = vol_bars.with_columns(
    pl.col("close")
    .anta.session_vwap("high", "low", "volume", session_by="trading_date")
    .alias("svwap"),
    pl.col("close").anta.vpin("volume", period=20).alias("vpin_20"),
    pl.col("bid_price").anta.ofi("bid_size", "ask_price", "ask_size", period=5).alias("ofi_5"),
    pl.col("close").anta.futures_basis("spot_close", "days_to_expiry", period=20).alias("basis"),
    pl.col("close").anta.oi_regime("open_interest", period=1).alias("oi_state"),
).unnest("svwap", "basis", "oi_state")

B. Quant Machine Learning (AFML) — Fractional Differentiation & Dynamic Labeling

# Memory-preserving stationary features (FFD) + Triple-Barrier & Trend-Scanning labels:
ml_dataset = df.with_columns(
    pl.col("close").anta.frac_diff(d=0.4, window=20).over("symbol").alias("close_ffd"),
    pl.col("close")
    .anta.triple_barrier_labels(
        volatility=pl.col("close").pct_change().rolling_std(20),
        horizon=12,
        pt_mult=2.0,
        sl_mult=1.5,
        side=pl.col("primary_signal"),  # Enables binary meta_label {0.0, 1.0}
    )
    .over("symbol")
    .alias("tb"),
    pl.col("close")
    .anta.trend_scanning_labels(min_window=5, max_window=20)
    .over("symbol")
    .alias("ts"),
).unnest("tb", "ts")

C. Cross-Sectional Standardization, Neutralization & Multi-Factor Orthogonalization

alpha_df = panel_df.with_columns(
    (
        -pl.col("close").anta.ts_delta(5).over("symbol")
        * pl.col("volume").anta.ts_rank(20).over("symbol")
    ).alias("raw_alpha")
).with_columns(
    pl.col("raw_alpha")
    .anta.cs_winsorize(over="date", method="mad", threshold=3.0)
    .anta.cs_zscore(over="date", clip_bound=3.0)
    .anta.neutralize(by="sector", over="date", standardize=True)
    # Gram-Schmidt OLS projection orthogonal to Beta, Size & Volatility:
    .anta.orthogonalize(factors=["mkt_beta", "log_mcap", "vol_20"], over="date", standardize=True)
    .anta.ts_scale(a=1.0, over="date")
    .alias("pure_alpha_weight")
)

D. Institutional Factor Validation (Newey-West HAC IC, Alpha Half-Life & PSR / DSR)

eval_df = alpha_df.anta.forward_returns(periods=(1, 5, 10), group_by="symbol")

# Autocorrelation-robust Newey-West HAC t-statistic & Multi-Horizon IC Decay Half-Life:
ic_stats = eval_df.anta.ic_summary("pure_alpha_weight", "fwd_ret_5", group_by="date", nw_lags=5)
decay_table = eval_df.anta.ic_decay("pure_alpha_weight", horizons=(1, 2, 3, 5, 10, 20), group_by="date")

# Non-normal skewness/kurtosis-adjusted PSR & multiple-testing Deflated Sharpe Ratio (DSR):
sharpe_ significance = eval_df.select(
    pl.col("strat_ret").anta.probabilistic_sharpe_ratio(benchmark_sr=1.0).alias("psr"),
    pl.col("strat_ret").anta.deflated_sharpe_ratio(n_trials=50, trials_sr_std=0.4).alias("dsr"),
)

E. Execution-Realistic Vectorized Backtest, Excursion Ledger (MAE/MFE) & Grid Sweep

bt = (
    df.anta.ema(period=12, alias="ema_12")
    .anta.ema(period=26, alias="ema_26")
    .anta.backtest(
        entries=pl.col("ema_12").anta.crosses_above("ema_26"),
        exits=pl.col("ema_12").anta.crosses_below("ema_26"),
        execution_price="open",  # Fill at next-bar open (or "twap", "vwap", "close")
        flat_mask=pl.col("is_atc_bar"),  # Mandatory intraday EOD / roll flatten mask
        vol_target=0.15,  # 15% annualized target volatility scaling
        no_trade_buffer=0.05,  # Hysteresis buffer suppressing micro-turnover
        fee_rate=0.0005,
        slippage_rate=0.0002,
        initial_capital=100_000.0,
    )
)
print(bt.report())
print(bt.trades())  # Round-trip trade ledger with PnL, holding_bars, MAE & MFE!

What can you model and compute?

How polars-anta is organized

The library separates data engineering, domain-specific indicator & alpha expressions, factor evaluation, and vectorized backtesting into clean, self-contained modules so that each layer can be inspected and extended independently:

polars_anta/
├── trend.py        # Moving averages, trend overlays, candlestick transforms & pivot systems
├── momentum.py     # Momentum oscillators, cycle detectors & divergence indicators
├── volatility.py   # OHLC volatility estimators, ATR trailing stops & price channels
├── volume.py       # Session/rolling VWAP bands, money flow & volume accumulation metrics
├── stats.py        # Rolling moments, CAPM beta/alpha, closed-form OLS & Fractional Diff (FFD)
├── alpha.py        # Cross-sectional orthogonalization, microstructure, futures & 101 alphas
├── evaluation.py   # AFML labeling, Newey-West Rank IC, IC decay, quantiles & PSR/DSR metrics
├── backtest.py     # Realistic vectorized backtester, vol-targeting, MAE/MFE ledger & sweeps
├── resample.py     # Calendar/Volume/Dollar/Imbalance bars, futures roll stitching & validation
└── namespace.py    # Dual .anta and .ta registration across Expr, DataFrame & LazyFrame

flowchart LR
    A["1. Microstructure & Roll<br/>Volume/Dollar/Imbalance Bars<br/>stitch_futures_roll • VPIN • OFI"] --> B["2. Quant ML & Stationarity<br/>Fixed-Window FracDiff (FFD)<br/>Triple-Barrier • Trend-Scanning"]
    B --> C["3. Factor Orthogonalization<br/>cs_winsorize • cs_zscore<br/>neutralize • orthogonalize (OLS)"]
    C --> D["4. Institutional Validation<br/>Newey-West HAC t-stat<br/>IC Decay Half-Life • PSR & DSR"]
    D --> E["5. Realistic Execution<br/>Next-Open/VWAP • Vol-Targeting<br/>No-Trade Buffer • MAE/MFE Ledger"]

Documentation and learning resources

Interactive Jupyter & Colab Notebooks

Notebook	Topic & Workflow Covered	Launch in Browser
quickstart_colab.ipynb	1-minute interactive demo covering expression syntax, 500-ticker scans, and live 112x speed benchmarks
01_quickstart.ipynb	Step-by-step introduction to .anta / .ta expressions, pl.Struct unnesting, and indicator plotting
02_multi_asset_portfolio_scan.ipynb	Screening a 500-ticker equity universe in ~50 ms using parallel .over("ticker") expressions
03_crypto_momentum_scan.ipynb	Cross-sectional cryptocurrency momentum, volatility filtering, and composite ranking workflow
04_backtest_and_alpha_eval.ipynb	1-line entry/exit crossovers, formatted tearsheets, 5-quantile IC analysis, and dollar-neutral portfolio backtesting

Performance benchmark (1,000,000 rows)

Benchmarks measured across 1,000,000 bars (single-asset random walk) and a 500 tickers × 2,000 bars universe (1,000,000 rows) on Polars' multi-threaded Rust engine vs. single-threaded Pandas:

API Reference & Indicator Catalog

All indicators, alpha primitives, and evaluation functions are exported at the top level (import polars_anta as pa) and registered on .anta and .ta namespaces. Click any module below to expand its complete function signature reference, or visit the Online API Reference.

Quantitative Theory, Mathematical Foundations & Rust Vectorization Architecture

For complete derivations, step-by-step proofs, and institutional research workflows, see Architecture & Mathematical Proofs and Quantitative Theory & Institutional Workflows.

1. Closed-Form Algebraic Reductions ($O(N)$ Rust Native Kernels)

• 112.4x Faster Rolling OLS Linear Regression (linear_regression_slope): Instead of solving $\left(X^\top X\right)^{-1} X^\top Y_t$ inside a Python loop over $N$ bars, polars-anta exploits the exact linear relationship between the Linearly Weighted Moving Average ($\text{WMA}_n$, weights $w_i \propto i+1$) and Simple Moving Average ($\text{SMA}_n$):

  $$\beta_{1,t} = \frac{6}{n + 1}\left(\text{WMA}_n(y)_t - \text{SMA}_n(y)t\right), \qquad \beta{0,t} = \text{SMA}_n(y)t - \beta{1,t}\frac{n - 1}{2}$$

  Both $\text{WMA}_n$ and $\text{SMA}_n$ execute natively inside Polars' multi-threaded Rust engine with $O(1)$ amortized cost per bar.

• Wilder's RMA & Heikin-Ashi via Exact ewm_mean Mapping: Wilder's recursive smoothing ($RMA_t = \frac{1}{n}x_t + \frac{n-1}{n}RMA_{t-1}$ in rsi, atr, adx) and Heikin-Ashi open prices ($HA_Open_t = \frac{1}{2}HA_Open_{t-1} + \frac{1}{2}HA_Close_{t-1}$) are mapped directly to pl.Expr.ewm_mean(alpha=1/n, adjust=False) and ewm_mean(alpha=0.5, adjust=False)—eliminating sequential Python loops completely.

• Fixed-Window Fractional Differentiation (frac_diff, López de Prado 2018): Expands the backshift operator $(1 - B)^d = \sum_{k=0}^{\infty} \omega_k B^k$ via recursive binomial weights $\omega_0 = 1, ; \omega_k = -\omega_{k-1} \frac{d - k + 1}{k}$ over a fixed window $W$, achieving statistical stationarity ($d \approx 0.3\text{–}0.5$) while preserving long-memory trend/cointegration information lost by first-differencing ($d=1$).

2. Cross-Sectional Factor Orthogonalization & Statistical Inference

• Modified Gram-Schmidt Multi-Factor Projection (orthogonalize): Applies the Frisch-Waugh-Lovell theorem per timestamp cross-section (over="date") to strip linear exposures to $K$ arbitrary risk factors $F = [f_1, \dots, f_K]$ (e.g., Market Beta, Log Size, Volatility, Liquidity) with optional Ridge regularization $\lambda \ge 0$:

  $$u_k = \tilde{f}k - \sum{j=1}^{k-1} \frac{\langle \tilde{f}k, u_j \rangle}{|u_j|2^2 + \lambda} u_j, \qquad \epsilon\alpha = \tilde{\alpha} - \sum{k=1}^{K} \frac{\langle \tilde{\alpha}, u_k \rangle}{|u_k|_2^2 + \lambda} u_k$$

• Newey-West HAC $t$-Statistics & Exponential Alpha Half-Life (ic_summary, ic_decay): Multi-period forward returns ($h > 1$) induce $MA(h-1)$ serial correlation in Information Coefficient series. polars-anta applies the Newey & West (1987) Bartlett kernel variance estimator $\hat{\Omega}{NW} = \hat{\gamma}0 + 2 \sum{j=1}^{L} \left(1 - \frac{j}{L+1}\right) \hat{\gamma}j$ so $t{NW} = \frac{\overline{IC}}{\sqrt{\hat{\Omega}{NW} / T}}$ remains unbiased, and fits $\ln |IC(h)| = a - \lambda h$ to estimate the exact signal Half-Life $t_{1/2} = \frac{\ln 2}{\lambda}$.

• Probabilistic & Deflated Sharpe Ratios (probabilistic_sharpe_ratio, deflated_sharpe_ratio): Adjusts Sharpe Ratio inference for non-normal skewness ($\hat{\gamma}_3$), fat tails ($\hat{\gamma}_4$), and selection bias across $K$ tested parameter configurations (Bailey & López de Prado, 2014):

  $$\text{PSR}(SR^) = \Phi!\left(\frac{(\widehat{SR} - SR^)\sqrt{T - 1}}{\sqrt{1 - \hat{\gamma}_3 \widehat{SR} + \frac{\hat{\gamma}4 - 1}{4}\widehat{SR}^2}}\right), \qquad SR^*{DSR} = \sqrt{V[{\widehat{SR}_k}]}\left((1 - \gamma)\Phi^{-1}!\left(1 - \frac{1}{K}\right) + \gamma \Phi^{-1}!\left(1 - \frac{1}{K e}\right)\right)$$

3. Zero-Copy Stride Windows & Loop-Free State Machines

• Zero-Copy 2D Stride Views: Path-dependent rolling operators (triple_barrier_labels, trend_scanning_labels, hurst_exponent, entropy, ts_rank, ts_argmax) construct virtual 2D rolling views (N - P + 1, P) via numpy.lib.stride_tricks.sliding_window_view with $O(1)$ pointer/stride metadata overhead and zero memory duplication.
• State-Machine Backtesting & Excursion Analytics (vectorized_backtest, extract_trades): Entry/exit signals compile into positions via .forward_fill(), apply ex-ante volatility targeting ($w_t^{\text{vol}} = \text{clip}(\sigma_{\text{target}} / \hat{\sigma}{t-1}, 0, L{\max})$), enforce intraday flatten masks (flat_mask), execute at next-bar Open/TWAP/VWAP prices (execution_price), and group active position runs via .rle_id() to compute exact per-trade Maximum Adverse Excursion (MAE) and Maximum Favorable Excursion (MFE).

Design philosophy

polars-anta aims to balance mathematical clarity, cross-sectional expressiveness, and execution speed:

1. Keep quantitative formulas inspectable — write indicators using closed-form algebraic identities and native Polars expressions (pl.Expr) rather than hiding logic behind compiled C extensions.
2. Eliminate Python loops — express recursive smoothing (Wilder's RMA, Heikin-Ashi) via exact ewm_mean recurrences and path-dependent rolling operators via zero-copy sliding_window_view kernels.
3. Treat single-asset and multi-asset panels uniformly — every expression composes naturally with .over("ticker") for time-series operations and .over("date") for cross-sectional ranking and neutralization.
4. Prevent look-ahead bias by default — backtesting utilities shift signals by signal_lag=1 bar out of the box and account for proportional transaction fees and slippage.
5. Provide reproducible examples and parity tests — verify mathematical accuracy through comprehensive unit test suites and self-contained notebooks.

Contributing

Contributions from quantitative researchers, developers, and finance students are welcome! You can help by implementing new indicators, expanding formulaic alphas, improving documentation, or adding tutorial notebooks.

• Browse our open Good First Issues & Help Wanted tasks to find a self-contained issue with full mathematical specifications.
• Read CONTRIBUTING.md for development setup, testing (pytest -v), and linting (ruff check .) guidelines.

Project status and support

polars-anta is an actively developed open-source project. If you find a bug, need an indicator, or want to suggest a quantitative workflow example, please open an issue or join GitHub Discussions.

Disclaimer: polars-anta is provided for educational and research purposes without warranty of any kind. Quantitative models and backtest results should be independently verified before being used for live trading, investment, or risk-management decisions.

Author

polars-anta was created and is maintained by Phan Bui Huu An (@huuan26 • phanbuihuuan261103@gmail.com).

License

polars-anta is licensed under the Apache License 2.0. See the LICENSE file for details.