Quartz 4

Market Explorer

3 min read

DD-MARKET-EXPLORER.md

Versione: 1.0 Data: 2025-10-10 Scopo: Descrivere in dettaglio l’architettura, i pattern e il flusso di dati del sottosistema Market Explorer. Documento Principale: FIRE 25.07 - ARCHITECTURE-OVERVIEW

1. Panoramica e Responsabilità

Il “Market Explorer” è il laboratorio di analisi statistica di FIRE. Il suo scopo è permettere agli utenti di scoprire “edge”, pattern e la “personalità” di un asset finanziario prima di dedicare tempo alla scrittura di una strategia di trading completa.

Fornisce una suite di strumenti di visualizzazione (heatmap, box plot, etc.) per analizzare i dati di mercato da diverse prospettive, rispondendo a domande come: “Quali sono le ore più volatili?” o “Esistono tendenze stagionali?“.

2. Architettura e Componenti Chiave

Come per tutti i sottosistemi di FIRE che eseguono calcoli, l’architettura è basata sulla separazione tra UI e logica di business tramite worker asincroni.

  • ExplorerTabWidget (Componente UI):

    • Responsabilità: Fornire l’interfaccia utente per selezionare un ticker, un intervallo di date e il tipo di analisi desiderata. Si occupa anche di visualizzare il risultato finale, gestendo quale grafico mostrare tramite un QStackedWidget.

  • ExplorerWorker (Worker Asincrono - QRunnable):

    • Responsabilità: Eseguire l’analisi statistica in un thread separato. Riceve i parametri dalla UI, orchestra il recupero dei dati e l’esecuzione dell’analisi, e comunica il risultato tramite segnali Qt.

  • DataManager (Servizio Core):

    • Responsabilità: Fornire i dati storici al worker, garantendo di recuperare la granularità corretta (dati giornalieri o orari) a seconda dell’analisi richiesta.
    • Approfondimento: DD-DATA-MANAGEMENT.md

  • AnalysisEngine (Motore di Analisi):

    • Responsabilità: Contenere la logica di calcolo effettiva. È implementato come una classe di utility con metodi statici (o di classe), ognuno dedicato a un tipo specifico di analisi (es. calculate_hourly_heatmap). Utilizza pesantemente la libreria pandas per la manipolazione dei dati.

  • Widget di Charting Specifici (HeatmapWidget, BoxplotWidget, etc.):

    • Responsabilità: Ogni widget è specializzato nel visualizzare un tipo specifico di dato prodotto dall’ AnalysisEngine.

3. Flusso dei Dati

Il flusso segue il pattern standard di FIRE per le operazioni asincrone.

  1. Input (UI): L’utente seleziona i parametri nell’ExplorerTabWidget e avvia l’analisi.
  2. Orchestrazione (Thread Principale): MainWindow istanzia l’ExplorerWorker con i parametri specificati e lo avvia in un thread separato.
  3. Esecuzione (Thread in Background): L’ExplorerWorker esegue i seguenti passaggi: a. Richiede i dati storici al DataManager. b. Invoca il metodo di analisi appropriato nell’AnalysisEngine, passandogli i dati. c. Riceve il risultato (es. la matrice di dati per la heatmap) e lo impacchetta in un dizionario.
  4. Comunicazione (Segnale): L’worker emette un segnale finished con il dizionario contenente i risultati.
  5. Visualizzazione (UI): a. L’ExplorerTabWidget riceve i risultati. b. Seleziona il widget di charting corretto all’interno del suo QStackedWidget. c. Passa i dati al widget di charting specifico, che si occupa di renderizzare la visualizzazione grafica.

4. Guide Pratiche

4.1. Come Aggiungere una Nuova Analisi al Market Explorer

  1. Implementa la Logica (AnalysisEngine):

    • Apri fire/synapses/explorer/analysis_engine.py.
    • Aggiungi un nuovo metodo statico che accetti un DataFrame pandas come input e restituisca i dati elaborati nel formato richiesto dalla tua visualizzazione.

  2. Integra nel Worker (ExplorerWorker):

    • Modifica l’worker per riconoscere il nuovo tipo di analisi. Aggiungi una condizione if/elif che chiami il nuovo metodo che hai creato nell’AnalysisEngine.

  3. Crea il Widget di Visualizzazione:

    • Sviluppa un nuovo widget Qt (es. NuovaAnalisiWidget) in grado di ricevere i dati prodotti dal tuo nuovo metodo e di visualizzarli graficamente (usando Matplotlib, PyQtGraph, etc.).

  4. Integra nella UI (ExplorerTabWidget):

    • Aggiungi una nuova opzione nella UI per permettere all’utente di selezionare la tua nuova analisi.
    • Aggiungi il tuo NuovaAnalisiWidget al QStackedWidget.
    • Aggiorna lo slot che riceve il segnale finished dal worker per attivare e passare i dati al tuo nuovo widget quando l’analisi corrispondente viene completata.

Graph View