Pubblicazione Separate e Combined, calibrazioni multiple e nomi dei Dataset

Il Curve Digitalizer di GX-TXT consente di raccogliere più realizzazioni di calibrazione dello stesso grafico. L’operatore può pubblicarle in due modi: Separate, che genera un Dataset numerico per ogni calibrazione selezionata, oppure Combined, che raccoglie più realizzazioni nello stesso Dataset aggiungendo l’identità della calibrazione a ogni riga.

Questa guida illustra le differenze nella GUI, i controlli sui nomi, la verifica delle coordinate nel CORE Scientific Dataset Viewer e l’impiego delle API pubbliche. Sono particolarmente importanti due distinzioni: calibrazione attiva non equivale a calibrazione selezionata per Publish; inoltre venti righe provenienti da dieci punti e due calibrazioni non rappresentano venti osservazioni indipendenti.

La sorgente utilizzata è una figura sintetica didattica. Gli angoli delle due calibrazioni sono stati scelti intenzionalmente in posizioni leggermente diverse: le differenze numeriche fra i risultati servono a mostrare la propagazione geometrica della trasformazione, non a stimare l’incertezza di uno strumento.

1. La figura di riferimento

Il raster originale contiene una traccia scura e una traccia rosa secondaria. La prima è l’oggetto della digitalizzazione.

Copertina illustrativa GX-TXT Curve Digitalizer con un tracciato scientifico digitalizzato.
Figura 1. L’immagine originale misura 1280 per 900 pixel e non proviene da uno strumento sperimentale.

Le dimensioni della sorgente sono 1280 × 900 pixel. Il nome del Dataset sorgente, la sua identità e la geometria dei pixel rimarranno invariati durante tutte le pubblicazioni descritte.

2. Una prima calibrazione a quattro angoli

Nella scheda Calibration definiamo X da 0 a 10 s e Y da −20 a 80 mV, entrambi lineari. Selezioniamo i quattro angoli del rettangolo del grafico e confermiamo la calibrazione.

Schermata Calibration con prima calibrazione a quattro angoli sul raster originale.
Figura 2. X si estende da zero a dieci secondi e Y da meno venti a ottanta millivolt.
Dettaglio dei comandi e dei riferimenti della prima calibrazione scientifica accettata.
Figura 3. I quattro riferimenti pixel vengono associati agli estremi fisici degli assi.

I quattro punti definiscono una trasformazione dai pixel originali alle coordinate scientifiche. La prima realizzazione verrà chiamata Trial A.

3. Acquisire dieci punti manuali

Nella scheda Curves creiamo una curva scientifica, quindi utilizziamo Add per acquisire dieci punti della linea scura.

Scheda Curves con dieci punti manuali acquisiti sulla traccia scura originale.
Figura 4. Questi punti saranno conservati nelle due differenti realizzazioni di calibrazione.

I punti possiedono un identificativo interno, una posizione originale sul raster e una coordinata X/Y calcolata. Il loro point_id non viene ricreato quando si seleziona una differente calibrazione.

4. Il gestore Calibration measurements

La sezione Calibration measurements distingue le realizzazioni che sono draft, accepted, rejected e active.

Accepted significa che la realizzazione può essere usata per la pubblicazione. Active indica invece la trasformazione mostrata e utilizzata nel documento corrente. La scheda Publish può selezionare una calibrazione accettata anche quando non è quella attiva.

5. Creare una seconda realizzazione

Premiamo New nel gestore delle misure di calibrazione.

Pannello Calibration measurements con seconda calibrazione appena creata in stato Draft.
Figura 5. New prepara una seconda realizzazione di calibrazione in stato Draft, da completare con quattro nuovi angoli.

Si crea un secondo elemento inizialmente draft. Il programma non lo tratta come già accettato: occorre fornire una nuova geometria completa e confermarla.

6. Selezionare gli angoli per Trial B

Per la seconda realizzazione selezioniamo angoli leggermente diversi dagli originali, pur mantenendo la stessa immagine e gli stessi limiti fisici degli assi.

Seconda calibrazione con quattro angoli selezionati in posizioni diverse sulla stessa immagine.
Figura 6. Le differenze dei quattro riferimenti producono coordinate fisiche leggermente diverse.
Dettaglio delle posizioni dei quattro angoli per la seconda realizzazione di calibrazione.
Figura 7. Si tratta di una seconda selezione didattica degli angoli, non di un nuovo esperimento.

