# Fase 3 — Modello di MEAN-REVERSION (rientro alla Mediana)

> Questo è il **modello principale** della Fase 3. Nasce dopo aver dimostrato
> (vedi `README.md` sez. 5b, validazione esterna) che l'edge **direzionale**
> "su/giù" **non generalizza** fuori da EURUSD, mentre la **mean-reversion** è
> universale (rientro alla Mediana entro 20g nell'87–90% dei casi su tutti i
> major FX). Quindi modelliamo ciò che è davvero robusto: il **rientro alla
> Mediana**.

---

## 1. Idea

Dopo un incrocio il prezzo tende a tornare sulla Mediana. Non vogliamo prevedere
la direzione, ma **caratterizzare il rientro**. Tre target, costruiti da esiti
già presenti nei CSV (nessuna baseline di regime: sono osservazioni dirette):

| target | tipo | colonna | domanda |
|---|---|---|---|
| `rev`   | classificazione | `rev_10` | rientra alla Mediana **entro 10 giorni**? (sì/no) |
| `speed` | regressione | `bars_to_revert` | in **quanti giorni** rientra (solo eventi rientrati) |
| `disc`  | regressione | `disc_max_pct` | **quanto si allontana** (max %) prima di rientrare |

Esclusione del banale (`drop_trivial`): gli eventi già praticamente sulla
Mediana (`|dist_med_pct| < 0.05%`) rientrano per costruzione; vengono esclusi per
studiare il rientro "vero".

## 2. Feature (note al momento dell'incrocio)

`abs_dist` (=|dist_med_pct|), `dist_med_pct`, `cluster_pct`, `cluster_exp`,
`slope_a`, `slope_b`, `vel_med`, `acc_med`, `vol_med` (numeriche) +
`pair`, `dir`, `trend`, `dow`, `month` (categoriche). Nessuna colonna di esito
futuro è tra le feature.

## 3. Pooling pulito + validazione (anti-inquinamento)

I 4 major FX (EURUSD, USDJPY, USDCHF, GBPUSD) hanno mean-reversion omogenea →
si possono **mettere in pool**. Le feature sono già in percentuale/relative,
quindi confrontabili tra simboli. Due validazioni, entrambe oneste:

1. **Walk-forward pooled**: train tutti i simboli fino all'anno T, test anno T+1
   → generalizzazione **nel tempo**.
2. **Leave-one-symbol-out (LOSO)**: train su 3 simboli, test sul 4° **mai visto**
   → generalizzazione **tra strumenti** (la prova più severa anti-inquinamento).

Ogni metrica è confrontata con una **baseline banale**:
- classificazione → accuratezza della classe maggioritaria;
- regressione → MAE ottenuto prevedendo sempre la mediana del train
  (`skill_% = 1 − MAE/MAE_baseline`).

## 4. Risultati (pool 4 major FX, ~39k incroci)

**Walk-forward (nel tempo):**
- `rev`   : **AUC ≈ 0.65** (la baseline è 0.5) → il modello sa **ordinare** quali
  incroci rientreranno entro 10g e quali no.
- `speed` : skill ≈ **+2%** → marginale (la mediana è ~3g e cambia poco).
- `disc`  : skill ≈ **−3%** → non meglio della mediana.

**Leave-one-symbol-out (su simbolo mai visto):**

| target | EURUSD | USDJPY | USDCHF | GBPUSD |
|---|---|---|---|---|
| `rev` AUC | 0.677 | 0.687 | 0.682 | 0.688 |
| `speed` skill | +1.3% | +4.8% | −2.9% | +2.8% |
| `disc` skill | +2.0% | +5.8% | −1.1% | −0.1% |

**Lettura:** il classificatore di rientro (`rev`) ha un edge **reale e
generalizzabile** — AUC ~0.68 anche su un simbolo completamente fuori dal
training. I due regressori (`speed`, `disc`) aggiungono poco: la velocità e
l'ampiezza dell'allontanamento sono in pratica vicine alla mediana storica.

## 5. Cosa guida il rientro (importanza, permutation su holdout 2018+)

```
abs_dist       +0.104   <- distanza dalla Mediana: di gran lunga il fattore #1
dist_med_pct   +0.025   <- il segno della distanza (sopra/sotto)
trend          +0.021
cluster_exp    +0.017   <- cluster in espansione/contrazione
vel_med        +0.010
... (vol_med, cluster_pct ~0)
pair           ~0       <- QUALI linee si incrociano e' irrilevante
```

Conferma economica: il rientro dipende da **quanto sei lontano dalla Mediana** e
dal **regime**, non dallo specifico tipo di incrocio. È coerente con la Fase 2 e
con la validazione esterna (il "pattern" di linee era rumore).

## 6. Uso operativo

Il modello `rev` non dice "compra/vendi": stima la **probabilità di rientro
rapido**. Serve da **filtro**: tra i setup di mean-reversion (prezzo lontano
dalla Mediana), privilegiare quelli con alta probabilità ed evitare il ~25% che
tende a NON rientrare in fretta (i casi rischiosi, spesso inizio di trend).

## 7. File e come eseguire

```
Modello/
├── config_mr.yaml              parametri del modello di mean-reversion
├── src/
│   ├── mr_labeling.py          costruzione dei 3 target + maschere
│   └── mr_train.py             pool + walk-forward + LOSO + modelli finali
└── results/
    ├── mr_wf_<task>.csv         metriche walk-forward per anno
    ├── mr_loso_<task>.csv       metriche leave-one-symbol-out
    ├── mr_summary.json          riepilogo medio
    └── mr_model_<task>.joblib   modelli finali (non versionati)
```

```bash
pip install -r requirements.txt
# copia in ./data i CSV crosses+bars dei 4 simboli (vedi data/README.md), poi:
cd src
python mr_train.py            # usa ../config_mr.yaml
```

## 8. Prossimi passi

- **Calibrazione** delle probabilità di `rev` e scelta soglia operativa
  (precisione vs copertura) per l'EA.
- Aggiungere altri major FX al pool per irrobustire ancora il LOSO.
- **Fase 4**: export del modello `rev` in **ONNX** (skl2onnx) e inferenza in MT5
  come filtro dei segnali di mean-reversion.