Шаблоны сопоставления CSV-to-BUFR
Результаты обучения
К концу этой практической сессии вы сможете:
- создать новый шаблон сопоставления BUFR для ваших данных в формате CSV
- редактировать и отлаживать ваш пользовательский шаблон сопоставления BUFR из командной строки
- настроить плагин данных CSV-to-BUFR для использования пользовательского шаблона сопоставления BUFR
- использовать встроенные шаблоны AWS и DAYCLI для преобразования данных CSV в BUFR
Введение
Файлы данных в формате CSV (значения, разделенные запятыми) часто используются для записи наблюдений и других данных в табличной форме. Большинство регистраторов данных, используемых для записи выходных данных датчиков, могут экспортировать наблюдения в файлы с разделителями, включая CSV. Аналогично, при загрузке данных в базу данных легко экспортировать необходимые данные в файлы формата CSV.
Модуль wis2box csv2bufr предоставляет инструмент командной строки для преобразования данных CSV в формат BUFR. При использовании csv2bufr необходимо предоставить шаблон сопоставления BUFR, который сопоставляет столбцы CSV с соответствующими элементами BUFR. Если вы не хотите создавать собственный шаблон сопоставления, вы можете использовать встроенные шаблоны AWS и DAYCLI для преобразования данных CSV в BUFR, но вам нужно будет убедиться, что данные CSV, которые вы используете, имеют правильный формат для этих шаблонов. Если вы хотите декодировать параметры, которые не включены в шаблоны AWS и DAYCLI, вам потребуется создать собственный шаблон сопоставления.
В этой сессии вы научитесь создавать собственный шаблон сопоставления для преобразования данных CSV в BUFR. Вы также узнаете, как использовать встроенные шаблоны AWS и DAYCLI для преобразования данных CSV в BUFR.
Подготовка
Убедитесь, что wis2box-stack запущен с помощью команды python3 wis2box.py start.
Убедитесь, что у вас открыт веб-браузер с интерфейсом MinIO для вашего экземпляра, перейдя по адресу http://YOUR-HOST:9000.
Если вы не помните свои учетные данные MinIO, вы можете найти их в файле wis2box.env в каталоге wis2box на вашей виртуальной машине.
Убедитесь, что у вас открыт MQTT Explorer и выполнено подключение к вашему брокеру с использованием учетных данных everyone/everyone.
Создание шаблона сопоставления
Модуль csv2bufr включает инструмент командной строки для создания собственного шаблона сопоставления с использованием набора последовательностей BUFR и/или элементов BUFR в качестве входных данных.
Чтобы найти конкретные последовательности и элементы BUFR, вы можете обратиться к таблицам BUFR по ссылке https://confluence.ecmwf.int/display/ECC/BUFR+tables.
Инструмент командной строки csv2bufr mappings
Чтобы получить доступ к инструменту командной строки csv2bufr, вам нужно войти в контейнер wis2box-api:
cd ~/wis2box
python3 wis2box-ctl.py login wis2box-api
Чтобы вывести справочную страницу для команды csv2bufr mapping:
csv2bufr mappings --help
Справочная страница показывает 2 подкоманды:
csv2bufr mappings create: Создать новый шаблон сопоставленияcsv2bufr mappings list: Показать доступные в системе шаблоны сопоставления
csv2bufr mapping list
Команда csv2bufr mapping list покажет вам доступные в системе шаблоны сопоставления.
Шаблоны по умолчанию хранятся в каталоге /opt/wis2box/csv2bufr/templates в контейнере.
Чтобы поделиться пользовательскими шаблонами сопоставления с системой, вы можете сохранить их в каталоге, определенном переменной $CSV2BUFR_TEMPLATES, которая по умолчанию установлена в /data/wis2box/mappings в контейнере. Поскольку каталог /data/wis2box/mappings в контейнере смонтирован в каталог $WIS2BOX_HOST_DATADIR/mappings на хосте, вы найдете свои пользовательские шаблоны сопоставления в каталоге $WIS2BOX_HOST_DATADIR/mappings на хосте.
Давайте попробуем создать новый пользовательский шаблон сопоставления с помощью команды csv2bufr mapping create, используя в качестве входных данных последовательность BUFR 301150 и элемент BUFR 012101.
csv2bufr mappings create 301150 012101 --output /data/wis2box/mappings/my_custom_template.json
Вы можете проверить содержимое только что созданного шаблона сопоставления с помощью команды cat:
cat /data/wis2box/mappings/my_custom_template.json
Проверка шаблона сопоставления
Сколько столбцов CSV сопоставлено с элементами BUFR? Какой заголовок CSV соответствует каждому элементу BUFR?
Нажмите, чтобы увидеть ответ
Созданный вами шаблон сопоставления сопоставляет 5 столбцов CSV с элементами BUFR, а именно 4 элемента BUFR из последовательности 301150 и элемент BUFR 012101.
Следующие столбцы CSV сопоставлены с элементами BUFR:
- wigosIdentifierSeries сопоставлен с
"eccodes_key": "#1#wigosIdentifierSeries"(элемент BUFR 001125) - wigosIssuerOfIdentifier сопоставлен с
"eccodes_key": "#1#wigosIssuerOfIdentifier"(элемент BUFR 001126) - wigosIssueNumber сопоставлен с
"eccodes_key": "#1#wigosIssueNumber"(элемент BUFR 001127) - wigosLocalIdentifierCharacter сопоставлен с
"eccodes_key": "#1#wigosLocalIdentifierCharacter"(элемент BUFR 001128) - airTemperature сопоставлен с
"eccodes_key": "#1#airTemperature"(элемент BUFR 012101)
Созданный вами шаблон сопоставления не содержит важные метаданные об измерении, такие как дата и время наблюдения, а также широта и долгота станции.
Далее мы обновим шаблон сопоставления и добавим следующие последовательности:
- 301011 для даты (год, месяц, день)
- 301012 для времени (час, минута)
- 301023 для местоположения (широта/долгота с грубой точностью)
И следующие элементы:
- 010004 для давления
- 007031 для высоты барометра над уровнем моря
Выполните следующую команду для обновления шаблона сопоставления:
csv2bufr mappings create 301150 301011 301012 301023 007031 012101 010004 --output /data/wis2box/mappings/my_custom_template.json
И снова проверьте содержимое шаблона сопоставления:
cat /data/wis2box/mappings/my_custom_template.json
Проверка обновленного шаблона сопоставления
Сколько столбцов CSV теперь сопоставлено с элементами BUFR? Какой заголовок CSV соответствует каждому элементу BUFR?
Нажмите, чтобы увидеть ответ
Обновленный шаблон сопоставления теперь сопоставляет 18 столбцов CSV с элементами BUFR: - 4 элемента BUFR из последовательности BUFR 301150 - 3 элемента BUFR из последовательности BUFR 301011 - 2 элемента BUFR из последовательности BUFR 301012 - 2 элемента BUFR из последовательности BUFR 301023 - элемент BUFR 007031 - элемент BUFR 012101
Следующие столбцы CSV сопоставлены с элементами BUFR:
- wigosIdentifierSeries сопоставлен с
"eccodes_key": "#1#wigosIdentifierSeries"(элемент BUFR 001125) - wigosIssuerOfIdentifier сопоставлен с
"eccodes_key": "#1#wigosIssuerOfIdentifier"(элемент BUFR 001126) - wigosIssueNumber сопоставлен с
"eccodes_key": "#1#wigosIssueNumber"(элемент BUFR 001127) - wigosLocalIdentifierCharacter сопоставлен с
"eccodes_key": "#1#wigosLocalIdentifierCharacter"(элемент BUFR 001128) - year сопоставлен с
"eccodes_key": "#1#year"(элемент BUFR 004001) - month сопоставлен с
"eccodes_key": "#1#month"(элемент BUFR 004002) - day сопоставлен с
"eccodes_key": "#1#day"(элемент BUFR 004003) - hour сопоставлен с
"eccodes_key": "#1#hour"(элемент BUFR 004004) - minute сопоставлен с
"eccodes_key": "#1#minute"(элемент BUFR 004005) - latitude сопоставлен с
"eccodes_key": "#1#latitude"(элемент BUFR 005002) - longitude сопоставлен с
"eccodes_key": "#1#longitude"(элемент BUFR 006002) - heightOfBarometerAboveMeanSeaLevel сопоставлен с
"eccodes_key": "#1#heightOfBarometerAboveMeanSeaLevel"(элемент BUFR 007031) - airTemperature сопоставлен с
"eccodes_key": "#1#airTemperature"(элемент BUFR 012101) - nonCoordinatePressure сопоставлен с
"eccodes_key": "#1#nonCoordinatePressure"(элемент BUFR 010004)
Проверьте содержимое файла custom_template_data.csv в каталоге /wis2box-api/data-conversion-exercises:
cd /wis2box-api/data-conversion-exercises
cat custom_template_data.csv
Обратите внимание, что заголовки этого CSV файла совпадают с заголовками CSV в шаблоне сопоставления, который вы создали.
Для тестирования преобразования данных мы можем использовать инструмент командной строки csv2bufr, чтобы преобразовать CSV файл в BUFR, используя созданный нами шаблон сопоставления:
csv2bufr data transform --bufr-template my_custom_template /wis2box-api/data-conversion-exercises/custom_template_data.csv
Вы должны увидеть следующий вывод:
CLI: ... Transforming /wis2box-api/data-conversion-exercises/custom_template_data.csv to BUFR ...
CLI: ... Processing subsets:
CLI: ..... 94 bytes written to ./WIGOS_0-20000-0-15015_20250412T210000.bufr4
CLI: End of processing, exiting.
Проверка содержимого BUFR файла
Как можно проверить содержимое только что созданного BUFR файла и убедиться, что данные закодированы корректно?
Нажмите, чтобы увидеть ответ
Вы можете использовать команду bufr_dump -p, чтобы проверить содержимое только что созданного BUFR файла.
Эта команда покажет содержимое BUFR файла в читаемом для человека формате.
bufr_dump -p ./WIGOS_0-20000-0-15015_20250412T210000.bufr4
В выводе вы увидите значения для элементов BUFR, которые вы сопоставили в шаблоне, например, "airTemperature" будет отображаться следующим образом:
airTemperature=298.15
Теперь вы можете выйти из контейнера:
exit
Использование шаблона сопоставления в wis2box
Чтобы новый шаблон сопоставления был распознан контейнером wis2box-api, необходимо перезапустить контейнер:
docker restart wis2box-api
Теперь вы можете настроить ваш набор данных в wis2box-webapp для использования пользовательского шаблона сопоставления для плагина преобразования CSV в BUFR.
Приложение wis2box-webapp автоматически обнаружит созданный вами шаблон сопоставления и сделает его доступным в списке шаблонов для плагина преобразования CSV в BUFR.
Нажмите на набор данных, который вы создали в предыдущем практическом занятии, и нажмите "UPDATE" рядом с плагином с именем "CSV data converted to BUFR":
Вы должны увидеть созданный вами новый шаблон в списке доступных шаблонов:
Hint
Обратите внимание, что если вы не видите созданный вами новый шаблон, попробуйте обновить страницу или открыть её в новом окне инкогнито.
На данный момент оставьте выбор шаблона AWS по умолчанию (нажмите в правом верхнем углу, чтобы закрыть конфигурацию плагина).
Использование шаблона 'AWS'
Шаблон 'AWS' предоставляет шаблон сопоставления для преобразования данных CSV в последовательности BUFR 301150, 307096, в поддержку минимальных требований GBON.
Описание шаблона AWS можно найти здесь aws-template.
Просмотр входных данных aws-example
Скачайте пример для этого упражнения по ссылке ниже:
Откройте скачанный файл в редакторе и изучите его содержимое:
Question
Изучая поля даты, времени и идентификаторов (WIGOS и традиционные идентификаторы), что вы замечаете? Как будет представлена сегодняшняя дата?
Нажмите, чтобы увидеть ответ
Каждый столбец содержит одну часть информации. Например, дата разделена на год, месяц и день, что соответствует тому, как данные хранятся в BUFR. Сегодняшняя дата будет разделена на столбцы "year", "month" и "day". Аналогично, время нужно разделить на "hour" и "minute", а идентификатор станции WIGOS — на его соответствующие компоненты.
Question
Как в файле данных кодируются отсутствующие данные?
Нажмите, чтобы увидеть ответ
Отсутствующие данные в файле представлены пустыми ячейками. В CSV файле это будет закодировано как ,,. Обратите внимание, что это пустая ячейка, а не строка нулевой длины, например, ,"",.
Отсутствующие данные
Признано, что данные могут отсутствовать по разным причинам, будь то сбой датчика или отсутствие наблюдаемого параметра. В таких случаях отсутствующие данные могут быть закодированы, как указано выше, при этом остальные данные в отчёте остаются действительными.
Обновление примерного файла
Обновите скачанный примерный файл, чтобы использовать сегодняшнюю дату и время, а также измените идентификаторы станций WIGOS на станции, которые вы зарегистрировали в wis2box-webapp.
Загрузка данных в MinIO и проверка результата
Перейдите в интерфейс MinIO и войдите в систему, используя учетные данные из файла wis2box.env.
Перейдите в wis2box-incoming и нажмите кнопку "Create new path":
Создайте новую папку в бакете MinIO, которая соответствует dataset-id для набора данных, который вы создали с шаблоном='weather/surface-weather-observations/synop':
Загрузите скачанный примерный файл в созданную вами папку в бакете MinIO:
Проверьте панель мониторинга Grafana по адресу http://YOUR-HOST:3000, чтобы увидеть, есть ли какие-либо ПРЕДУПРЕЖДЕНИЯ или ОШИБКИ. Если вы их видите, попробуйте исправить их и повторить упражнение.
Проверьте MQTT Explorer, чтобы убедиться, что вы получаете уведомления о данных WIS2.
Если данные успешно загружены, вы должны увидеть 3 уведомления в MQTT Explorer по теме origin/a/wis2/<centre-id>/data/weather/surface-weather-observations/synop для 3 станций, для которых вы сообщили данные:
Использование шаблона 'DayCLI'
Шаблон DayCLI предоставляет шаблон сопоставления для преобразования ежедневных климатических данных CSV в последовательность BUFR 307075, в поддержку отчётности по ежедневным климатическим данным.
Описание шаблона DAYCLI можно найти здесь daycli-template.
Чтобы поделиться этими данными в WIS2, вам нужно будет создать новый набор данных в wis2box-webapp, который имеет правильную иерархию тем WIS2 и использует шаблон DAYCLI для преобразования данных CSV в BUFR.
Создание набора данных wis2box для публикации сообщений DAYCLI
Перейдите в редактор набора данных в wis2box-webapp и создайте новый набор данных. Используйте тот же centre-id, что и в предыдущих практических занятиях, и выберите Data Type='climate/surface-based-observations/daily':
Нажмите "CONTINUE TO FORM" и добавьте описание для вашего набора данных, укажите ограничивающий прямоугольник и предоставьте контактную информацию для набора данных. После заполнения всех разделов нажмите 'VALIDATE FORM' и проверьте форму.
Просмотрите плагины данных для наборов данных. Нажмите "UPDATE" рядом с плагином с именем "CSV data converted to BUFR", и вы увидите, что шаблон установлен на DayCLI:
Закройте конфигурацию плагина и отправьте форму, используя токен аутентификации, созданный вами в предыдущем практическом занятии.
Теперь у вас должен быть второй набор данных в wis2box-webapp, настроенный для использования шаблона DAYCLI для преобразования данных CSV в BUFR.
Просмотр входных данных daycli-example
Скачайте пример для этого упражнения по ссылке ниже:
Откройте скачанный файл в редакторе и изучите его содержимое:
Question
Какие дополнительные переменные включены в шаблон daycli?
Нажмите, чтобы увидеть ответ
Шаблон daycli включает важные метаданные о размещении инструментов и классификациях качества измерений температуры и влажности, флаги контроля качества и информацию о том, как была рассчитана средняя дневная температура.
Обновление примерного файла
Примерный файл содержит одну строку данных для каждого дня месяца и сообщает данные для одной станции. Обновите скачанный примерный файл, чтобы использовать сегодняшнюю дату и время, а также измените идентификаторы станций WIGOS на станцию, которую вы зарегистрировали в wis2box-webapp.
Загрузка данных в MinIO и проверка результата
```
Как и ранее, вам нужно загрузить данные в корзину 'wis2box-incoming' в MinIO, чтобы они были обработаны конвертером csv2bufr. На этот раз вам нужно создать новую папку в корзине MinIO, которая соответствует dataset-id для набора данных, который вы создали с использованием шаблона climate/surface-based-observations/daily. Этот dataset-id будет отличаться от того, который вы использовали в предыдущем упражнении:
После загрузки данных проверьте, чтобы на панели мониторинга Grafana не было ПРЕДУПРЕЖДЕНИЙ (WARNINGS) или ОШИБОК (ERRORS), а также проверьте MQTT Explorer, чтобы убедиться, что вы получаете WIS2 уведомления о данных.
Если данные были успешно загружены, вы должны увидеть 30 уведомлений в MQTT Explorer по теме origin/a/wis2/<centre-id>/data/climate/surface-based-observations/daily за 30 дней месяца, за который вы предоставили данные:
Заключение
Поздравляем
В ходе этой практической сессии вы узнали:
- как создать пользовательский шаблон для преобразования данных CSV в BUFR
- как использовать встроенные шаблоны AWS и DAYCLI для преобразования данных CSV в BUFR