Questa differenza è volutamente didattica. Non è una replica sperimentale e non permette, da sola, di stimare incertezze standard o accuratezza.

7. Accettare entrambe le calibrazioni

Dopo aver completato i quattro angoli, premiamo Accept.

Gestore delle calibrazioni con due realizzazioni accettate e identificativi distinti.
Figura 8. Ogni calibrazione possiede un identificativo di realizzazione distinto.
Dettaglio dell'elenco Calibration measurements con due realizzazioni Accepted.
Figura 9. Le pubblicazioni possono scegliere entrambe, non soltanto quella attiva.

Sono ora presenti due realizzazioni accettate, con identificativi differenti. Entrambe possono essere scelte nella scheda Publish.

8. Attiva e selezionata: che cosa cambia?

Attivando la prima realizzazione, le coordinate X/Y del documento vengono ricalcolate sulla sua trasformazione; quando è attiva la seconda, vengono ricalcolate sulla trasformazione di quest’ultima.

Schermata Calibration con Trial A attiva e dieci punti sorgente non modificati.
Figura 10. Le coordinate pixel non cambiano anche quando cambia la trasformazione di calibrazione.

Le coordinate pixel e gli identificativi dei dieci punti restano invariati. La scelta Active non decide automaticamente quali calibrazioni saranno incluse in un’operazione Publish.

9. Perché il nome visibile non è un identificativo

Per mostrare un errore comune, assegniamo temporaneamente lo stesso nome visibile alle due calibrazioni, pur mantenendo distinti i loro identificativi interni.

Due realizzazioni di calibrazione con la stessa etichetta visibile Measurement 1.
Figura 11. L’identità interna rimane diversa, ma il modello di denominazione può produrre collisioni.
Dettaglio dei due identificativi di calibrazione distinti con etichetta uguale.
Figura 12. Un nome di calibrazione non deve essere usato da solo come chiave univoca.

Un nome come Measurement 1 è una descrizione modificabile. L’identità scientifica stabile della realizzazione è il suo measurement_id.

10. La collisione nel piano di pubblicazione

Con il layout Separate e il template predefinito, due calibrazioni dallo stesso nome generano lo stesso ID previsto.

Scheda Publish con collisione tra nomi dei Dataset generati dalle calibrazioni.
Figura 13. Il piano di pubblicazione non può contenere due Dataset con lo stesso identificativo.
Dettaglio del messaggio Dataset naming collision nell'anteprima di Publish.
Figura 14. Per correggere la collisione si cambia etichetta o si usa calibration_id oppure index.

La scheda Publish segnala che i nomi collidono. Questo avviene prima di creare i Dataset canonici.

11. Il blocco della pubblicazione con nomi duplicati

Tentando di proseguire compare il messaggio nativo relativo alla collisione.

Finestra di errore che impedisce la pubblicazione di due Dataset con lo stesso ID.
Figura 15. Il rifiuto avviene prima della registrazione dei dati canonici.

La protezione impedisce di produrre due Dataset con lo stesso identificativo. Si può risolvere il problema cambiando i nomi delle calibrazioni oppure introducendo nel template [calibration_id] o [index].

12. Assegnare nomi distinti alle realizzazioni

Rinominiamo le due misure Trial A e Trial B tramite il gestore Calibration measurements.

Gestore Calibration dopo la modifica del nome della seconda realizzazione in Trial B.
Figura 16. Il nome visibile può essere modificato senza sostituire la calibrazione memorizzata.
Elenco delle due calibrazioni accettate denominate Trial A e Trial B.
Figura 17. Le etichette diverse consentono un’anteprima non ambigua con il modello predefinito.

Non sono state modificate né le posizioni degli angoli né le coordinate originali dei punti: è cambiata soltanto la descrizione visibile.

13. Trial B attiva e Trial A disponibile

Attiviamo Trial B, mantenendo Trial A nello stato Accepted.

Trial B attiva mentre Trial A resta accettata e disponibile per Publish.
Figura 18. Active controlla la visualizzazione corrente, ma Publish può selezionare entrambe.

Nella scheda Publish possiamo selezionare entrambe le realizzazioni: la pubblicazione non è limitata a quella attiva.

