GX-TXT — Guida completa a Scientific Dataset Plot (plot.dataset)

Indice

1. Versione e provenienza della guida

La baseline di questa guida è GX-TXT 0.9.8.10-dev-031. Il modulo presente nella build è Scientific Dataset Plot / plot.dataset 3.12.2.

Materiale di audit usato

È stato esaminato l'audit esteso in H:\work-agent\plotdataset-audit\plotdataset_extended_gui_audit.zip, eseguito il 2 ottobre 2026 su GX-TXT dev-023 ma con la stessa versione del modulo plot.dataset 3.12.2. L'audit contiene Session, Dataset, configurazioni e PNG esportati. I casi grafici di questa guida sono ricostruiti dai Dataset dell'audit per renderli leggibili e autosufficienti nell'HTML.

Aggiornamento alla dev-031

Le descrizioni di funzionalità, opzioni, multi-panel, large Dataset, 3D e API sono state controllate sui sorgenti e sulla documentazione della dev-031. Dove l'audit non ha esercitato direttamente una funzione, la guida lo segnala.

2. Il modello mentale corretto

Per usare bene Plot Dataset è utile separare quattro concetti.

Dataset canonico

È la sorgente scientifica registrata nella Sessione. Lo script o il grafico deve riferirsi al Dataset ID, non a un percorso CSV/HDF5 fisico.

Variable ID

X, Y, Z, family, color e variabili ausiliarie sono identificate con ID canonici. Etichette e unità sono metadati; l'identità è il Variable ID.

Graph Series

Per il 2D, CORE conserva l'autorità scientifica della serie: dataset_id + x_variable_id + y_variable_id + axis + order, più un Series ID stabile.

PlotSpec / Variant

La presentazione — stile, errori, bande, pannelli, assi, annotazioni — appartiene allo stato del plot. Un Variant può avere una presentazione indipendente dalla Base.

Dataset ID→Variable ID→Graph Series→PlotSpec→Render / Variant / Export

Errore concettuale da evitare

Non costruire il grafico pensando al file fisico da cui arrivano i dati. Il file è un dettaglio dell'importazione; Plot Dataset deve lavorare sul Dataset canonico della Sessione.

3. Da Dataset a primo grafico

Apri una Sessione che contenga almeno un Dataset canonico con variabili numeriche utilizzabili.

Vai nella pagina Analysis e abilita Scientific Dataset Plot.

Usa Run / recalculate now se serve inizializzare o aggiornare l'analisi.

Sul grafico 2D apri Series..., scegli il Dataset, quindi X e Y.

Premi Add o aggiorna la riga esistente, quindi Save Config.

Esegui Run enabled analyses, apri Plots e controlla il render.

Regola pratica

Nel Series editor scegli prima il Dataset; solo dopo seleziona X e Y. In questo modo le liste delle variabili sono coerenti con la sorgente effettiva.

4. I tre grafici offerti dal modulo

Graph ID	Nome	Uso principale
`plot.dataset.xy`	Scientific dataset 2D	Grafico 2D generale, Series multiple, più Dataset, dual-Y, famiglie, stili, multi-panel e Variant.
`plot.dataset.xy_region`	Scientific dataset 2D - rectangle selection	Versione 2D con selezione rettangolare in coordinate X/Y. Rimane single-panel.
`plot.dataset.xyz`	Scientific dataset 3D	Linee/scatter/surface/mesh/contour3/trisurf/heatmap con binding X/Y/Z/family/color.

Ogni offerta dispone del normale flusso GX-TXT con Configure..., Variants... e, dove previsto, Series....

5. Series editor: anatomia e uso

Il Series editor è il centro operativo del 2D. L'audit ha verificato creazione, modifica, rimozione, riordinamento, famiglie, filtri, uso di un secondo Dataset e persistenza.

AddUpdateRemove UpDownRefresh values

ID	On	Dataset	X	Y	Axis	Label	Filters	Panel
series_0001	✓	audit.longform	x_s	response_V	left	Copper A	material=Copper...	main
series_0002	✓	audit.reference	x_s	baseline_V	right	Reference	—	main

Datasetaudit.longform

X variablex_s

Y variableresponse_V

Axisleft / right

Primary familymaterial

Second variablebatch

Orderingpoint_order

Exact filterquality = pass

Schema didattico dell'organizzazione dei controlli, non screenshot dell'interfaccia.

5.1 Tabella delle Series

