Exporter des données : le format .h5dcnvs

La règle fondamentale #

Toute métadonnée relative à une mesure, notamment ses unités, son libellé, la variable concernée et l’observation à laquelle elle appartient, est un attribut HDF5. Les deux seuls types de jeux de données HDF5 présents dans l’ensemble du fichier sont le tableau values d’une série et la valeur unique value d’un scalaire. Une fois ce principe compris, l’arborescence devient prévisible : les attributs indiquent ce qu’est un élément, tandis que les jeux de données fournissent les nombres.

Vue d’ensemble de la structure #

/                                        (groupe racine, attributs au niveau du fichier, voir ci-dessous)
├─ observations_summary                  (miroir JSON de toute l’arborescence, pour plus de commodité)
├─ catalog/
│   ├─ quantity_kinds/
│   │   └─ temperature/                  (un groupe par type de grandeur, nommé d’après sa clé)
│   └─ variables/
│       └─ temperature/                  (un groupe par variable, nommé d’après sa clé)
└─ observations/
    └─ obs_000001/
        ├─ sample/                       (présent uniquement si l’observation comporte un échantillon)
        ├─ scalars/
        │   └─ contextual_furnace_setpoint/
        │       └─ value                 (Jeu de données)
        ├─ series/
        │   ├─ index_time/
        │   │   └─ values                (Jeu de données)
        │   └─ dependent_temperature/
        │       └─ values                (Jeu de données)
        └─ series_groups/                (présent uniquement lorsque des séries partagent un index commun)
            └─ group_000001/

Les noms des groupes et des champs sont stables, déterministes et lisibles. Une même observation exportée deux fois produit la même arborescence, et le chemin HDF5 d’un champ (par exemple observations/obs_000001/series/dependent_temperature) constitue également son emplacement en langage clair.

Attributs racine #

Quelques attributs du groupe racine du fichier décrivent l’export dans son ensemble :

Catalogue : variables et types de grandeur #

catalog/quantity_kinds/<key>/ et catalog/variables/<key>/ contiennent les métadonnées partagées auxquelles les champs scalaires et de séries font référence. Elles ne sont ainsi écrites qu’une seule fois, même si plusieurs champs utilisent la même variable. Un groupe de types de grandeur se présente comme suit :

catalog/quantity_kinds/temperature/
├─ @key             = "temperature"
├─ @label           = "Temperature"
├─ @canonical_units = "K"
├─ @units           = "K"          (doublon, au format CF, voir ci-dessous)
├─ @symbol          = "T"
└─ @common_units    = ["degC", "degF", "K"]

Un groupe de variables est similaire et comporte en plus @quantity_kind_key, la chaîne à rechercher dans catalog/quantity_kinds/ pour déterminer ses unités et sa définition.

L’observation #

Le groupe observations/obs_000001/ correspond à l’observation exportée. Il comporte obs_type, title, technique, notes, ingestion_status et created_at comme attributs, ainsi qu’un sous-groupe sample/ si un échantillon y est associé.

À l’intérieur, chaque champ scalaire ou de série possède son propre groupe sous scalars/ ou series/, nommé à l’aide d’un slug lisible (par exemple contextual_furnace_setpoint, dependent_temperature, index_time). Tous les groupes de champs utilisent le même vocabulaire d’attributs, selon deux styles qui se recoupent et sont présentés côte à côte :

Les noms au format CF (units, long_name, standard_name) existent parce qu’ils sont largement reconnus par les outils scientifiques HDF5/NetCDF génériques. Vous obtenez ainsi des unités et des libellés lisibles sans plugin propre à DataCNVS. Les noms au format DataCNVS permettent quant à eux des recherches non ambiguës et adaptées au code. Les deux styles décrivent le même champ ; utilisez celui qui convient à votre outil.

Les champs de séries comportent également series_kind ("series" ou "index"), length et, si la série partage un index commun avec d’autres (par exemple un axe temporel commun à plusieurs courbes dépendantes), series_group_ref, qui pointe vers une entrée de series_groups/ (voir la section suivante).

Groupes de séries #

Lorsque deux séries ou plus d’une observation partagent un index commun (le plus souvent, un axe temporel ou de position avec plusieurs mesures dépendantes correspondantes), elles sont reliées au moyen de observations/obs_000001/series_groups/group_NNNNNN/. Ce groupe ne duplique aucune donnée ; il répertorie simplement les chemins des membres et, uniquement pour faciliter la navigation, fournit des liens symboliques HDF5 vers les véritables jeux de données values, afin qu’un navigateur d’arborescence affiche visuellement la relation. Le code doit toujours déterminer la relation à partir de l’attribut series_group_ref, et non en parcourant les liens.

Une série dépourvue d’attribut series_group_ref n’a tout simplement pas d’index partagé ; considérez donc que ses valeurs sont ordonnées selon la position des lignes (point 0, point 1, point 2, …).

observations_summary #

Le jeu de données racine observations_summary contient les mêmes informations que l’ensemble de l’arborescence, reformulées sous la forme d’un document JSON unique réunissant l’observation, ses champs et les entrées du catalogue avec leurs chemins HDF5. Il facilite les scripts qui préfèrent analyser un seul bloc JSON plutôt que parcourir l’arborescence des groupes, et constitue nécessairement un miroir strict de ce qu’indiquent déjà les attributs (jamais une source d’informations supplémentaires).