Compartilhar via

Início Rápido: Introdução aos cubos de dados no Microsoft Planetary Computer Pro

Pré-requisitos

Configurar a fonte de ingestão

Antes de começar a ingerir dados de cubo de dados, você precisará configurar uma Fonte de Ingestão, que servirá como suas credenciais para acessar a conta de Armazenamento de Blobs em que seus ativos e Itens STAC são armazenados. Você pode configurar uma fonte de ingestão usando Identidade Gerenciada ou Token SAS.

Criar uma coleção de cubos de dados

Depois que a Fonte de Ingestão for configurada, você poderá criar uma Coleção para os ativos do cubo de dados. As etapas para criar uma coleção podem ser seguidas em Criar uma coleção STAC com o Microsoft Planetary Computer Pro usando Python.

Ingerir ativos de cubo de dados

O início do processo de ingestão para dados de cubo de dados e outros tipos de dados pode ser seguido na Visão Geral de Ingestão. Conforme descrito na Visão Geral do Cubo de Dados, no entanto, a ingestão é a etapa no tratamento de dados do Planetry Computer Pro que difere para esses tipos de arquivo. Embora dados GRIB2 e itens STAC associados sejam ingeridos da mesma forma que qualquer outro arquivo de raster bidimensional, os ativos NetCDF e HDF5 passam por mais enriquecimento de dados. A geração de Manifestos Kerchunk está documentada na Visão Geral do Cubo de Dados, mas o importante é observar que os ativos kerchunk serão adicionados ao contêiner de Armazenamento de Blobs junto com os ativos originais e um campo adicional cube:variables será adicionado ao JSON do Item STAC. Isso é importante ao renderizar esses tipos de dados no Planetry Computer Pro Explorer.

Configurar uma coleção de cubos de dados

A configuração da coleção de cubos de dados é outra etapa que será ligeiramente diferente da de outros tipos de dados. Você pode seguir as etapas descritas em Configurar uma coleção com a interface web do Microsoft Planetary Computer Pro para configurar sua coleção de cubos de dados, mas precisará estar ciente das seguintes diferenças ao criar sua Configuração de Renderização:

Configuração de renderização para ativos NetCDF e HDF5

Lembrando que um argumento de Configuração de Renderização padrão no formato JSON tem esta aparência:

[
  {
    "id": "prK1950-06-30",
    "name": "prK1950-06-30",
    "type": "raster-tile",
    "options": "assets=pr-kerchunk&subdataset_name=pr&rescale=0,0.01&colormap_name=viridis&datetime=1950-06-30",
    "minZoom": 1
  }
]

O campo options é onde você desejará utilizar o ativo Kerchunk otimizado para nuvem, ao invés do ativo original que está listado no Item STAC. Você também precisará incluir o subdataset_name argumento, que é o nome da variável que você deseja renderizar.

Configuração de renderização para ativos GRIB2

O options campo para a Configuração de Renderização de ativos GRIB2 é semelhante ao exemplo anterior, mas você não precisará incluir o subdataset_name argumento. Isso ocorre porque os dados GRIB2 já estão estruturados e referenciados de forma ideal por meio de seus arquivos indexados. O assets argumento, nesse caso, representa a faixa ou a camada de raster 2D que você deseja renderizar. Veja abaixo um exemplo de uma configuração de renderização GRIB2:

[ 
 {
    "id": "render-config-1",
    "name": "Mean Zero-Crossing Wave Period",
    "description": "A sample render configuration. Update `options` below.",
    "type": "raster-tile",
    "options": "assets=data&subdataset_bands=1&colormap_name=winter&rescale=0,10",
    "minZoom": 1
 }
]

Configuração de renderização para ativos Zarr

O options campo para ativos Zarr é semelhante ao NetCDF e HDF5, mas há dois requisitos importantes:

  1. Selecione uma única fatia de tempo para renderização usando sel=time=....
  2. Reduza os dados a uma saída 2D antes da renderização.

Se dimensões adicionais não forem recolhidas, a renderização poderá falhar com erros como Source data must be 1 band.

Você pode ler mais sobre o sel parâmetro em Xarray DataArray.sel. Veja a seguir uma configuração mínima de renderização Zarr para uma única etapa temporal e uma saída 2D:

[
    {
        "id": "era5-zarr-single-time",
        "name": "ERA5 single timestep",
        "type": "raster-tile",
        "options": "assets=data&subdataset_name=precipitation_amount_1hour_Accumulation&sel=time=2024-01-01&sel_method=nearest&colormap_name=viridis&rescale=0,0.01",
        "minZoom": 12
    }
]

Visualizar ativos de cubo de dados no Explorer

Depois que os ativos do cubo de dados forem ingeridos e configurados, você poderá visualizá-los no Explorador do Computador Planetário Pro. Um guia passo a passo para usar o Explorer pode ser seguido no Início Rápido: Usar o Explorer no Microsoft Planetary Computer Pro.

Embora o Computador Planetário Pro da Microsoft inclua um recurso de mosaico que pode ser usado para ver alguns ativos de cubos de dados, há algumas ressalvas a serem observadas de cada tipo de dado compatível.

Visualização de NetCDF e HDF5

Nem todos os conjuntos de dados NetCDF que podem ser ingeridos no Microsoft Planetary Computer são compatíveis com visualização em bloco do Computador Planetário Pro. Um conjunto de dados deve ter eixos X e Y, coordenadas de latitude e longitude e dimensões espaciais e limites a serem visualizados. Por exemplo, um conjunto de dados em que latitude e longitude são variáveis, mas não coordenadas, não é compatível com o tiler do Planetary Computer Pro.