14. Separate: un output per calibrazione

Apriamo la scheda Publish, scegliamo Separate, selezioniamo entrambe le calibrazioni e impostiamo un ID base per gli output.

Anteprima di pubblicazione Separate con due Dataset, uno per Trial A e uno per Trial B.
Figura 19. Gli ID previsti terminano in trial_a.curves e trial_b.curves.
Dettaglio dei due identificativi di output generati dal template Separate.
Figura 20. Il modello predefinito usa name e calibration per comporre i nomi canonici.

Il template predefinito [name].[calibration].curves genera in questo esempio due nomi distinti: uno termina in trial_a.curves, l’altro in trial_b.curves.

15. Pubblicare i due Dataset Separate

Premiamo Publish selected calibrations.

Conferma Publish di due Dataset Separate con dieci righe per calibrazione.
Figura 21. Entrambe le calibrazioni accettate producono un risultato numerico autonomo.
Dettaglio degli identificativi dei due Dataset Separate pubblicati.
Figura 22. I Dataset pubblicati mantengono la stessa sorgente e identificativi punto.

La GUI conferma due Dataset pubblicati, ognuno con dieci righe. Entrambi sono tabelle numeriche canoniche di GX-TXT, separate dal raster originale e dal documento interattivo.

16. Una sola origine, due trasformazioni

Nei due output Separate i dieci point_id e le coordinate pixel sono uguali. Le coordinate scientifiche X/Y sono invece leggermente differenti, perché sono state calcolate usando due omografie accettate differenti.

Questo significa che sono state pubblicate due interpretazioni della stessa acquisizione di punti. Non sono state acquisite altre dieci posizioni sul raster.

17. Combined: un solo Dataset

Torniamo a Publish, selezioniamo Combined e manteniamo le due calibrazioni accettate.

Scheda Publish con anteprima Combined per venti righe e due calibrazioni.
Figura 23. Il piano contiene una tabella con due realizzazioni delle medesime posizioni raster.
Dettaglio del nome dell'unico Dataset previsto dalla modalità Combined.
Figura 24. Il suffisso combined deriva dalla modalità e non dal nome di una singola misura.

L’anteprima mostra un solo ID, il cui nome predefinito contiene combined. Questo layout non crea un Dataset Group: crea una sola tabella con più realizzazioni.

18. La conferma avverte del rischio di mescolare dati

Premendo Publish, GX-TXT presenta una conferma specifica per Combined.

Finestra di conferma Combined che avverte del raggruppamento di calibrazioni multiple.
Figura 25. Un lettore che ignori calibration_key potrebbe mescolare erroneamente le due realizzazioni.

L’avviso è importante: un programma che unisse tutte le righe ignorando calibration_key potrebbe mescolare coordinate ottenute con trasformazioni differenti.

19. Rispondere No: non viene creato nulla

Scegliendo No, il Viewer abbandona la pubblicazione Combined.

I due Dataset Separate precedenti restano disponibili e non nasce alcun terzo risultato. L’anteprima può continuare a mostrare l’ID Combined progettato: l’anteprima non dimostra che il Dataset sia stato registrato.

20. Rispondere Yes: il risultato Combined

Ripetiamo l’azione e scegliamo Yes nella conferma.

Il programma registra un solo Dataset Combined, costituito da venti righe.

Schermata Publish dopo creazione di un Dataset Combined con venti righe.
Figura 26. Le due calibrazioni sono rappresentate insieme senza creare nuovi punti originali.
Dettaglio del Dataset Combined canonico pubblicato in GX-TXT.
Figura 27. Il risultato è un unico Dataset numerico, non un gruppo di due Dataset.

Le venti righe rappresentano i dieci punti originali, ciascuno espresso una volta con Trial A e una volta con Trial B.

21. Due chiavi per un raggruppamento sicuro

Nel Dataset Combined, il raggruppamento non deve avvenire soltanto per curva. La API pubblica dichiara grouping_roles = curve_key + calibration_key.

La prima chiave indica la serie, la seconda la realizzazione della calibrazione. I campi descrittivi curve_name e calibration_name non devono essere utilizzati come identificativi stabili.

Selezionare correttamente le due chiavi impedisce di collegare punti fisicamente non omogenei tra le due trasformazioni.

