Краткое руководство. Начало работы с кубами данных в Microsoft Planetary Computer Pro

Предпосылки

Учетная запись Azure с активной подпиской; создайте учетную запись бесплатно.
Ресурс Microsoft Planetary Computer Pro GeoCatalog
Учетная запись хранения BLOB-объектов создает учетную запись хранения BLOB.
Контейнер хранилища BLOB-объектов с ресурсами куба данных (NetCDF, HDF5, GRIB2), элементами STAC и статическим каталогом STAC. Узнайте, как создать элементы STAC.

Настройка источника приема

Прежде чем начать загрузку данных куба, необходимо настроить источник загрузки данных, который будет использоваться в качестве учетных данных для доступа к учетной записи хранилища Blob, в которой хранятся ваши активы и элементы STAC. Вы можете настроить источник загрузки с помощью управляемого удостоверения или SAS-токена.

Создание коллекции кубов данных

После настройки источника загрузки данных можно создать коллекцию для активов куба данных. Чтобы создать коллекцию, можно выполнить инструкции по созданию коллекции STAC с помощью Microsoft Planetary Computer Pro с помощью Python.

Обработка активов куба данных

Запуск процесса загрузки данных куба данных и других типов данных можно отслеживать в разделе Обзор загрузки данных. Как описано в обзоре куба данных, прием — это шаг обработки данных Planetary Computer Pro, который отличается для этих типов файлов. Хотя данные GRIB2 и связанные элементы STAC обрабатываются так же, как и любые другие двухмерные растровые файлы, NetCDF и HDF5 ресурсы проходят дальнейшее обогащение данных. Создание манифестов Kerchunk задокументировано в обзоре куба данных, но важно отметить, что ресурсы Kerchunk будут добавлены в контейнер хранилища BLOB-объектов вместе с исходными ресурсами, а дополнительное cube:variables поле добавляется в JSON элемента STAC. Это важно при рендеринге этих типов данных в Planetary Computer Pro Explorer.

Настройка коллекции кубов данных

Конфигурация коллекции кубов данных — это еще один шаг, который будет немного отличаться от конфигурации других типов данных. Вы можете выполнить действия, описанные в статье "Настройка коллекции с помощью веб-интерфейса Microsoft Planetary Computer Pro", чтобы настроить коллекцию кубов данных, но при создании конфигурации отрисовки необходимо учитывать следующие различия.

Настройка рендеринга для ресурсов NetCDF и HDF5

Помните, что стандартный аргумент конфигурации отрисовки в формате JSON выглядит следующим образом:

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

В options этом поле вы хотите использовать оптимизированный для облака ресурс Kerchunk, а не исходный ресурс, указанный в элементе STAC. Кроме того, необходимо включить subdataset_name аргумент, который является именем переменной, которую вы хотите отобразить.

Поле info_options включает временной ползунок в Explorer для этой коллекции. Он использует тот же формат строки запроса URL, что и options, но должен включать только параметры, необходимые для обнаружения /info, обычно assets и subdataset_name. Опустите параметры стилизации и нарезки, такие как rescale, colormap_name и datetime. Если вы хотите, чтобы ползунок оставался активным, не закрепляйте datetime=... в options, потому что жестко заданное значение переопределяет значение ползунка. Если опустить info_options, Explorer будет брать временные границы из метаданных элемента STAC (cube:dimensions, start_datetime, end_datetime).

Настройка отрисовки для объектов GRIB2

Поле options для конфигурации отрисовки для ресурсов GRIB2 похоже на предыдущий пример, но вам не нужно включать аргумент subdataset_name. Это связано с тем, что данные GRIB2 уже оптимально структурированы и ссылаются на их файлы индекса. Аргумент assets , в данном случае, представляет полосу или 2D-растровый слой, который требуется отобразить. Ниже приведен пример конфигурации отрисовки 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,
    "info_options": "assets=data"
 }
]

Для GRIB2 задайте для info_options значение ключа ресурса, используемого в options. Добавление info_options включает временной ползунок Explorer, который напрямую обнаруживает доступные индексы диапазонов/сообщений GRIB с конечной точки /info Tiler. Если ваша коллекция GRIB показывает несколько конфигураций рендера для разных ассетов, добавьте info_options в каждую опцию рендера, которая должна управлять ползунком.

Конфигурация рендеринга для активов Zarr

Поле options для ресурсов Zarr аналогично NetCDF и HDF5, но существует два важных требования:

Выберите один срез времени для отрисовки с помощью sel=time=....
Перед отрисовкой уменьшите объем данных до вывода из 2D.

Если дополнительные измерения не свернуты, рендеринг может завершиться с ошибкой, в том числе Source data must be 1 band.

Дополнительные сведения о параметре sel см. в Xarray DataArray.sel. Ниже представлена минимальная действующая конфигурация отрисовки Zarr для единственного временного шага и двухмерных выходных данных.

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

Визуализация ресурсов куба данных в обозревателе

После приема и настройки кубов данных их можно визуализировать в Planetary Computer Pro Explorer. Пошаговое руководство по использованию Обозревателя можно найти в кратком руководстве: Использование Обозревателя в Microsoft Planetary Computer Pro.

Хотя Microsoft Planetary Computer Pro включает тайлер, который может использоваться для визуализации некоторых ресурсов куба данных, существуют некоторые предупреждения, которые следует учитывать, когда речь идет о каждом поддерживаемом типе данных.

Визуализация NetCDF и HDF5

Не все наборы данных NetCDF, которые можно загрузить в Microsoft Planetary Computer, совместимы с визуализирующим модулем Planetary Computer Pro. Набор данных должен иметь оси X и Y, широту и долготу, а также пространственные измерения и границы для визуализации. Например, набор данных, в котором широта и долгота являются переменными, но не координатами, несовместим с тайлером Planetary Computer Pro.

Прежде чем визуализировать набор данных NetCDF или HDF5, можно использовать следующее, чтобы проверить соответствие требованиям.

Установка необходимых зависимостей
```
pip install xarray[io] rioxarray cf_xarray
```

Выполните следующую функцию:

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

Ресурсы GRIB2, которые были приняты в Microsoft Planetary Computer Pro, можно визуализировать в обозревателе, если у них есть связанный файл индекса (IDX), хранящийся в том же контейнере хранилища BLOB-объектов. Файл индекса формируется во время обработки данных и необходим для оптимального доступа и визуализации информации GRIB2.

Визуализация Zarr

Ресурсы Zarr, которые загружены в Microsoft Planetary Computer Pro, можно визуализировать в просмотрщике, если конфигурация отрисовки указывает, какую переменную и временной срез следует отрисовывать, используя параметр sel в поле options. Сбой этого приведет к попытке обозревателя отобразить все переменные и временные срезы хранилища Zarr одновременно, что приведет к сбою обозревателя.

Размер хранилища Zarr и пространственных блоков также влияет на производительность. Необходимо поддерживать общий размер хранилища Zarr в пределах 2 ГБ, а также каждый блок менее 100 МБ для оптимальной производительности тайлера.

Ограничения визуализации Zarr и известные проблемы

Поведение ползунка времени (известное ограничение)

Замечание

Поведение ползунка времени для Zarr в настоящее время ограничено. Ползунок времени эксплорера отображается только при правильном обнаружении временного измерения во время приема.

Даже если ресурсы Zarr содержат значения времени, инструмент загрузки может не обнаруживать временных метаданных для некоторых наборов данных. В таких случаях ползунок времени не будет отображаться, и необходимо визуализировать один шаг за раз в конфигурации визуализации (например, sel=time=2024-01-01).

Обязательные и рекомендуемые темпоральные метаданные

Чтобы включить поведение с учетом времени, в метаданных STAC должно быть включено темпоральное измерение в cube:dimensions:

type: temporal
extent
step

Для исходных данных Zarr следуйте соглашениям о времени CF, где это возможно, например:

standard_name="time"
axis="T"

Эти соглашения необходимы для согласованной интерпретации метаданных, но из-за текущих ограничений они не всегда достаточно для обеспечения поддержки ползунка времени для каждого набора данных Zarr.

Заметки Kerchunk

Kerchunk может повысить производительность в многомерных шаблонах доступа, но не решает проблемы с временным ползунком, если во время загрузки не были обнаружены временные измерения.

Некоторые наборы данных Zarr также могут завершиться ошибкой во время обработки индекса с такими ошибками, как Index must be monotonic increasing or decreasing.

Ползунок времени для визуализации куба данных

Если ресурсы куба данных имеют темпоральный компонент, вы можете использовать ползунок времени в обозревателе для визуализации изменений с течением времени. Ползунок времени будет автоматически отображаться, если элементы STAC содержат ресурсы с time измерением и с полями extent и step.