debug_timesfm_quantiles

debug_timesfm_quantiles.md (Versione Aggiornata)

1. A Cosa Serve Questo Script?

Lo script debug_timesfm_quantiles.py è uno strumento di diagnostica avanzata il cui scopo è “reverse-engineering” l’output del modello TimesFM. Ci permette di rispondere a domande critiche sulla struttura e la validità dei dati di previsione prima di implementarli in FIRE.

Questo script serve a:

1. Eseguire una previsione controllata con TimesFM.
2. Analizzare la struttura (shape) degli array restituiti per capire come sono organizzati i dati.
3. Estrarre la previsione corretta, isolando i dati rilevanti dall’output complesso del modello.
4. Ispezionare i valori numerici dei quantili (gli intervalli di confidenza) per un singolo punto nel futuro.
5. Validare la coerenza statistica dei quantili, verificando che siano in ordine crescente (un quantile più basso non può avere un valore più alto di uno superiore).
6. Identificare la Mediana (P50), confrontando la previsione puntuale con i valori dei quantili.
7. Analizzare le possibili distribuzioni dei quantili e fornire una mappatura raccomandata da usare nel codice di produzione.
8. Esportare tutti i dati grezzi in un file CSV (timesfm_quantiles_debug.csv) per un’analisi manuale approfondita.

In sintesi, è il nostro strumento principale per passare da un’ipotesi su come TimesFM funziona alla certezza oggettiva, basata sui dati che il modello stesso produce.

2. Come si Lancia lo Script?

Lanciare lo script è molto semplice.

Prerequisiti:

• Avere un terminale (come PowerShell o CMD) aperto.
• Avere l’ambiente virtuale del progetto attivo.

Comando da Eseguire:

1. Assicurati di essere nella directory principale del progetto (es. D:\01_DevOps\fire\fireDev).

2. Digita il seguente comando e premi Invio:

   python debug_timesfm_quantiles.py

3. Come Interpretare l’Output?

Lo script produrrà diverse sezioni nel terminale. Ecco come leggerle:

• ANALISI SHAPE: Ti dice come sono organizzati gli array. È il primo passo per capire come estrarre i dati.
• ESTRAZIONE FORECAST: Mostra che lo script ha isolato con successo la previsione finale dal resto dei dati.
• ISPEZIONE DETTAGLIATA: Mostra i valori numerici dei 10 quantili per il primo giorno di previsione.
• VALIDAZIONE ORDINE MONOTONO: Sezione critica. Se qui appare ”✗ NO”, significa che l’output del modello è statisticamente incoerente, un problema grave.
• IDENTIFICAZIONE MEDIANA: Ci aiuta a capire quale indice corrisponde al 50° percentile (P50), un punto di riferimento fondamentale.
• ANALISI DISTRIBUZIONE QUANTILI: Confronta i dati reali con diverse ipotesi teoriche e ci dice quale è la più probabile.
• MAPPATURA RACCOMANDATA: La sezione più importante. Fornisce il blocco di codice esatto da implementare nel nostro worker per mappare correttamente gli intervalli, basandosi sull’analisi appena fatta.
• EXPORT DATI: Conferma che il file CSV è stato creato per ulteriori analisi.

Questo script è la nostra “fonte di verità” per l’integrazione di TimesFM e deve essere il primo strumento da utilizzare in caso di futuri dubbi o anomalie.