22. Il template predefinito dei nomi

In Configuration → Viewer settings… → Axes & output compare la casella Dataset naming template.

Viewer settings, scheda Axes and output, con modello predefinito dei nomi.
Figura 28. Le preferenze iniziali sono applicate come valori User e non inventano identificativi.
Dettaglio del campo Dataset naming template con formato name calibration curves.
Figura 29. La scelta name calibration richiede etichette non collidenti quando si pubblica Separate.

Il valore predefinito è:

[name].[calibration].curves

Il template è distinto dall’ID base inserito in Publish. Il primo decide come comporre il nome completo; il secondo fornisce il valore del token [name].

23. I sei token riconosciuti

Il template supporta questi elementi di sostituzione:

TokenSignificato
[name]ID base dell’output
[calibration]Etichetta della calibrazione normalizzata
[calibration_id]Identificativo stabile della realizzazione
[configuration]Nome della configurazione normalizzato
[index]Indice dell’output nel piano corrente, a partire da 1
[mode]Modalità Separate o Combined

Il modello deve contenere [name]. Le parti letterali ammesse usano caratteri ASCII e separatori consentiti; il risultato finale deve essere un ID Dataset valido.

24. Token sconosciuti: operazione rifiutata

Inseriamo volutamente il token inesistente [unknown].

L’editor rifiuta il template e indica i token riconosciuti.

Finestra Invalid viewer settings per token sconosciuto nel template di pubblicazione.
Figura 30. Sono accettati soltanto i token name calibration calibration_id configuration index e mode.

La configurazione CORE non viene aggiornata da un tentativo di Apply non valido.

25. Il token [name] è obbligatorio

Proviamo un secondo template che contiene il nome della calibrazione ma non l’ID base.

La GUI richiede esplicitamente [name].

Messaggio di validazione del template che richiede il token obbligatorio name.
Figura 31. Il Viewer blocca il template privo del token obbligatorio senza applicarlo.

Questo controllo impedisce di generare identificativi completamente scollegati dalla scelta effettuata in Publish.

26. Un template personalizzato non ambiguo

Scegliamo:

[name].[index].[calibration_id].[mode].curves

Template personalizzato nella scheda Axes and output con name, index, calibration_id e mode.
Figura 32. Il modello può generare ID differenti anche quando le etichette visibili coincidono.
Dettaglio del template di denominazione personalizzato con i quattro token.
Figura 33. Index conta gli output della selezione attuale a partire da uno.

Questo template contiene sia un indice progressivo di output sia l’ID stabile della calibrazione. Può evitare collisioni anche quando due calibrazioni condividono la stessa etichetta.

27. Apply salva le preferenze della Session

Premendo Apply, la GUI registra il nuovo template.

Conferma Apply del template personalizzato come Session override.
Figura 34. Le preferenze User rimangono separate dagli override della Session di lavoro.

Il CORE conferma che il template personalizzato è un Session override. Il template User predefinito rimane invariato. Nell’esempio è stato salvato Combined come layout predefinito della Session.

Ciò non impedisce di scegliere Separate nella singola scheda Publish, dove la scelta locale può essere differente.

28. Calibrazione attiva contro selezione Publish

Per distinguere i due concetti, manteniamo Trial A attiva nel documento.

Gestore calibrazioni con Trial A attiva e Trial B selezionabile per la pubblicazione.
Figura 35. La selezione scientifica di pubblicazione non coincide necessariamente con Active.

Nella scheda Publish è possibile scegliere soltanto Trial B. Il risultato numerico deve corrispondere alla calibrazione selezionata, non a quella attiva.

29. Anteprima con due calibrazioni selezionate

Con il template personalizzato, selezioniamo entrambe le realizzazioni in modalità Separate.

Anteprima Separate con due ID composti da index e calibration_id.
Figura 36. Calibration_id elimina l’ambiguità dei nomi e Index distingue le uscite pianificate.
Dettaglio dei due nomi di output personalizzati con indici e identificativi delle calibrazioni.
Figura 37. Quando si selezionano due calibrazioni, gli indici previsti sono uno e due.

L’anteprima produce due nomi: il primo usa index = 1, il secondo index = 2. Entrambi includono il rispettivo calibration_id.

30. Selezionare soltanto la Trial B

