Validazione numerica del fit Terrain: residui, statistiche e grafici diagnostici

Due Dataset persistenti → Table Stream v3 → NUMERIC API v1 → Dataset residui/statistiche → Plot Dataset v3.

Indice

Workflow verificato Tutorial 02 Python · API pubbliche

Questo tutorial continua direttamente il workflow Terrain 3D. Il Dataset osservato terrain_profiles_raw e il Dataset fitted tutorial.terrain_surface_fit vengono confrontati punto per punto; il calcolo scientifico dei residui e delle statistiche passa attraverso NUMERIC_API_v1, quindi i risultati vengono pubblicati come normali Dataset GX-TXT e visualizzati con PLOT_DATASET_API_v3.

Prerequisito. Il Dataset sorgente e i relativi metadata appartengono al Tutorial 01 — Terrain 3D e non sono duplicati qui. Da quella pagina puoi scaricare direttamente terrain_profiles_raw.csv e terrain_profiles_raw.metadata.txt.
Idea centrale. Python orchestra il workflow e associa i record tramite coordinate X/Y, ma l'aritmetica scientifica è eseguita tramite NUMERIC_API_v1. Il tutorial verifica quindi che analisi numerica, identità delle variabili, metadata, pubblicazione e plotting rimangano all'interno delle API pubbliche GX-TXT.

Indice

  1. Materiali e prerequisiti
  2. Architettura del workflow
  3. API utilizzate
  4. Stage 1 — Analysis Sources
  5. Calcolo numerico dei residui
  6. Dataset pubblicati
  7. Risultati numerici attesi
  8. Metadata di validazione
  9. Continuazione tra Session
  10. Stage 2 — grafici diagnostici
  11. Errori intenzionali e contratti
  12. Risultati grafici
  13. Checklist di riproduzione
  14. Download

1. Materiali e prerequisiti

Il Tutorial 02 usa come input scientifici i risultati del Tutorial 01. Deve essere disponibile una Session contenente:

terrain_profiles_raw
tutorial.terrain_surface_fit

Il secondo Dataset deve mantenere i metadata scritti dal fit precedente, inclusi almeno processing.kind=surface_fit, processing.source_dataset_id=terrain_profiles_raw, fit.rmse_m, fit.r2 e gli ID stabili delle variabili X/Y/Z.

Apri i materiali del Tutorial 01Scarica il Dataset CSV sorgenteScarica i metadata del Dataset

I file specifici di questo tutorial sono due script: 01_validate_fit_numeric_api.py esegue la validazione e pubblica i Dataset derivati; 02_plot_fit_validation_v3.py genera i grafici diagnostici persistenti.

2. Architettura del workflow

terrain_profiles_raw              tutorial.terrain_surface_fit
        \                               /
         \ primary               model /
          +---------------------------+
                        ↓
             TABLE_STREAM_API_v3
                        ↓
       metadata-driven variable binding
                        ↓
                 NUMERIC_API_v1
                        ↓
        exact XY residual validation
                        ↓
   tutorial.terrain_fit_residuals
   tutorial.terrain_fit_profile_statistics
                        ↓
               PLOT_DATASET_API_v3
                        ↓
      diagnostic plots + Session commit

3. API utilizzate

TABLE_STREAM_API_v3DATASET_VARIABLE_SCHEMA_API_v3DATASET_METADATA_API_v1NUMERIC_API_v1DATASET_PUBLICATION_API_v2PLOT_DATASET_API_v3SESSION_PERSISTENCE_API_v1