La tabella superiore mostra almeno ID, stato enabled, Dataset, X/Y, asse, label, numero di filtri e — quando il multi-panel è attivo — il pannello assegnato.

5.2 Operazioni fondamentali

Add: crea una nuova Series.
Update: modifica la Series selezionata mantenendone l'identità.
Remove: rimuove la Series dal grafico.
Up / Down: cambia l'ordine delle Series.
Refresh values: rilegge i valori disponibili per family/filter dalla sorgente corrente.

6. Famiglie, second values e filtri

Le famiglie permettono di trasformare una colonna categoriale o numerica in più Series senza costruirle a mano una per una.

6.1 Primary family variable

Scegli una variabile, per esempio material o gain. Le modalità principali sono:

All values as separate series — una Series per ogni valore distinto;
Selected value — un solo valore;
Selected values — più valori scelti, con selezione multipla.

Il comando Create family series materializza le combinazioni come Series vere e proprie con filtri esatti.

6.2 Secondary parameter / Second values

Modalità	Effetto	Esempio
Filter	Il secondo valore restringe i punti della Series.	`batch=B`
Split into series	Ogni secondo valore crea una nuova Series.	`material × batch`
Style category	Il secondo valore genera categorie di stile coerenti fra Series.	batch A/B con colori ricorrenti per categoria

6.3 Filtri esatti

L'audit ha verificato filtri sia testuali sia numerici, per esempio quality=pass, quality=review, temperature_C=20 e successiva modifica a temperature_C=40.

Famiglie testuali material per batch dal Dataset dell'audit — AUDIT Riproduzione didattica del caso `material × batch` con filtro `quality=pass`. L'audit reale ha creato sei Series `textfam_`, ciascuna con 64 punti quality-pass.

Comportamento da conoscere quando riapri una Series generata

L'audit ha osservato che una combinazione family materializzata viene salvata come Series con filtri esatti. Quando la riapri, il form può mostrare la forma materializzata — per esempio Filter — invece della modalità originaria Style category o della precedente selezione multipla. Label, filtri, Series e colori di categoria sono comunque rimasti persistenti. Non è stato classificato come difetto.

7. Ordering e collegamento dei punti

Quando più righe condividono X o provengono da combinazioni sperimentali diverse, collegare i punti nell'ordine di registrazione può creare segmenti scientificamente sbagliati. La variabile di ordering serve a imporre un ordine stabile, per esempio point_order.

Opzione	Quando usarla
`auto`	Lascia al modulo la scelta del comportamento.
`dataset_order`	Preserva l'ordine canonico delle righe.
`sort_x`	Ordina per X prima del rendering della curva.
Ordering variable	Quando un indice esplicito descrive la sequenza corretta dentro ogni combinazione.

Audit

point_order è stato scelto per le Series generate e risultava ancora presente dopo Save Config, chiusura e riapertura della Sessione.

8. Più Dataset e doppio asse Y

Ogni Series 2D può scegliere il proprio Dataset. Non è quindi necessario copiare i dati in una tabella unica per mostrare, nello stesso grafico, una misura e una sorgente di riferimento.

Crea la prima Series da audit.longform con x_s → response_V sull'asse left.

Aggiungi una seconda Series scegliendo audit.reference.

Imposta x_s → baseline_V e asse right.

In Configure assegna label/unità e, se necessario, limiti indipendenti per Y Left e Y Right.

Doppio asse Y e secondo Dataset, caso derivato dall'audit — AUDIT Caso derivato dall'audit: famiglia numerica `gain` su Copper, una Series modificata a 40 °C e la baseline di `audit.reference` sul secondo asse Y.

Cosa ha verificato l'audit

La riga audit.reference / baseline_V è stata aggiunta realmente sull'asse destro. Il preview mostrava il secondo asse e la baseline; dopo riapertura della Sessione la configurazione era ancora presente.

9. Stili e rappresentazioni 2D

Nella dev-031 lo strato avanzato delle Series/PlotSpec supporta i seguenti kind:

autolinescatter line_markersteperrorbar bandbarhistogram box_whisker

Per ogni Series sono disponibili campi di stile come color, line style, line width, marker, marker size, marker fill e opacity. Per i kind specializzati compaiono parametri specifici: step mode, bar width/baseline, histogram bins/normalization, box whisker IQR e outliers.

Due nomi simili ma non identici

La configurazione semplice del graph offering espone plot_style=auto;line;scatter;line_markers. Nello strato avanzato Series/PlotSpec il kind corrispondente è line_marker. Non confondere le due liste.