Ora scegliamo soltanto Trial B, lasciando Trial A attiva.

Scheda Publish con sola Trial B selezionata e Trial A attiva.
Figura 38. La scelta di una sola uscita fa partire l’indice da uno anche per Trial B.
Dettaglio del checkbox Trial B scelto per la pubblicazione indipendentemente da Active.
Figura 39. L’operatore deve controllare i checkbox prima di confermare la pubblicazione.

Poiché il piano contiene un solo output, l’indice riparte da 1. Non è l’indice immutabile della calibrazione nel gestore delle misure, ma la posizione dell’output nel piano di pubblicazione corrente.

31. Pubblicare realmente il nome personalizzato

Confermiamo Publish.

Risultato della pubblicazione del Dataset personalizzato con i dieci punti di Trial B.
Figura 40. Le dieci righe contengono le coordinate di Trial B, non quelle della misura attiva.
Dettaglio dell'identificativo del Dataset creato con calibration_id e modalità Separate.
Figura 41. Il Dataset contiene soltanto la realizzazione effettivamente selezionata.

Il Dataset risultante contiene dieci righe di Trial B, con la stessa trasformazione della pubblicazione Separate precedente di Trial B. L’ID personalizzato è più lungo, ma non cambia le coordinate.

32. Il template in modalità Combined

Se scegliamo nuovamente Combined con entrambe le calibrazioni, l’anteprima del template diventa un unico ID contenente i valori index = 1, calibration_id = combined e mode = combined.

Anteprima del template personalizzato in modalità Combined con indice uno.
Figura 42. I token vengono sostituiti secondo il layout effettivamente scelto per l’uscita.

È una nuova anteprima, non un’ulteriore pubblicazione. La scelta dei token dipende dal layout effettivo selezionato, non soltanto dal default della Session.

33. Consultare la Trial A nel CORE

Apriamo il risultato Separate di Trial A dal browser Dataset di GX-TXT.

CORE Scientific Dataset Viewer, vista Plot del Dataset Separate di Trial A.
Figura 43. La vista Plot rappresenta soltanto la prima realizzazione della calibrazione.

Il CORE Scientific Dataset Viewer visualizza la curva nella vista Plot. La tabella canonica è il riferimento per controllare esattamente le coordinate pubblicate.

34. Le dieci righe di Trial A

Nella scheda Canonical table troviamo dieci righe.

Tabella canonica CORE con dieci righe numeriche della calibrazione Trial A.
Figura 44. Le colonne contengono coordinate calibrate e posizioni pixel originali.
Dettaglio delle coordinate scientifiche e degli identificativi dei punti per Trial A.
Figura 45. La sorgente raster è condivisa con Trial B, ma i numeri X e Y possono differire.

Il Variable Schema v3 descrive le otto variabili del Dataset Separate: coordinate scientifiche, identificativi della curva e del punto, ordine e posizioni raster.

Variable Schema v3 con otto variabili del Dataset Separate di Trial A.
Figura 46. Nella modalità Separate non è necessaria una colonna calibration_id per riga.

Per un Dataset Separate l’ID della calibrazione è conservato nei metadati del Dataset, non ripetuto come campo di ogni singola riga.

35. Aprire la Trial B come Dataset autonomo

Apriamo il secondo Dataset Separate nel Viewer CORE.

CORE Scientific Dataset Viewer, vista Plot del Dataset Separate di Trial B.
Figura 47. I dati sono ricalcolati dalla seconda calibrazione accettata della stessa immagine.

Anche in questo caso il risultato è un oggetto canonico autonomo, con dieci righe e un riferimento alla propria realizzazione di calibrazione.

36. Le coordinate di Trial B sono diverse

La tabella canonica di Trial B contiene gli stessi dieci identificativi e pixel della Trial A.

Tabella canonica Trial B con dieci punti e coordinate ricalcolate dalla seconda calibrazione.
Figura 48. I point_id e le coordinate pixel corrispondono a quelli della prima realizzazione.
Dettaglio delle coordinate di Trial B riferite agli stessi pixel di Trial A.
Figura 49. La differenza deriva dalla calibrazione e non da un nuovo esperimento.

I valori X/Y differiscono: nell’esempio lo scarto massimo osservato per gli stessi dieci punti è circa 0,0475 s su X e 0,3272 mV su Y. È un effetto delle due calibrazioni sintetiche, non una stima di accuratezza strumentale.