APIRuolo nel tutorial
TABLE_STREAM_API_v3Legge in streaming le colonne dei due Dataset persistenti mantenendo l'allineamento.
DATASET_VARIABLE_SCHEMA_API_v3Risoluzione e verifica degli ID stabili delle variabili.
DATASET_METADATA_API_v1Recupera i binding scientifici e registra i metadata dei risultati.
NUMERIC_API_v1Esegue sottrazione, valore assoluto, quadrato, media, somma, massimo, radice quadrata e operazioni per R².
DATASET_PUBLICATION_API_v2Pubblica i Dataset canonici di residui e statistiche per profilo.
PLOT_DATASET_API_v3Crea due normali Variant plot.dataset.xy.
SESSION_PERSISTENCE_API_v1Esegue il commit dello stato finale nella Session.

4. Stage 1 — configurare le Analysis Sources

Registra 01_validate_fit_numeric_api.py nel Python Script Workspace. Un ID di Session consigliato è terrain_numeric_validation.

Script di validazione nel Python Script Workspace
Lo script di validazione numerica registrato nel Python Script Workspace.

Lo script dichiara un contratto esplicito su due Analysis Sources:

primary -> terrain_profiles_raw
model   -> tutorial.terrain_surface_fit
Analysis Sources primary e model configurate
Configurazione corretta delle Analysis Sources primary e model.

5. Calcolo numerico dei residui

Per ogni osservazione lo script cerca nel Dataset fitted il punto con le stesse coordinate X/Y. Nel Dataset deterministico fornito, tutti gli 891 punti originali sono presenti esattamente sulla griglia fitted 81 × 51: non viene introdotta interpolazione.

Le quantità principali sono:

\[r_i=z_{i,obs}-z_{i,fit}\]

\[\mathrm{MAE}=\frac{1}{N}\sum_i |r_i|\qquad \mathrm{RMSE}=\sqrt{\frac{1}{N}\sum_i r_i^2}\]

\[R^2=1-\frac{\sum_i r_i^2}{\sum_i(z_{i,obs}-\bar z_{obs})^2}\]

Le stesse operazioni vengono ripetute indipendentemente per ciascuna delle 11 famiglie di profilo. Nel codice le operazioni scientifiche sono richieste a NUMERIC_API_v1; Python gestisce il controllo del flusso, i gruppi e l'associazione esatta X/Y.

6. Dataset pubblicati

tutorial.terrain_fit_residuals

Contiene 891 righe e le variabili:

v_x_m
v_y_m
v_profile_id
v_z_observed_m
v_z_fit_m
v_residual_m
v_abs_residual_m
v_residual_squared_m2

tutorial.terrain_fit_profile_statistics

Contiene 11 righe, una per profilo:

v_profile_id
v_profile_y_m
v_point_count
v_bias_m
v_mae_m
v_rmse_m
v_max_abs_error_m
Due Dataset di validazione pubblicati
I due Dataset derivati pubblicati nella Session.
Dataset dei residui nella Session
Il Dataset tutorial.terrain_fit_residuals visto nella Session.

7. Risultati numerici attesi

Con il Dataset deterministico del Tutorial 01 il risultato globale di accettazione è:

QuantitàValore atteso
Osservazioni891
Profili11
Bias≈ 5.02×10−13 m
MAE≈ 0.465583403 m
RMSE≈ 0.575562597 m
Errore assoluto massimo≈ 1.994135503 m
R²≈ 0.998712481

Lo script confronta inoltre RMSE e R² ricalcolati con i valori conservati nei metadata del Dataset fitted; una discrepanza superiore alla tolleranza prevista interrompe il run.

PASS TERRAIN_NUMERIC_VALIDATION ...

8. Metadata di validazione

Il Dataset dei residui registra esplicitamente la catena di validazione, inclusi:

validation.kind=fit_residual_analysis
validation.observed_dataset_id=terrain_profiles_raw
validation.model_dataset_id=tutorial.terrain_surface_fit
validation.numeric_backend=NUMERIC_API_v1
validation.data_access=TABLE_STREAM_API_v3
validation.matching=exact_xy
validation.global_bias_m=...
validation.global_mae_m=...
validation.global_rmse_m=...
validation.global_max_abs_error_m=...
validation.global_r2=...
Metadata del Dataset dei residui
Metadata di validazione del Dataset residui: backend numerico, accesso dati, matching e metriche globali.

