Quartz 4

Forecast Lab

4 min read

DD-FORECAST-LAB.md

Versione: 1.0 Data: 2025-10-27 Scopo: Descrivere l’architettura, i componenti e i flussi di dati del sottosistema “Forecast Lab”. Documento Principale: FIRE 25.07 - ARCHITECTURE-OVERVIEW

1. Panoramica e Filosofia

Il “Forecast Lab” è la sinapsi dedicata all’analisi predittiva. Fornisce un ambiente integrato per due attività distinte ma complementari:

  1. Generazione di Previsioni (Live Forecast): Permette all’utente di applicare un modello predittivo (es. TimesFM) ai dati attualmente visualizzati sul grafico per ottenere una previsione immediata del futuro.
  2. Validazione del Modello (Model Backtester): Permette di valutare le performance storiche del modello predittivo su un dato ticker, eseguendo un backtest rigoroso di tipo “rolling-origin” per misurarne l’accuratezza nel tempo.

La filosofia è fornire non solo uno strumento per “guardare avanti”, ma anche un metodo robusto per capire quanto ci si può fidare di quella previsione.

2. Architettura e Componenti Chiave

L’architettura del Lab è modulare, con un contenitore principale che ospita due sottosistemi quasi indipendenti.

  • ForecastLabWidget (Contenitore Principale):
    • Responsabilità: Un semplice QTabWidget che serve da punto di ingresso per l’utente, ospitando le due funzionalità principali in schede separate: “Live Forecast” e “Model Backtester”.

2.1 Sottosistema “Live Forecast”

  • ForecastManagerTab (Componente UI):

    • Responsabilità: Fornire l’interfaccia per avviare una previsione. Si occupa di raccogliere le opzioni di visualizzazione (es. quali intervalli di confidenza mostrare) e di emettere un segnale forecast_requested quando l’utente clicca il pulsante. Non gestisce dati, ma delega l’orchestrazione a MainWindow.

  • TimesFMForecastWorker (Worker Asincrono):

    • Responsabilità: Eseguire il calcolo della previsione in un thread separato. Riceve la serie storica dei prezzi e produce un dizionario contenente la previsione puntuale e gli intervalli di confidenza.

  • LightweightChartWidget (Visualizzazione):

    • Responsabilità: Il grafico principale dell’applicazione. Riceve i risultati dal worker (attraverso MainWindow) e ha la capacità di disegnare la previsione come un overlay sui dati di prezzo esistenti.

2.2 Sottosistema “Model Backtester”

  • ForecastBacktestWidget (Componente UI):

    • Responsabilità: Fornire l’interfaccia per configurare, avviare e monitorare un backtest del modello. Raccoglie parametri specifici (es. dimensione della finestra di training) e legge il contesto (ticker, date) da AppState. Mostra il progresso dell’analisi ma delega la visualizzazione dei risultati.

  • ForecastBacktestWorker (Worker Asincrono):

    • Responsabilità: Eseguire il complesso backtest “rolling-origin” in background. Itera sulla serie storica, ri-addestrando il modello a ogni passo e calcolando l’errore di previsione. Produce un dizionario completo con i risultati.

  • ForecastResultsWidget (Dashboard dei Risultati):

    • Responsabilità: Un cruscotto specializzato e dinamico per visualizzare i risultati del backtest. Viene creato da MainWindow quando i dati sono pronti. Utilizza QCPlotlyChartWidget per mostrare grafici interattivi (previsioni vs. dati reali, andamento dell’errore) e fornisce funzionalità di esportazione.

3. Flussi dei Dati

3.1 Flusso “Live Forecast”

  1. Input (UI): L’utente seleziona le opzioni di visualizzazione nel ForecastManagerTab e clicca “Esegui previsione”.
  2. Trigger (Segnale): ForecastManagerTab emette forecast_requested.
  3. Orchestrazione (MainWindow): Lo slot in MainWindow riceve il segnale, recupera i dati di prezzo attuali dal pannello del grafico, istanzia il TimesFMForecastWorker e lo avvia.
  4. Esecuzione (Background): Il worker calcola la previsione.
  5. Visualizzazione (Overlay): Al termine, il worker emette un segnale finished. MainWindow riceve i risultati e li passa al LightweightChartWidget, che li disegna come overlay sul grafico principale.

3.2 Flusso “Model Backtester”

  1. Input (UI): L’utente imposta i parametri nel ForecastBacktestWidget e clicca “Run Backtest”.
  2. Trigger (Segnale): ForecastBacktestWidget emette backtest_requested con i parametri.
  3. Orchestrazione (MainWindow): Lo slot in MainWindow recupera i dati storici necessari, istanzia il ForecastBacktestWorker e lo avvia.
  4. Monitoraggio (UI): Il ForecastBacktestWidget ascolta i segnali di progresso del worker e aggiorna la sua UI (barra di progresso, log).
  5. Risultati Pronti (Segnale): Al termine, il worker emette finished. ForecastBacktestWidget riceve i risultati e li ri-emette tramite il suo segnale results_ready.
  6. Visualizzazione (Nuovo Pannello): MainWindow riceve il segnale results_ready, istanzia un nuovo ForecastResultsWidget, gli passa i dati e lo mostra all’utente come un nuovo pannello (dock).

Graph View