Annotazioni e presentazione dei grafici
Corso Python scientifico in GX-TXT · Modulo 6 · Lezione 36
Un’annotazione aiuta il lettore a individuare un punto o una regione significativa. Deve aggiungere contesto senza modificare i dati o suggerire conclusioni non supportate. In questa lezione annotiamo un valore della serie sintetica usando il PlotSpec.
Obiettivi
- Inserire un’annotazione testuale in un pannello.
- Riconoscere coordinate e unità dell’annotazione.
- Distinguere Dataset, specifica, grafico e screenshot.
- Preparare una figura con titolo e didascalia coerenti.
Un punto noto
La serie sintetica del corso vale 1,5 mV a
0,5 s. Aggiungiamo vicino a quel punto il testo «Valore
sintetico: 1.5 mV». Il testo descrive un valore già presente: non
aggiunge un campione e non implica che sia una misura reale.
Nella Sessione corso_python, importa annotazioni.py, salva lo script e
avvialo con Run → Open Script Runner → Run Job.

from gxtxt import gxtxt_api_call, gxtxt_api_require
gxtxt_api_require("PLOT_DATASET_API_v4@4")
api = "PLOT_DATASET_API_v4"
spec = gxtxt_api_call(api, "new_spec", ["plot.dataset.xy", "Segnale sintetico annotato"])
pannello = spec["panels"][0]
pannello["series"] = [{"id": "segnale", "dataset_id": "corso_python_serie_sintetica", "x_variable_id": "tempo", "y_variable_id": "segnale", "axis": "left", "kind": "line_marker", "label": "Serie sintetica"}]
pannello["annotations"] = [{"type": "text", "axis": "left", "x": 0.52, "y": 1.65, "label": "Valore sintetico: 1.5 mV"}]
print("Spec valido:", gxtxt_api_call(api, "validate_spec", [spec]))
plot = gxtxt_api_call(api, "create_plot", [spec, "variant"])
gxtxt_api_call(api, "set_panel_axis", [plot, "main", "x", {"label": "Tempo (s)", "display_unit": "s"}])
gxtxt_api_call(api, "set_panel_axis", [plot, "main", "y_left", {"label": "Segnale (mV)", "display_unit": "mV", "min": 0., "max": 2.}])
print("Grafico:", plot)
print("Rendering:", gxtxt_api_call(api, "render", [plot]).get("execution"))
La lista annotations appartiene al pannello. Il
dizionario definisce type: text, l’asse verticale
left, le coordinate x e y e la
stringa label. Le coordinate collocano il testo leggermente
sopra il punto, in modo da non coprire la linea. Il valore riportato
nell’etichetta è verificabile nella serie; le coordinate del testo sono
una scelta di impaginazione e non costituiscono un nuovo dato.

Lo screenshot è una cattura della finestra grafica GX-TXT, ritagliata per mostrare la figura senza lo sfondo esterno. Il rendering deriva dal PlotSpec e dal Dataset; la cattura è una figura per la guida. Una ritagliatura non deve cancellare elementi scientificamente rilevanti o aggiungerne di nuovi. Conservare anche i file di origine e il riferimento al Dataset aiuta a ricostruire la figura.
GX-TXT mette a disposizione anche un’API di annotazione separata per gli overlay: il suo sistema di coordinate e il suo ciclo di vita vanno letti nel rispettivo contratto. L’esempio di questa lezione usa invece l’annotazione del pannello nel PlotSpec, con coordinate della rappresentazione dati.
Esercizio
- Qual è il valore annotato e a quale tempo appartiene?
- Cambiare la posizione del testo modifica il Dataset?
- Perché è utile includere «sintetico» nel titolo o nell’etichetta?
Soluzione ragionata
1,5 mVa0,5 s.- No: si modifica la presentazione, non il valore della variabile sorgente.
- Distingue un dato costruito per l’esercizio da una misura sperimentale.
Nel prossimo modulo collegheremo parametri, Sessione e trasformazioni per costruire analisi ripetibili.