Esportazione dei dati: il formato .h5dcnvs

La regola fondamentale #

Tutto ciò che costituisce un metadato relativo a una misura, incluse le unità, l'etichetta, la variabile a cui corrisponde e l'osservazione a cui appartiene, è un attributo HDF5. Gli unici due tipi di dataset HDF5 presenti nell'intero file sono l'array values di una serie e il singolo value di uno scalare. Una volta compreso questo principio, esplorare l'albero diventa prevedibile: gli attributi indicano che cos'è un elemento, mentre i dataset forniscono i numeri.

La struttura in sintesi #

/                                        (gruppo radice, attributi a livello di file, vedi sotto)
├─ observations_summary                  (una rappresentazione JSON dell'intero albero, per praticità)
├─ catalog/
│   ├─ quantity_kinds/
│   │   └─ temperature/                  (un gruppo per ogni tipo di grandezza, denominato in base alla relativa chiave)
│   └─ variables/
│       └─ temperature/                  (un gruppo per ogni variabile, denominato in base alla relativa chiave)
└─ observations/
    └─ obs_000001/
        ├─ sample/                       (presente solo se l'osservazione ha un campione)
        ├─ scalars/
        │   └─ contextual_furnace_setpoint/
        │       └─ value                 (Dataset)
        ├─ series/
        │   ├─ index_time/
        │   │   └─ values                (Dataset)
        │   └─ dependent_temperature/
        │       └─ values                (Dataset)
        └─ series_groups/                (presente solo quando le serie condividono un indice comune)
            └─ group_000001/

I nomi dei gruppi e dei campi sono stabili, deterministici e leggibili. Esportando due volte la stessa osservazione si ottiene lo stesso albero e il percorso HDF5 di un campo (ad esempio observations/obs_000001/series/dependent_temperature) ne costituisce anche la posizione in forma leggibile.

Attributi radice #

Alcuni attributi nel gruppo radice del file descrivono l'esportazione nel suo complesso:

Catalogo: variabili e tipi di grandezza #

catalog/quantity_kinds/<key>/ e catalog/variables/<key>/ contengono i metadati condivisi a cui fanno riferimento i campi scalari e serie, così vengono scritti una sola volta anche se più campi utilizzano la stessa variabile. Un gruppo relativo a un tipo di grandezza ha questo aspetto:

catalog/quantity_kinds/temperature/
├─ @key             = "temperature"
├─ @label           = "Temperature"
├─ @canonical_units = "K"
├─ @units           = "K"          (duplicato, in stile CF, vedi sotto)
├─ @symbol          = "T"
└─ @common_units    = ["degC", "degF", "K"]

Un gruppo relativo a una variabile è simile e contiene inoltre @quantity_kind_key, ovvero la stringa da cercare in catalog/quantity_kinds/ per risolverne le unità e la definizione.

L'osservazione #

Il gruppo observations/obs_000001/ rappresenta l'osservazione esportata, con obs_type, title, technique, notes, ingestion_status e created_at come attributi, oltre a un sottogruppo sample/ se è associato un campione.

Al suo interno, ogni campo scalare e serie ha un proprio gruppo in scalars/ o series/, denominato mediante uno slug leggibile (ad esempio contextual_furnace_setpoint, dependent_temperature, index_time). Ogni gruppo di campi utilizza lo stesso vocabolario di attributi, presentato affiancato in due stili parzialmente sovrapposti:

I nomi in stile CF (units, long_name, standard_name) esistono perché sono ampiamente riconosciuti dagli strumenti scientifici generici per HDF5/NetCDF, permettendo di ottenere unità ed etichette leggibili senza alcun plugin specifico per DataCNVS. I nomi in stile DataCNVS servono per ricerche univoche e facilmente gestibili dal codice. Entrambi descrivono lo stesso campo; usa quello più adatto al tuo strumento.

I campi serie contengono inoltre series_kind ("series" o "index"), length e, se la serie condivide un indice comune con altre (ad esempio un asse temporale condiviso da più curve dipendenti), series_group_ref, che punta a una voce in series_groups/ (vedi la sezione successiva).

Gruppi di serie #

Quando due o più serie dell'osservazione condividono un indice comune (nella maggior parte dei casi, un asse temporale o di posizione con diverse misure dipendenti rispetto a esso), vengono collegate tramite observations/obs_000001/series_groups/group_NNNNNN/. Questo gruppo non duplica alcun dato; elenca semplicemente i percorsi dei membri e, solo per agevolarne l'esplorazione, fornisce collegamenti simbolici HDF5 ai dataset values effettivi, in modo che un visualizzatore dell'albero mostri visivamente la relazione. Il codice deve sempre risolvere la relazione dall'attributo series_group_ref, non seguendo i collegamenti.

Una serie priva dell'attributo series_group_ref non ha semplicemente alcun indice condiviso, quindi considera i suoi valori ordinati in base alla posizione delle righe (punto 0, punto 1, punto 2, …).

observations_summary #

Il dataset observations_summary a livello radice contiene le stesse informazioni dell'intero albero, riformulate in un unico documento JSON che include l'osservazione, i relativi campi e le voci del catalogo con i rispettivi percorsi HDF5. È una soluzione pratica per gli script che preferiscono analizzare un unico blocco JSON anziché attraversare l'albero dei gruppi ed è garantito che sia una rappresentazione rigorosamente fedele di quanto già indicato dagli attributi (mai una fonte di informazioni aggiuntive).