Selected family values e style category — AUDIT Riproduzione del caso con valori `Copper` e `Steel` selezionati dalla family `material` e `batch` usato come Style category. Nell'audit furono create quattro Series `styled_` e i colori per categoria batch rimasero persistenti.

10. Error bar, band e variabili ausiliarie

La dev-031 espone nel Series editor le variabili ausiliarie provenienti dallo stesso Dataset della Series.

Funzione	Campi principali
Y error	none / symmetric / asymmetric; error oppure lower/upper variable
X error	none / symmetric / asymmetric; error oppure lower/upper variable
Band	lower variable, upper variable, opzionale center series
Bar interval	X lower / X upper

Disponibile nella dev-031

Questi controlli sono presenti nel codice UI e nel PlotSpec corrente. L'audit esteso del 2 ottobre non ha però esercitato direttamente error bar, band e alignment; vanno quindi considerati documentati nella build corrente, non audit-verified da quella specifica Sessione.

11. Multi-panel a X condivisa

plot.dataset.xy può essere organizzato in pannelli verticali con un'unica X visibile condivisa.

Configure...

Qui si abilita Multi-panel (vertically stacked, shared X), si creano/rimuovono/riordinano i pannelli, si assegna il titolo del pannello e si configurano Y Left / Y Right.

Series...

Il Series editor non crea i pannelli: quando il multi-panel è già attivo, assegna ogni Series a uno dei panel esistenti tramite il suo Series ID stabile.

Ogni panel possiede assi Y locali, annotazioni e legenda; titolo del grafico e X rimangono globali. Le Series possono provenire da Dataset diversi e persino usare X Variable differenti, purché il dominio visibile condiviso sia compatibile.

Il grafico rectangle-selection è diverso

plot.dataset.xy_region resta single-panel perché la selezione rettangolare ha un solo dominio Y. Il normale meccanismo di selezione x_range del grafico multi-panel, invece, opera sull'X condivisa e può attraversare tutti i pannelli.

12. Assi, unità, tick, legenda e annotazioni

La configurazione corrente distingue correttamente proprietà scientifiche e presentazione dell'asse. Sono disponibili label, display unit, scala, direzione, minimo, massimo, tick positions e tick labels.

Y Left / Y Right

Ogni panel può avere presentazione indipendente sui due assi Y.

Restore automatic

Quando torni all'automatico, lo stato CORE dell'asse è autorevole e sopprime limiti/unità provider stale che altrimenti potrebbero sopravvivere in configurazioni precedenti.

Le annotazioni supportano almeno linee di riferimento, regioni e testo. La legenda può essere automatica, disabilitata oppure costruita sulle Series; nel 3D può anche riflettere le family.

13. Base e Variant

Un Variant non è una copia informale del PNG: è uno stato persistente del grafico con configurazione di presentazione indipendente. Nella dev-031 il multi-panel e gli assi possono differire fra Base e Variant senza perdere l'identità scientifica delle Series.

Costruisci e salva una Base leggibile e scientificamente corretta.

Apri Variants... e duplica/crea la variante desiderata.

Modifica layout, assi, stili o pannelli nel Variant.

Verifica che la Base sia invariata: l'isolamento è parte del modello persistente.

14. Region selection

Ci sono due concetti da distinguere:

Modalità	Dominio	Note
x_range	Solo X	Nel multi-panel usa il dominio X visibile condiviso; non introduce un secondo registry di dati.
rectangle / `xy_region`	X e Y	Richiede un singolo dominio Y e quindi resta single-panel.

Stato della verifica

La semantica è documentata nel modulo corrente. L'audit esteso non ha eseguito materialmente il drag rettangolare, quindi questo specifico gesto non appartiene alla matrice audit-verified.

15. Large Dataset e riduzione

Plot Dataset non modifica il Dataset canonico per renderlo più leggero. La riduzione riguarda il display/rendering.

Parametro dev-031	Default	Significato
`reduction_mode`	`auto`	auto / none / stride / minmax
`target_points`	6000	budget indicativo di punti per la visualizzazione
`auto_reduce_threshold`	12000	soglia oltre la quale l'auto reduction entra in gioco
`chunk_rows`	5000	dimensione di lavoro per letture a chunk

In modalità automatica il comportamento corrente privilegia una riduzione min/max per bucket che conserva gli estremi locali meglio di un semplice stride.

Illustrazione della riduzione di rendering per grandi Dataset — DEV-031 Illustrazione concettuale: il Dataset canonico resta completo; il renderer può usare un campione extrema-preserving per contenere tempi e memoria.