9. Continuare il workflow in una nuova Session

Il tutorial è stato verificato anche esportando tutorial.terrain_surface_fit dalla Session precedente e importandolo in una nuova Session. Metadata e Notes associati al Dataset consentono al workflow downstream di continuare senza ricostruire il fit.

Dataset fitted importato in una nuova Session
Il Dataset fitted importato dalla Session del Tutorial 01.
Metadata conservati nel Dataset fitted importato
I metadata scientifici necessari al downstream restano associati al Dataset importato.

10. Stage 2 — grafici diagnostici

Registra 02_plot_fit_validation_v3.py, ad esempio come terrain_validation_plots, e configura:

primary -> tutorial.terrain_fit_residuals
summary -> tutorial.terrain_fit_profile_statistics
Script dei grafici nel Python Script Workspace
Lo script che costruisce i grafici diagnostici tramite Plot Dataset v3.

Il primo PlotSpec è multi-panel: il pannello superiore sovrappone profili osservati e fitted; quello inferiore mostra i residui per famiglia con una linea di riferimento a zero. Il secondo PlotSpec mostra RMSE in funzione della posizione Y del profilo.

11. Errori intenzionali e contratti delle API

Le schermate di errore sono parte del tutorial: documentano che il framework rifiuta configurazioni incomplete o non conformi invece di indovinare implicitamente l'intento.

Analysis Source model mancante

Analysis Source model mancante
Configurazione incompleta: è presente il Dataset osservato ma manca la sorgente model.
Errore atteso per sorgente model mancante
Errore atteso: lo script rifiuta il contratto incompleto.

Alias summary errato

Alias source2 errato al posto di summary
Nel secondo script l'alias richiesto è summary; source2 non soddisfa il contratto registrato.
Errore atteso per alias summary mancante
Il rifiuto esplicito conferma che gli Analysis Source ID fanno parte del contratto dello script.

Validazione PlotSpec

Durante la prova una prima versione del tutorial usava axis="y" nella reference line. Il validatore ha correttamente rifiutato il valore: per questa annotazione sono validi x, left e right. La versione corrente usa axis="left".

Errore di validazione PlotSpec per axis y
Errore della prima prova, conservato perché documenta il contratto pubblico del PlotSpec.

12. Risultati grafici

Grafico finale osservati fitted e residui
Plot Dataset finale a due pannelli: profili osservati/fitted e residui.
Grafico RMSE per profilo
RMSE per famiglia di profilo in funzione della posizione Y.
PASS TERRAIN_VALIDATION_PLOTS ...

13. Checklist di riproduzione

  1. Completa il Tutorial 01 — Terrain 3D, oppure importa in una nuova Session il Dataset fitted conservandone Metadata e Notes.
  2. Verifica la presenza di terrain_profiles_raw e tutorial.terrain_surface_fit.
  3. Registra 01_validate_fit_numeric_api.py.
  4. Configura esattamente primary e model.
  5. Esegui e verifica i due Dataset pubblicati e la linea PASS TERRAIN_NUMERIC_VALIDATION.
  6. Controlla i metadata di tutorial.terrain_fit_residuals.
  7. Registra 02_plot_fit_validation_v3.py.
  8. Configura esattamente primary e summary.
  9. Esegui e verifica i due grafici persistenti e la linea PASS TERRAIN_VALIDATION_PLOTS.

14. Download

Il pacchetto del Tutorial 02 contiene solo i materiali propri di questa fase. Dataset sorgente e metadata restano nel Tutorial 01 e non vengono duplicati.

Pacchetto Tutorial 02 (.zip) 01 · Validazione numerica e pubblicazione 02 · Grafici diagnostici Plot Dataset v3 Risultati numerici attesi Changelog del pacchetto sorgente README materiali web SHA-256 dei materiali del Tutorial 02