Инструменты конвертации данных

Ожидаемые результаты

К концу этой практической сессии вы сможете:

Получить доступ к инструментам командной строки ecCodes в контейнере wis2box-api
Использовать инструмент synop2bufr для конвертации отчетов FM-12 SYNOP в BUFR из командной строки
Запустить конвертацию synop2bufr через wis2box-webapp
Использовать инструмент csv2bufr для конвертации данных CSV в BUFR из командной строки

Введение

Данные, публикуемые в WIS2, должны соответствовать требованиям и стандартам, определенным различными сообществами экспертов в области дисциплин/доменов системы Земли. Для снижения барьеров на пути публикации данных наземных поверхностных наблюдений, wis2box предоставляет инструменты для конвертации данных в формат BUFR. Эти инструменты доступны через контейнер wis2box-api и могут использоваться из командной строки для тестирования процесса конвертации данных.

Основные поддерживаемые конвертации в wis2box включают отчеты FM-12 SYNOP в BUFR и данные CSV в BUFR. Данные FM-12 поддерживаются, так как они все еще широко используются и обмениваются в сообществе ВМО, в то время как поддержка данных CSV позволяет отображать данные, произведенные автоматическими метеостанциями, в формат BUFR.

О FM-12 SYNOP

Поверхностные метеорологические отчеты с наземных станций исторически сообщались ежечасно или в основные (00, 06, 12 и 18 UTC) и промежуточные (03, 09, 15, 21 UTC) синоптические часы. До перехода на BUFR эти отчеты кодировались в виде простого текста в форме кода FM-12 SYNOP. Хотя переход на BUFR был запланирован к завершению к 2012 году, большое количество отчетов все еще обменивается в устаревшем формате FM-12 SYNOP. Дополнительную информацию о формате FM-12 SYNOP можно найти в Руководстве ВМО по кодам, Том I.1 (ВМО-№ 306, Том I.1).

О ecCodes

Библиотека ecCodes представляет собой набор программных библиотек и утилит, предназначенных для декодирования и кодирования метеорологических данных в форматах GRIB и BUFR. Она разработана Европейским центром среднесрочных прогнозов погоды (ECMWF), см. документацию ecCodes для получения дополнительной информации.

Программное обеспечение wis2box включает библиотеку ecCodes в базовый образ контейнера wis2box-api. Это позволяет пользователям получать доступ к инструментам командной строки и библиотекам изнутри контейнера. Библиотека ecCodes используется в стеке wis2box для декодирования и кодирования сообщений BUFR.

О csv2bufr и synop2bufr

В дополнение к ecCodes, wis2box использует следующие модули Python, работающие с ecCodes для конвертации данных в формат BUFR:

synop2bufr: для поддержки устаревшего формата FM-12 SYNOP, традиционно используемого ручными наблюдателями. Модуль synop2bufr полагается на дополнительные метаданные станции для кодирования дополнительных параметров в файл BUFR. См. репозиторий synop2bufr на GitHub
csv2bufr: для обеспечения конвертации данных CSV, полученных от автоматизированных метеостанций, в формат BUFR. Модуль csv2bufr используется для конвертации данных CSV в формат BUFR с использованием шаблона отображения, который определяет, как данные CSV должны быть отображены в формат BUFR. См. репозиторий csv2bufr на GitHub

Эти модули могут использоваться как самостоятельно, так и как часть стека wis2box.

Подготовка

Предварительные условия

