Exportação de dados: o formato .h5dcnvs

A regra principal #

Tudo o que for metadado sobre uma medição, incluindo suas unidades, seu rótulo, a variável à qual corresponde e a observação à qual pertence, é um atributo HDF5. Os únicos dois tipos de conjunto de dados HDF5 em todo o arquivo são a matriz values de uma série e o único value de um escalar. Depois que você entende isso, navegar pela árvore se torna previsível: os atributos informam o que algo é, e os conjuntos de dados fornecem os números.

Visão geral da estrutura #

/                                        (grupo raiz, atributos no nível do arquivo; veja abaixo)
├─ observations_summary                  (um espelho em JSON de toda a árvore, por conveniência)
├─ catalog/
│   ├─ quantity_kinds/
│   │   └─ temperature/                  (um grupo por tipo de grandeza, nomeado por sua chave)
│   └─ variables/
│       └─ temperature/                  (um grupo por variável, nomeado por sua chave)
└─ observations/
    └─ obs_000001/
        ├─ sample/                       (presente somente 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 somente quando as séries compartilham um índice comum)
            └─ group_000001/

Os nomes de grupos e campos são estáveis, determinísticos e legíveis por pessoas. 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) também serve como sua localização em linguagem simples.

Atributos da raiz #

Alguns atributos no grupo raiz do arquivo descrevem 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 compartilhados aos quais os campos escalares e de série fazem referência. Assim, eles são gravados apenas uma vez, mesmo que vários campos usem a mesma variável. Um grupo de tipo de grandeza tem esta aparência:

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

Um grupo de variáveis é semelhante e também contém @quantity_kind_key, que é a string a ser consultada em catalog/quantity_kinds/ para resolver suas unidades e sua definição.

A observação #

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

Em seu interior, cada campo escalar e de série recebe seu próprio grupo em scalars/ ou series/, nomeado com 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, apresentado lado a lado em dois estilos sobrepostos:

Os nomes no estilo CF (units, long_name, standard_name) existem porque são amplamente reconhecidos por ferramentas científicas genéricas para HDF5/NetCDF. Assim, você obtém unidades e rótulos legíveis sem nenhum plugin específico do DataCNVS. Os nomes no estilo DataCNVS existem para permitir consultas inequívocas e fáceis de usar em código. Ambos descrevem o mesmo campo; use o que melhor se adaptar à sua ferramenta.

Os campos de série também contêm series_kind ("series" ou "index"), length e, se a série compartilhar um índice comum com outras (por exemplo, um eixo de tempo compartilhado por várias curvas dependentes), series_group_ref, que aponta para uma entrada em series_groups/ (veja a próxima seção).

Grupos de séries #

Quando duas ou mais séries na observação compartilham um índice comum (na maioria das vezes, um eixo de tempo ou posição com várias medições dependentes relacionadas a ele), elas são vinculadas por meio de observations/obs_000001/series_groups/group_NNNNNN/. Esse grupo não duplica nenhum dado; ele apenas lista os caminhos dos membros e, somente para facilitar a navegação, fornece links simbólicos HDF5 para os conjuntos de dados values reais, de modo que um navegador de árvore mostre visualmente a relação. O código deve sempre resolver essa relação a partir do atributo series_group_ref, e não percorrendo os links.

Uma série sem o atributo series_group_ref simplesmente não tem um índice compartilhado; portanto, trate seus valores como ordenados pela posição da linha (ponto 0, ponto 1, ponto 2, …).

observations_summary #

O conjunto de dados observations_summary no nível da raiz contém as mesmas informações que a árvore inteira, reapresentadas como um único documento JSON com a observação, seus campos e as entradas do catálogo com seus caminhos HDF5. É uma conveniência para scripts que prefiram analisar um único bloco JSON em vez de percorrer a árvore de grupos, e há a garantia de que ele seja um espelho fiel do que os atributos já informam (nunca uma fonte de informações adicionais).