Reconcile/README.md

# Reconcile

Forecast reconciliation in native MQL5: a projection that makes a set of
mutually contradictory forecasts consistent, and provably cannot increase
their total squared error while doing it.

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

## What it does

Run one model per timeframe and the answers disagree. The H1 model describes
the next few hours, the H4 model describes the same hours differently, and the
D1 model describes a window containing both. All three describe the same
stretch of price, so at most one of them can be right. The same thing happens
across instruments, where the arithmetic is not a modelling convention: in log
space EURUSD plus USDJPY is EURJPY, whether or not you forecast the cross
directly.

Reconciliation treats that disagreement as measurable error rather than as
something to average away. Write the constraints as a summing matrix `S`, and
the truth is guaranteed to lie in its column space while your forecasts
generally do not. Every component pointing out of that subspace is aimed
somewhere the target can never be, so removing it cannot move you further from
the truth. Under the orthogonal projection that is the Pythagorean theorem, not
a claim about markets.

`CReconciler` implements the projection and knows nothing about markets. It
receives a summing matrix and a weighting, and from then on does arithmetic,
which is what lets one object serve two structures with no code in common
between them: a temporal hierarchy of sixty nodes over twenty-four free hourly
returns, and a currency graph of twenty-one pairs over seven free log prices.
Five weightings are available, from OLS through structural and measured WLS to
MinT on the sample and Schaefer-Strimmer shrunk covariances.

The numerics are the part that decides whether the guarantee survives contact
with real data. `W` is never inverted. It is factorised by Cholesky with a
ridge that escalates until it succeeds, `S` is pushed through the same factor,
and the only explicit inverse in the library is taken on the small `m x m`
normal-equation matrix. Three exact invariants are measured on every inspect
run: a coherent input returns unchanged, reconciling twice equals reconciling
once, and the output satisfies the constraints, the last checked by an
independent projector so it cannot flatter itself.

`Recon_Evidence.mq5` then tests the theorem instead of asserting it, walking
forward one top period at a time with residuals entering the error store only
after they have been scored. Loss differentials go through a Diebold-Mariano
test with a Bartlett kernel and the Harvey-Leybourne-Newbold small-sample
correction, both of which push toward believing the result less. Pooled squared
error falls on both hierarchies under the orthogonal projection. Textbook MinT
on an unregularised sample covariance does not merely underperform at sixty
nodes, it destroys the forecasts it was given, which is a dimensionality
problem rather than a verdict on the estimator: the same scheme costs about one
percent on the twenty-one node currency graph.

The diagnostic that follows sorts origins by how incoherent the base forecasts
were and finds the payoff tracks the contradiction, monotonically. It also
finds the uncomfortable half of the same fact. MinT minimises the trace, the
sum across all nodes, and a sum will buy a large reduction in fifty-nine terms
with an increase in the sixtieth. In a temporal hierarchy the widest node is
the cheapest place to put that error, so if you act on a single forecast you
should check that node specifically.

## Layout

```
Include/Reconcile/ReconcileTypes.mqh         enums and the dense linear algebra kernel
Include/Reconcile/Shrinkage.mqh              rolling error store, sample, diagonal and shrunk covariance
Include/Reconcile/Reconcile.mqh              CReconciler: the projection and the five weightings
Include/Reconcile/Hierarchy.mqh              both summing matrices, connectivity check, time-keyed loader
Include/Reconcile/BaseForecast.mqh           random walk, window mean and fitted AR(1)
Scripts/Reconcile/Recon_Inspect.mq5          summing matrix, per-node adjustment, invariants, triangle violations
Scripts/Reconcile/Recon_Evidence.mq5         walk-forward over five weightings, DM tests, incoherence buckets
Indicators/Reconcile/ReconciledForecast.mq5  base against reconciled for one node, with the incoherence histogram
```

Run `Recon_Inspect.mq5` first. It prints the structure you are about to trust
and the three invariants, and if those are not at machine precision nothing
downstream is worth reading. `Recon_Evidence.mq5` produces the walk-forward
tables. The indicator defaults to the daily node under OLS, which is both the
node where base and reconciled visibly disagree and the node the trace is most
willing to sacrifice.

Substituting your own models is a single edit: `BaseForecast.mqh` is the only
place that turns a price series into a number, and the engine never asks where
the vector it receives came from. Adding a third structure is the same kind of
edit at the other end, since nothing downstream of `S` knows what the
constraints mean.

## Disclaimer

Educational code. Reconciliation is a forecast-accuracy method, and nothing
here demonstrates a trading edge: the directional hit rates it measures are
flat before and after. What it improves is squared error, which is a different
thing from money. Test on your own data and broker conditions before drawing
conclusions.