A Python library implementing techniques from López de Prado's Advances in Financial Machine Learning. Modular, typed, and tested — drop the pieces you need into your own pipeline.
If you're applying ML to financial time series, standard cross-validation will lie to you. Overlapping labels, multiple testing, and look-ahead bias produce Sharpe ratios that vanish in production.
Q solves this with:
- PurgedKFold & CPCV — cross-validation that respects temporal label overlap and applies embargo periods, so your backtest scores mean something
- Deflated Sharpe Ratio — quantifies the probability your SR is real after accounting for all the strategies you tried and didn't ship
- Standalone modules —
q.cv,q.stats, andq.fdhave minimal dependencies and plug into any existing pipeline
New to this? Read Is Your Backtest Lying? — a practical guide to auditing any quant strategy with Q.
cd python
pip install -e .
# With optional dependencies (entropy features, Hurst exponent)
pip install -e ".[full]"Requires Python >= 3.10.
import q.cv as qcv
import q.stats as qstats
# Combinatorial Purged Cross-Validation
splits = qcv.get_cpcv_splits(n=6, k=2) # C(6,2) = 15 train/test combos
paths = qcv.get_cpcv_path_groups(splits, n=6) # 5 backtest paths
phi = qcv.get_cpcv_phi(6, 2) # number of paths
# Purged K-Fold with embargo
pkf = qcv.PurgedKFold(n_splits=5, t1=label_end_times, pct_embargo=0.02)
for train_idx, test_idx in pkf.split(X):
model.fit(X.iloc[train_idx], y.iloc[train_idx])
# Deflated Sharpe Ratio — is your SR statistically significant?
dsr_val, sr0 = qstats.dsr(sr=0.08, N=100, v=0.01, T=2520, y3=-0.5, y4=4.0)
# dsr_val: probability true SR > sr0 (expected max SR from 100 trials)Construct alternative bar types from raw tick data:
| Function | Description |
|---|---|
tick_bars_idx |
Fixed number of ticks per bar |
volume_bar_idx |
Fixed volume per bar |
dollar_bar_idx |
Fixed dollar volume per bar |
imbalance_tick_df |
Information-driven tick imbalance bars |
imbalance_v_df |
Volume imbalance bars |
imbalance_dv_df |
Dollar volume imbalance bars |
run_tick_df |
Tick run bars |
Event-driven label generation for supervised learning:
- CUSUM filter (
getTEvents) — detect structural changes with dynamic thresholds - Triple barrier (
getEventsMP) — label by profit-taking, stop-loss, or time expiry - Meta-labeling (
get_bins) — learn bet sizing on top of a primary model - Multiclass (
get_bins_multiclass) — three-class labeling
Time-series aware validation that prevents look-ahead bias:
PurgedKFold— purges training observations whose labels overlap the test set, with configurable embargoget_cpcv_splits— generates all C(n,k) combinatorial test-set selectionsget_cpcv_path_groups— assigns splits to complete backtest pathsget_cpcv_phi— computes number of backtest pathssplit_cpcv_pe— standalone CPCV with purge + embargosplit_cpcv_2— CPCV without purge (for comparison)
Guard against overfitting and multiple testing bias:
psr(sr, t, y3, y4, sr0)— Probabilistic Sharpe Ratio: probability that true SR exceeds a benchmark, accounting for skewness and kurtosissr_star(mean, var, N)— expected maximum SR from N independent trials (the "haircut")dsr(sr, N, v, T, y3, y4)— Deflated Sharpe Ratio: PSR adjusted for multiple testing
- Entropy features — Shannon, permutation entropy, Lempel-Ziv complexity
- Microstructure — Roll model, Corwin-Schultz spread, Kyle/Amihud lambda, VPIN
- Fractional differentiation (
q.fd) — make series stationary while preserving memory - Structural encoding (
SigmaEncoder) — discretize returns into symbolic sequences
- Sequential bootstrap — respects label overlap structure
- Uniqueness weighting — downweight redundant observations
- Concurrency analysis — count overlapping labels per bar
- EWM daily volatility, rolling sigma estimators
- Parkinson, Garman-Klass, Rogers-Satchell, Yang-Zhang estimators
- Hierarchical Risk Parity — cluster-based allocation (López de Prado)
- Critical Line Algorithm — exact Markowitz efficient frontier
- Signal generation from ML predictions (OvR t-values)
- Concurrent signal averaging and discretization
- Strategy rule algebra: min precision, implied SR, implied frequency, probability of failure
- Synthetic testing (
bt.synthetic) — OU-process simulation with barrier strategies - Backtest stats (
bt.stats) — HHI concentration, drawdown, time-under-water - Performance (
q.metrics) — comprehensive KPIs including DSR, PSR, correlation analysis
Transaction, position, and portfolio management framework for live and paper trading.
python/
q/
bars.py # Bar construction
labels.py # Event detection & labeling
features.py # Feature engineering
mfeatures.py # Microstructural features
sample.py # Sampling & bootstrapping
fd.py # Fractional differentiation
volatility.py # Volatility estimators
sizing.py # Position sizing
risks.py # Risk metrics & strategy algebra
returns.py # Return calculations
HRP.py # Hierarchical Risk Parity
CLA.py # Critical Line Algorithm
model_selection.py # CV scoring, feature importance
cv/
cpcv.py # CPCV combinatorial math
purged_kfold.py # PurgedKFold + split generators
stats/
sharpe.py # PSR, DSR, sr*
bt/
stats.py # Backtest statistics
synthetic.py # Synthetic price generation
viz.py # Visualization
metrics/
general.py # Portfolio metrics
metrics2.py # ML metrics
performance.py # Aggregated performance stats
e/
qml_engine2.py # ML experimentation engine
tests/ # 31 test files, 150+ tests
notebooks/ # 25 Jupyter notebooks
pyproject.toml
cd python/q/tests
python -m pytest . # all tests
python -m pytest test_cpcv.py # CPCV tests (23 tests)
python -m pytest test_dsr.py # DSR/PSR tests (22 tests)
python -m pytest test_bars.py -k "test_tick_bars" # single testCore: pandas, numpy, scipy, scikit-learn, matplotlib, numba, tqdm
Optional: pyentrp (entropy features), hurst (Hurst exponent), shap (SHAP explanations)
- López de Prado, M. (2018). Advances in Financial Machine Learning. Wiley.
- Bailey, D. & López de Prado, M. (2012). "The Sharpe Ratio Efficient Frontier."
- Bailey, D. & López de Prado, M. (2014). "The Deflated Sharpe Ratio."