diff --git a/docs/book-guide/index.md b/docs/book-guide/index.md
index 65b74d3e..0080e3d3 100644
--- a/docs/book-guide/index.md
+++ b/docs/book-guide/index.md
@@ -7,19 +7,29 @@ backtest operations. For the library task guide, start at the
bundled synthetic data, so the book and its datasets are optional. All book
links below point to one checked companion revision.
+Each notebook description distinguishes direct library examples from
+research that supplies inputs or interprets outputs. A case study that uses a
+book-specific helper is labeled as such; its helper and datasets are not part
+of the installed `ml4t-backtest` package. Start with the linked library workflow
+for a standalone example.
+
## Chapters and workflows
-| Book section and notebook | What it adds | Library workflow |
+| Book section and notebook | Role and learning task | Library workflow |
|---|---|---|
-| [16.3 Vectorized and event-driven backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/04_single_asset_ml4t_backtest.ipynb) | Run one strategy, reconcile fills and trades | [First backtest](../getting-started/quickstart.md) |
-| [16.3 Stateful strategies](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/05_stateful_strategies.ipynb) | Carry realized state into later decisions | [Risk and state](../tutorials/risk-and-state.md) |
-| [16.5 Understanding performance metrics](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/09_performance_reporting.ipynb) | Read returns and drawdowns | [Result exports](../tutorials/results-and-analysis.md) |
-| [16.3 Vectorized and event-driven backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/07_engine_divergence_anatomy.ipynb) | Change one execution assumption at a time | [Profiles and parity](../tutorials/profiles-and-parity.md) |
-| [17.4 Defining Baseline Allocators](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/17_portfolio_construction/07_conformal_position_sizing.ipynb) | Turn uncertainty into position sizes | [Accounts and constraints](../tutorials/accounts-and-constraints.md) |
-| [17.7 Comparing Allocator Performance](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/17_portfolio_construction/08_library_comparison.ipynb) | Compare allocators with matched inputs | [Multi-asset rebalancing](../tutorials/multiasset-rebalancing.md) |
-| [18.7 Transaction Cost Analysis and Model Validation](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/18_transaction_costs/10_gross_vs_net_performance.ipynb) | Reconcile gross and net performance | [Costs and funding](../tutorials/costs-and-funding.md) |
-| [19.4 Drawdowns, Path Risk, and Time-to-Recovery](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/19_risk_management/02_exit_strategies.ipynb) | Compare fixed and trailing exits | [Risk and state](../tutorials/risk-and-state.md) |
-| [19.4 Drawdowns, Path Risk, and Time-to-Recovery](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/19_risk_management/10_ml4t_backtest_risk_demo.ipynb) | Use library position rules and portfolio limits | [Risk management](../user-guide/risk-management.md) |
+| [Futures backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/02_futures_backtesting.ipynb) | Calls `DataFeed` and `Engine`. Prepare futures bars and contract specifications. | [Example data](../tutorials/data.md) |
+| [16.3 Vectorized and event-driven backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/04_single_asset_ml4t_backtest.ipynb) | Calls `DataFeed` and `Engine`. Run one strategy, reconcile fills and trades. | [First backtest](../getting-started/quickstart.md) |
+| [16.3 Stateful strategies](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/05_stateful_strategies.ipynb) | Calls `DataFeed` and `Engine`. Carry realized state into later decisions. | [Risk and state](../tutorials/risk-and-state.md) |
+| [16.3 Vectorized and event-driven backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/07_engine_divergence_anatomy.ipynb) | Calls `Engine` with controlled settings. Change one execution assumption at a time. | [Profiles and parity](../tutorials/profiles-and-parity.md); [Zipline migration](../user-guide/migrate-from-zipline.md) |
+| [16.5 Understanding performance metrics](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/09_performance_reporting.ipynb) | Calls `Engine` and `ml4t-diagnostic`. Read returns and drawdowns. | [Result exports](../tutorials/results-and-analysis.md) |
+| [Case-study LEAN parity](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/16_case_study_lean_parity.ipynb) | Reads retained comparison evidence. Interpret the bounded framework audit. | [Profiles and parity](../tutorials/profiles-and-parity.md) |
+| [Portfolio performance analysis](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/01_portfolio_metrics.ipynb) | Calls `ml4t-diagnostic` for downstream analysis. Analyze returns and drawdowns. | [Diagnostic handoff](../tutorials/diagnostic-handoff.md) |
+| [17.4 Defining Baseline Allocators](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/07_conformal_position_sizing.ipynb) | Teaches sizing from prediction uncertainty. Turn uncertainty into position sizes. | [Accounts and constraints](../tutorials/accounts-and-constraints.md) |
+| [17.7 Comparing Allocator Performance](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/08_library_comparison.ipynb) | Calls `Engine` for allocator comparison. Compare allocators with matched inputs. | [Multi-asset rebalancing](../tutorials/multiasset-rebalancing.md) |
+| [Market impact scenarios](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/18_transaction_costs/03_market_impact_calibration.ipynb) | Teaches calibration from market panels. Assess size and capacity assumptions. | [Market impact](../user-guide/market-impact.md) |
+| [18.7 Transaction Cost Analysis and Model Validation](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/18_transaction_costs/10_gross_vs_net_performance.ipynb) | Teaches cost analysis from return series. Reconcile gross and net performance. | [Costs and funding](../tutorials/costs-and-funding.md) |
+| [19.4 Drawdowns, Path Risk, and Time-to-Recovery](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/19_risk_management/02_exit_strategies.ipynb) | Uses library risk and trade types in a research comparison. Compare fixed and trailing exits. | [Risk and state](../tutorials/risk-and-state.md) |
+| [19.4 Drawdowns, Path Risk, and Time-to-Recovery](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/19_risk_management/10_ml4t_backtest_risk_demo.ipynb) | Calls `ml4t.backtest.risk` directly. Use library position rules and portfolio limits. | [Risk management](../user-guide/risk-management.md) |
The book develops research questions, statistical interpretation, and
larger datasets. The library pages specify feed contracts, order timing,
@@ -28,13 +38,13 @@ reference when a notebook and the current API differ.
## Case studies
-| Companion example | What it adds | Library workflow |
+| Companion example | Role and learning task | Library workflow |
|---|---|---|
-| [ETF backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/case_studies/etfs/14_backtest.ipynb) | Weight targets from a prediction stream | [Multi-asset rebalancing](../tutorials/multiasset-rebalancing.md) |
-| [CME futures backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/case_studies/cme_futures/13_backtest.ipynb) | Contract multipliers and futures sessions | [Example data](../tutorials/data.md) |
-| [FX pairs backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/case_studies/fx_pairs/13_backtest.ipynb) | USD-quoted pairs and signal alignment | [Data Feed](../user-guide/data-feed.md) |
-| [Crypto perpetual funding](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/case_studies/crypto_perps_funding/16_costs.ipynb) | Funding and transaction-cost assumptions | [Costs and funding](../tutorials/costs-and-funding.md) |
-| [ETF risk controls](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/case_studies/etfs/16_risk_management.ipynb) | Position exits in a full strategy | [Risk management](../tutorials/risk-and-state.md) |
+| [ETF backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/case_studies/etfs/14_backtest.ipynb) | Calls the book helper `backtest_runner`, which uses `Engine`. Weight targets from a prediction stream. | [Multi-asset rebalancing](../tutorials/multiasset-rebalancing.md) |
+| [CME futures backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/case_studies/cme_futures/13_backtest.ipynb) | Uses a book research workflow. Futures prediction selection and equal-weight baseline. | [Example data](../tutorials/data.md) |
+| [FX pairs backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/case_studies/fx_pairs/13_backtest.ipynb) | Uses a book research workflow. FX prediction population and strategy grid. | [Data Feed](../user-guide/data-feed.md) |
+| [Crypto perpetual funding](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/case_studies/crypto_perps_funding/16_costs.ipynb) | Uses a book research workflow. Funding and transaction-cost assumptions. | [Costs and funding](../tutorials/costs-and-funding.md) |
+| [ETF risk controls](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/case_studies/etfs/16_risk_management.ipynb) | Calls the book helper `backtest_runner`, which uses `Engine`. Position exits in a full strategy. | [Risk management](../tutorials/risk-and-state.md) |
## Move from a notebook to a reusable run
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
index 064b3a40..bfd0d197 100644
--- a/docs/getting-started/quickstart.md
+++ b/docs/getting-started/quickstart.md
@@ -81,7 +81,7 @@ choice and timing change fills.
## In the book
-Chapter 16, Section 16.3, [Vectorized and event-driven backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/README.md),
-and [notebook 04, Single Asset Backtest with ml4t-backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/04_single_asset_ml4t_backtest.ipynb)
+Chapter 16, Section 16.3, [Vectorized and event-driven backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/README.md),
+and [notebook 04, Single Asset Backtest with ml4t-backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/04_single_asset_ml4t_backtest.ipynb)
extend this first round trip to a stateful RSI rule, explicit costs, and a matched
comparison with a vectorized backtest.
diff --git a/docs/index.md b/docs/index.md
index cd717e90..fcdf545b 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -10,7 +10,7 @@ how cash is reserved, and how results change when you match another framework's
- :material-play-circle:{ .lg .middle } __Run Your First Backtest__
---
- Define a strategy, pick a config profile, get results in 10 lines.
+ Run a complete strategy on bundled synthetic bars and inspect its fills.
[:octicons-arrow-right-24: Quickstart](getting-started/quickstart.md)
- :material-tune:{ .lg .middle } __User Guide__
@@ -76,6 +76,9 @@ fills=2 final=$100300.00
Each `Engine` instance is single-use. Create a new instance for every independent run.
+Moving a Zipline strategy? Follow the [task-level migration map](user-guide/migrate-from-zipline.md)
+and run its checked target-weight example before comparing framework results.
+
The convenience function accepts the same price panel and strategy directly:
@@ -108,8 +111,8 @@ exercise high event counts.
| Feature | Description |
|---------|-------------|
-| Event-driven | Point-in-time correctness, no look-ahead bias |
-| 40+ behavioral knobs | Every execution detail is configurable |
+| Event-driven | Explicit decision and fill timing; same-bar settings require a causal-data check |
+| Configurable behavior | Set fill timing, cash, costs, and order processing explicitly |
| Quote-aware execution | Side-aware fills and separate mark pricing |
| 10 framework profiles | Configure VectorBT, Backtrader, Zipline, and LEAN semantics |
| Risk management | Stop-loss, take-profit, trailing stops, portfolio limits |
diff --git a/docs/tutorials/accounts-and-constraints.md b/docs/tutorials/accounts-and-constraints.md
index 474f41c6..20bed93c 100644
--- a/docs/tutorials/accounts-and-constraints.md
+++ b/docs/tutorials/accounts-and-constraints.md
@@ -141,9 +141,9 @@ instead of inferring acceptance from requested weights.
## In the book
-Chapter 17, Section 17.1, [Defining the allocation problem](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/17_portfolio_construction/README.md),
+Chapter 17, Section 17.1, [Defining the allocation problem](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/README.md),
sets out the role of constraints and leverage. [Notebook 07, Conformal position
-sizing](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/17_portfolio_construction/07_conformal_position_sizing.ipynb)
+sizing](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/07_conformal_position_sizing.ipynb)
uses registered ETF and futures predictions to study a larger sizing problem.
The controlled runs here make the account and execution layer inspectable
before applying a book allocator.
diff --git a/docs/tutorials/costs-and-funding.md b/docs/tutorials/costs-and-funding.md
index adf25dc7..33d203f0 100644
--- a/docs/tutorials/costs-and-funding.md
+++ b/docs/tutorials/costs-and-funding.md
@@ -188,8 +188,8 @@ total commission: $10.00
## In the book
-Chapter 18, Section 18.7, [Transaction cost analysis and model validation](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/18_transaction_costs/README.md),
-and [notebook 10, Gross versus net performance](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/18_transaction_costs/10_gross_vs_net_performance.ipynb)
+Chapter 18, Section 18.7, [Transaction cost analysis and model validation](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/18_transaction_costs/README.md),
+and [notebook 10, Gross versus net performance](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/18_transaction_costs/10_gross_vs_net_performance.ipynb)
extend the cost decomposition to larger strategy runs. The [crypto-perpetual
-cost notebook](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/case_studies/crypto_perps_funding/16_costs.ipynb)
+cost notebook](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/case_studies/crypto_perps_funding/16_costs.ipynb)
adds case-study funding and fee assumptions.
diff --git a/docs/tutorials/data.md b/docs/tutorials/data.md
index 3888b8c1..57282664 100644
--- a/docs/tutorials/data.md
+++ b/docs/tutorials/data.md
@@ -173,4 +173,4 @@ sources for the synthetic panels.
## In the book
-Chapter 16, Section 16.3, [Futures backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/02_futures_backtesting.ipynb) extends the small synthetic futures panel to a longer contract history. [FX pairs backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/case_studies/fx_pairs/13_backtest.ipynb) shows how a research prediction stream becomes aligned feed input.
+Chapter 16, Section 16.3, [Futures backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/02_futures_backtesting.ipynb) extends the small synthetic futures panel to a longer contract history. [FX pairs backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/case_studies/fx_pairs/13_backtest.ipynb) shows how a research prediction stream becomes aligned feed input.
diff --git a/docs/tutorials/diagnostic-handoff.md b/docs/tutorials/diagnostic-handoff.md
index aec0aa74..b1e3dadd 100644
--- a/docs/tutorials/diagnostic-handoff.md
+++ b/docs/tutorials/diagnostic-handoff.md
@@ -48,4 +48,4 @@ reference for trade, fill, and portfolio-state handoffs.
## In the book
-Chapter 17, Section 17.3, [Portfolio metrics](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/17_portfolio_construction/01_portfolio_metrics.ipynb) applies `ml4t-diagnostic` to a larger ETF allocation. The small example above tests the bridge before adding benchmark and rolling analyses.
+Chapter 17, Section 17.3, [Portfolio metrics](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/01_portfolio_metrics.ipynb) applies `ml4t-diagnostic` to a larger ETF allocation. The small example above tests the bridge before adding benchmark and rolling analyses.
diff --git a/docs/tutorials/multiasset-rebalancing.md b/docs/tutorials/multiasset-rebalancing.md
index ded14bcf..62dcbd52 100644
--- a/docs/tutorials/multiasset-rebalancing.md
+++ b/docs/tutorials/multiasset-rebalancing.md
@@ -228,8 +228,8 @@ guide covers cash and margin settings used by these variants.
## In the book
-Chapter 17, Section 17.7, [Comparing allocator performance](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/17_portfolio_construction/README.md),
-and [notebook 08, Library comparison](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/17_portfolio_construction/08_library_comparison.ipynb)
-compare portfolio construction workflows. [Chapter 16's futures notebook](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/02_futures_backtesting.ipynb)
-adds contract and overnight-session assumptions; the [FX case-study backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/case_studies/fx_pairs/13_backtest.ipynb)
+Chapter 17, Section 17.7, [Comparing allocator performance](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/README.md),
+and [notebook 08, Library comparison](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/08_library_comparison.ipynb)
+compare portfolio construction workflows. [Chapter 16's futures notebook](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/02_futures_backtesting.ipynb)
+adds contract and overnight-session assumptions; the [FX case-study backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/case_studies/fx_pairs/13_backtest.ipynb)
applies targets to a larger prediction stream.
diff --git a/docs/tutorials/orders-and-timing.md b/docs/tutorials/orders-and-timing.md
index d51ba08b..feea74b3 100644
--- a/docs/tutorials/orders-and-timing.md
+++ b/docs/tutorials/orders-and-timing.md
@@ -83,6 +83,6 @@ describes processing order and price selection.
## In the book
-Chapter 16, Section 16.3, [Vectorized and event-driven backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/README.md),
-and [notebook 04, Single Asset Backtest with ml4t-backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/04_single_asset_ml4t_backtest.ipynb)
+Chapter 16, Section 16.3, [Vectorized and event-driven backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/README.md),
+and [notebook 04, Single Asset Backtest with ml4t-backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/04_single_asset_ml4t_backtest.ipynb)
apply order timing to a stateful RSI example with explicit costs.
diff --git a/docs/tutorials/profiles-and-parity.md b/docs/tutorials/profiles-and-parity.md
index 9458d89d..31cefb78 100644
--- a/docs/tutorials/profiles-and-parity.md
+++ b/docs/tutorials/profiles-and-parity.md
@@ -124,8 +124,8 @@ describes the comparison process and canonical precision.
## In the book
-Chapter 16, [Framework parity and engine divergence](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/README.md),
-includes [notebook 07, Engine divergence anatomy](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/07_engine_divergence_anatomy.ipynb),
+Chapter 16, [Framework parity and engine divergence](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/README.md),
+includes [notebook 07, Engine divergence anatomy](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/07_engine_divergence_anatomy.ipynb),
which changes one configuration field at a time, and [notebook 16, Case-study
-LEAN parity](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/16_case_study_lean_parity.ipynb),
+LEAN parity](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/16_case_study_lean_parity.ipynb),
which reports the bounded cross-framework audit.
diff --git a/docs/tutorials/results-and-analysis.md b/docs/tutorials/results-and-analysis.md
index 2bbd9766..13fca79b 100644
--- a/docs/tutorials/results-and-analysis.md
+++ b/docs/tutorials/results-and-analysis.md
@@ -121,7 +121,7 @@ shows an optional, tested post-backtest analysis step.
## In the book
-Chapter 16, [Strategy simulation and reporting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/README.md),
-uses fill and trade reconciliation in [notebook 04, Single asset ml4t-backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/04_single_asset_ml4t_backtest.ipynb).
-Chapter 17's [portfolio metrics notebook](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/17_portfolio_construction/01_portfolio_metrics.ipynb)
+Chapter 16, [Strategy simulation and reporting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/README.md),
+uses fill and trade reconciliation in [notebook 04, Single asset ml4t-backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/04_single_asset_ml4t_backtest.ipynb).
+Chapter 17's [portfolio metrics notebook](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/01_portfolio_metrics.ipynb)
extends the reporting workflow to allocation diagnostics.
diff --git a/docs/tutorials/risk-and-state.md b/docs/tutorials/risk-and-state.md
index cde27154..6403e977 100644
--- a/docs/tutorials/risk-and-state.md
+++ b/docs/tutorials/risk-and-state.md
@@ -129,7 +129,7 @@ show other uses of callback state.
## In the book
-Chapter 19, Section 19.4, [Drawdowns, path risk, and time to recovery](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/19_risk_management/README.md),
+Chapter 19, Section 19.4, [Drawdowns, path risk, and time to recovery](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/19_risk_management/README.md),
puts this event trace in a broader risk framework. [Notebook 10, ml4t-backtest
-risk demo](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/19_risk_management/10_ml4t_backtest_risk_demo.ipynb)
+risk demo](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/19_risk_management/10_ml4t_backtest_risk_demo.ipynb)
uses the library's position rules and portfolio controls on larger examples.
diff --git a/docs/user-guide/accounts.md b/docs/user-guide/accounts.md
index de06e5d1..81bce29a 100644
--- a/docs/user-guide/accounts.md
+++ b/docs/user-guide/accounts.md
@@ -276,7 +276,7 @@ schema change requires `--write` and review of the resulting snapshot diff.
## In the book
-Chapter 17, Section 17.4, [Conformal position sizing](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/17_portfolio_construction/07_conformal_position_sizing.ipynb) turns prediction uncertainty into position sizes. The account tutorial here shows how buying power and share precision affect those sizes.
+Chapter 17, Section 17.4, [Conformal position sizing](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/07_conformal_position_sizing.ipynb) turns prediction uncertainty into position sizes. The account tutorial here shows how buying power and share precision affect those sizes.
## Next Steps
diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
index ee997264..1e5f8606 100644
--- a/docs/user-guide/configuration.md
+++ b/docs/user-guide/configuration.md
@@ -518,7 +518,7 @@ Use this with a `DataFeed` whose `FeedSpec` maps `price_col`, `bid_col`, `ask_co
## In the book
-Chapter 16, Section 16.3, [Engine divergence anatomy](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/07_engine_divergence_anatomy.ipynb) changes one execution assumption at a time. Use this reference to identify and record the corresponding `BacktestConfig` fields.
+Chapter 16, Section 16.3, [Engine divergence anatomy](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/07_engine_divergence_anatomy.ipynb) changes one execution assumption at a time. Use this reference to identify and record the corresponding `BacktestConfig` fields.
## Next Steps
diff --git a/docs/user-guide/data-feed.md b/docs/user-guide/data-feed.md
index 0cc43413..67a71428 100644
--- a/docs/user-guide/data-feed.md
+++ b/docs/user-guide/data-feed.md
@@ -282,7 +282,7 @@ DataFeed pre-partitions data by timestamp at initialization and pre-extracts col
## In the book
-Chapter 16, Section 16.3, [Futures backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/02_futures_backtesting.ipynb) works through contract and session inputs. The [FX pairs backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/case_studies/fx_pairs/13_backtest.ipynb) extends feed alignment to a prediction stream.
+Chapter 16, Section 16.3, [Futures backtesting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/02_futures_backtesting.ipynb) works through contract and session inputs. The [FX pairs backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/case_studies/fx_pairs/13_backtest.ipynb) extends feed alignment to a prediction stream.
## Next Steps
diff --git a/docs/user-guide/execution-semantics.md b/docs/user-guide/execution-semantics.md
index 16f7355c..8f553ea6 100644
--- a/docs/user-guide/execution-semantics.md
+++ b/docs/user-guide/execution-semantics.md
@@ -547,7 +547,7 @@ config = BacktestConfig(share_type=ShareType.INTEGER)
## In the book
-Chapter 16, Section 16.3, [Engine divergence anatomy](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/07_engine_divergence_anatomy.ipynb) isolates fill timing and ordering differences. This page specifies the current engine behavior behind those comparisons.
+Chapter 16, Section 16.3, [Engine divergence anatomy](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/07_engine_divergence_anatomy.ipynb) isolates fill timing and ordering differences. This page specifies the current engine behavior behind those comparisons.
## Next Steps
diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md
index 4ebe6f52..e83dcb2f 100644
--- a/docs/user-guide/index.md
+++ b/docs/user-guide/index.md
@@ -6,17 +6,18 @@ The code in the [Getting Started tutorials](../getting-started/quickstart.md) ru
## Find the task you need
-| Task | Start here | Complete example |
+| Task | Guide and runnable example | API contract and book notebook |
|---|---|---|
-| Prepare bars, signals, context, and timestamps | [Data Feed](data-feed.md) | [Bundled example data](../tutorials/data.md) |
-| Write decisions and carry state between callbacks | [Strategies](strategies.md) and [Stateful Strategies](stateful-strategies.md) | [First backtest](../getting-started/quickstart.md) and [Risk and State](../tutorials/risk-and-state.md) |
-| Choose order types and determine when fills can occur | [Order Types](orders.md) and [Execution Semantics](execution-semantics.md) | [Orders and Timing](../tutorials/orders-and-timing.md) |
-| Allocate across assets and deal with different daily close times | [Rebalancing](rebalancing.md) | [Multi-asset Rebalancing](../tutorials/multiasset-rebalancing.md) |
-| Set cash, margin, contract, and sizing rules | [Account Policies](accounts.md) and [Configuration](configuration.md) | [Accounts and Constraints](../tutorials/accounts-and-constraints.md) |
-| Model commission, slippage, impact, and funding | [Market Impact and Execution Costs](market-impact.md) | [Costs and Funding](../tutorials/costs-and-funding.md) |
-| Add position exits and portfolio limits | [Risk Management](risk-management.md) | [Risk and State](../tutorials/risk-and-state.md) |
-| Compare explicit execution settings | [Profiles](profiles.md) | [Profiles and Parity](../tutorials/profiles-and-parity.md) |
-| Export fills, trades, equity, and portfolio state | [Results and Analysis](results.md) | [Results and Analysis](../tutorials/results-and-analysis.md) |
+| Prepare bars, signals, context, and timestamps | [Data Feed](data-feed.md)
Run: [Bundled example data](../tutorials/data.md) | [DataFeed](../api/index.md#ml4t.backtest.datafeed.DataFeed)
Book: [Futures feed](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/02_futures_backtesting.ipynb) |
+| Write decisions and carry state between callbacks | [Strategies](strategies.md) and [Stateful Strategies](stateful-strategies.md)
Run: [First backtest](../getting-started/quickstart.md) and [Risk and State](../tutorials/risk-and-state.md) | [Strategy.on_data](../api/index.md#ml4t.backtest.strategy.Strategy.on_data)
Book: [Stateful strategies](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/05_stateful_strategies.ipynb) |
+| Choose order types and determine when fills can occur | [Order Types](orders.md) and [Execution Semantics](execution-semantics.md)
Run: [Orders and Timing](../tutorials/orders-and-timing.md) | [Broker.submit_order](../api/index.md#ml4t.backtest.broker.Broker.submit_order)
Book: [Single asset backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/04_single_asset_ml4t_backtest.ipynb) |
+| Allocate across assets and deal with different daily close times | [Rebalancing](rebalancing.md)
Run: [Multi-asset Rebalancing](../tutorials/multiasset-rebalancing.md) | [Broker.rebalance_to_weights](../api/index.md#ml4t.backtest.broker.Broker.rebalance_to_weights)
Book: [Allocator comparison](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/08_library_comparison.ipynb) |
+| Set cash, margin, contract, and sizing rules | [Account Policies](accounts.md) and [Configuration](configuration.md)
Run: [Accounts and Constraints](../tutorials/accounts-and-constraints.md) | [BacktestConfig](../api/index.md#ml4t.backtest.config.BacktestConfig)
Book: [Conformal sizing](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/07_conformal_position_sizing.ipynb) |
+| Model commission, slippage, impact, and funding | [Market Impact and Execution Costs](market-impact.md)
Run: [Costs and Funding](../tutorials/costs-and-funding.md) | [BacktestConfig](../api/index.md#ml4t.backtest.config.BacktestConfig)
Book: [Gross versus net](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/18_transaction_costs/10_gross_vs_net_performance.ipynb) |
+| Add position exits and portfolio limits | [Risk Management](risk-management.md)
Run: [Risk and State](../tutorials/risk-and-state.md) | [StopLoss](../api/index.md#ml4t.backtest.risk.position.static.StopLoss)
Book: [Library risk demo](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/19_risk_management/10_ml4t_backtest_risk_demo.ipynb) |
+| Compare explicit execution settings | [Profiles](profiles.md)
Run: [Profiles and Parity](../tutorials/profiles-and-parity.md) | [BacktestConfig.from_preset](../api/index.md#ml4t.backtest.config.BacktestConfig.from_preset)
Book: [Engine divergence](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/07_engine_divergence_anatomy.ipynb) |
+| Export fills, trades, equity, and portfolio state | [Results and Analysis](results.md)
Run: [Results and Analysis](../tutorials/results-and-analysis.md) | [BacktestResult](../api/index.md#ml4t.backtest.result.BacktestResult)
Book: [Performance reporting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/09_performance_reporting.ipynb) |
+| Move an existing Zipline strategy to prepared bars and explicit settings | [Migrate from Zipline](migrate-from-zipline.md)
Run: [Complete migration example](migrate-from-zipline.md#run-the-mapped-strategy) | [Engine.run](../api/index.md#ml4t.backtest.engine.Engine.run)
Book: [Engine divergence](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/07_engine_divergence_anatomy.ipynb) |
## Choose an asset example
diff --git a/docs/user-guide/market-impact.md b/docs/user-guide/market-impact.md
index be7a278c..60bb5e3f 100644
--- a/docs/user-guide/market-impact.md
+++ b/docs/user-guide/market-impact.md
@@ -294,7 +294,7 @@ print(f"Cost drag: {cost_drag:.2f}%")
## In the book
-Chapter 18, Section 18.4, [Market impact calibration](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/18_transaction_costs/03_market_impact_calibration.ipynb) examines how execution size changes impact. [Gross versus net performance](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/18_transaction_costs/10_gross_vs_net_performance.ipynb) shows the portfolio effect of those costs.
+Chapter 18, Section 18.4, [Market impact calibration](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/18_transaction_costs/03_market_impact_calibration.ipynb) examines how execution size changes impact. [Gross versus net performance](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/18_transaction_costs/10_gross_vs_net_performance.ipynb) shows the portfolio effect of those costs.
## Next Steps
diff --git a/docs/user-guide/migrate-from-zipline.md b/docs/user-guide/migrate-from-zipline.md
new file mode 100644
index 00000000..57ce9a58
--- /dev/null
+++ b/docs/user-guide/migrate-from-zipline.md
@@ -0,0 +1,102 @@
+# Migrate a Zipline strategy
+
+Move one strategy at a time. Start with the same prepared bars, decision times,
+order sizes, and account assumptions, then compare fills and equity. The
+[complete example below](#run-the-mapped-strategy) runs from the installed
+`ml4t-backtest` wheel with bundled synthetic bars. It does not require a Zipline
+installation or a data service.
+
+## Map the work, not just the function names
+
+| Zipline Reloaded task | ML4T Backtest task | Difference to check |
+|---|---|---|
+| Ingest a data bundle, then select assets with `symbol()` | Prepare a Polars panel with `timestamp`, `asset`, and `close`; pass it to [`DataFeed`](data-feed.md) | `DataFeed` does not ingest a Zipline bundle or apply its asset metadata and corporate-action adjustments. Prepare and validate those inputs before the run. |
+| Define `initialize(context)` and `handle_data(context, data)` | Subclass [`Strategy`](strategies.md), initialize state in `__init__` or `on_start`, and decide in `on_data(timestamp, data, context, broker)` | `on_data` receives a mapping of the assets present at that event. Strategy state belongs on the instance. `on_start` runs before any bar; `on_prepare` is reserved for causally available preopen decisions. |
+| Read `data.current(asset, "price")` and `data.history(...)` | Read the current asset's bar in `data[asset]`; precompute rolling features and supply them through `signals_df` | A `DataFeed` callback does not expose Zipline's rolling `data.history` API. Align each feature with the bar on which it becomes available. |
+| Call `order(asset, quantity)` or `order_target_percent(asset, weight)` | Call [`broker.submit_order`](../api/index.md#ml4t.backtest.broker.Broker.submit_order) or [`broker.order_target_percent`](../api/index.md#ml4t.backtest.broker.Broker.order_target_percent) inside `on_data` | The asset is a string identifier. Check share precision, pending orders, buying power, and next eligible fill; identical method names do not imply identical execution. |
+| Use `schedule_function` with date and time rules | Decide in `on_data`, or use [`RebalanceSchedule`](rebalancing.md#schedule-metadata) with `TargetWeightExecutor` for session-based rebalancing | The scheduling APIs are different. Supply calendar and session metadata explicitly; for assets with different close times, use `session_col` and next-bar execution. |
+| Set commission and slippage models | Set explicit [`BacktestConfig`](configuration.md) costs and, where needed, market impact and funding inputs | Default ML4T examples charge no commission or slippage. Reconcile cost amounts separately from fills and share quantities. |
+| Call `record(...)` and inspect the performance frame | Keep custom observations on the strategy instance; inspect [`BacktestResult`](results.md) fills, trades, equity, and exported frames | There is no `record` call with Zipline's performance-frame contract. Join your observations to result timestamps explicitly. |
+| Run `zipline run` or `run_algorithm(...)` | Construct [`Engine`](../api/index.md#ml4t.backtest.engine.Engine) and call `run()`, or use `run_backtest(...)` | A run uses prepared inputs and one `Engine` instance. Create a new engine for another scenario. |
+
+Zipline's [tutorial](https://zipline.ml4trading.io/beginner-tutorial) documents
+its callback, bundle, order, history, and `record` workflow. Its
+[API reference](https://zipline.ml4trading.io/api-reference.html) defines
+`order_target_percent` and `schedule_function`. The mapping above names
+corresponding tasks; it does not promise framework equivalence.
+
+## Run the mapped strategy
+
+This strategy targets 10% AAPL exposure at its first daily bar and zero at its
+fifth. The nine AAPL bars are synthetic. With integer shares and $100,000
+starting cash, the first target becomes 53 shares. The default `NEXT_BAR`
+execution mode fills market orders at the next asset bar's open. No cost,
+slippage, corporate action, or live market behavior is modeled in this example.
+
+
+```python
+from importlib.metadata import version
+
+import polars as pl
+from ml4t.backtest import BacktestConfig, DataFeed, Engine, Strategy
+from ml4t.backtest.example_data import load_example_prices
+
+
+class TargetStrategy(Strategy):
+ def __init__(self):
+ self.asset_bars = 0
+
+ def on_data(self, timestamp, data, context, broker):
+ if "AAPL" not in data:
+ return
+ self.asset_bars += 1
+ if self.asset_bars == 1:
+ broker.order_target_percent("AAPL", 0.10)
+ elif self.asset_bars == 5:
+ broker.order_target_percent("AAPL", 0.0)
+
+
+prices = load_example_prices("equity").filter(pl.col("asset") == "AAPL")
+result = Engine(
+ DataFeed(prices_df=prices), TargetStrategy(), BacktestConfig(initial_cash=100_000)
+).run()
+print("ml4t-backtest " + version("ml4t-backtest"))
+for fill in result.fills:
+ print(f"{fill.timestamp:%Y-%m-%d} {fill.side.value} {fill.quantity:g} @ ${fill.price:.2f}")
+print(f"closed trades: {len(result.to_trades_dataframe())}")
+print(f"final equity: ${result.metrics['final_value']:.2f}")
+```
+
+
+```text
+ml4t-backtest {package_version}
+2024-01-03 buy 53 @ $188.37
+2024-01-09 sell 53 @ $191.37
+closed trades: 1
+final equity: $100159.00
+```
+
+The January 2 and January 8 decisions fill on January 3 and January 9. The
+$159 gain is 53 shares times the $3 change between the two fill prices. Check
+[`to_fills_dataframe()`](../api/index.md#ml4t.backtest.result.BacktestResult.to_fills_dataframe)
+and [`to_equity_dataframe()`](../api/index.md#ml4t.backtest.result.BacktestResult.to_equity_dataframe)
+when migrating a real strategy; a matching final value alone can hide different
+orders or interim exposure.
+
+## Check a migrated run
+
+1. Export Zipline's ordered transactions and portfolio values from the original
+ run. Preserve its data bundle, calendar, cost models, and package version.
+2. Prepare the same adjusted price history and asset set for `DataFeed`. State
+ each timestamp's timezone and whether it represents a bar open or close.
+3. Start with one asset and one order. Compare submission times, fill times,
+ quantities, fill prices, cash, and equity. Add target sizing, costs, and
+ multi-asset sessions separately.
+4. Use the [`zipline` profile](profiles.md) only for the library's documented
+ comparison protocol. It is not a substitute for recording the original
+ Zipline run's native settings.
+
+The [engine-divergence notebook](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/07_engine_divergence_anatomy.ipynb)
+calls `ml4t-backtest` with controlled setting changes. The [Book Guide](../book-guide/index.md)
+identifies the role of other linked notebooks. For existing framework evidence,
+see [Profiles](profiles.md); its supported workload and cost boundaries apply.
diff --git a/docs/user-guide/orders.md b/docs/user-guide/orders.md
index 21c861a6..ecf477fe 100644
--- a/docs/user-guide/orders.md
+++ b/docs/user-guide/orders.md
@@ -156,7 +156,7 @@ broker.cancel_order(order.id)
## In the book
-Chapter 16, Section 16.3, [Single asset ml4t-backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/04_single_asset_ml4t_backtest.ipynb) reconciles submitted decisions with completed fills. The [engine divergence notebook](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/07_engine_divergence_anatomy.ipynb) in the companion varies execution assumptions.
+Chapter 16, Section 16.3, [Single asset ml4t-backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/04_single_asset_ml4t_backtest.ipynb) reconciles submitted decisions with completed fills. The [engine divergence notebook](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/07_engine_divergence_anatomy.ipynb) in the companion varies execution assumptions.
## Next Steps
diff --git a/docs/user-guide/profiles.md b/docs/user-guide/profiles.md
index 547f1575..c9744c71 100644
--- a/docs/user-guide/profiles.md
+++ b/docs/user-guide/profiles.md
@@ -263,7 +263,7 @@ print(list_profiles())
## In the book
-Chapter 16, Section 16.3, [Engine divergence anatomy](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/07_engine_divergence_anatomy.ipynb) changes one setting at a time; [Case-study LEAN parity](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/16_case_study_lean_parity.ipynb) reports the bounded comparison audit. The profile tables here identify the configuration used for each retained library workload.
+Chapter 16, Section 16.3, [Engine divergence anatomy](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/07_engine_divergence_anatomy.ipynb) changes one setting at a time; [Case-study LEAN parity](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/16_case_study_lean_parity.ipynb) reports the bounded comparison audit. The profile tables here identify the configuration used for each retained library workload.
## Next Steps
diff --git a/docs/user-guide/rebalancing.md b/docs/user-guide/rebalancing.md
index 15a399d9..4c1dc15a 100644
--- a/docs/user-guide/rebalancing.md
+++ b/docs/user-guide/rebalancing.md
@@ -179,7 +179,7 @@ callback override.
## In the book
-Chapter 17, Section 17.7, [Library comparison](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/17_portfolio_construction/08_library_comparison.ipynb) compares allocation methods on matched inputs. This page covers how those target weights become timed, sized orders.
+Chapter 17, Section 17.7, [Library comparison](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/17_portfolio_construction/08_library_comparison.ipynb) compares allocation methods on matched inputs. This page covers how those target weights become timed, sized orders.
## Next Steps
diff --git a/docs/user-guide/results.md b/docs/user-guide/results.md
index 53330a82..5937c8f0 100644
--- a/docs/user-guide/results.md
+++ b/docs/user-guide/results.md
@@ -577,7 +577,7 @@ print(result.config.preset_name)
## In the book
-Chapter 16, Section 16.5, [Performance reporting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/09_performance_reporting.ipynb) develops return and drawdown interpretation. This page defines the result frames and artifact format used to reproduce those reports.
+Chapter 16, Section 16.5, [Performance reporting](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/09_performance_reporting.ipynb) develops return and drawdown interpretation. This page defines the result frames and artifact format used to reproduce those reports.
## Next Steps
diff --git a/docs/user-guide/risk-management.md b/docs/user-guide/risk-management.md
index 33522ffe..916eb230 100644
--- a/docs/user-guide/risk-management.md
+++ b/docs/user-guide/risk-management.md
@@ -341,7 +341,7 @@ if risk_manager.is_halted:
## In the book
-Chapter 19, Section 19.4, [ml4t-backtest risk demo](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/19_risk_management/10_ml4t_backtest_risk_demo.ipynb) applies position rules and portfolio limits. The [exit strategies notebook](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/19_risk_management/02_exit_strategies.ipynb) compares stop choices.
+Chapter 19, Section 19.4, [ml4t-backtest risk demo](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/19_risk_management/10_ml4t_backtest_risk_demo.ipynb) applies position rules and portfolio limits. The [exit strategies notebook](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/19_risk_management/02_exit_strategies.ipynb) compares stop choices.
## Next Steps
diff --git a/docs/user-guide/stateful-strategies.md b/docs/user-guide/stateful-strategies.md
index c326d292..8d13d0e6 100644
--- a/docs/user-guide/stateful-strategies.md
+++ b/docs/user-guide/stateful-strategies.md
@@ -409,7 +409,7 @@ See `examples/stateful_strategies.py` for complete implementations and `examples
## In the book
-Chapter 16, Section 16.3, [Stateful strategies](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/05_stateful_strategies.ipynb) demonstrates decisions that depend on prior fills and account state. The runnable risk tutorial here traces one such path across callbacks.
+Chapter 16, Section 16.3, [Stateful strategies](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/05_stateful_strategies.ipynb) demonstrates decisions that depend on prior fills and account state. The runnable risk tutorial here traces one such path across callbacks.
## Next Steps
diff --git a/docs/user-guide/strategies.md b/docs/user-guide/strategies.md
index 4fc52c7e..d30b3b46 100644
--- a/docs/user-guide/strategies.md
+++ b/docs/user-guide/strategies.md
@@ -293,7 +293,7 @@ class AssetSpecificRules(Strategy):
## In the book
-Chapter 16, Section 16.3, [Single asset ml4t-backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/366e1d51ace2d851776499a68da3d6e3c2641b02/16_strategy_simulation/04_single_asset_ml4t_backtest.ipynb) implements an event-driven strategy and reconciles its trade log. This page describes the reusable `Strategy` interface.
+Chapter 16, Section 16.3, [Single asset ml4t-backtest](https://github.com/stefan-jansen/machine-learning-for-trading/blob/2d6e8f95eeccaee66906245606471f570b5807e5/16_strategy_simulation/04_single_asset_ml4t_backtest.ipynb) implements an event-driven strategy and reconciles its trade log. This page describes the reusable `Strategy` interface.
## Next Steps
diff --git a/mkdocs.yml b/mkdocs.yml
index 8d947cea..72b4d737 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -124,6 +124,7 @@ nav:
- Execution Semantics: user-guide/execution-semantics.md
- Configuration: user-guide/configuration.md
- Profiles: user-guide/profiles.md
+ - Migrate from Zipline: user-guide/migrate-from-zipline.md
- Risk Management: user-guide/risk-management.md
- Account Policies: user-guide/accounts.md
- Rebalancing: user-guide/rebalancing.md
diff --git a/tests/contracts/test_documentation_links.py b/tests/contracts/test_documentation_links.py
index d67ecb6d..1b6c0e76 100644
--- a/tests/contracts/test_documentation_links.py
+++ b/tests/contracts/test_documentation_links.py
@@ -1,4 +1,4 @@
-"""Rendered guide links must resolve to pages, sections, and reachable URLs."""
+"""Rendered internal links and external guide URLs must resolve."""
from __future__ import annotations
@@ -71,3 +71,17 @@ def log_message(self, *args: object) -> None:
server.shutdown()
thread.join()
server.server_close()
+
+
+def test_homepage_internal_fragment_is_checked(tmp_path: Path) -> None:
+ checker = _load_checker()
+ homepage = tmp_path / "index.html"
+ guide = tmp_path / "user-guide" / "index.html"
+ guide.parent.mkdir(parents=True)
+ guide.write_text('Working
')
+ homepage.write_text('Guide')
+ assert checker.check_links(tmp_path) == (1, 0)
+
+ homepage.write_text('Guide')
+ with pytest.raises(ValueError, match="missing anchor"):
+ checker.check_links(tmp_path)
diff --git a/validation/book_link_manifest.json b/validation/book_link_manifest.json
index cd6888f3..2b527861 100644
--- a/validation/book_link_manifest.json
+++ b/validation/book_link_manifest.json
@@ -1,5 +1,5 @@
{
- "commit": "366e1d51ace2d851776499a68da3d6e3c2641b02",
+ "commit": "2d6e8f95eeccaee66906245606471f570b5807e5",
"blobs": {
"16_strategy_simulation/02_futures_backtesting.ipynb": "66fd0866d02a5e30e6f07d9ae5b2f39d121f1d98",
"16_strategy_simulation/04_single_asset_ml4t_backtest.ipynb": "7cdb38231b8250531db3c17eebcb63959471fda0",
diff --git a/validation/check_documentation_examples.py b/validation/check_documentation_examples.py
index 96eff290..0189f56f 100644
--- a/validation/check_documentation_examples.py
+++ b/validation/check_documentation_examples.py
@@ -33,6 +33,7 @@
_ROOT / "docs" / "user-guide" / "accounts.md",
_ROOT / "docs" / "user-guide" / "execution-semantics.md",
_ROOT / "docs" / "user-guide" / "risk-management.md",
+ _ROOT / "docs" / "user-guide" / "migrate-from-zipline.md",
)
_API_AUDIT_PATHS = (
_ROOT / "docs" / "index.md",
@@ -43,6 +44,7 @@
"account-engine-direct",
"account-gatekeeper",
"installation-import",
+ "migration-zipline-target",
"preopen-mixed-rules",
"readme-quickstart",
"risk-volatility-stop",
diff --git a/validation/check_documentation_links.py b/validation/check_documentation_links.py
index e03dc0e3..92c6f49b 100644
--- a/validation/check_documentation_links.py
+++ b/validation/check_documentation_links.py
@@ -1,4 +1,4 @@
-"""Check links in rendered documentation content, including section anchors."""
+"""Check all rendered internal links and external guide destinations."""
from __future__ import annotations
@@ -90,8 +90,7 @@ def check_links(site: Path) -> tuple[int, int]:
external: set[str] = set()
checked = 0
for page, content in pages.items():
- if page.relative_to(site).parts[0] not in _GUIDE_SECTIONS:
- continue
+ section = page.relative_to(site).parts[0]
for link in content.links:
checked += 1
destination = urlsplit(urljoin(_page_url(page, site), link))
@@ -99,10 +98,12 @@ def check_links(site: Path) -> tuple[int, int]:
failures.append(f"{page.relative_to(site)}: unsupported link {link}")
continue
if destination.netloc not in {"www.ml4trading.io", "ml4trading.io"}:
- external.add(destination._replace(fragment="").geturl())
+ if section in _GUIDE_SECTIONS:
+ external.add(destination._replace(fragment="").geturl())
continue
if not destination.path.startswith(_SITE_PREFIX):
- external.add(destination._replace(fragment="").geturl())
+ if section in _GUIDE_SECTIONS:
+ external.add(destination._replace(fragment="").geturl())
continue
try:
target = _target_path(site, destination.path)