Quickstart: Aan de slag met gegevenskubussen in Microsoft Planetary Computer Pro

Vereiste voorwaarden

Opnamebron instellen

Voordat u data uit een datacube kunt inladen, moet u een Ingestiebron instellen, die dient als uw verificatie voor toegang tot het Blob Storage-account waarin uw assets en STAC-items worden opgeslagen. U kunt een opnamebron instellen met beheerde identiteit of SAS-token.

Een gegevenskubusverzameling maken

Zodra uw opnamebron is ingesteld, kunt u een verzameling voor uw gegevenskubusobjecten maken. Stappen voor het maken van een verzameling kunnen worden gevolgd in Een STAC-verzameling maken met Microsoft Planetary Computer Pro met behulp van Python.

Gegevenskubusassets opnemen

De inleiding van het opnameproces voor gegevenskubusgegevens en andere gegevenstypen kan worden gevolgd in Het opnameoverzicht. Zoals beschreven in Data Cube Overview, is opname echter de stap in Planetary Computer Pro's gegevensverwerking die verschilt voor deze bestandstypen. Hoewel GRIB2-gegevens en bijbehorende STAC-items worden opgenomen, net als elk ander tweedimensionaal rasterbestand, ondergaan NetCDF- en HDF5-assets verdere gegevensverrijking. Het genereren van Kerchunk-manifesten wordt beschreven in het overzicht van de gegevenskubus, maar wat belangrijk is om op te merken is dat Kerchunk-assets naast de oorspronkelijke assets worden toegevoegd aan uw Blob Storage-container en dat er een extra cube:variables veld wordt toegevoegd aan de JSON van het STAC-item. Dit is belangrijk bij het weergeven van deze gegevenstypen in de Planetary Computer Pro Explorer.

Een gegevenskubusverzameling configureren

De configuratie van uw gegevenskubusverzameling is een andere stap die er iets anders uitziet dan die van andere gegevenstypen. U kunt de stappen volgen die worden beschreven in Een verzameling configureren met de microsoft Planetary Computer Pro-webinterface om uw gegevenskubusverzameling te configureren, maar u moet rekening houden met de volgende verschillen bij het bouwen van uw Render-configuratie:

Configuratie renderen voor NetCDF- en HDF5-assets

Onthoud dat een standaardargument Render Configuration in JSON-indeling er als volgt uitziet:

[
  {
    "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",
    "minZoom": 1,
    "info_options": "assets=pr-kerchunk&subdataset_name=pr"
  }
]

In options het veld wilt u de geoptimaliseerde Kerchunk-asset in de cloud gebruiken, in plaats van de oorspronkelijke asset die wordt vermeld in het STAC-item. U moet ook het subdataset_name argument opnemen. Dit is de naam van de variabele die u wilt weergeven.

Het info_options veld schakelt de tijdschuif van de Explorer voor deze collectie in. Het gebruikt hetzelfde URL-querystringformaat als options, maar het zou alleen de parameters moeten bevatten die nodig zijn voor /info ontdekking, meestal assets en subdataset_name. Laat styling- en slicingparameters zoals rescale, colormap_name, en datetimeweg. Als je wilt dat de schuifregelaar actief blijft, pin datetime=... dan niet in options, want een hardgecodeerde waarde overschrijft de schuifregelaar. Als je info_options weglaat, gebruikt de Explorer als terugval tijdsgrenzen uit de metadata van het STAC-item (cube:dimensions, start_datetime, end_datetime).

Configuratie weergeven voor GRIB2-assets

Het options veld voor de renderconfiguratie van GRIB2-assets lijkt op het vorige voorbeeld, maar u hoeft het subdataset_name argument niet op te nemen. Dit komt doordat GRIB2-gegevens al optimaal zijn gestructureerd en waarnaar wordt verwezen via hun indexbestanden. Het assets argument vertegenwoordigt in dit geval de band- of 2D-rasterlaag die u wilt weergeven. Hieronder ziet u een voorbeeld van een GRIB2 Render-configuratie:

[ 
 {
    "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,
    "info_options": "assets=data"
 }
]

Voor GRIB2, stel je info_options in op de assetsleutel die wordt gebruikt in options. Het toevoegen van info_options schakelt de tijdschuifregelaar van de Explorer in, die de beschikbare GRIB-band-/berichtindexen rechtstreeks via het /info-eindpunt van de Tiler ophaalt. Als je GRIB-collectie meerdere renderconfiguraties voor verschillende onderdelen beschikbaar stelt, voeg dan info_options toe aan elke renderoptie die een schuifregelaar moet aansturen.

Configuratie weergeven voor Zarr-assets

Het options veld voor Zarr-assets is vergelijkbaar met NetCDF en HDF5, maar er zijn twee belangrijke vereisten:

  1. Selecteer één tijdssegment voor rendering met behulp van sel=time=....
  2. Verminder de gegevens tot een 2D-uitvoer voordat u de weergave uitvoert.

Als extra dimensies niet zijn samengevouwen, kan rendering mislukken met fouten zoals Source data must be 1 band.

Meer informatie over de sel parameter vindt u in Xarray DataArray.sel. Hier volgt een minimale werkende Zarr-weergaveconfiguratie voor één timestep en 2D-uitvoer.