Убедитесь, что ваш wis2box настроен и запущен
Убедитесь, что вы настроили набор данных и сконфигурировали по крайней мере одну станцию в вашем wis2box
Подключитесь к брокеру MQTT вашего экземпляра wis2box с использованием MQTT Explorer
Откройте веб-приложение wis2box (http://YOUR-HOST/wis2box-webapp) и убедитесь, что вы вошли в систему
Откройте панель управления Grafana для вашего экземпляра, перейдя по адресу http://YOUR-HOST:3000

Для использования инструментов командной строки BUFR вам необходимо войти в контейнер wis2box-api. Если не указано иначе, все команды должны выполняться в этом контейнере. Вам также потребуется открыть MQTT Explorer и подключиться к вашему брокеру.

Сначала подключитесь к вашему студенческому VM через ваш SSH-клиент и скопируйте учебные материалы в контейнер wis2box-api:

docker cp ~/exercise-materials/data-conversion-exercises wis2box-api:/root

Затем войдите в контейнер wis2box-api и перейдите в каталог, где находятся учебные материалы:

cd ~/wis2box
python3 wis2box-ctl.py login wis2box-api
cd /root/data-conversion-exercises

Подтвердите, что инструменты доступны, начиная с ecCodes:

bufr_dump -V

Вы должны получить следующий ответ:

ecCodes Version 2.36.0

Затем проверьте версию synop2bufr:

synop2bufr --version

Вы должны получить следующий ответ:

synop2bufr, версия 0.7.0

Затем проверьте csv2bufr:

csv2bufr --version

Вы должны получить следующий ответ:

csv2bufr, версия 0.8.5

Инструменты командной строки ecCodes

Библиотека ecCodes, включенная в контейнер wis2box-api, предоставляет ряд инструментов командной строки для работы с файлами BUFR. Следующие упражнения демонстрируют, как использовать bufr_ls и bufr_dump для проверки содержимого файла BUFR.

bufr_ls

В этом первом упражнении вы будете использовать команду bufr_ls для проверки заголовков файла BUFR и определения типа содержимого файла.

Используйте следующую команду для запуска bufr_ls на файле bufr-cli-ex1.bufr4:

bufr_ls bufr-cli-ex1.bufr4

Вы должны увидеть следующий вывод:

bufr-cli-ex1.bufr4
centre                     masterTablesVersionNumber  localTablesVersionNumber   typicalDate                typicalTime                numberOfSubsets
cnmc                       29                         0                          20231002                   000000                     1
1 из 1 сообщений в bufr-cli-ex1.bufr4

1 из 1 общих сообщений в 1 файле

Различные параметры могут быть переданы bufr_ls для изменения как формата, так и печатаемых полей заголовков.

Question

Какой будет команда для вывода предыдущего вывода в формате JSON?

Вы можете запустить команду bufr_ls с флагом -h, чтобы увидеть доступные параметры.

Нажмите, чтобы увидеть ответ

Вы можете изменить формат вывода на JSON, используя флаг -j, т.е.

bufr_ls -j bufr-cli-ex1.bufr4

При запуске это должно дать вам следующий вывод:

{ "messages" : [
  {
    "centre": "cnmc",
    "masterTablesVersionNumber": 29,
    "localTablesVersionNumber": 0,
    "typicalDate": 20231002,
    "typicalTime": "000000",
    "numberOfSubsets": 1
  }
]}

Вывод, который печатается, представляет значения некоторых ключей заголовков в файле BUFR.

Сам по себе эта информация не очень информативна, поскольку предоставляется только ограниченная информация о содержимом файла.

При изучении файла BUFR мы часто хотим определить тип данных, содержащихся в файле, и типичную дату/время данных в файле. Эту информацию можно вывести, используя флаг -p для выбора выводимых заголовков. Несколько заголовков можно включить, используя список, разделенный запятыми.

Вы можете использовать следующую команду для вывода категории данных, подкатегории, типичной даты и времени:

bufr_ls -p dataCategory,internationalDataSubCategory,typicalDate,typicalTime -j bufr-cli-ex1.bufr4

Question

Выполните предыдущую команду и интерпретируйте вывод, используя Общую таблицу кодов C-13, чтобы определить категорию данных и подкатегорию.

Какой тип данных (категория данных и подкатегория) содержится в файле? Какая типичная дата и время для данных?

Нажмите, чтобы увидеть ответ

{ "messages" : [
  {
    "dataCategory": 2,
    "internationalDataSubCategory": 4,
    "typicalDate": 20231002,
    "typicalTime": "000000"
  }
]}

Из этого мы видим, что:

Категория данных - 2, что указывает на данные "Вертикальные зондирования (кроме спутников)".
Международная подкатегория - 4, что указывает на данные "Отчеты о температуре/влажности/ветре верхних уровней от стационарных наземных станций (TEMP)".
Типичная дата и время - 2023-10-02 и 00:00:00z соответственно.

bufr_dump

Команда bufr_dump может быть использована для просмотра и изучения содержимого файла BUFR, включая сами данные.

Попробуйте запустить команду bufr_dump на втором примере файла bufr-cli-ex2.bufr4:

bufr_dump bufr-cli-ex2.bufr4

Это приведет к JSON, который может быть сложно анализировать, попробуйте использовать флаг -p для вывода данных в простом тексте (формат key=value):

bufr_dump -p bufr-cli-ex2.bufr4

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

Вы можете использовать команду grep для фильтрации вывода и показа только ключей, которые не отсутствуют. Например, чтобы показать все ключи, которые не отсутствуют, вы можете использовать следующую команду:

bufr_dump -p bufr-cli-ex2.bufr4 | grep -v MISSING

Question

Какое давление, приведенное к уровню моря, сообщается в файле BUFR bufr-cli-ex2.bufr4?

Нажмите, чтобы увидеть ответ

Используя следующую команду:

bufr_dump -p bufr-cli-ex2.bufr4 | grep -i 'pressureReducedToMeanSeaLevel'

Вы должны увидеть следующий вывод:

pressureReducedToMeanSeaLevel=105590

Это указывает, что давление, приведенное к уровню моря, составляет 105590 Па (1055.90 гПа).

Question

Какой идентификатор станции WIGOS станции, которая сообщила данные в файле BUFR bufr-cli-ex2.bufr4?

Нажмите, чтобы увидеть ответ

Используя следующую команду:

bufr_dump -p bufr-cli-ex2.bufr4 | grep -i 'wigos'

Вы должны увидеть следующий вывод:

wigosIdentifierSeries=0
wigosIssuerOfIdentifier=20000
wigosIssueNumber=0
wigosLocalIdentifierCharacter="99100"

Это указывает, что идентификатор станции WIGOS - 0-20000-0-99100.

Конвертация synop2bufr

Далее рассмотрим, как конвертировать данные FM-12 SYNOP в формат BUFR с использованием модуля synop2bufr. Модуль synop2bufr используется для конвертации данных FM-12 SYNOP в формат BUFR. Модуль установлен в контейнере wis2box-api и может использоваться из командной строки следующим образом:

synop2bufr data transform \
    --metadata <station-metadata.csv> \
    --output-dir <output-directory-path> \
    --year <year-of-observation> \
    --month <month-of-observation> \
    <input-fm12.txt>

Аргумент --metadata используется для указания файла метаданных станции, который предоставляет дополнительную информацию для кодирования в файле BUFR. Аргумент --output-dir используется для указания каталог

Аргумент --metadata требует CSV-файл, использующий предопределенный формат, рабочий пример предоставлен в файле station_list.csv:

Используйте следующую команду для просмотра содержимого файла station_list.csv:

more station_list.csv

Question

Сколько станций перечислено в списке станций? Каковы идентификаторы станций WIGOS?

Нажмите, чтобы увидеть ответ

Вывод показывает следующее:

station_name,wigos_station_identifier,traditional_station_identifier,facility_type,latitude,longitude,elevation,barometer_height,territory_name,wmo_region
OCNA SUGATAG,0-20000-0-15015,15015,landFixed,47.7770616258,23.9404602638,503.0,504.0,ROU,europe
BOTOSANI,0-20000-0-15020,15020,landFixed,47.7356532437,26.6455501701,161.0,162.1,ROU,europe

Это соответствует метаданным станции для 2 станций: для идентификаторов станций WIGOS 0-20000-0-15015 и 0-20000-0-15020.

конвертация SYNOP в BUFR

Далее используйте следующую команду для конвертации сообщения FM-12 SYNOP в формат BUFR:

synop2bufr data transform --metadata station_list.csv --output-dir ./ --year 2024 --month 09 synop_message.txt

Question

Сколько файлов BUFR было создано? Что означает предупреждающее сообщение в выводе?

Нажмите, чтобы увидеть ответ

Вывод показывает следующее:

[WARNING] Station 15090 not found in station file

Если вы проверите содержимое вашей директории с помощью команды ls -lh, вы должны увидеть, что было создано 2 новых файла BUFR: WIGOS_0-20000-0-15015_20240921T120000.bufr4 и WIGOS_0-20000-0-15020_20240921T120000.bufr4.

Предупреждающее сообщение указывает, что станция с традиционным идентификатором станции 15090 не найдена в файле списка станций station_list.csv. Это означает, что отчет SYNOP для этой станции не был конвертирован в формат BUFR.

Question

Проверьте содержимое файла BUFR WIGOS_0-20000-0-15015_20240921T120000.bufr4 с помощью команды bufr_dump.

Можете ли вы подтвердить, что информация, предоставленная в файле station_list.csv, присутствует в файле BUFR?

Нажмите, чтобы увидеть ответ

Вы можете использовать следующую команду для проверки содержимого файла BUFR:

bufr_dump -p WIGOS_0-20000-0-15015_20240921T120000.bufr4 | grep -v MISSING

Вы должны увидеть следующий вывод:

wigosIdentifierSeries=0
wigosIssuerOfIdentifier=20000
wigosIssueNumber=0
wigosLocalIdentifierCharacter="15015"
blockNumber=15
stationNumber=15
stationOrSiteName="OCNA SUGATAG"
stationType=1
year=2024
month=9
day=21
hour=12
minute=0
latitude=47.7771
longitude=23.9405
heightOfStationGroundAboveMeanSeaLevel=503
heightOfBarometerAboveMeanSeaLevel=504

Обратите внимание, что это включает данные, предоставленные файлом station_list.csv.

Форма SYNOP в wis2box-webapp

Модуль synop2bufr также используется в wis2box-webapp для конвертации данных FM-12 SYNOP в формат BUFR с использованием веб-формы.

Для тестирования перейдите по адресу http://YOUR-HOST/wis2box-webapp и войдите в систему.

Выберите SYNOP Form в меню слева и скопируйте содержимое файла synop_message.txt:

AAXX 21121
15015 02999 02501 10103 21090 39765 42952 57020 60001=
15020 02997 23104 10130 21075 30177 40377 58020 60001 81041=
15090 02997 53102 10139 21075 30271 40364 58031 60001 82046=

В текстовое поле SYNOP message:

synop-form

Question

Можете ли вы отправить форму? Какой результат?

Нажмите, чтобы увидеть ответ

Вам нужно выбрать набор данных и предоставить токен для "processes/wis2box", который вы создали в предыдущем упражнении, чтобы отправить форму.

Если вы предоставите недействительный токен, вы увидите:

Результат: Неавторизовано, пожалуйста, предоставьте действительный токен 'processes/wis2box'

Если вы предоставите действительный токен, вы увидите "ПРЕДУПРЕЖДЕНИЯ: 3". Нажмите на "ПРЕДУПРЕЖДЕНИЯ", чтобы открыть выпадающее меню, которое покажет:

Станция 15015 не найдена в файле станции
Станция 15020 не найдена в файле станции
Станция 15090 не найдена в файле станции

Для конвертации этих данных в формат BUFR вам нужно настроить соответствующие станции в вашем wis2box и убедиться, что станции связаны с темой вашего набора данных.

Note

В упражнении ingesting-data-for-publication вы загрузили файл "synop_202412030900.txt", и он был конвертирован в формат BUFR модулем synop2bufr.

В автоматизированном рабочем процессе в wis2box год и месяц автоматически извлекаются из имени файла и используются для заполнения аргументов --year и --month, требуемых synop2bufr, в то время как метаданные станции автоматически извлекаются из конфигурации станции в wis2box.

конвертация csv2bufr

Note

Убедитесь, что вы все еще вошли в контейнер wis2box-api и находитесь в директории /root/data-conversion-exercises, если вы вышли из контейнера в предыдущем упражнении, вы можете войти снова следующим образом:

cd ~/wis2box
python3 wis2box-ctl.py login wis2box-api
cd /root/data-conversion-exercises

Теперь давайте посмотрим, как конвертировать данные CSV в формат BUFR с использованием модуля csv2bufr. Модуль установлен в контейнере wis2box-api и может быть использован из командной строки следующим образом:

csv2bufr data transform \
    --bufr-template <bufr-mapping-template> \
    <input-csv-file>

Аргумент --bufr-template используется для указания файла шаблона сопоставления BUFR, который предоставляет сопоставление между входными данными CSV и выходными данными BUFR, указанными в файле JSON. Шаблоны сопоставления по умолчанию установлены в директории /opt/csv2bufr/templates в контейнере wis2box-api.

ознакомьтесь с примером CSV-файла

Ознакомьтесь с содержимым примера CSV-файла aws-example.csv:

more aws-example.csv

Question

Сколько строк данных в CSV-файле? Какой идентификатор станции WIGOS у станций, сообщающих в CSV-файле?

Нажмите, чтобы увидеть ответ

Вывод показывает следующее:

wsi_series,wsi_issuer,wsi_issue_number,wsi_local,wmo_block_number,wmo_station_number,station_type,year,month,day,hour,minute,latitude,longitude,station_height_above_msl,barometer_height_above_msl,station_pressure,msl_pressure,geopotential_height,thermometer_height,air_temperature,dewpoint_temperature,relative_humidity,method_of_ground_state_measurement,ground_state,method_of_snow_depth_measurement,snow_depth,precipitation_intensity,anemometer_height,time_period_of_wind,wind_direction,wind_speed,maximum_wind_gust_direction_10_minutes,maximum_wind_gust_speed_10_minutes,maximum_wind_gust_direction_1_hour,maximum_wind_gust_speed_1_hour,maximum_wind_gust_direction_3_hours,maximum_wind_gust_speed_3_hours,rain_sensor_height,total_precipitation_1_hour,total_precipitation_3_hours,total_precipitation_6_hours,total_precipitation_12_hours,total_precipitation_24_hours
0,20000,0,60355,60,355,1,2024,3,31,1,0,47.77706163,23.94046026,503,504.43,100940,101040,1448,5,298.15,294.55,80,3,1,1,0,0.004,10,-10,30,3,30,5,40,9,20,11,2,4.7,5.3,7.9,9.5,11.4
0,20000,0,60355,60,355,1,2024,3,31,2,0,47.77706163,23.94046026,503,504.43,100940,101040,1448,5,25.,294.55,80,3,1,1,0,0.004,10,-10,30,3,30,5,40,9,20,11,2,4.7,5.3,7.9,9.5,11.4
0,20000,0,60355,60,355,1,2024,3,31,3,0,47.77706163,23.94046026,503,504.43,100940,101040,1448,5,298.15,294.55,80,3,1,1,0,0.004,10,-10,30,3,30,5,40,9,20,11,2,4.7,5.3,7.9,9.5,11.4

Первая строка CSV-файла содержит заголовки столбцов, которые используются для идентификации данных в каждом столбце.

После строки заголовка есть 3 строки данных, представляющие 3 наблюдения за погодой от одной и той же станции с идентификатором станции WIGOS 0-20000-0-60355 в три разных момента времени 2024-03-31 01:00:00, 2024-03-31 02:00:00 и 2024-03-31 03:00:00.

ознакомьтесь с шаблоном aws

В wis2box-api включен набор предопределенных шаблонов сопоставления BUFR, которые установлены в директории /opt/csv2bufr/templates.

Проверьте содержимое директории /opt/csv2bufr/templates:

ls /opt/csv2bufr/templates

Вы должны увидеть следующий вывод:

CampbellAfrica-v1-template.json  aws-template.json  daycli-template.json

Давайте проверим содержимое файла aws-template.json:

cat /opt/csv2bufr/templates/aws-template.json

Это возвращает большой JSON-файл, предоставляющий сопоставление для 43 столбцов CSV.

Question

Какой столбец CSV сопоставлен с ключом eccodes airTemperature? Каковы допустимые минимальные и максимальные значения для этого ключа?

Нажмите, чтобы увидеть ответ

Используя следующую команду для фильтрации вывода:

cat /opt/csv2bufr/templates/aws-template.json | grep -i airTemperature

Вы должны увидеть следующий вывод:

{"eccodes_key": "#1#airTemperature", "value": "data:air_temperature", "valid_min": "const:193.15", "valid_max": "const:333.15"},

Значение, которое будет закодировано для ключа eccodes airTemperature, будет взято из данных в столбце CSV: air_temperature.

Минимальные и максимальные значения для этого ключа составляют 193.15 и 333.15 соответственно.

Question

Какой столбец CSV сопоставлен с ключом eccodes internationalDataSubCategory? Каково значение этого ключа?

Нажмите, чтобы увидеть ответ

Используя следующую команду для фильтрации вывода:

cat /opt/csv2bufr/templates/aws-template.json | grep -i internationalDataSubCategory

Вы должны увидеть следующий вывод:

{"eccodes_key": "internationalDataSubCategory", "value": "const:2"},

Нет CSV-столбца, сопоставленного с ключом eccodes internationalDataSubCategory, вместо этого используется постоянное значение 2, которое будет закодировано во всех файлах BUFR, созданных с этим шаблоном сопоставления.

конвертация CSV в BUFR

Давайте попробуем конвертировать файл в формат BUFR с помощью команды csv2bufr:

csv2bufr data transform --bufr-template aws-template ./aws-example.csv

Question

Сколько файлов BUFR было создано?

Нажмите, чтобы увидеть ответ

Вывод показывает следующее:

```{.copy} CLI: ... Transforming ./aws-example.csv to BUFR ... CLI: ... Processing subsets: CLI: ..... 384 bytes written to ./WIGOS_0-20000-0-60355_20240331T010000.bufr4

1#airTemperature: Value (25.0) out of valid range (193.15 - 333.15).; Element set to missing

CLI: ..... 384 bytes written to ./WIGOS_0-20000-0-60355_20240331T020000.bufr4 CLI: ..... 384 bytes written to ./WIGOS_0-20000-0-60355_20240331T030000.bufr4 CLI:

Вы не получили результат, что указывает на отсутствие значения для ключа airTemperature в файле BUFR WIGOS_0-20000-0-60355_20240331T020000.bufr4. Программа csv2bufr отказалась кодировать значение 25.0 из данных CSV, так как оно выходит за допустимые пределы 193.15 и 333.15, определенные в шаблоне сопоставления.

Обратите внимание, что преобразование CSV в BUFR с использованием одного из предопределенных шаблонов сопоставления BUFR имеет ограничения:

файл CSV должен быть в формате, определенном в шаблоне сопоставления, т.е. имена столбцов CSV должны соответствовать именам, определенным в шаблоне сопоставления
вы можете кодировать только ключи, определенные в шаблоне сопоставления
проверки качества ограничены проверками, определенными в шаблоне сопоставления

Для получения информации о том, как создать и использовать пользовательские шаблоны сопоставления BUFR, смотрите следующее практическое упражнение csv2bufr-templates.

Заключение

Поздравляем!

В этом практическом занятии вы узнали:

как получить доступ к инструментам командной строки ecCodes в контейнере wis2box-api
как использовать synop2bufr для преобразования отчетов FM-12 SYNOP в BUFR с командной строки
как использовать форму SYNOP в wis2box-webapp для преобразования отчетов FM-12 SYNOP в BUFR
как использовать csv2bufr для преобразования данных CSV в BUFR с командной строки