Netcdf Reader

Общее описание сервиса

Этот сервис реализован на основе FastAPI и предназначен для работы с файлами в формате CDF. Сервис позволяет загружать, обрабатывать, усреднять и выполнять статистическую обработку данных из CDF-файлов. FastAPI обеспечивает быстрый и удобный интерфейс для выполнения этих операций через REST API.

Подготовка данных

Источник данных

Сервис загружает данные с сайта NOAA на основе конфигурации в файле preload.yml. Поддерживаются ежемесячные данные температуры воздуха, u и v компонентов ветра. При каждом новом запуске приложения проверяется целостность и актуальность данных, при необходимости данные обновляются с указанного сайта автоматически.

Эндпоинты для работы с CDF файлами

Загрузка данных

• /api/v1/netcdf/load — Загружает файл с заданного URL, указанного в параметре запроса url. В зависимости от содержимого URL (ежедневные или ежемесячные данные) файл сохраняется в соответствующей директории. Если файл уже существует, возвратится сообщение об этом.

Список и информация о файлах

• /api/v1/netcdf/list — Возвращает список всех файлов в директории data, где хранятся загруженные данные. Для каждого файла указано его имя и размер в мегабайтах (МБ).

• /api/v1/netcdf/info — Принимает имя файла (параметр filename) и возвращает мета данные CDF-файла. Данная информация включает размеры, координаты, переменные и их атрибуты, глобальные атрибуты и диапазон времени (если доступен).

• /api/v1/netcdf/variables_list — Отображает HTML-страницу со списком доступных переменных из NOAA, их описаниями и форматами данных, доступных для анализа. Это помогает пользователям лучше понять, какие данные они могут использовать в анализе.

Управление файлами

• /api/v1/netcdf/shorten — Укорачивает указанный файл CDF (параметр filename) до последних 36 временных шагов и сохраняет его в директорию tests. Если файл не найден, возвращается ошибка 404.

• /api/v1/netcdf/update_test_data — Генерирует тестовые запросы на основе заданного количества записей (параметр size). Создает файл requests.yaml с указанным количеством тестовых запросов, каждый из которых включает случайные точки и уровни для различных метрик (например, температуры и ветра).

Загрузка и обновление Docker

• /api/v1/docker/images — Вычисляет и возвращает текущий размер контейнера в гигабайтах (ГБ), исключая системные директории /proc, /sys, и /dev.

Загрузка и кеширование данных

В зависимости от значения переменной окружения PRELOAD, сервис либо загружает данные автоматически при запуске, либо загружает их только по запросу пользователя через эндпоинты. Если переменная PYTEST_VERSION установлена, сервис использует тестовую директорию для загрузки данных, а также отключает OpenTelemetry для тестов.

Работа с погодными данными

Сервис предоставляет несколько эндпоинтов для получения и обработки погодных данных. Эти эндпоинты позволяют выполнять различные операции, такие как получение данных для конкретных точек, обработка данных за период, усреднение данных и другие статистические вычисления.

Эндпоинты для обработки погодных данных

1. Получение погодных данных для заданных точек на определенную дату

• POST /api/v1/weather/in_points

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

Параметры запроса:

• date (datetime): Дата, для которой требуется получить данные (формат YYYY-MM-DDTHH:MM:SS).
• points (List[Point]): Список точек с указанными координатами и диапазонами уровней давления.
  • lat (float): Широта точки.
  • lon (float): Долгота точки.
  • maxLevel (int): Максимальный уровень высоты (FL).
  • minLevel (int): Минимальный уровень высоты (FL).

Пример запроса:

json { "date": "2023-08-01T00:00:00", "points": [ { "lat": 55.7558, "lon": 37.6176, "maxLevel": 300, "minLevel": 100 } ] }

2. Получение усредненных погодных данных за период для заданных точек

POST /api/v1/weather/in_period

Описание: Возвращает усредненные погодные данные за указанный период для заданных точек.

Параметры запроса:

date_from (datetime): Начальная дата периода (формат YYYY-MM-DDTHH:MM:SS).
date_to (datetime): Конечная дата периода.
points (List[Point]): Список точек (см. описание выше).

Пример запроса:

json { "date_from": "2023-01-01T00:00:00", "date_to": "2023-12-31T00:00:00", "points": [ { "lat": 34.0522, "lon": -118.2437, "maxLevel": 300, "minLevel": 100 } ] }

3. Получение усредненных погодных данных за последние N лет для указанного месяца и точек

POST /api/v1/weather/in_points_avg/

POST /api/v1/weather/in_points_avg/{n:int}/

Описание:
Возвращает усредненные погодные данные за последние N лет для указанного месяца и заданных точек.

Параметры запроса:

date (datetime): Дата, определяющая месяц для усреднения.
points (List[Point]): Список точек.
n (int, optional): Количество лет для усреднения (по умолчанию 10).

Пример запроса: json { "date": "2023-07-01T00:00:00", "points": [ { "lat": 51.5074, "lon": -0.1278, "maxLevel": 300, "minLevel": 100 } ] } Примечание: Если указать n, например /in_points_avg/15/, данные будут усреднены за последние 15 лет.