Metadati di calibrazione Trial B nel CORE Scientific Dataset Viewer.
Figura 50. La pubblicazione conserva l’identificativo dell’esatta realizzazione selezionata.

37. Selezionare il risultato Combined nel browser

Nel catalogo GX-TXT possiamo scegliere il Dataset Combined, distinto da Trial A e Trial B.

Browser Dataset GX-TXT con il risultato Combined selezionato.
Figura 51. Il risultato Combined è un oggetto canonico distinto dalle pubblicazioni Separate.

Il suo identificativo e il suo payload canonico sono diversi dalle due pubblicazioni Separate.

38. La vista Plot non risolve da sola la semantica

Il CORE Scientific Dataset Viewer apre anche il Combined.

CORE Scientific Dataset Viewer, vista Plot del Dataset Combined di venti righe.
Figura 52. Le due realizzazioni non devono essere analizzate ignorando calibration_key.

Una rappresentazione grafica che ignori le due realizzazioni può risultare fuorviante. La chiave di calibrazione è parte integrante del significato dei record.

39. La tabella Combined ha venti righe

La sezione Canonical table mostra venti record, con i campi aggiuntivi calibration_id e calibration_label.

Tabella canonica Combined con colonne calibration_id e calibration_label per ogni punto.
Figura 53. Dieci righe appartengono a Trial A e dieci a Trial B, con gli stessi point_id.
Dettaglio delle venti righe del Dataset Combined e della colonna calibration_id.
Figura 54. Un programma deve raggruppare per curve_key e calibration_key congiuntamente.

Le prime dieci righe sono associate a Trial A e le successive dieci a Trial B. Gli stessi point_id possono quindi comparire due volte, ma ciascuna riga è distinta anche dalla sua calibration_key.

40. Dieci variabili nel Variable Schema v3

Il Combined dichiara dieci variabili, contro le otto del Separate.

Variable Schema v3 del Dataset Combined con dieci variabili.
Figura 55. Le colonne calibration_id e calibration_label si aggiungono alle otto già presenti.
Dettaglio dei ruoli semantici e delle colonne della calibrazione nello schema Combined.
Figura 56. La chiave stabile è l’identificativo, mentre il label è descrittivo e modificabile.

I ruoli semantici aggiuntivi sono calibration_key e calibration_name. Il secondo è una descrizione, il primo è l’identificativo stabile. Il CORE dichiara che il raggruppamento completo utilizza curve_key e calibration_key.

41. Provenienza e trasformazioni

I metadati del Combined conservano l’origine e le realizzazioni di calibrazione pubblicate.

Metadati delle due calibrazioni pubblicate nel Dataset Combined.
Figura 57. Ogni realizzazione mantiene la propria omografia e la propria identità di calibrazione.

La sezione Source ancestry mostra il legame con l’immagine originale.

Scheda Source ancestry del Dataset Combined con riferimento al raster originale.
Figura 58. La catena di provenienza identifica la sorgente anziché duplicare i pixel.
Dettaglio della provenienza comune e delle due trasformazioni di calibrazione.
Figura 59. Un Dataset Combined può contenere più trasformazioni della stessa sorgente.

Questo legame permette di ricondurre le coordinate al raster e alla trasformazione appropriata, evitando di confondere due interpretazioni della stessa posizione pixel.

42. Verificare il Dataset con nome personalizzato

Nel browser Dataset è disponibile anche la pubblicazione personalizzata della sola Trial B.

Browser Dataset con la pubblicazione della sola Trial B dal template personalizzato.
Figura 60. Il nome contiene un identificativo di calibrazione distinto da quello leggibile.

Il CORE Scientific Dataset Viewer ne mostra Plot e Canonical table.

Tabella canonica del Dataset personalizzato con dieci righe di Trial B.
Figura 61. L’ID del Dataset cambia, ma non le coordinate ottenute dalla realizzazione B.

I metadati confermano che è stata pubblicata la realizzazione Trial B, benché durante la procedura fosse attiva Trial A.

Metadati del Dataset personalizzato che identificano esplicitamente Trial B.
Figura 62. L’identità della calibrazione pubblicata non dipende dalla misura attiva al momento.

43. Salvare il lavoro e verificare la riapertura

