btlab 0.3.0__tar.gz

btlab-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yousuf Hossain Shafeen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

btlab-0.3.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: btlab
+Version: 0.3.0
+Summary: A backtesting framework built around avoiding the common ways backtests lie
+License-Expression: MIT
+Project-URL: Repository, https://github.com/hossainyousuf751/backtest-lab
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: pandas>=2.0
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == "plot"
+Provides-Extra: data
+Requires-Dist: yfinance>=0.2; extra == "data"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: matplotlib>=3.7; extra == "dev"
+Dynamic: license-file
+
+# backtest-lab
+
+![tests](https://github.com/hossainyousuf751/backtest-lab/actions/workflows/ci.yml/badge.svg)
+
+A backtesting framework built around one question: **should you believe this backtest?**
+
+Most backtests that look good are wrong for one of a handful of reasons: look-ahead bias,
+survivorship bias, ignored trading costs and capacity, returns that are really just factor
+exposure, or picking the best of many configurations and reporting it as if it were the only one. This project builds the tools to detect each of
+these, and validates them on synthetic markets where the true answer is known.
+
+```bash
+pip install -e ".[dev]"
+pytest
+cd examples && python 01_overfitting.py && python 02_survivorship.py && python 03_planted_signal.py && python 05_capacity.py
+pip install -e "..[data]" && python 04_live_sector_momentum.py   # needs internet: Yahoo Finance + Ken French
+```
+
+## Design
+
+| Module | What it does |
+|---|---|
+| `strategies.py` | Strategies return target weights; row *t* is decided at the close of day *t* |
+| `engine.py` | Execution lag, drift between rebalances, turnover-based costs, square-root market impact, delistings, point-in-time universe |
+| `validation.py` | Truncation test for look-ahead bias; walk-forward selection; Probability of Backtest Overfitting (CSCV); effective number of trials |
+| `metrics.py` | Sharpe, Sortino, drawdown, Probabilistic and Deflated Sharpe ratios, block-bootstrap CIs, factor attribution with Newey-West t-stats |
+| `data.py` | Synthetic markets with controllable signal, listings, delistings and traded volume; Yahoo Finance and Ken French factor loaders |
+
+**Timing is explicit.** With close-only data, weights decided at the close of day *t* are
+traded at the close of *t+1* by default (`execution_lag=1`). Positions then drift with
+returns until the next rebalance, so turnover and costs are measured on what the portfolio
+actually holds, not on idealised constant weights.
+
+**Look-ahead is tested, not assumed.** `check_lookahead` recomputes a strategy's weights
+on data truncated at random dates and requires them to match the full-history weights.
+The test suite includes a deliberately cheating strategy: the engine reports a Sharpe
+above 10 for it with zero execution lag, which is why the truncation test, not the engine,
+is the line of defence.
+
+**Walk-forward is a real backtest.** The out-of-sample series trades the stitched weights of
+each fold's chosen configuration, so entering the market and switching configurations pay costs.
+
+**Point-in-time universes need no special engine support.** Mask what the *strategy* sees, not
+the prices the *engine* trades on:
+
+```python
+weights = strategy.weights(prices.where(index_membership))   # rank only current members
+result = run_backtest(prices, weights)                       # exits sold at real prices
+```
+
+Masking the engine's prices instead would turn every index deletion into a fake delisting.
+
+## Study 1: overfitting and luck
+
+On 30 independent markets with **no signal**, 12-1 momentum has a mean Sharpe of +0.01
+but a standard deviation of 0.33, matching the theoretical 1/√years. Twelve years of noise
+routinely produces Sharpe ratios of ±0.6.
+
+On the luckiest of 12 noise markets (deliberately chosen, as a researcher who stops at the
+first good result would), a search over 45 momentum configurations finds:
+
+| Measure | Value | Verdict |
+|---|---|---|
+| Best full-sample Sharpe | 0.86 | looks like a discovery |
+| Probabilistic Sharpe vs 0 | 0.997 | "significant" (ignores the search) |
+| **Deflated Sharpe** | **0.92** | not significant at 95% once 45 trials are accounted for |
+| Deflated Sharpe, N = 2 effective trials | 0.99 | **fooled**: the 45 configs are really ~2 independent bets |
+| Probability of Backtest Overfitting | 0.34 | **fooled**: the in-sample winner usually stays above median |
+| Walk-forward out-of-sample Sharpe | 0.82 | **fooled**: the whole sample is lucky, not just the selection |
+| Chosen config on 20 fresh noise markets | +0.00 | the truth |
+
+![Trial Sharpes](https://raw.githubusercontent.com/hossainyousuf751/backtest-lab/main/docs/overfitting_trials.png)
+
+The lesson is that every in-sample defence (DSR, PBO, walk-forward) protects against
+*selection* bias but not against a lucky *sample*. Only independent data (other markets,
+periods, or asset classes) does that.
+
+The two refinements cut in opposite directions. Counting all 45 near-duplicate configurations as
+independent trials makes the Deflated Sharpe too strict; clustering them (`effective_trials`)
+is more accurate, but it removes the margin that rejected this lucky sample. The cluster count also
+depends on the correlation threshold: here it is 1, 2, 10 and 35 at ρ > 0.3, 0.5, 0.7 and 0.9.
+The threshold-free eigenvalue participation ratio is about 3, which supports the 0.5 default.
+
+## Study 2: survivorship bias
+
+150 firms are listed over 12 years; 57 fail, after a decline, with a −50% final return.
+Testing only on the 93 survivors:
+
+| Strategy | Point-in-time universe | Survivors only |
+|---|---|---|
+| Equal-weight: annual return | 9.3% | **12.8%** |
+| Equal-weight: Sharpe | 0.67 | 0.88 |
+| Long-only momentum: annual return | 16.1% | 15.6% |
+
+The bias is large for strategies that would have held the failures, and nearly absent for
+momentum, which sells declining firms before they delist. The engine handles this correctly:
+assets cannot be bought before listing, and delisted holdings become cash.
+
+![Survivorship](https://raw.githubusercontent.com/hossainyousuf751/backtest-lab/main/docs/survivorship.png)
+
+## Study 3: a genuine signal, and what costs leave of it
+
+With a planted persistent-return effect, every check agrees the signal is real: the
+look-ahead test passes, the Deflated Sharpe is 0.996 (1.000 with effective N = 2), and walk-forward
+out-of-sample Sharpe, after the costs of switching configuration, is 1.01 against 1.06 in the full sample.
+
+PBO is 0.54, no better than on noise, and that is the correct answer to a narrower question.
+PBO asks whether picking the in-sample winner *among these configurations* beats picking one at
+random. All 45 variants capture the same signal, so choosing among them adds nothing. A high PBO
+says "don't trust the tuning", not "there is no edge".
+
+Factor attribution against the market (equal-weight index) separates the edge from exposure:
+
+| | Alpha | t-stat | Market beta | R² |
+|---|---|---|---|---|
+| Long-short momentum | 6.1%/yr | 3.3 | 0.01 | 0.00 |
+| Long-only momentum | 6.8%/yr | 3.0 | 1.03 | 0.82 |
+
+The long-only version earns 16%/yr in raw terms, but most of that is beta.
+
+The remaining question is economic. At ~6.4× annual turnover, net Sharpe falls from 1.11
+gross to 0.79 at 30 bps and 0.58 at 50 bps. Borrowing the short leg costs more: a 50 bps/yr
+general-collateral fee takes Sharpe from 1.06 to 1.01, and a 300 bps/yr hard-to-borrow fee takes it to 0.80.
+
+![Cost sensitivity](https://raw.githubusercontent.com/hossainyousuf751/backtest-lab/main/docs/planted_costs.png)
+
+## Study 4: real data
+
+`04_live_sector_momentum.py` runs long-short momentum across the 11 SPDR sector ETFs since
+2000. Sector ETFs are a deliberately survivorship-free universe; late launches (XLRE, XLC)
+enter only once listed. For single stocks, a point-in-time constituent list is required.
+
+Over 2000 to October 2026, the result at 3 bps is a Sharpe of 0.12 (95% CI −0.23 to 0.47), and it
+is gone by 20 bps. Regressed on the Fama-French factors plus momentum:
+
+| | Coef | Newey-West t |
+|---|---|---|
+| Alpha | −0.5%/yr | −0.4 |
+| Market | 0.02 | 2.0 |
+| Size (SMB) | −0.02 | −1.3 |
+| Value (HML) | −0.08 | −5.5 |
+| **Momentum** | **0.40** | **39.6** |
+
+R² is 0.58. Sector momentum is not a new strategy: it is a weak, diluted copy of the stock-level
+momentum factor, which you could hold directly.
+
+![Sector momentum](https://raw.githubusercontent.com/hossainyousuf751/backtest-lab/main/docs/live_sector_momentum.png)
+
+## Study 5: capacity
+
+Flat basis-point costs ignore size. `run_backtest(..., dollar_volume=, capital=)` adds
+square-root market impact, charging `σ_daily × √(trade / ADV)` per unit traded. On the Study 3
+market, with a median stock trading $20m/day:
+
+| Capital | Net Sharpe, monthly | Net Sharpe, quarterly | Cost/yr, monthly |
+|---|---|---|---|
+| $1m | 0.96 | 0.94 | 0.8% |
+| $10m | 0.76 | 0.82 | 1.9% |
+| $100m | 0.13 | 0.43 | 5.3% |
+| $300m | −0.49 | 0.06 | 8.9% |
+| $1bn | −1.41 | −0.52 | 16.1% |
+
+The edge that survives 30 bps of flat costs is gone by about $150m. Rebalancing quarterly
+gives up a little at small size but roughly doubles capacity. The square-root law is
+calibrated for trades below about 10–20% of daily volume, so the far right of the curve
+(where trades exceed ADV) is indicative only.
+
+![Capacity](https://raw.githubusercontent.com/hossainyousuf751/backtest-lab/main/docs/capacity.png)
+
+## Roadmap
+
+- [x] **M1** Engine, strategies, look-ahead test, walk-forward, PSR/DSR, bootstrap CIs, four studies
+- [x] **M2** Probability of Backtest Overfitting via combinatorially symmetric cross-validation
+- [x] **M3** Effective number of trials (cluster correlated configurations) for a sharper DSR
+- [x] **M4** Realistic costs: spread plus square-root market impact as a function of trade size and volume
+- [x] **M5** Factor attribution: regress returns on market, size, value and momentum factors to separate alpha from beta
+- [x] **M6** Walk-forward pays to switch configuration; borrow fees on shorts; point-in-time universe recipe
+
+A real-data single-stock study remains out of scope: free sources such as Yahoo Finance drop
+delisted tickers, so it needs a survivorship-free database (e.g. CRSP or Norgate) plus
+historical index membership.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the project's invariants, roles, workflow and
+testing rules, and [CHANGELOG.md](CHANGELOG.md) for what changed between versions.
+
+## References
+
+- Bailey, D. & López de Prado, M. (2012). The Sharpe Ratio Efficient Frontier. *Journal of Risk* 15(2).
+- Bailey, D. & López de Prado, M. (2014). The Deflated Sharpe Ratio. *Journal of Portfolio Management* 40(5).
+- Bailey, D., Borwein, J., López de Prado, M. & Zhu, Q. (2017). The Probability of Backtest Overfitting. *Journal of Computational Finance* 20(4).
+- Politis, D. & Romano, J. (1994). The Stationary Bootstrap. *JASA* 89(428).
+- Jegadeesh, N. & Titman, S. (1993). Returns to Buying Winners and Selling Losers. *Journal of Finance* 48(1).
+- López de Prado, M. & Lewis, M. (2019). Detection of False Investment Strategies Using Unsupervised Learning Methods. *Quantitative Finance* 19(9).
+- Almgren, R., Thum, C., Hauptmann, E. & Li, H. (2005). Direct Estimation of Equity Market Impact. *Risk* 18(7).
+- Newey, W. & West, K. (1987). A Simple, Positive Semi-Definite, Heteroskedasticity and Autocorrelation Consistent Covariance Matrix. *Econometrica* 55(3).
+- Fama, E. & French, K. (1993). Common Risk Factors in the Returns on Stocks and Bonds. *Journal of Financial Economics* 33(1).
+- Carhart, M. (1997). On Persistence in Mutual Fund Performance. *Journal of Finance* 52(1).

btlab-0.3.0/README.md

@@ -0,0 +1,199 @@
+# backtest-lab
+
+![tests](https://github.com/hossainyousuf751/backtest-lab/actions/workflows/ci.yml/badge.svg)
+
+A backtesting framework built around one question: **should you believe this backtest?**
+
+Most backtests that look good are wrong for one of a handful of reasons: look-ahead bias,
+survivorship bias, ignored trading costs and capacity, returns that are really just factor
+exposure, or picking the best of many configurations and reporting it as if it were the only one. This project builds the tools to detect each of
+these, and validates them on synthetic markets where the true answer is known.
+
+```bash
+pip install -e ".[dev]"
+pytest
+cd examples && python 01_overfitting.py && python 02_survivorship.py && python 03_planted_signal.py && python 05_capacity.py
+pip install -e "..[data]" && python 04_live_sector_momentum.py   # needs internet: Yahoo Finance + Ken French
+```
+
+## Design
+
+| Module | What it does |
+|---|---|
+| `strategies.py` | Strategies return target weights; row *t* is decided at the close of day *t* |
+| `engine.py` | Execution lag, drift between rebalances, turnover-based costs, square-root market impact, delistings, point-in-time universe |
+| `validation.py` | Truncation test for look-ahead bias; walk-forward selection; Probability of Backtest Overfitting (CSCV); effective number of trials |
+| `metrics.py` | Sharpe, Sortino, drawdown, Probabilistic and Deflated Sharpe ratios, block-bootstrap CIs, factor attribution with Newey-West t-stats |
+| `data.py` | Synthetic markets with controllable signal, listings, delistings and traded volume; Yahoo Finance and Ken French factor loaders |
+
+**Timing is explicit.** With close-only data, weights decided at the close of day *t* are
+traded at the close of *t+1* by default (`execution_lag=1`). Positions then drift with
+returns until the next rebalance, so turnover and costs are measured on what the portfolio
+actually holds, not on idealised constant weights.
+
+**Look-ahead is tested, not assumed.** `check_lookahead` recomputes a strategy's weights
+on data truncated at random dates and requires them to match the full-history weights.
+The test suite includes a deliberately cheating strategy: the engine reports a Sharpe
+above 10 for it with zero execution lag, which is why the truncation test, not the engine,
+is the line of defence.
+
+**Walk-forward is a real backtest.** The out-of-sample series trades the stitched weights of
+each fold's chosen configuration, so entering the market and switching configurations pay costs.
+
+**Point-in-time universes need no special engine support.** Mask what the *strategy* sees, not
+the prices the *engine* trades on:
+
+```python
+weights = strategy.weights(prices.where(index_membership))   # rank only current members
+result = run_backtest(prices, weights)                       # exits sold at real prices
+```
+
+Masking the engine's prices instead would turn every index deletion into a fake delisting.
+
+## Study 1: overfitting and luck
+
+On 30 independent markets with **no signal**, 12-1 momentum has a mean Sharpe of +0.01
+but a standard deviation of 0.33, matching the theoretical 1/√years. Twelve years of noise
+routinely produces Sharpe ratios of ±0.6.
+
+On the luckiest of 12 noise markets (deliberately chosen, as a researcher who stops at the
+first good result would), a search over 45 momentum configurations finds:
+
+| Measure | Value | Verdict |
+|---|---|---|
+| Best full-sample Sharpe | 0.86 | looks like a discovery |
+| Probabilistic Sharpe vs 0 | 0.997 | "significant" (ignores the search) |
+| **Deflated Sharpe** | **0.92** | not significant at 95% once 45 trials are accounted for |
+| Deflated Sharpe, N = 2 effective trials | 0.99 | **fooled**: the 45 configs are really ~2 independent bets |
+| Probability of Backtest Overfitting | 0.34 | **fooled**: the in-sample winner usually stays above median |
+| Walk-forward out-of-sample Sharpe | 0.82 | **fooled**: the whole sample is lucky, not just the selection |
+| Chosen config on 20 fresh noise markets | +0.00 | the truth |
+
+![Trial Sharpes](https://raw.githubusercontent.com/hossainyousuf751/backtest-lab/main/docs/overfitting_trials.png)
+
+The lesson is that every in-sample defence (DSR, PBO, walk-forward) protects against
+*selection* bias but not against a lucky *sample*. Only independent data (other markets,
+periods, or asset classes) does that.
+
+The two refinements cut in opposite directions. Counting all 45 near-duplicate configurations as
+independent trials makes the Deflated Sharpe too strict; clustering them (`effective_trials`)
+is more accurate, but it removes the margin that rejected this lucky sample. The cluster count also
+depends on the correlation threshold: here it is 1, 2, 10 and 35 at ρ > 0.3, 0.5, 0.7 and 0.9.
+The threshold-free eigenvalue participation ratio is about 3, which supports the 0.5 default.
+
+## Study 2: survivorship bias
+
+150 firms are listed over 12 years; 57 fail, after a decline, with a −50% final return.
+Testing only on the 93 survivors:
+
+| Strategy | Point-in-time universe | Survivors only |
+|---|---|---|
+| Equal-weight: annual return | 9.3% | **12.8%** |
+| Equal-weight: Sharpe | 0.67 | 0.88 |
+| Long-only momentum: annual return | 16.1% | 15.6% |
+
+The bias is large for strategies that would have held the failures, and nearly absent for
+momentum, which sells declining firms before they delist. The engine handles this correctly:
+assets cannot be bought before listing, and delisted holdings become cash.
+
+![Survivorship](https://raw.githubusercontent.com/hossainyousuf751/backtest-lab/main/docs/survivorship.png)
+
+## Study 3: a genuine signal, and what costs leave of it
+
+With a planted persistent-return effect, every check agrees the signal is real: the
+look-ahead test passes, the Deflated Sharpe is 0.996 (1.000 with effective N = 2), and walk-forward
+out-of-sample Sharpe, after the costs of switching configuration, is 1.01 against 1.06 in the full sample.
+
+PBO is 0.54, no better than on noise, and that is the correct answer to a narrower question.
+PBO asks whether picking the in-sample winner *among these configurations* beats picking one at
+random. All 45 variants capture the same signal, so choosing among them adds nothing. A high PBO
+says "don't trust the tuning", not "there is no edge".
+
+Factor attribution against the market (equal-weight index) separates the edge from exposure:
+
+| | Alpha | t-stat | Market beta | R² |
+|---|---|---|---|---|
+| Long-short momentum | 6.1%/yr | 3.3 | 0.01 | 0.00 |
+| Long-only momentum | 6.8%/yr | 3.0 | 1.03 | 0.82 |
+
+The long-only version earns 16%/yr in raw terms, but most of that is beta.
+
+The remaining question is economic. At ~6.4× annual turnover, net Sharpe falls from 1.11
+gross to 0.79 at 30 bps and 0.58 at 50 bps. Borrowing the short leg costs more: a 50 bps/yr
+general-collateral fee takes Sharpe from 1.06 to 1.01, and a 300 bps/yr hard-to-borrow fee takes it to 0.80.
+
+![Cost sensitivity](https://raw.githubusercontent.com/hossainyousuf751/backtest-lab/main/docs/planted_costs.png)
+
+## Study 4: real data
+
+`04_live_sector_momentum.py` runs long-short momentum across the 11 SPDR sector ETFs since
+2000. Sector ETFs are a deliberately survivorship-free universe; late launches (XLRE, XLC)
+enter only once listed. For single stocks, a point-in-time constituent list is required.
+
+Over 2000 to October 2026, the result at 3 bps is a Sharpe of 0.12 (95% CI −0.23 to 0.47), and it
+is gone by 20 bps. Regressed on the Fama-French factors plus momentum:
+
+| | Coef | Newey-West t |
+|---|---|---|
+| Alpha | −0.5%/yr | −0.4 |
+| Market | 0.02 | 2.0 |
+| Size (SMB) | −0.02 | −1.3 |
+| Value (HML) | −0.08 | −5.5 |
+| **Momentum** | **0.40** | **39.6** |
+
+R² is 0.58. Sector momentum is not a new strategy: it is a weak, diluted copy of the stock-level
+momentum factor, which you could hold directly.
+
+![Sector momentum](https://raw.githubusercontent.com/hossainyousuf751/backtest-lab/main/docs/live_sector_momentum.png)
+
+## Study 5: capacity
+
+Flat basis-point costs ignore size. `run_backtest(..., dollar_volume=, capital=)` adds
+square-root market impact, charging `σ_daily × √(trade / ADV)` per unit traded. On the Study 3
+market, with a median stock trading $20m/day:
+
+| Capital | Net Sharpe, monthly | Net Sharpe, quarterly | Cost/yr, monthly |
+|---|---|---|---|
+| $1m | 0.96 | 0.94 | 0.8% |
+| $10m | 0.76 | 0.82 | 1.9% |
+| $100m | 0.13 | 0.43 | 5.3% |
+| $300m | −0.49 | 0.06 | 8.9% |
+| $1bn | −1.41 | −0.52 | 16.1% |
+
+The edge that survives 30 bps of flat costs is gone by about $150m. Rebalancing quarterly
+gives up a little at small size but roughly doubles capacity. The square-root law is
+calibrated for trades below about 10–20% of daily volume, so the far right of the curve
+(where trades exceed ADV) is indicative only.
+
+![Capacity](https://raw.githubusercontent.com/hossainyousuf751/backtest-lab/main/docs/capacity.png)
+
+## Roadmap
+
+- [x] **M1** Engine, strategies, look-ahead test, walk-forward, PSR/DSR, bootstrap CIs, four studies
+- [x] **M2** Probability of Backtest Overfitting via combinatorially symmetric cross-validation
+- [x] **M3** Effective number of trials (cluster correlated configurations) for a sharper DSR
+- [x] **M4** Realistic costs: spread plus square-root market impact as a function of trade size and volume
+- [x] **M5** Factor attribution: regress returns on market, size, value and momentum factors to separate alpha from beta
+- [x] **M6** Walk-forward pays to switch configuration; borrow fees on shorts; point-in-time universe recipe
+
+A real-data single-stock study remains out of scope: free sources such as Yahoo Finance drop
+delisted tickers, so it needs a survivorship-free database (e.g. CRSP or Norgate) plus
+historical index membership.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the project's invariants, roles, workflow and
+testing rules, and [CHANGELOG.md](CHANGELOG.md) for what changed between versions.
+
+## References
+
+- Bailey, D. & López de Prado, M. (2012). The Sharpe Ratio Efficient Frontier. *Journal of Risk* 15(2).
+- Bailey, D. & López de Prado, M. (2014). The Deflated Sharpe Ratio. *Journal of Portfolio Management* 40(5).
+- Bailey, D., Borwein, J., López de Prado, M. & Zhu, Q. (2017). The Probability of Backtest Overfitting. *Journal of Computational Finance* 20(4).
+- Politis, D. & Romano, J. (1994). The Stationary Bootstrap. *JASA* 89(428).
+- Jegadeesh, N. & Titman, S. (1993). Returns to Buying Winners and Selling Losers. *Journal of Finance* 48(1).
+- López de Prado, M. & Lewis, M. (2019). Detection of False Investment Strategies Using Unsupervised Learning Methods. *Quantitative Finance* 19(9).
+- Almgren, R., Thum, C., Hauptmann, E. & Li, H. (2005). Direct Estimation of Equity Market Impact. *Risk* 18(7).
+- Newey, W. & West, K. (1987). A Simple, Positive Semi-Definite, Heteroskedasticity and Autocorrelation Consistent Covariance Matrix. *Econometrica* 55(3).
+- Fama, E. & French, K. (1993). Common Risk Factors in the Returns on Stocks and Bonds. *Journal of Financial Economics* 33(1).
+- Carhart, M. (1997). On Persistence in Mutual Fund Performance. *Journal of Finance* 52(1).

btlab-0.3.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "btlab"
+version = "0.3.0"
+description = "A backtesting framework built around avoiding the common ways backtests lie"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["numpy>=1.24", "scipy>=1.10", "pandas>=2.0"]
+
+[project.urls]
+Repository = "https://github.com/hossainyousuf751/backtest-lab"
+
+[project.optional-dependencies]
+plot = ["matplotlib>=3.7"]
+data = ["yfinance>=0.2"]
+dev = ["pytest>=7", "matplotlib>=3.7"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

btlab-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

btlab-0.3.0/src/btlab/__init__.py

@@ -0,0 +1,22 @@
+"""btlab: honest backtesting, with tools to detect look-ahead, survivorship and overfitting."""
+
+from btlab.data import synthetic_dollar_volume, synthetic_market
+from btlab.engine import BacktestResult, cost_sensitivity, rebalance_dates, run_backtest
+from btlab.metrics import (
+    annual_return, annual_vol, bootstrap_sharpe_ci, deflated_sharpe, expected_max_sharpe,
+    factor_attribution, max_drawdown, probabilistic_sharpe, sharpe, sortino, summary,
+)
+from btlab.strategies import CrossSectionalMomentum, Strategy, TimeSeriesMomentum
+from btlab.validation import (
+    WalkForwardResult, check_lookahead, effective_trials, probability_of_backtest_overfitting,
+    walk_forward,
+)
+
+__all__ = [
+    "BacktestResult", "CrossSectionalMomentum", "Strategy", "TimeSeriesMomentum",
+    "WalkForwardResult", "annual_return", "annual_vol", "bootstrap_sharpe_ci", "check_lookahead",
+    "cost_sensitivity", "deflated_sharpe", "effective_trials", "expected_max_sharpe",
+    "factor_attribution", "max_drawdown", "probabilistic_sharpe",
+    "probability_of_backtest_overfitting", "rebalance_dates", "run_backtest", "sharpe", "sortino",
+    "summary", "synthetic_dollar_volume", "synthetic_market", "walk_forward",
+]

btlab-0.3.0/src/btlab/data.py

@@ -0,0 +1,117 @@
+"""Synthetic markets with controllable signal, listings and delistings.
+
+Because the data-generating process is known, every claim a backtest makes
+can be checked: on a pure-noise market, no strategy should be significant.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+TRADING_DAYS = 252
+
+
+def synthetic_market(n_assets: int = 100, n_years: int = 10, momentum_strength: float = 0.0,
+                     momentum_half_life: int = 126, delist_rate: float = 0.0,
+                     delisting_return: float = -0.5, late_listing_frac: float = 0.0,
+                     seed: int | None = 0, start: str = "2014-01-01") -> pd.DataFrame:
+    """Daily prices (dates x assets) with NaN before listing and after delisting.
+
+    Returns = beta * market + mu_t + idiosyncratic noise, where mu_t is a
+    persistent AR(1) expected return with annualised cross-sectional standard
+    deviation `momentum_strength`. Past returns are informative about mu_t,
+    so momentum works exactly when momentum_strength > 0.
+
+    Firms that delist (annual hazard `delist_rate`) drift down for six months,
+    then suffer `delisting_return` on their final day.
+    """
+    rng = np.random.default_rng(seed)
+    n_days = TRADING_DAYS * n_years
+    dates = pd.bdate_range(start, periods=n_days)
+
+    vol = rng.uniform(0.20, 0.50, n_assets) / np.sqrt(TRADING_DAYS)
+    beta = rng.uniform(0.6, 1.4, n_assets)
+    market = rng.normal(0.07 / TRADING_DAYS, 0.15 / np.sqrt(TRADING_DAYS), n_days)
+
+    phi = 0.5 ** (1 / momentum_half_life)
+    mu_sd = momentum_strength / TRADING_DAYS
+    mu = np.zeros((n_days, n_assets))
+    mu[0] = rng.normal(0, mu_sd, n_assets)
+    shocks = rng.normal(0, mu_sd * np.sqrt(1 - phi**2), (n_days, n_assets))
+    for t in range(1, n_days):
+        mu[t] = phi * mu[t - 1] + shocks[t]
+
+    rets = beta * market[:, None] + mu + rng.standard_normal((n_days, n_assets)) * vol
+
+    alive = np.ones((n_days, n_assets), dtype=bool)
+    daily_hazard = 1 - (1 - delist_rate) ** (1 / TRADING_DAYS)
+    for j in range(n_assets):
+        if late_listing_frac and rng.random() < late_listing_frac:
+            alive[: rng.integers(1, int(0.6 * n_days)), j] = False
+        if delist_rate:
+            hits = np.flatnonzero(rng.random(n_days) < daily_hazard)
+            hits = hits[hits > 130]
+            if len(hits):
+                d = hits[0]
+                rets[d - 126:d, j] -= 0.4 / 126          # slow decline before failure
+                rets[d, j] = delisting_return
+                alive[d + 1:, j] = False
+
+    rets = np.clip(rets, -0.95, None)
+    rets[0] = 0.0
+    prices = 100 * np.cumprod(1 + rets, axis=0)
+    prices[~alive] = np.nan
+    return pd.DataFrame(prices, index=dates, columns=[f"A{j:03d}" for j in range(n_assets)])
+
+
+def synthetic_dollar_volume(prices: pd.DataFrame, median_adv: float = 2e7, size_dispersion: float = 1.0,
+                            seed: int | None = 0) -> pd.DataFrame:
+    """Daily traded value per asset: a lognormal firm size times lognormal daily noise.
+
+    Firm sizes span roughly two orders of magnitude around `median_adv`
+    (default $20m/day, a small/mid-cap stock), which is what makes capacity
+    depend on which names a strategy trades.
+    """
+    rng = np.random.default_rng(seed)
+    size = median_adv * np.exp(rng.normal(0, size_dispersion, prices.shape[1]))
+    noise = np.exp(rng.normal(-0.045, 0.3, prices.shape))     # mean-one daily variation
+    return pd.DataFrame(size * noise, index=prices.index, columns=prices.columns).where(prices.notna())
+
+
+FRENCH_URL = "https://mba.tuck.dartmouth.edu/pages/faculty/ken.french/ftp/"
+
+
+def load_french_factors(start: str = "1990-01-01") -> pd.DataFrame:
+    """Daily US factors from Kenneth French's data library, as decimals.
+
+    Columns: Mkt-RF, SMB (size), HML (value), RF (T-bill), Mom (momentum).
+    """
+    import io
+    import urllib.request
+    import zipfile
+
+    frames = []
+    for name in ("F-F_Research_Data_Factors_daily_CSV.zip", "F-F_Momentum_Factor_daily_CSV.zip"):
+        with urllib.request.urlopen(FRENCH_URL + name, timeout=60) as resp:
+            zf = zipfile.ZipFile(io.BytesIO(resp.read()))
+        lines = zf.read(zf.namelist()[0]).decode("latin1").splitlines()
+        header = next(i for i, ln in enumerate(lines) if ln.startswith(","))
+        body = [ln for ln in lines[header + 1:] if ln[:8].isdigit()]
+        df = pd.read_csv(io.StringIO("\n".join(body)), header=None, index_col=0,
+                         names=["date"] + [c.strip() for c in lines[header].split(",")[1:]])
+        df.index = pd.to_datetime(df.index.astype(str), format="%Y%m%d")
+        frames.append(df)
+    out = pd.concat(frames, axis=1, join="inner").rename(columns={"MOM": "Mom"}) / 100
+    return out.loc[start:]
+
+
+def load_yfinance(tickers: list[str], start: str = "2005-01-01", end: str | None = None,
+                  field: str = "Close") -> pd.DataFrame:
+    """Adjusted prices (or field="Volume"). Today's ticker list is survivorship-biased for stocks."""
+    try:
+        import yfinance as yf
+    except ImportError as exc:
+        raise ImportError("install the data extra: pip install -e '.[data]'") from exc
+    data = yf.download(tickers, start=start, end=end, auto_adjust=True, progress=False)
+    return data[field].dropna(how="all")