Exportar dados: o formato .h5dcnvs

A regra fundamental #

Tudo o que constitua metadados sobre uma medição, incluindo as unidades, a etiqueta, a variável a que corresponde e a observação a que pertence, é um atributo HDF5. Os únicos dois tipos de conjunto de dados HDF5 em todo o ficheiro são a matriz values de uma série e o value único de um escalar. Depois de compreender isto, é fácil prever como percorrer a árvore: os atributos indicam o que algo é e os conjuntos de dados fornecem os números.

Visão geral da estrutura #

/                                        (grupo raiz, atributos ao nível do ficheiro, ver abaixo)
├─ observations_summary                  (uma representação JSON de toda a árvore, para maior comodidade)
├─ catalog/
│   ├─ quantity_kinds/
│   │   └─ temperature/                  (um grupo por tipo de grandeza, com o nome da respetiva chave)
│   └─ variables/
│       └─ temperature/                  (um grupo por variável, com o nome da respetiva chave)
└─ observations/
    └─ obs_000001/
        ├─ sample/                       (presente apenas se a observação tiver uma amostra)
        ├─ scalars/
        │   └─ contextual_furnace_setpoint/
        │       └─ value                 (Conjunto de dados)
        ├─ series/
        │   ├─ index_time/
        │   │   └─ values                (Conjunto de dados)
        │   └─ dependent_temperature/
        │       └─ values                (Conjunto de dados)
        └─ series_groups/                (presente apenas quando as séries partilham um índice comum)
            └─ group_000001/

Os nomes dos grupos e dos campos são estáveis, determinísticos e legíveis. A mesma observação exportada duas vezes produz a mesma árvore, e o caminho HDF5 de um campo (por exemplo, observations/obs_000001/series/dependent_temperature) funciona também como a sua localização em linguagem corrente.

Atributos da raiz #

Um pequeno conjunto de atributos no grupo raiz do ficheiro descreve a exportação como um todo:

Catálogo: variáveis e tipos de grandeza #

catalog/quantity_kinds/<key>/ e catalog/variables/<key>/ contêm os metadados partilhados a que os campos escalares e de série fazem referência, pelo que são escritos apenas uma vez, mesmo que vários campos utilizem a mesma variável. Um grupo de tipo de grandeza tem o seguinte aspeto:

catalog/quantity_kinds/temperature/
├─ @key             = "temperature"
├─ @label           = "Temperature"
├─ @canonical_units = "K"
├─ @units           = "K"          (duplicado, ao estilo CF, ver abaixo)
├─ @symbol          = "T"
└─ @common_units    = ["degC", "degF", "K"]

Um grupo de variável é semelhante e contém também @quantity_kind_key, que é a cadeia que deve procurar em catalog/quantity_kinds/ para resolver as respetivas unidades e definição.

A observação #

O grupo observations/obs_000001/ corresponde à observação que exportou, com obs_type, title, technique, notes, ingestion_status e created_at como atributos, além de um subgrupo sample/ caso esteja associada uma amostra.

No interior, cada campo escalar e de série tem o seu próprio grupo em scalars/ ou series/, com o nome de um slug legível (por exemplo, contextual_furnace_setpoint, dependent_temperature, index_time). Cada grupo de campos contém o mesmo vocabulário de atributos em dois estilos sobrepostos, apresentados lado a lado:

Os nomes ao estilo CF (units, long_name, standard_name) existem porque são amplamente reconhecidos pelas ferramentas científicas HDF5/NetCDF genéricas, permitindo obter unidades e etiquetas legíveis sem qualquer plug-in específico do DataCNVS. Os nomes ao estilo DataCNVS existem para permitir consultas inequívocas e fáceis de utilizar em código. Ambos descrevem o mesmo campo; utilize o que melhor se adequar à sua ferramenta.

Os campos de série contêm ainda series_kind ("series" ou "index"), length e, se a série partilhar um índice comum com outras (por exemplo, um eixo temporal partilhado por várias curvas dependentes), series_group_ref, que aponta para uma entrada series_groups/ (consulte a secção seguinte).

Grupos de séries #

Quando duas ou mais séries da observação partilham um índice comum (na maioria dos casos, um eixo temporal ou de posição com várias medições dependentes representadas em função desse eixo), são associadas através de observations/obs_000001/series_groups/group_NNNNNN/. Este grupo não duplica quaisquer dados; limita-se a enumerar os caminhos dos membros e, apenas para facilitar a navegação, disponibiliza ligações simbólicas HDF5 para os verdadeiros conjuntos de dados values, para que um visualizador em árvore mostre visualmente a relação. O código deve resolver sempre a relação a partir do atributo series_group_ref, e não percorrendo as ligações.

Uma série sem o atributo series_group_ref simplesmente não tem um índice partilhado; por isso, considere os respetivos valores ordenados pela posição da linha (ponto 0, ponto 1, ponto 2, …).

observations_summary #

O conjunto de dados observations_summary ao nível da raiz contém as mesmas informações que toda a árvore, reformuladas num único documento JSON que inclui a observação, os respetivos campos e as entradas do catálogo com os seus caminhos HDF5. É uma comodidade para scripts que prefiram analisar um único bloco JSON em vez de percorrer a árvore de grupos, e é garantidamente uma representação estrita do que os atributos já indicam (nunca uma fonte de informações adicionais).