4. Получение усредненных погодных данных за последние N лет для указанных месяцев и точек

POST /api/v1/weather/in_points_avg_selected_months/

POST /api/v1/weather/in_points_avg_selected_months/{n:int}/

Описание:
Возвращает усредненные погодные данные за последние N лет для заданных месяцев и точек.

Параметры запроса:

months (List[int]): Список месяцев (числа от 1 до 12).
points (List[Point]): Список точек.
n (int, optional): Количество лет для усреднения (по умолчанию 10).

Валидация:
Все значения в months должны быть в диапазоне от 1 до 12.

Пример запроса:
json { "months": [6, 7, 8], "points": [ { "lat": 35.6895, "lon": 139.6917, "maxLevel": 300, "minLevel": 100 } ] } Примечание: Этот эндпоинт позволяет получать усредненные данные за конкретные месяцы (например, за летние месяцы) за указанный период лет.

Пример структуры ответа:
json [ { "lat": 35.6895, "lon": 139.6917, "data": [ { "year_from": "2014", "year_to": "2024", "months": [ 6, 7, 8 ], "levels": [ { "level": 138.0, "windSpeed": 8.46, "windDirection": 78.06, "temperature": 2.82 }, { "level": 182.89, "windSpeed": 10.06, "windDirection": 80.44, "temperature": -5.07 }, { "level": 235.74, "windSpeed": 12.29, "windDirection": 82.64, "temperature": -15.25 } ] } ] } ]

Визуальный анализ погодных данных

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

Визуализаия статистических данных на всей карте

GET /visualize_variance
Описание:
Эндпоинт выполняет расчет и визуализацию одной дисперсии, стандартного отклонения и коэффициента вариации для выбранного типа данных: температура, компонент ветра или скорости и направления ветра. Результат представляется в виде графика и возвращается в формате PNG.
Пример запроса:
/visualize_variance?month=1,2&min_level=1000&max_level=1000&years=10&report_type=3&data_type=1

Параметры запроса:
month (str): Список месяцев, разделенных запятыми, например, I-й квартал - "1,2,3". min_level (int): Минимальная высота (от 10 до 1000). max_level (int): Максимальная высота (от 10 до 1000). years (int, optional): Количество лет для усреднения (от 2 до 40). report_type (int): Тип отчета: 1 - дисперсия, 2 - стандартное отклонение, 3 - коэффициент вариации. data_type (int): Тип данных: 1 - температура, 2 - v-компонента, 3 - u-компонента, 4 - скорость ветра, 5 - направление ветра.

График показывает коэффициент вариации температуры в январе на высотах от 200 до 250 гПа (что соответствует высотам полета самолетов, примерно 10–12 км) за последние 10 лет. Коэффициент вариации отражает степень изменчивости температуры относительно среднего значения: более высокие значения указывают на значительную изменчивость, а более низкие — на стабильность данных.
На этом графике видно, что на этих высотах изменчивость температуры варьируется от 0.01 ближе к полюсам до 0.025 ближе к экватору. Это говорит о том, что на экваторе температурная изменчивость выше и составляет около 2.5% от среднего значения в январе за последние 10 лет.
Интересно, что если провести аналогичный анализ для уровней, близких к поверхности, мы увидим обратную картину: у экватора изменчивость температуры будет ниже, чем в полярных зонах.

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

GET /plot_time_series
Описание:
Эндпоинт генерирует временной ряд для выбранного типа данных (температура, скорость ветра, направление ветра или компоненты ветра) на заданной широте и долготе за указанные месяцы. Результат визуализируется в виде графика и возвращается в формате PNG.
Пример запроса:
/stat/plot_time_series?month=1&min_level=1000&max_level=1000&lat=55.7558&lon=37.6176&data_type=1

Параметры запроса:
month (str): Список месяцев для анализа, разделенных запятыми, например, "1,2,3". min_level (int): Минимальная высота в гектопаскалях (гПа), диапазон от 10 до 1000. max_level (int): Максимальная высота в гПа, диапазон от 10 до 1000. lat (float): Широта точки, для которой выполняется анализ. lon (float): Долгота точки, для которой выполняется анализ. data_type (int): Тип данных для построения временного ряда: 1 - температура (°C), 2 - v-компонента ветра (м/с), 3 - u-компонента ветра (м/с), 4 - скорость ветра (м/с), 5 - направление ветра (градусы).

График показывает динамику температуры в точке с координатами lat=55.7558 и lon=37.6176, что соответствует московскому региону. Данные построены за январь, на высоте, близкой к поверхности земли. Данные доступны с 1979г. по 2024г.

Тестирование

Описание тестирования сервисов

Сервис поддерживает тестирование для проверки корректности работы всех функций.

Запуск тестов и проверки корректности работы

Команды и инструкции для запуска тестов и проверки работоспособности сервиса.

Дополнительные материалы

Источники данных и полезные ресурсы

Месячные данные получены отсюда NOAA downloads

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