Antes de tentar visualizar seu conjunto de dados NetCDF ou HDF5, você pode usar o seguinte para verificar se ele atende aos requisitos.

  1. Instalar as dependências necessárias

    pip install xarray[io] rioxarray cf_xarray

  2. Execute a seguinte função:

    import xarray as xr
import cf_xarray
import rioxarray

def is_dataset_visualizable(ds: xr.Dataset):
    """
    Test if the dataset is compatible with the Planetary Computer tiler API.
    Raises an informative error if the dataset is not compatible.
    """
    if not ds.cf.axes:
        raise ValueError("Dataset does not have CF axes")
    if not ds.cf.coordinates:
        raise ValueError("Dataset does not have CF coordinates")
    if not {"X", "Y"} <= ds.cf.axes.keys():
        raise ValueError(f"Dataset must have CF X and Y axes, found: {ds.cf.axes.keys()}")

    if not {"latitude", "longitude"} <= ds.cf.coordinates.keys():
        raise ValueError("Dataset must have CF latitude and longitude coordinates, "
                         f"actual: {ds.cf.coordinates.keys()}")

    if ds.rio.x_dim is None or ds.rio.y_dim is None:
        raise ValueError("Dataset does not have rioxarray spatial dimensions")

    if ds.rio.bounds() is None:
        raise ValueError("Dataset does not have rioxarray bounds")

    left, bottom, right, top = ds.rio.bounds()
    if left < -180 or right > 180 or bottom < -90 or top > 90:
        raise ValueError("Dataset bounds are not valid; they must be within [-180, 180] and [-90, 90]")

    if ds.rio.resolution() is None:
        raise ValueError("Dataset does not have rioxarray resolution")

    if ds.rio.transform() is None:
        raise ValueError("Dataset does not have rioxarray transform")

    print("✅ Dataset is compatible with the Planetary Computer tiler API.")

Visualização de GRIB2

Os ativos GRIB2 que foram ingeridos no Microsoft Planetary Computer Pro podem ser visualizados no Explorer, desde que tenham um arquivo Index (.idx) associado armazenado no mesmo contêiner de Armazenamento de Blobs. O arquivo Index é gerado durante o processamento e é necessário para acesso otimizado e renderização de dados GRIB2.

Visualização do Zarr

Os ativos Zarr ingeridos no Microsoft Planetary Computer Pro podem ser visualizados no Explorer, desde que a configuração de renderização especifique qual variável e fatia de tempo renderizar, utilizando o parâmetro sel no campo options. A falha ao fazer isso resultará na tentativa do Explorer de renderizar todas as variáveis e fatias de tempo do repositório Zarr de uma só vez, o que fará com que o Explorer falhe.

O tamanho do repositório Zarr e os blocos espaciais também afetarão o desempenho. Para uma performance ideal do gerenciador de blocos, o ideal é manter o tamanho total de um armazenamento Zarr abaixo de 2 GB e cada bloco com menos de 100 MB.

Limitações de visualização do Zarr e problemas conhecidos

Comportamento do controle deslizante de tempo (limitação conhecida)

Observação

O comportamento do controle deslizante de tempo para Zarr atualmente é limitado. O controle deslizante de tempo do Explorer só aparece quando uma dimensão temporal é detectada corretamente durante a ingestão.

Mesmo quando os ativos Zarr contêm valores de tempo, a ingestão pode falhar ao detectar metadados temporais para alguns conjuntos de dados. Nesses casos, o slider de tempo não será renderizado e você deve visualizar uma etapa de tempo por vez na configuração de renderização (por exemplo, sel=time=2024-01-01).

Para habilitar o comportamento consciente do tempo, os metadados do STAC devem incluir uma dimensão temporal em cube:dimensions com:

  • type: temporal
  • extent
  • step

Para dados de origem do Zarr, siga as convenções de tempo CF sempre que possível, por exemplo:

  • standard_name="time"
  • axis="T"

Essas convenções são necessárias para uma interpretação consistente de metadados, mas devido às limitações atuais, nem sempre são suficientes para garantir o suporte ao controle deslizante de tempo para cada conjunto de dados Zarr.

Notas de Kerchunk

O Kerchunk pode melhorar o desempenho para padrões de acesso multidimensional, mas não resolve problemas do deslizador temporal quando dimensões temporais não foram detectadas durante a ingestão.

Alguns conjuntos de dados zarr também podem falhar durante o processamento de índice com erros como Index must be monotonic increasing or decreasing.

Roteiro e suporte futuro

O suporte atual e planejado é:

  • Zarr v2: com suporte hoje
  • Zarr v3: ainda sem suporte, planejado para suporte futuro
  • Visualização multitemporal de Zarr e manipulação temporal: parcial hoje, com melhorias contínuas planejadas

Controle deslizante de tempo para visualização de cubo de dados

Se os ativos do cubo de dados tiverem um componente temporal, você poderá usar o controle deslizante de tempo no Explorer para visualizar as alterações ao longo do tempo. O controle deslizante de tempo será exibido automaticamente se os Itens do STAC contiver ativos com uma dimensão time com um campo extent e step.

Observação

Para ativos Zarr, consulte limitações de visualização do Zarr e problemas conhecidos para restrições atuais do controle deslizante de tempo e padrões necessários de configuração de renderização.

Conteúdo relacionado

  • Last updated on