# Runnable examples

Start with the [first backtest](https://docs.openbacktesting.com/quickstart/index.md), which runs directly from an installed package. The examples here offer longer recipes: `advanced/` files run directly; `strategies/` files declare a strategy and use the example runner to supply data.

## Choose by topic

Use [advanced/optimizer_results.py](https://docs.openbacktesting.com/repository/examples/advanced/optimizer_results.py/index.md) for parameter experiments: retain complete Portfolio results, fix unselected inputs at current values, submit results individually, cancel and resume, reopen offline, and sort by fields.

Choose the topic you need. Bundled GOOG daily and EURUSD hourly data are read locally without downloads. The commands below run from a source checkout.

| Path | Execution category | Recommendation | Topic and prerequisites | Data and extra dependencies |
| --- | --- | --- | --- | --- |
| [advanced/optimizer_results.py](https://docs.openbacktesting.com/repository/examples/advanced/optimizer_results.py/index.md) | Imperative tutorial | Advanced | Select inputs; save complete Portfolios and reopen for sorting | Fixed bundled data; none |
| [strategies/local_value_helpers.py](https://docs.openbacktesting.com/repository/examples/strategies/local_value_helpers.py/index.md) | Author script | Recommended | Tick rounding and per-bar gradients | Fixed host data; none |
| [strategies/local_builtin_indicators.py](https://docs.openbacktesting.com/repository/examples/strategies/local_builtin_indicators.py/index.md) | Author script | Recommended | Conditional VWAP, mode, and five parameter extensions | Fixed host data; none |
| [strategies/closed_trade_statistics.py](https://docs.openbacktesting.com/repository/examples/strategies/closed_trade_statistics.py/index.md) | Author script | Recommended | Partial exits with fees and frozen statistics | Fixed host data; none |
| [strategies/strategy_logs.py](https://docs.openbacktesting.com/repository/examples/strategies/strategy_logs.py/index.md) | Author script | Recommended | Three log levels, nonfatal error logs, explicit exceptions, and end records | Host historical data; none |
| [advanced/strategy_logs.py](https://docs.openbacktesting.com/repository/examples/advanced/strategy_logs.py/index.md) | Imperative tutorial | Advanced | Timestamps, bars, source lines, failure retrieval, reruns, and host sessions | First four GOOG bars; none |
| [strategies/bar_states.py](https://docs.openbacktesting.com/repository/examples/strategies/bar_states.py/index.md) | Author script | Recommended | First-bar callbacks, boundary states, positions, labels, and local validity guards | GOOG; none |
| [strategies/custom_indicators.py](https://docs.openbacktesting.com/repository/examples/strategies/custom_indicators.py/index.md) | Author script | Recommended | Custom functions, two parameter sets, named outputs, and reusable composition | First 120 GOOG bars; none |
| [strategies/plotting.py](https://docs.openbacktesting.com/repository/examples/strategies/plotting.py/index.md) | Author script | Recommended | Color Input, Color/strings, transparency, panes, and per-bar coloring | First 120 GOOG bars; none |
| [advanced/portfolio_report.py](https://docs.openbacktesting.com/repository/examples/advanced/portfolio_report.py/index.md) | Imperative tutorial | Advanced | All report sections, partial-exit identities, MFE/MAE, signals, and frozen JSON | Fixed offline data; none |
| [advanced/plotting_export.py](https://docs.openbacktesting.com/repository/examples/advanced/plotting_export.py/index.md) | Imperative tutorial | Advanced | Color overrides, configuration replay, frozen snapshots, strict JSON, signals, and fills | Trusted author script; none |
| [strategies/trading_lifecycle.py](https://docs.openbacktesting.com/repository/examples/strategies/trading_lifecycle.py/index.md) | Author script | Recommended | Order events, rejection, partial fees, accounts, and end-of-run policies |  |
| [strategies/fractional_sizing.py](https://docs.openbacktesting.com/repository/examples/strategies/fractional_sizing.py/index.md) | Author script | Recommended | Three sizing modes, default overrides, frozen snapshots, named targets, and reduce-only |  |
| [strategies/managed_orders.py](https://docs.openbacktesting.com/repository/examples/strategies/managed_orders.py/index.md) | Author script | Advanced | Expiry, mixed-size OrderRequest OCO, protection, and trailing stops |  |
| [strategies/first_backtest.py](https://docs.openbacktesting.com/repository/examples/strategies/first_backtest.py/index.md) | Author script | Recommended | First backtest: EMA registration, stepwise decisions, and decorator declarations | GOOG; none |
| [advanced/strategy_settings.py](https://docs.openbacktesting.com/repository/examples/advanced/strategy_settings.py/index.md) | Imperative tutorial | Advanced | Five enum categories, flat overrides, JSON versions, and interest recalculation | GOOG and fixed data; none |
| [advanced/chart_context.py](https://docs.openbacktesting.com/repository/examples/advanced/chart_context.py/index.md) | Imperative tutorial | Advanced | Instrument/timeframe injection, chart-local hours, statistical day boundaries, and DST repeated hours | Fixed offline data; none |
| [advanced/run_author.py](https://docs.openbacktesting.com/repository/examples/advanced/run_author.py/index.md) | Imperative tutorial | Advanced | Host loads author scripts and reads results | Example-host data; none |
| [advanced/indicator_reference.py](https://docs.openbacktesting.com/repository/examples/advanced/indicator_reference.py/index.md) | Imperative tutorial | Advanced | Explore by indicator ID and check each channel for validity | GOOG and demonstration extra columns; none |
| [strategies/ema_macd.py](https://docs.openbacktesting.com/repository/examples/strategies/ema_macd.py/index.md) | Author script | Recommended | Preferred template: inputs, EMA, MACD; understand init/next | GOOG; none |
| [strategies/data_sources.py](https://docs.openbacktesting.com/repository/examples/strategies/data_sources.py/index.md) | Author script | Recommended | Eight data sources, saved handles, and derived prices; read the preferred template first | GOOG; none |
| [strategies/cross_signals.py](https://docs.openbacktesting.com/repository/examples/strategies/cross_signals.py/index.md) | Author script | Recommended | Crossover composition and current is_* booleans; understand init/next | GOOG; none |
| [strategies/confirmed_events.py](https://docs.openbacktesting.com/repository/examples/strategies/confirmed_events.py/index.md) | Author script | Advanced | Composition, confirmed events, patterns, and monthly anchors; understand validity/time alignment | GOOG; none |
| [strategies/ema_inputs.py](https://docs.openbacktesting.com/repository/examples/strategies/ema_inputs.py/index.md) | Author script | Recommended | Built-in EMA and inputs; check indicator validity | GOOG; none |
| [strategies/all_inputs.py](https://docs.openbacktesting.com/repository/examples/strategies/all_inputs.py/index.md) | Author script | Recommended | All nine inputs, enum/color runtime values, and time/session boundaries | First 120 GOOG bars; none |
| [advanced/native_run.py](https://docs.openbacktesting.com/repository/examples/advanced/native_run.py/index.md) | Imperative tutorial | Advanced | Native runs, statistics/equity/trade tables; direct Python script | GOOG; none |
| [advanced/composable_strategies.py](https://docs.openbacktesting.com/repository/examples/advanced/composable_strategies.py/index.md) | Imperative tutorial | Advanced | Signal and trailing-stop base classes; understand super call order | GOOG; none |
| [advanced/multiple_time_frames.py](https://docs.openbacktesting.com/repository/examples/advanced/multiple_time_frames.py/index.md) | Imperative tutorial | Advanced | Built-in daily/weekly RSI; understand resampling, completed periods, and calendar assumptions | GOOG; none |
| [advanced/parameter_optimization.py](https://docs.openbacktesting.com/repository/examples/advanced/parameter_optimization.py/index.md) | Imperative tutorial | Advanced | Four grid combinations and parameter scores; understand native parameters | GOOG; SAMBO requires optimize extra |
| [advanced/machine_learning.py](https://docs.openbacktesting.com/repository/examples/advanced/machine_learning.py/index.md) | Imperative tutorial | Research only | Feature columns, one-time/rolling training; requires ML and time-series evaluation knowledge | EURUSD; scikit-learn in test extra |

See [advanced/strategy_settings.py](https://docs.openbacktesting.com/repository/examples/advanced/strategy_settings.py/index.md) for a complete flat-configuration run covering five enum categories, three commission modes, two quantity modes, two slippage modes, JSON overrides, rejection of type changes without values, None clearing, and version 2 envelopes. It retains low-level composite fees and compares inherited interest with explicit zero. `test_flat_backtest_settings.py`, `test_strategy_settings.py`, and `test_examples.py` verify these cases. Quantity budgets do not reserve fees, so actual fills can still fail for insufficient funds.

## Run and verify

In the repository root, install the environment with `uv sync --locked --extra test`, then run the commands below. After unpacking an sdist, start at its package root, run `pip install '.[test]'` in your virtual environment, and replace `uv run --locked python` with `python`. Wheels omit examples; obtain the source or sdist rather than assuming these paths exist after wheel installation.

Run author scripts with this recipe; replace path to select another author script. `runpy` executes trusted local source only and is not a sandbox; runtime does not load source code.

```python
import runpy
from openbacktesting import runtime

path = "examples/strategies/ema_macd.py"
namespace = runpy.run_path(path)
schema = runtime.describe(namespace)  # No backtest has run yet
chart_for = runpy.run_path("examples/advanced/run_author.py")["chart_for"]
chart = chart_for(path)
result = runtime.run(namespace, **chart)
print(schema)
print(result)
```

Execute the recipe in the current Python session. Imperative tutorials calculate only when explicitly run; loading definitions does not backtest, optimize, or train. Run all commands from the package root described above:

```sh
uv run --locked python examples/advanced/strategy_logs.py
uv run --locked python examples/advanced/plotting_export.py
uv run --locked python examples/advanced/run_author.py
uv run --locked python examples/advanced/run_author.py examples/strategies/local_value_helpers.py
uv run --locked python examples/advanced/run_author.py examples/strategies/local_builtin_indicators.py
uv run --locked python examples/advanced/run_author.py examples/strategies/closed_trade_statistics.py
uv run --locked python examples/advanced/run_author.py examples/strategies/all_inputs.py
uv run --locked python examples/advanced/chart_context.py
uv run --locked python examples/advanced/strategy_settings.py
uv run --locked python examples/advanced/indicator_reference.py --indicator ta.macd
uv run --locked python examples/advanced/native_run.py
uv run --locked python examples/advanced/composable_strategies.py
uv run --locked python examples/advanced/multiple_time_frames.py
uv run --locked python examples/advanced/parameter_optimization.py
uv run --locked python examples/advanced/parameter_optimization.py --method sambo
uv run --locked python examples/advanced/machine_learning.py
```

Optimization defaults to four grid combinations; SAMBO uses at most 40 attempts with a fixed seed and requires `python -m pip install '.[optimize]'`. ML runs a random-split classification demonstration and two full backtests, predicts every bar, and retrains every 20 bars. This slow example requires `python -m pip install '.[test]'`. Neither installs dependencies automatically.

## Essential semantics

- `self.open/high/low/close/volume/hl2/hlc3/hlcc4` are stable read-only handles; saved references and slices follow the cursor. `hlcc4=(H+L+2C)/4`. Compose indicators in init; in next, `[-1]` is current and `[-2]` is previous. Prepare data before first accessing a source.
- Each `self.data_index/df` read reflects current visibility; saved pandas objects do not update automatically. `pip` is a price-precision scalar. Array conversions and arithmetic results are not stable handles.
- EMA and daily/weekly RSI use built-in default algorithms. The earlier first-value-seeded EMA and approximate RSI examples were removed; their sequences and backtest results are not current baselines. Weekly data uses Friday right labels and forward filling, without claiming Pine multi-timeframe equivalence.
- Random-split ML accuracy does not establish time-series out-of-sample performance. Label horizons, temporal splits, and gaps require independent evaluation, so the example remains Research only.
- Each docstring explains fees, sizing, and end-of-run liquidation choices. Return output is the calculation for that particular data and configuration.

For maintenance and validation, see the [development guide](https://docs.openbacktesting.com/development/index.md).