16. Grafici 3D

Il graph offering plot.dataset.xyz usa binding Analysis per X, Y, Z, family e color. La dev-031 espone sette rappresentazioni 3D:

line3scatter3surface meshcontour3trisurf heatmap

La configurazione include title, label X/Y/Z, ordering, legenda, family label prefix, line width, marker size, contour levels, riduzione e target points. È disponibile anche extra_format=svg/pdf per output vettoriale aggiuntivo dove applicabile.

Scatter 3D raggruppato per materiale, dataset audit — AUDIT Riproduzione del caso 3D: `x_s` / `temperature_C` / `response_V`, family `material`. Nell'audit finale il graph 3 conteneva 504 punti validi in tre gruppi material.

16.1 Viewer 3D persistente

La API v3 separa il source graph/Variant dalla rappresentazione nel Viewer 3D. Le rappresentazioni possono riportare stati di sincronizzazione come SYNCED, OUT OF SYNC e SOURCE MISSING. Questo evita di confondere la sorgente persistente con una vista interattiva derivata.

17. Tutorial completi basati sull'audit

17.1 Tutorial A — sei curve material × batch, solo quality=pass

Apri plot.dataset.xy → Series....

Dataset: audit.longform; X: x_s; Y: response_V.

Primary family: material → All values as separate series.

Second variable: batch → Split into series.

Exact filter: quality=pass.

Ordering: point_order; quindi Create family series.

Risultato audit

Sei Series textfam_; 64 punti quality-pass per Series. Nel graph 1 finale risultavano sette Series perché era presente anche una Series aggiuntiva.

17.2 Tutorial B — famiglia numerica gain e modifica del filtro

Primary family: gain, valori 1 e 2.

Filtro: material=Copper.

Second filter: temperature_C=20.

Crea le due Series numeriche.

Seleziona numericfam_0001, cambia temperature_C da 20 a 40, modifica la label e premi Update.

Risultato audit

La label e il filtro modificati erano ancora corretti dopo riapertura del Series editor e dopo Save/reopen della Sessione.

17.3 Tutorial C — aggiungere un secondo Dataset sull'asse destro

Premi Add.

Dataset: audit.reference; X: x_s; Y: baseline_V.

Axis: right; label: per esempio “Reference baseline”.

Save Config e Run.

Risultato audit

Graph 2 mostrava realmente il secondo asse Y e la baseline proveniente dal Dataset separato.

17.4 Tutorial D — Selected values + Style category

Primary family: material → Selected values.

Con Ctrl seleziona Copper e Steel.

Second variable: batch → Style category.

Crea le Series.

Risultato audit

Quattro righe styled_ fra batch A/B; i colori salvati si ripetevano per categoria batch.

17.5 Tutorial E — 3D per materiale

Nella configurazione Analysis del graph 3D assegna X=x_s.

Y=temperature_C.

Z=response_V.

Family=material.

Usa scatter3, salva ed esegui.

Risultato audit

504 punti validi raggruppati in tre gruppi di legenda: Copper, Aluminum e Steel.

18. Save, Run, Plots ed export

Series / Configure→Save Config→Run enabled analyses→Plots→Export...

Il flusso di audit ha inoltre verificato Session Tools → Export Session to HTML. I tre PNG finali sono stati esportati dalla GUI e inclusi nel pacchetto di audit.

Persistenza

Dopo Save Config, chiusura/riapertura della Sessione e nuova apertura del Series editor, le Series intenzionali risultavano ancora presenti, inclusi filtro/label modificati, ordering, Series testuali e categorie di stile.

19. API pubbliche e integrazione avanzata

La dev-031 dichiara le API pubbliche PLOT_DATASET_API_v1, PLOT_DATASET_API_v2, PLOT_DATASET_API_v3 e PLOT_DATASET_3D_API_v1. Per nuovo codice, la facade corrente è PLOT_DATASET_API_v3.

La v3 mantiene il lifecycle stabile delle versioni precedenti e aggiunge/espone operazioni per PlotSpec, viewer interattivo, snapshot e preview transient. Fra le firme documentate:

upsertPlotFromSpec producerModuleId providerKey spec

captureForArtifact ...
renderSnapshot ...
writePointIndex ...

renderTransientOverlay ...
renderTransientCurve3D ...
renderTransientCurves2D ...

Per moduli e script

Usa le API pubbliche del framework e gli ID canonici. Non dipendere dai file interni della Sessione né da procedure private ::GX quando esiste un'operazione pubblica equivalente.