Prima di chiudere il Viewer, il gestore Calibration mostra entrambe le realizzazioni accettate.

Gestore Calibration con Trial A e Trial B accettate prima del salvataggio.
Figura 63. Entrambe le realizzazioni sono accettate e mantengono gli identificativi originali.

La scheda Publish contiene ancora la scelta locale Separate, anche se il layout predefinito della Session è Combined.

Scheda Publish impostata su Separate mentre il layout predefinito di Session è Combined.
Figura 64. Una scelta specifica del documento può prevalere sulla preferenza generale della Session.

Dopo Configuration → Save configuration, Close e Reopen, sono ancora disponibili i dieci punti e le due calibrazioni.

Gestore delle calibrazioni dopo Save, Close e Reopen con due realizzazioni conservate.
Figura 65. La riapertura conserva angoli, identità e dieci posizioni originali della curva.

La scheda Publish continua a permettere la scelta degli output e il template personalizzato.

Scheda Publish riaperta con template personalizzato e due calibrazioni disponibili.
Figura 66. Il piano di pubblicazione resta utilizzabile, ma la selezione va sempre controllata.

44. Preferenze della Session e sorgente dopo Reopen

Aprendo Viewer settings si ritrovano il template personalizzato e il layout predefinito Combined.

Viewer settings dopo il riavvio con template personalizzato e layout Combined.
Figura 67. I default User non sono stati modificati; il risultato proviene dall’override Session.
Dettaglio delle preferenze di Session ripristinate, distinte dai default User.
Figura 68. La preferenza globale User rimane la versione predefinita.

La sorgente originale e i quattro Dataset numerici già pubblicati sono ancora disponibili.

Scheda Source dopo Reopen con il raster originale e i Dataset pubblicati.
Figura 69. I quattro Dataset numerici rimangono separati dal Dataset raster d’origine.

L’identità degli output canonici è indipendente dal fatto che il Viewer sia aperto; le tabelle già pubblicate non vengono riscritte dalla riapertura.

45. Controllare la selezione dopo Reopen: una precauzione importante

Dopo la riapertura del Viewer è possibile che Publish ripristini una selezione diversa da quella salvata. Nell’esempio era stata selezionata soltanto Trial B, mentre Trial A era attiva.

Scheda Publish prima del riavvio con Trial B selezionata e Trial A attiva.
Figura 70. Il documento viene salvato con Trial B, mentre la misura attiva rimane Trial A.
Dettaglio della casella di selezione di Trial B prima del riavvio del Viewer.
Figura 71. La selezione di pubblicazione non deve essere confusa con Active.

Dopo la riapertura, la GUI ha mostrato Trial A selezionata al posto della Trial B precedentemente scelta.

Dettaglio della selezione inattesa di Trial A al posto di Trial B dopo Reopen.
Figura 72. Controllare manualmente le calibrazioni selezionate dopo ogni riapertura del Viewer.

Dopo ogni riapertura, controllare e, se necessario, riselezionare le calibrazioni in Publish prima di pubblicare. Gli output canonici precedenti non vengono modificati: il problema riguarda soltanto la selezione ripristinata nell’Interactive Document, non le trasformazioni già pubblicate.

46. API pubbliche: riconoscere il layout

Un programma che lavora sui Dataset dovrebbe risolvere le colonne e i loro ruoli tramite le API pubbliche, senza affidarsi alla posizione delle colonne CSV.

Nel framework con la Session pertinente attiva, utilizzare gli identificativi effettivi del Dataset e della realizzazione di calibrazione al posto dei valori esemplificativi nel codice:

# Activate versioned, public Curve Digitalizer Dataset Schema API.
::GX::modulePublicApiActivate viewer.curve_digitizer CURVE_DIGITIZER_DATASET_SCHEMA_API_v1

set dataset_id "example.combined.curves"
set manifest [::GX::CurveDigitizerDataset::read $dataset_id]

# The full set of grouping roles may contain more than one key.
set roles [dict get $manifest grouping_roles]
set curve_column [dict get $manifest columns curve_key]

if {[dict exists $manifest columns calibration_key]} {
    set calibration_column [dict get $manifest columns calibration_key]
}

# Read a bounded canonical subset for one calibration realization.
set measurement_id "example_measurement_id"
set rows [::GX::CurveDigitizerDataset::rasterPoints \
    $dataset_id "" 0 100 $measurement_id]

