|
| 1 | +# Multi-Timeframe (MTF) {#mtf} |
| 2 | + |
| 3 | +@tableofcontents |
| 4 | + |
| 5 | +PineForge exposes two distinct multi-timeframe surfaces. They look |
| 6 | +similar from Pine but resolve through completely different runtime |
| 7 | +paths, and they have different rules: |
| 8 | + |
| 9 | +| Surface | Pine call | Direction | Bars source | |
| 10 | +| --- | --- | --- | --- | |
| 11 | +| **Upward (HTF)** | `request.security(sym, "60", expr)` | target TF **coarser** than input | aggregated from input bars | |
| 12 | +| **Downward (LTF)** | `request.security_lower_tf(sym, "1", expr)` | target TF **finer** than input | **synthesized** from each input bar's OHLC path | |
| 13 | + |
| 14 | +The downward path is where PineForge diverges from TradingView. TV |
| 15 | +downloads a separate finer-resolution feed when you switch to a lower |
| 16 | +timeframe; PF does **not**. The input feed's resolution is the upper |
| 17 | +bound on what `request.security_lower_tf` can target — beyond that, no |
| 18 | +data exists. Sub-bars are synthesized on demand by walking the input |
| 19 | +bar's OHLC path. See @ref magnifier for the same idea applied to fill |
| 20 | +resolution. |
| 21 | + |
| 22 | +For the upward path and the chart-aggregation rules, see also |
| 23 | +@ref timeframes. |
| 24 | + |
| 25 | +## The script_tf / input_tf model |
| 26 | + |
| 27 | +Every backtest run takes two timeframe strings on |
| 28 | +`run_backtest_full(...)`: |
| 29 | + |
| 30 | +```c |
| 31 | +run_backtest_full(s, bars, n, |
| 32 | + /* input_tf */ "", // empty → auto-detect from bar timestamps |
| 33 | + /* script_tf */ "", // empty → defaults to input_tf |
| 34 | + /* magnifier */ 0, 4, PF_MAGNIFIER_ENDPOINTS, |
| 35 | + &report); |
| 36 | +``` |
| 37 | +
|
| 38 | +The runtime resolves them in order: |
| 39 | +
|
| 40 | +1. `input_tf` — what the bar feed actually is. If empty, the runtime |
| 41 | + computes the median delta between consecutive `pf_bar_t::timestamp` |
| 42 | + values and snaps to a canonical Pine TF. |
| 43 | +2. `script_tf` — what the strategy script believes it's running on. |
| 44 | + If empty, defaults to the resolved `input_tf`. |
| 45 | +3. If `script_tf > input_tf`, the runtime aggregates input bars up to |
| 46 | + script-TF parents before each `on_bar` dispatch. The two timeframes |
| 47 | + are concatenated by an aggregator (ratio or calendar — see |
| 48 | + `src/engine_security.cpp`). |
| 49 | +
|
| 50 | +The report exposes the resolved values and the ratio: |
| 51 | +
|
| 52 | +| Report field | Meaning | |
| 53 | +| --- | --- | |
| 54 | +| `input_tf_seconds` | Resolved input TF (after auto-detect). | |
| 55 | +| `script_tf_seconds` | Resolved script TF (after defaulting). | |
| 56 | +| `script_tf_ratio` | `script_tf_seconds / input_tf_seconds`. | |
| 57 | +| `needs_aggregation` | `1` when ratio > 1, `0` otherwise. | |
| 58 | +
|
| 59 | +## Switching timeframes — C |
| 60 | +
|
| 61 | +```c |
| 62 | +pf_report_t r = {0}; |
| 63 | +
|
| 64 | +// 1. Both empty → auto-detect input, default script to input. |
| 65 | +run_backtest_full(s, bars, n, "", "", 0, 4, PF_MAGNIFIER_ENDPOINTS, &r); |
| 66 | +// r.input_tf_seconds == 900 (15m, auto-detected) |
| 67 | +// r.script_tf_seconds == 900 (defaulted) |
| 68 | +// r.script_tf_ratio == 1 |
| 69 | +// r.needs_aggregation == 0 |
| 70 | +
|
| 71 | +// 2. Explicit input + explicit higher script → 4:1 aggregation. |
| 72 | +run_backtest_full(s, bars, n, "15", "60", 0, 4, PF_MAGNIFIER_ENDPOINTS, &r); |
| 73 | +// r.input_tf_seconds == 900 |
| 74 | +// r.script_tf_seconds == 3600 |
| 75 | +// r.script_tf_ratio == 4 |
| 76 | +// r.needs_aggregation == 1 |
| 77 | +
|
| 78 | +// 3. Explicit input, script defaults to input. |
| 79 | +run_backtest_full(s, bars, n, "15", "", 0, 4, PF_MAGNIFIER_ENDPOINTS, &r); |
| 80 | +// r.input_tf_seconds == 900 |
| 81 | +// r.script_tf_seconds == 900 (defaulted, NOT inferred separately) |
| 82 | +``` |
| 83 | + |
| 84 | +## Switching timeframes — Python (ctypes) |
| 85 | + |
| 86 | +```python |
| 87 | +# Same three calls, byte-string TFs. |
| 88 | +lib.run_backtest_full(s, bars, n, b"", b"", 0, 4, 3, byref(r)) |
| 89 | +lib.run_backtest_full(s, bars, n, b"15", b"60", 0, 4, 3, byref(r)) |
| 90 | +lib.run_backtest_full(s, bars, n, b"15", b"", 0, 4, 3, byref(r)) |
| 91 | +``` |
| 92 | + |
| 93 | +The full runnable harness — three tables walking the script_tf sweep, |
| 94 | +the input_tf/script_tf pair matrix, and the lower-TF synthesis ratio |
| 95 | +— is in `tutorial/run_mtf.py`. See the **Worked example** section |
| 96 | +below. |
| 97 | + |
| 98 | +## request.security_lower_tf — the codegen contract |
| 99 | + |
| 100 | +The lower-TF builtin returns an array of one value per synthesized |
| 101 | +sub-bar. The codegen pattern in `generated.cpp` is: |
| 102 | + |
| 103 | +```cpp |
| 104 | +class GeneratedStrategy : public BacktestEngine { |
| 105 | +public: |
| 106 | + // Accumulator vector for the sub-bar values. |
| 107 | + std::vector<double> _req_sec_lower_tf_0{}; |
| 108 | + |
| 109 | + void configure_security_evaluators() override { |
| 110 | + security_eval_states_.clear(); |
| 111 | + // sec_id 0, target "1" minute, input_tf passed through from the |
| 112 | + // run-time resolved value. |
| 113 | + register_security_lower_tf_eval(0, std::string("1"), input_tf_); |
| 114 | + } |
| 115 | + |
| 116 | + void evaluate_security(int sec_id, const Bar& bar, bool is_complete) override { |
| 117 | + if (sec_id != 0 || !is_complete) return; |
| 118 | + // Sub-bar 0 marks the start of a new chart bar — clear before pushing. |
| 119 | + if (security_lower_tf_sub_bar_index(0) == 0) { |
| 120 | + _req_sec_lower_tf_0.clear(); |
| 121 | + } |
| 122 | + _req_sec_lower_tf_0.push_back(bar.close); |
| 123 | + } |
| 124 | + |
| 125 | + void on_bar(const Bar& bar) override { |
| 126 | + // _req_sec_lower_tf_0 is the Pine array returned by |
| 127 | + // request.security_lower_tf(sym, "1", close). |
| 128 | + // ... compute on it ... |
| 129 | + } |
| 130 | +}; |
| 131 | +``` |
| 132 | +
|
| 133 | +### Validation rules |
| 134 | +
|
| 135 | +When `configure_security_evaluators` runs, the engine validates each |
| 136 | +registered lower-TF site against `input_tf_`: |
| 137 | +
|
| 138 | +- The target TF must be **strictly finer** than the resolved input TF. |
| 139 | +- The input TF (in seconds) must be an **integer multiple** of the |
| 140 | + target TF — non-clean ratios are rejected. |
| 141 | +- `lookahead` and `gaps` must be off (TV does not expose them on this |
| 142 | + builtin and PF refuses to fake them). |
| 143 | +
|
| 144 | +Violations raise at run-time with a precise diagnostic, e.g.: |
| 145 | +
|
| 146 | +``` |
| 147 | +request.security_lower_tf requires a timeframe finer than the |
| 148 | +chart's input timeframe: requested 30 from input timeframe 15 |
| 149 | +``` |
| 150 | +
|
| 151 | +### Sub-bar synthesis |
| 152 | +
|
| 153 | +For each input bar, the engine generates `input_tf / target_tf` |
| 154 | +synthetic sub-bars by walking the input bar's OHLC endpoints (the |
| 155 | +same path-sampling primitive the bar magnifier uses, see |
| 156 | +`src/engine_lower_tf.cpp`). Each synthetic sub-bar gets `1/ratio` of |
| 157 | +the input bar's volume. |
| 158 | +
|
| 159 | +Per-run sub-bar counts surface in the report's `security_feeds_total` |
| 160 | +field. With a 15m chart and a `"1"` lower-TF target, expect: |
| 161 | +
|
| 162 | +``` |
| 163 | +security_feeds_total == 15 * input_bars_processed |
| 164 | +``` |
| 165 | +
|
| 166 | +## Worked example |
| 167 | +
|
| 168 | +`tutorial/mtf/` ships two strategies side-by-side: |
| 169 | +
|
| 170 | +| File | Demonstrates | |
| 171 | +| --- | --- | |
| 172 | +| `tutorial/mtf/strategy_htf.pine` + `generated_htf.cpp` | `request.security` (HTF SMA filter on a 15m chart). HTF is an input — sweepable without rebuild. | |
| 173 | +| `tutorial/mtf/strategy_ltf.pine` + `generated_ltf.cpp` | `request.security_lower_tf("1", close)` — intra-bar 1m range as an entry signal. | |
| 174 | +| `tutorial/run_mtf.py` | Three tables: script_tf sweep, input_tf/script_tf pair matrix, lower-TF synthesis ratio. | |
| 175 | +
|
| 176 | +Build: |
| 177 | +
|
| 178 | +```bash |
| 179 | +cmake --build build --target strategy_tutorial_mtf_htf strategy_tutorial_mtf_ltf -j |
| 180 | +python3 tutorial/run_mtf.py |
| 181 | +``` |
| 182 | + |
| 183 | +Expected (excerpt): |
| 184 | + |
| 185 | +``` |
| 186 | +Table A — script_tf sweep, fixed input (HTF .so) |
| 187 | + script_tf in_s sc_s ratio agg? in_bars sc_bars trades net_pnl |
| 188 | + "" 900 900 1 0 672 672 1 -653.46 |
| 189 | + "15" 900 900 1 0 672 672 1 -653.46 |
| 190 | + "60" 900 3600 4 1 672 168 6 -962.57 |
| 191 | + "240" 900 14400 16 1 672 42 0 +0.00 |
| 192 | +``` |
| 193 | + |
| 194 | +Numbers depend on the OHLCV snapshot. |
| 195 | + |
| 196 | +## See also |
| 197 | + |
| 198 | +- @ref timeframes — TF strings, auto-detection, calendar vs ratio aggregation. |
| 199 | +- @ref magnifier — sub-bar synthesis for fill resolution (same primitive). |
| 200 | +- @ref tutorial_macd — single-cadence baseline this tutorial extends. |
0 commit comments