Quartz 4

Charting - Guida agli Overlay

2 min read

FIRE DD-CHARTING-OVERLAYS.md

Versione: 1.0
Data: 2025-10-29
Scopo: Fornire una guida pratica per gli sviluppatori su come disegnare overlay personalizzati (linee, aree, indicatori) sul grafico principale.
Documento Principale: FIRE DD-CHARTING.md

1. Filosofia: Disaccoppiamento e Riutilizzabilità

Il nostro sistema di charting è progettato per essere estensibile. La logica di “cosa” disegnare (es. calcolare una media mobile, generare un forecast) è completamente separata da “come” disegnarlo.

Qualsiasi dato che può essere rappresentato come una colonna in un DataFrame indicizzato per data può essere visualizzato sul grafico. Il lavoro dello sviluppatore consiste nel modificare il LWCOverlayManager per insegnargli a riconoscere e a plottare queste nuove colonne.

2. L’Architettura del Disegno di Overlay

Il processo segue sempre tre passi:

  1. Arricchimento Dati: Un worker (es. TimesFMEnrichmentWorker o la strategia stessa) aggiunge una o più colonne al DataFrame principale.

  2. Logica di Business (LWCOverlayManager): Questo è il “cervello”. Contiene un metodo per ogni tipo di overlay (es. draw_backtest_forecast_area). Questo metodo controlla se le colonne necessarie esistono e chiama l’API di basso livello per disegnarle.

  3. API di Disegno (LWCJsApi): Questo è il “braccio”. Contiene i metodi di basso livello che generano il codice JavaScript per interagire con la libreria Lightweight Charts (es. add_line_series).

3. Catalogo degli Effetti Visivi Disponibili

Questa sezione funge da “ricettario” per gli effetti visivi.

3.1. Disegnare una Linea Semplice

  • Scopo: Visualizzare un indicatore come una media mobile, il valore di un oscillatore, o il valore di un forecast.

  • API da Usare: LWCJsApi.add_line_series(series_id, data, options)

  • Guida Pratica (LWCOverlayManager):

    1. Controlla se la colonna nome_indicatore esiste nel DataFrame.

    2. Prepara i dati usando LWCJsApi.dataframe_to_js_format(dfnome_indicatore, nome_indicatore).

    3. Definisci le options (colore, spessore, stile della linea).

      • lineStyle: 0 = Solido

      • lineStyle: 1 = Punteggiato

      • lineStyle: 2 = Tratteggiato

      • lineStyle: 3 = Punti-trattini

    4. Chiama self.js_api.add_line_series(…).

3.2. Disegnare Bande di Incertezza (es. Bande di Bollinger, Canali di Keltner, Forecast)

  • Scopo: Visualizzare un intervallo tra due valori.

  • Implementazione: Si disegnano due linee separate.

  • Guida Pratica (LWCOverlayManager):

    1. Controlla l’esistenza delle colonne banda_superiore e banda_inferiore.

    2. Prepara i dati per entrambe le colonne come nel caso della linea semplice.

    3. Definisci le options per le linee (solitamente stesso colore e stile, es. tratteggiato).

    4. Chiama self.js_api.add_line_series(…) due volte, una per ogni banda, con series_id diversi (es. nome_indicatore_upper, nome_indicatore_lower).

3.3. Disegnare Marcatori sul Grafico (es. Segnali di Buy/Sell)

  • Scopo: Evidenziare punti specifici nel tempo con un simbolo.

  • API da Usare: LWCJsApi.set_markers(markers_list)

  • Guida Pratica (LWCOverlayManager):

    1. Il metodo _create_markers_from_signals è l’implementazione di riferimento.

    2. Crea una lista di dizionari Python, dove ogni dizionario rappresenta un marker e ha le chiavi: time, position (‘aboveBar’ o ‘belowBar’), color, shape (‘arrowUp’, ‘arrowDown’, ‘circle’), text.

    3. Passa l’intera lista a self.js_api.set_markers(…).

Graph View