Guia de início rápido: introdução aos cubos de dados no Microsoft Planetary Computer Pro

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa; Crie uma conta gratuitamente.
• Um recurso do Microsoft Planetary Computer Pro GeoCatalog
• Uma conta de Armazenamento de Blob criar uma conta de Armazenamento de Blob.
• Um contentor de armazenamento de blobs com ativos de cubo de dados (NetCDF, HDF5, GRIB2), itens STAC e catálogo STAC estático. Saiba como criar itens STAC.

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 Blob onde seus ativos e Itens STAC estão armazenados. Você pode configurar uma Fonte de Ingestão usando Identidade Gerenciada ou Token SAS.

Criar uma coleção de cubo de dados

Depois que a Fonte de ingestão estiver configurada, você poderá criar uma Coleção para seus ativos de 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 de dados de cubo de dados e outros tipos de dados pode ser seguido em Visão geral da ingestão. Conforme descrito em Visão geral do cubo de dados, no entanto, a ingestão é a etapa no tratamento de dados do Planetary Computer Pro que difere para esses tipos de arquivo. Enquanto os dados GRIB2 e os itens STAC associados são ingeridos como qualquer outro arquivo raster bidimensional, os ativos NetCDF e HDF5 passam por um enriquecimento de dados adicional. A geração de Manifestos Kerchunk está documentada em Visão Geral do Cubo de Dados, mas o que é importante observar é que os ativos Kerchunk serão adicionados ao contêiner de Armazenamento de Blob ao lado dos ativos originais e um campo adicional cube:variables será adicionado ao JSON do Item STAC. Isso é importante ao renderizar esses tipos de dados no Planetary Computer Pro Explorer.

Configurar uma coleção de cubo de dados

A configuração da sua coleção de cubos de dados é outra etapa que terá uma aparência ligeiramente diferente da de outros tipos de dados. Você pode seguir as etapas descritas em Configurar uma coleção com a interface da Web do Microsoft Planetary Computer Pro para configurar sua coleção de cubo 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 options campo é onde você vai querer utilizar o ativo Kerchunk otimizado para nuvem, em oposição ao ativo original 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 perfeitamente estruturados e referenciados por meio de seus arquivos de índice. O assets argumento, neste caso, representa a banda, ou camada raster 2D, que você deseja renderizar. Abaixo está 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 recursos Zarr

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

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

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

Pode ler mais sobre o sel parâmetro em Xarray DataArray.sel. Segue-se uma configuração mínima de renderização Zarr funcional para um único passo de tempo e 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 seus ativos de cubo de dados forem ingeridos e configurados, você poderá visualizá-los no Planetary Computer Pro Explorer. Um guia passo a passo para usar o Explorer pode ser seguido em Guia de início rápido: use o Explorer no Microsoft Planetary Computer Pro.

Embora o Microsoft Planetary Computer Pro inclua um tiler que pode ser usado para visualizar alguns ativos de cubos de dados, há algumas ressalvas a ter em conta relativamente a cada tipo de dado suportado.

Visualização do NetCDF e HDF5

Nem todos os conjuntos de dados NetCDF que podem ser incorporados no Microsoft Planetary Computer são compatíveis com o tiler de visualização do Planetary Computer Pro. Um conjunto de dados deve ter eixos X e Y, coordenadas de latitude e longitude, e dimensões e limites espaciais para ser visualizado. 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 o seu conjunto de dados NetCDF ou HDF5, pode usar o seguinte para verificar se cumpre os 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 do GRIB2

Os ativos GRIB2 que foram ingeridos no Computador Planetário da Microsoft Pro podem ser visualizados no Explorador, desde que tenham um ficheiro de índice associado (.idx) armazenado no mesmo contentor do Armazenamento de Blobs. O ficheiro Index é gerado durante a ingestão e é necessário para o acesso e renderização ótima dos dados GRIB2.

Visualização de Zarr

Os ativos Zarr ingeridos no Microsoft Planetary Computer Pro podem ser visualizados no Explorador, contanto que a Configuração de Renderização especifique qual variável e fatia de tempo renderizar no campo sel usando o parâmetro options. Se não o fizer, o Explorador tentará renderizar todas as variáveis e fatias temporais da memória Zarr de uma só vez, o que fará com que o Explorador crashe.

O tamanho da loja Zarr e os blocos espaciais também influenciam o desempenho. Deves procurar manter o tamanho total de uma loja Zarr abaixo dos 2 GB, e cada bloco inferior a 100 MB para um desempenho ótimo do tiler.

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

Comportamento do controle deslizante temporal (limitação conhecida)

Metadados temporais obrigatórios e recomendados

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

• type: temporal
• extent
• step

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

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

Estas convenções são necessárias para uma interpretação consistente dos metadados, mas devido às limitações atuais nem sempre são suficientes para garantir suporte por time slider para todos os conjuntos de dados Zarr.

Notas de Kerchunk

O Kerchunk pode melhorar o desempenho para padrões de acesso multidimensionais, mas não resolve problemas de controle de tempo quando as dimensões temporais não foram detetadas durante a ingestão.

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

Roteiro e apoio futuro

O apoio atual e planeado é:

• Zarr v2: suportado atualmente
• Zarr v3: ainda não suportado, planeado para suporte futuro
• Visualização e gestão temporal multi-temporal de Zarr: atualmente parcial, com melhorias contínuas planejadas

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

Se seus ativos de 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 controlo deslizante de tempo aparecerá automaticamente se os seus Itens STAC contiverem ativos com uma dimensão time e um campo extent e step atributo.

Conteúdo relacionado

• Acesse os ativos do cubo de dados da coleção STAC com um token SAS a nível de coleção