[
    {
        "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
    }
]

Gegevenskubusassets visualiseren in Explorer

Zodra uw gegevenskubusassets zijn opgenomen en geconfigureerd, kunt u ze visualiseren in Planetary Computer Pro Explorer. Een stapsgewijze handleiding voor het gebruik van De Verkenner kan worden gevolgd in quickstart: De Verkenner gebruiken in Microsoft Planetary Computer Pro.

Hoewel Microsoft Planetary Computer Pro een tiler bevat die kan worden gebruikt om bepaalde gegevenskubusassets te visualiseren, zijn er enkele opmerkingen bij elk ondersteund gegevenstype.

NetCDF- en HDF5-visualisatie

Niet alle NetCDF-gegevenssets die kunnen worden ingelezen in de Microsoft Planetary Computer zijn compatibel met de visualisatietegel van Planetary Computer Pro. Een gegevensset moet X- en Y-assen, breedte- en lengtegraadcoördinaten en ruimtelijke dimensies en grenzen hebben die moeten worden gevisualiseerd. Een gegevensset waarin breedtegraad en lengtegraad variabelen zijn, maar geen coördinaten, is bijvoorbeeld niet compatibel met de tiler van Planetary Computer Pro.

Voordat u uw NetCDF- of HDF5-gegevensset probeert te visualiseren, kunt u het volgende gebruiken om te controleren of deze voldoet aan de vereisten.

  1. De vereiste afhankelijkheden installeren

    pip install xarray[io] rioxarray cf_xarray

  2. Voer de volgende functie uit:

    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.")

GRIB2-visualisatie

GRIB2-assets die zijn opgenomen in Microsoft Planetary Computer Pro, kunnen worden gevisualiseerd in de Explorer zolang ze een gekoppeld indexbestand (.idx) hebben opgeslagen in dezelfde Blob Storage-container. Het indexbestand wordt gegenereerd tijdens de opname en is vereist voor optimale toegang en rendering van GRIB2-gegevens.

Zarr-visualisatie

Zarr-assets die zijn opgenomen in Microsoft Planetary Computer Pro, kunnen worden gevisualiseerd in de Explorer zolang de renderconfiguratie aangeeft welke variabele en tijdssegment moeten worden weergegeven met behulp van de sel parameter in het options veld. Als u dit niet doet, wordt geprobeerd alle variabelen en tijdsegmenten van het Zarr-archief tegelijk weer te geven, waardoor de Explorer vastloopt.

De grootte van het Zarr-archief en ruimtelijke blokken heeft ook invloed op de prestaties. U moet de totale grootte van een Zarr-opslag onder 2 GB houden en elke chunk kleiner dan 100 MB voor optimale prestaties van de tiler.

Beperkingen en bekende problemen met Zarr-visualisatie

Gedrag van tijdschuifregelaar (bekende beperking)

Opmerking

Gedrag van tijdschuifregelaars voor Zarr is momenteel beperkt. De tijdschuifbalk van Explorer wordt alleen weergegeven wanneer een temporele dimensie correct wordt gedetecteerd tijdens de invoer.

Zelfs wanneer Zarr-assets tijdwaarden bevatten, kan opname geen tijdelijke metagegevens voor sommige gegevenssets detecteren. In dergelijke gevallen wordt de tijdslider niet weergegeven en moet u één tijdstap per keer visualiseren in de weergaveconfiguratie (bijvoorbeeld sel=time=2024-01-01).

Als u tijdbewust gedrag wilt inschakelen, moeten uw STAC-metagegevens een tijdelijke dimensie cube:dimensions bevatten met:

  • type: temporal
  • extent
  • step

Voor Zarr-brongegevens volgt u waar mogelijk CF-tijdconventies, bijvoorbeeld:

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

Deze conventies zijn nodig voor consistente interpretatie van metagegevens, maar vanwege de huidige beperkingen zijn ze niet altijd voldoende om ondersteuning voor tijdschuifregelaars voor elke Zarr-gegevensset te garanderen.

Kerchunk-notities

Kerchunk kan de prestaties voor multidimensionale toegangspatronen verbeteren, maar lost problemen met tijdschuifregelaars niet op wanneer tijdelijke dimensies niet zijn gedetecteerd tijdens opname.

Sommige Zarr-gegevenssets kunnen ook mislukken tijdens het verwerken van indexen met fouten zoals Index must be monotonic increasing or decreasing.

Tijdschuifregelaar voor gegevenskubusvisualisatie

Als uw gegevenskubusassets een tijdelijk onderdeel hebben, kunt u de tijdschuifregelaar in Explorer gebruiken om wijzigingen in de loop van de tijd te visualiseren. De tijdschuifregelaar wordt automatisch weergegeven als uw STAC Items assets bevatten met een time-dimensie met een extent- en step-veld.

Opmerking

Voor Zarr-assets, zie beperkingen en bekende problemen van Zarr-visualisatie voor de huidige beperkingen van de tijdschuifregelaar en de vereiste configuratiepatronen voor weergave.

Verwante inhoud

  • Laatst bijgewerkt om