20. Cosa è stato realmente verificato

Area	Stato	Evidenza
Dataset/variable per Series, anche da Dataset diversi	AUDIT	`audit.longform` + `audit.reference` nello stesso grafico.
Text family + second values split	AUDIT	material × batch → 6 Series.
Filtri testuali e numerici	AUDIT	quality, temperature_C, batch.
Numeric family e modifica Series	AUDIT	gain 1/2, edit 20 → 40 °C.
Selected family values	AUDIT	Copper + Steel.
Style category	AUDIT	batch A/B con colori persistenti.
Ordering	AUDIT	`point_order`.
Dual-Y e secondo Dataset	AUDIT	baseline_V su right axis.
3D da Analysis bindings	AUDIT	504 punti, 3 gruppi material.
Save/reopen e export PNG/HTML	AUDIT	stato persistito; export completati.
Rectangle drag selection	DEV-031 NON AUDIT	Disponibile/documentato, non esercitato da quell'audit.
Direct style entry, alignment, error variables	DEV-031 NON AUDIT	Controlli presenti nella UI corrente.
Manual annotations, alternate representations	DEV-031 NON AUDIT	Documentati, non esercitati dall'audit.
3D Series editor	DEV-031 NON AUDIT	L'audit 3D ha usato i binding Analysis.

Esito audit

Nessun difetto confermato nei percorsi esercitati. Il run finale ha renderizzato tutti e tre i grafici; graph 1 aveva 7 Series, graph 2 aveva 8 Series e graph 3 aveva 504 punti validi in tre gruppi.

21. Troubleshooting

Sintomo	Causa probabile	Correzione
La lista X/Y non contiene ciò che cerchi	Dataset non scelto o Dataset sbagliato	Seleziona prima il Dataset, poi premi Refresh values.
Una linea collega punti non correlati	Ordering errato	Usa `point_order`, dataset_order o sort_x secondo la semantica dei dati.
La family produce troppe Series	All values + split second variable	Usa Selected values oppure Second variable=Filter.
Dopo una family generata il form sembra diverso	La family è stata materializzata in filtri esatti	Controlla la riga salvata e i filtri effettivi; è comportamento osservato nell'audit.
Il secondo asse non appare	Tutte le Series sono su left	Imposta almeno una Series su right e salva.
Multi-panel: non posso assegnare una Series a un panel	I panel non esistono ancora	Creali prima in Configure, poi torna in Series.
Limiti/unità sembrano “bloccati”	Stato provider precedente	Usa Restore automatic sull'asse e salva.
Large Dataset lento	reduction=none o budget troppo alto	Usa auto/minmax e un target_points ragionevole.
Il 3D non si raggruppa	Family binding assente	Imposta la variabile family nell'Analysis binding.

22. Riferimento rapido

2D base

plot.dataset.xy
Series, family, filter, dual-Y, multi-panel, Variant.

2D region

plot.dataset.xy_region
Rectangle selection; single-panel.

3D

plot.dataset.xyz
X/Y/Z + family/color; 7 rappresentazioni.

Family

All values / Selected value / Selected values.

Second values

Filter / Split into series / Style category.

Large Dataset

auto / none / stride / minmax; target 6000; threshold 12000.

Checklist prima del Run

Dataset corretto per ogni Series.
X/Y (e Z per 3D) corretti.
Axis left/right corretto.
Filtri e family coerenti con la domanda scientifica.
Ordering verificato.
Panel già creati se usi multi-panel.
Label/unità/limiti degli assi controllati.
Save Config prima del Run.

23. File dell'audit usati come riferimento

Il pacchetto originale esaminato contiene, fra gli altri:

exports/analysis/plot.dataset/01_dataset_xy.png — graph 1, famiglie testuali;
exports/analysis/plot.dataset/02_dataset_xy_region.png — graph 2, configurazione 2D complessa e dual-Y;
exports/analysis/plot.dataset/03_dataset_xyz.png — graph 3, 3D;
exports/intermediate/02_numeric_family_before_additional_series.png — fase intermedia della famiglia numerica;
exports/intermediate/03_3d_before_final_rerender.png — render 3D intermedio;
GUI_TEST_REPORT.md e PLOTDATASET_MANUAL.md — report e manuale dell'audit.

Le immagini della guida sono ricostruite dai dati dell'audit per mantenere gli esempi visuali riproducibili e leggibili. I PNG originali restano nel pacchetto audit come evidenza del run GUI.