PDV/README.md

# PDV

Path-dependent volatility in native MQL5: the Guyon-Lekeufack model written as
four exponential accumulators, so the whole thing costs four multiplies and
four adds per bar and stores no history at all.

Companion code for the MQL5 article: https://www.mql5.com/en/articles/24607

## What it does

Square a return and you throw away its sign. Every GARCH-family model does this
in its first step, which is why a market that has fallen five percent and a
market that has risen five percent look identical to it. The econometric
patches, GJR and TARCH and EGARCH, add back one bit of that discarded
information: the sign of yesterday's return, times a single fixed multiplier.

Guyon and Lekeufack keep the whole path instead. Volatility becomes

```
sigma = b0 + b1 * R1 + b2 * sqrt(R2)
```

where `R1` is a kernel-weighted sum of past signed returns and `R2` the same
construction on squared returns. `R1` carries where the path has been going,
`R2` how hard it has been moving, and the claim is that those two numbers are
most of what there is to know about today's volatility.

The reason this belongs in an indicator rather than a research report is the
kernel. Both kernels are convex mixtures of two exponentials, and an
exponential kernel has a recursive update, so a sum over unbounded history
collapses to one running scalar. Two exponentials per feature and two features
make four scalars. `CPdvState` is that arithmetic and nothing else: no lookback
array, no matrix, nothing that grows with the length of the history, and no
knowledge of bars, so the same object serves a calibration sweep over ten years
and an indicator updating on every tick.

Calibration splits nine parameters by how they are found rather than solving
all nine the same way. Hold the kernels fixed and the model is a plain linear
regression of realised volatility on two features, so the three betas come out
of a closed form with no search. Only the six kernel parameters need an
optimiser, and they get a Nelder-Mead simplex with the regression nested inside
its objective. Six dimensions searched over three solved exactly is what makes
this calibrate in seconds rather than minutes.

Two choices in `CPdvModel` are about honesty rather than accuracy. The features
at bar `i` use returns up to and including bar `i` while the target is measured
from bar `i+1` onward, and the train/test cut is chronological, because a
shuffled split on data this autocorrelated will manufacture an R-squared out of
nothing. The evaluation window is also fixed before the search starts rather
than derived per candidate: a long-memoried kernel needs more warm-up than a
short one, so letting the window follow the candidate would score different
models on different samples and quietly reward whichever got the easiest bars.

`PDV_Evidence.mq5` is where the method has to justify itself. It scores the
model out of sample against a constant, an EWMA volatility and GARCH(1,1),
every baseline given the same intercept and slope the model gets, and then runs
the ablation that matters: the identical machinery with `b1` pinned at zero.
Same data, same target, same split, same two-exponential kernel on squared
returns, and the only difference is whether the sign of the path is allowed to
count. Whatever R-squared the trend term adds over that is the entire
measurable value of path dependence.

On H1 equity indices it is worth a lot. The trend term adds +0.171 out-of-sample
R-squared on SPX500 and +0.15 and +0.11 on US30 and NDX100. On FX it adds
roughly nothing, and that null is the useful part of the result rather than a
failure: the leverage effect is an equity phenomenon, a currency pair has no
issuer whose equity can be geared, and a `b1` near zero there is the model
reporting the truth. Gold's `b1` comes out positive, which is a different
market telling a different story about its own path.

Two things are worth knowing before reading any of those numbers.

A realised-volatility target caps the attainable R-squared by its own sampling
noise, because the target is an estimate and not the thing itself. On synthetic
data with a known generating process the fit scored 0.1156 against a
close-to-close target while a forecaster that *knew* the true volatility scored
0.1114. The fit was not weak; the target was noisy. Against the true generating
sigma the same fit correlated 0.976. Compute that ceiling before calling an
R-squared disappointing.

The model is linear in `R1` and `b1` is negative wherever leverage exists, so a
long enough rally can drive fitted volatility through zero. That is a property
of the specification, which the paper is explicit about, not a bug in the port.
Both values are exposed: `Sigma()` is floored at a share of the activity term
and is what a stop distance should be built on, while `SigmaRaw()` is what tells
you the model has been pushed outside the range it was fitted in.
`PDV_Calibrate.mq5` reports the count of negative raw bars for exactly this
reason. A handful is the model working as specified; thousands means the fit is
not usable.

The decomposition, not the R-squared, is the deliverable. Splitting volatility
into a direction component and an activity component answers a question a
single conditional-variance number cannot express, and it costs nothing extra
to compute: a market falling steadily and a market thrashing sideways at the
same volatility become distinguishable, before the fact, from the state alone.

## Layout

```
Include/PDV/PdvTypes.mqh            structs, buffer map, half-life and decay conversions
Include/PDV/PdvState.mqh            CPdvState: the four accumulators, O(1) per bar
Include/PDV/PdvModel.mqh            CPdvModel: forward target, closed-form betas, Nelder-Mead, ablation
Include/PDV/PdvForecast.mqh         CPdvForecast: decomposition, floor, trend share, multi-step projection
Indicators/PDV/PDV_Decomposition.mq5  total volatility against its trend and activity components
Scripts/PDV/PDV_Calibrate.mq5       fits one symbol, reports parameters, split scores, decomposition summary
Scripts/PDV/PDV_Evidence.mq5        out-of-sample comparison against constant, EWMA and GARCH(1,1)
```

Run `PDV_Calibrate.mq5` first on the symbol you care about. Its last line
prints the nine fitted parameters in input order, which paste straight into
`PDV_Decomposition.mq5`; the defaults shipped in the indicator are the SPX500
H1 fit. Then run `PDV_Evidence.mq5` for the comparison table and the ablation.
Pick the instrument deliberately, because it is load-bearing: an FX-only run
will show a gain near zero and no story at all. Broker symbol names vary, and
the indices are not always called what you expect.

Do not reconcile a figure from one script against another. Each rebuilds its
own scored window, so a different warm-up starts the scored range at a
different bar and the numbers legitimately differ: SPX500 comes out at 0.4480
under `PDV_Calibrate` at a 750-bar warm-up and 0.4464 inside the `PDV_Evidence`
loop, and both are correct.

Substituting your own target is a single edit. `BuildTarget()` in
`PdvModel.mqh` is the only place that decides what the model is being asked to
predict, and nothing downstream knows where the target came from. The two
supplied forms are close-to-close and Parkinson, which are on the same scale
and interchangeable; Parkinson reads the whole bar range and is several times
more efficient, at the cost of ignoring gaps.

## Disclaimer

Educational code. This is a volatility measurement and forecasting library, not
a trading system: there is no Expert Advisor here and nothing in this repository
demonstrates a trading edge. A better volatility forecast is an input to
position sizing and stop placement, which is a different thing from money.
The out-of-sample gains reported above are R-squared against a realised
volatility target on H1 bars from one broker's history, and they are strongly
instrument-dependent, close to zero on FX by construction. Test on your own
data and broker conditions before drawing conclusions.