Daten exportieren: das .h5dcnvs-Format

Die Grundregel #

Alle Metadaten zu einer Messung – einschließlich ihrer Einheiten, ihres Labels, der zugehörigen Variable und der zugehörigen Beobachtung – werden als HDF5-Attribut gespeichert. Die einzigen beiden Arten von HDF5-Datensätzen in der gesamten Datei sind das values-Array einer Reihe und der einzelne value-Wert eines Skalars. Sobald Sie dies wissen, lässt sich der Baum vorhersehbar durchsuchen: Attribute erklären, worum es sich handelt, Datensätze liefern die Zahlen.

Struktur auf einen Blick #

/                                        (Stammgruppe, Attribute auf Dateiebene, siehe unten)
├─ observations_summary                  (eine JSON-Abbildung des gesamten Baums zur einfacheren Verwendung)
├─ catalog/
│   ├─ quantity_kinds/
│   │   └─ temperature/                  (eine Gruppe pro Größenart, benannt nach ihrem Schlüssel)
│   └─ variables/
│       └─ temperature/                  (eine Gruppe pro Variable, benannt nach ihrem Schlüssel)
└─ observations/
    └─ obs_000001/
        ├─ sample/                       (nur vorhanden, wenn die Beobachtung eine Probe hat)
        ├─ scalars/
        │   └─ contextual_furnace_setpoint/
        │       └─ value                 (Datensatz)
        ├─ series/
        │   ├─ index_time/
        │   │   └─ values                (Datensatz)
        │   └─ dependent_temperature/
        │       └─ values                (Datensatz)
        └─ series_groups/                (nur vorhanden, wenn Reihen einen gemeinsamen Index verwenden)
            └─ group_000001/

Gruppen- und Feldnamen sind stabil, deterministisch und menschenlesbar. Wird dieselbe Beobachtung zweimal exportiert, entsteht derselbe Baum, und der HDF5-Pfad eines Feldes (z. B. observations/obs_000001/series/dependent_temperature) dient zugleich als Klartextangabe seiner Position.

Stammattribute #

Einige Attribute in der Stammgruppe der Datei beschreiben den Export als Ganzes:

Katalog: Variablen und Größenarten #

catalog/quantity_kinds/<key>/ und catalog/variables/<key>/ enthalten die gemeinsamen Metadaten, auf die Skalar- und Reihenfelder zurückverweisen. So werden sie nur einmal geschrieben, selbst wenn mehrere Felder dieselbe Variable verwenden. Eine Größenartgruppe sieht wie folgt aus:

catalog/quantity_kinds/temperature/
├─ @key             = "temperature"
├─ @label           = "Temperature"
├─ @canonical_units = "K"
├─ @units           = "K"          (Duplikat im CF-Stil, siehe unten)
├─ @symbol          = "T"
└─ @common_units    = ["degC", "degF", "K"]

Eine Variablengruppe ist ähnlich aufgebaut und enthält zusätzlich @quantity_kind_key. Dies ist die Zeichenfolge, die Sie in catalog/quantity_kinds/ nachschlagen, um ihre Einheiten und Definition zu ermitteln.

Die Beobachtung #

Die Gruppe observations/obs_000001/ enthält die von Ihnen exportierte Beobachtung mit obs_type, title, technique, notes, ingestion_status und created_at als Attributen sowie einer Untergruppe sample/, sofern eine Probe zugeordnet ist.

Darin erhält jedes Skalar- und Reihenfeld eine eigene Gruppe unter scalars/ beziehungsweise series/, die nach einem lesbaren Slug benannt ist (z. B. contextual_furnace_setpoint, dependent_temperature, index_time). Jede Feldgruppe verwendet parallel dasselbe Attributvokabular in zwei sich überschneidenden Stilen:

Die Namen im CF-Stil (units, long_name, standard_name) sind vorhanden, weil sie von generischen wissenschaftlichen HDF5-/NetCDF-Werkzeugen weithin erkannt werden. Dadurch erhalten Sie auch ohne DataCNVS-spezifisches Plugin lesbare Einheiten und Labels. Die Namen im DataCNVS-Stil dienen eindeutigen, codefreundlichen Nachschlagevorgängen. Beide beschreiben dasselbe Feld; verwenden Sie den Stil, der zu Ihrem Werkzeug passt.

Reihenfelder enthalten zusätzlich series_kind ("series" oder "index"), length und – falls die Reihe einen gemeinsamen Index mit anderen Reihen verwendet (z. B. eine von mehreren abhängigen Kurven gemeinsam genutzte Zeitachse) – series_group_ref mit einem Verweis auf einen Eintrag unter series_groups/ (siehe nächsten Abschnitt).

Reihengruppen #

Wenn zwei oder mehr Reihen in der Beobachtung einen gemeinsamen Index verwenden (meist eine Zeit- oder Positionsachse mit mehreren daran aufgetragenen abhängigen Messungen), werden sie über observations/obs_000001/series_groups/group_NNNNNN/ verknüpft. Diese Gruppe dupliziert keine Daten. Sie führt lediglich die Pfade der Mitglieder auf und stellt – ausschließlich zum bequemeren Durchsuchen – HDF5-Softlinks zu den tatsächlichen values-Datensätzen bereit, sodass ein Baumbrowser die Beziehung visuell darstellt. Code sollte die Beziehung immer anhand des Attributs series_group_ref und nicht durch das Verfolgen von Links auflösen.

Eine Reihe ohne Attribut series_group_ref hat schlicht keinen gemeinsamen Index. Behandeln Sie ihre Werte daher als nach Zeilenposition geordnet (Punkt 0, Punkt 1, Punkt 2, …).

observations_summary #

Der Datensatz observations_summary auf Stammebene enthält dieselben Informationen wie der gesamte Baum, erneut dargestellt als ein JSON-Dokument mit der Beobachtung, ihren Feldern und den Katalogeinträgen samt ihrer HDF5-Pfade. Dies erleichtert Skripten die Verarbeitung, wenn sie lieber einen einzelnen JSON-Datenblock parsen, als den Gruppenbaum zu durchlaufen. Dabei handelt es sich garantiert um eine exakte Abbildung dessen, was bereits in den Attributen steht, und niemals um eine Quelle zusätzlicher Informationen.