La firma di rasterPoints ammette un filtro sul parametro calibrationKey, oltre all’eventuale filtro curveKey. Il numero di righe restituite va verificato; non bisogna presumere che corrisponda all’intero Dataset Combined.

47. API di calibrazione: leggere ogni realizzazione

La API CURVE_DIGITIZER_CALIBRATION_API_v1 permette di consultare le realizzazioni pubblicate e applicare la trasformazione adeguata ai pixel originali. Nel blocco Tcl successivo, dataset_id è lo stesso identificativo impostato nell’esempio precedente.

# Activate the public calibration manifest API.
::GX::modulePublicApiActivate viewer.curve_digitizer CURVE_DIGITIZER_CALIBRATION_API_v1

set calibrations [::GX::CurveDigitizerCalibration::replicates $dataset_id]

foreach cal $calibrations {
    if {![dict get $cal valid]} {
        continue
    }

    set mid [dict get $cal measurement_id]
    set original_pixels {{235.74 441.71}}

    set xy [::GX::CurveDigitizerCalibration::transformPoints \
        $dataset_id $original_pixels pixel_to_scientific $mid]
}

La realizzazione deve essere indicata tramite measurement_id, non dedotta dalla sua etichetta. La stessa API consente la trasformazione inversa scientific_to_pixel con la calibrazione specificata.

48. Regole per scegliere Separate o Combined

Utilizzare Separate quando è utile trattare ciascuna calibrazione come un Dataset distinto, con la sua identità e la sua tabella. La gestione è più semplice per i consumatori che non sono predisposti a distinguere più realizzazioni nello stesso output.

Utilizzare Combined quando serve un’unica tabella con più realizzazioni, ma soltanto se gli strumenti a valle rispettano calibration_key e il CORE conferma che le unità fisiche degli assi sono compatibili.

La pubblicazione Combined richiede infatti le stesse unità fisiche X per tutte le calibrazioni selezionate e le stesse unità Y. Non è un modo per unire direttamente grandezze incompatibili.

49. Limiti della procedura

Questa guida ha esaminato una curva, due calibrazioni accettate e quattro pubblicazioni di prova, tutte provenienti dallo stesso raster sintetico.

Non abbiamo creato nuove misure indipendenti, calcolato intervalli di confidenza o dichiarato incertezze metrologiche. Un modello d’incertezza revisionato per una calibrazione non deve essere trasferito automaticamente a un’altra. La pubblicazione Combined di più calibrazioni con incertezza numerica revisionata non è supportata scientificamente da questa versione: utilizzare Separate o disabilitare la dichiarazione, quando appropriato.

I Dataset Group, i due assi Y e gli schemi multi-Y sono trattati in una guida successiva, non sono impliciti nel semplice layout Combined.

50. Procedura operativa consigliata

  1. Conservare il raster originale e acquisire i punti scientifici da una sorgente identificata.
  2. Creare e accettare le realizzazioni di calibrazione, mantenendo distinti i loro measurement_id.
  3. Assegnare nomi descrittivi, ma non usare l’etichetta come identità scientifica stabile.
  4. Controllare la differenza fra misura attiva nel Viewer e misure selezionate in Publish.
  5. Scegliere Separate per Dataset distinti oppure Combined per una tabella unica con calibration_key.
  6. Verificare l’anteprima degli ID prima della pubblicazione. Usare [calibration_id] o [index] quando le etichette possono collidere.
  7. Per un template personalizzato, includere [name] e soltanto token autorizzati.
  8. In Combined, leggere l’avviso e proseguire soltanto se gli strumenti a valle comprendono le chiavi di calibrazione.
  9. Controllare i Dataset nel CORE, confrontando i record con le realizzazioni attraverso le API pubbliche.
  10. Dopo Save/Close/Reopen, verificare nuovamente le calibrazioni selezionate in Publish prima di confermare un’ulteriore uscita.

Conclusione: Separate e Combined consentono due organizzazioni differenti di dati ottenuti dagli stessi punti pixel. La correttezza scientifica dipende dal mantenimento delle identità di calibrazione, dalla denominazione non ambigua e dalla lettura dei ruoli semantici, non soltanto dal numero di righe della tabella.