Руководство API
1 Подготовка к работе
1.1 Состав и содержание передаваемых материалов
  • Документация: Руководство пользователя. Файл с зависимостями requirements.txt.
  • Файл с кодом visualization.ipynb.
1.2 Запуск сервиса
Для демонстрационного запуска Продукта требуется:
  1. Установленный интерпретатор Python версии не ниже 3.8. Скачать его можно через магазин приложений операционной системы или же с официального сайта — https://www.python.org/downloads/.
  2. Установить среду для чтения файлов с расширением *.ipynb. Рекомендуется установить Jupiter Notebook (инструкция по установке представлена на официальном сайте — https://jupyter.org/install).
  3. Установить зависимости из requirements.txt.
1.3 Порядок проверки работоспособности
Для проверки работоспособности пользователь может вызвать функцию get_root(), которая возвращает json-файл с сообщением «Welcome to API!», если работоспособность сервиса не нарушена, иначе возвращает код ошибки и ее описание.
2 Описание ноутбука
Ноутбук имеет два раздела:
  1. Работа с API.
  2. Отрисовка результатов.
2.1 Работа с API
В данном разделе описаны функции, использующиеся для получения ответов от сервиса и примеры их работы.

В первой ячейке раздела описаны следующие функции:
  1. Функция get_root() — используется для проверки работоспособности соединения возвращает json-файл с сообщением «Welcome to API!», если работоспособность сервиса не нарушена, иначе возвращает код ошибки и ее описание.
  2. Функция get_last_forecast() — используется для получения прогноза на последнюю доступную дату в формате xarray.Dataset, если работоспособность сервиса не нарушена, иначе возвращает код ошибки и ее описание. Получаемый датасет содержит прогнозные значения для четырех переменных: sithick_GLORYS, usi_vsi_GLORYS_speed, usi_vsi_GLORYS_direct, sea_ice_fraction_OSTIA — на следующие трое суток, относительно последней известной даты. Пример прогноза приведён на Рисунке 1.
  3. Функция get_forecast_on_the_date(date) — используется для получения прогноза на заданную дату — date (передаётся в функцию в формате строки вида “YYYY-MM-DD”), в формате xarray.Dataset, если работоспособность сервиса не нарушена, иначе возвращает код ошибки и ее описание. Получаемый датасет содержит прогнозные значения для четырех переменных: sithick_GLORYS, usi_vsi_GLORYS_speed, usi_vsi_GLORYS_direct, sea_ice_fraction_OSTIA — на следующие трое суток, относительно заданной даты. Пример прогноза приведён на Рисунке 2
  4. Функция get_forecast_info() — используется для получения json-файла со справочной информацией, содержащей словарь доступных дат, граничные координаты рассматриваемого региона по широте и долготе, значение частоты обновления и дату последнего обновления, если работоспособность сервиса не нарушена, иначе возвращает код ошибки и ее описание.
  5. Функция get_last_assim_forecast() — используется для получения ассимилированного прогноза на последнюю доступную дату в формате xarray.Dataset, если работоспособность сервиса не нарушена, иначе возвращает код ошибки и ее описание. Получаемый датасет содержит ассимилированные прогнозные значения для переменной sea_ice_fraction_OSTIA на следующие трое суток, относительно последней известной даты. Пример прогноза приведён на Рисунке 3.
  6. Функция get_assim_forecast_on_the_date(date) — используется для получения ассимилированного прогноза на заданную дату — date (передаётся в функцию в формате строки вида “YYYY-MM-DD”), в формате xarray.Dataset, если работоспособность сервиса не нарушена, иначе возвращает код ошибки и ее описание. Получаемый датасет содержит ассимилированные прогнозные значения для переменной sea_ice_fraction_OSTIA на следующие трое суток, относительно заданной даты. Пример прогноза приведён на Рисунке 4.
  7. Функция get_assim_forecast_info() — используется для получения json-файла со справочной информацией, содержащей словарь доступных дат, граничные координаты рассматриваемого региона по широте и долготе, значение частоты обновления и дату последнего обновления, если работоспособность сервиса не нарушена, иначе возвращает код ошибки и ее описание.
  8. Функция get_model_metrics() — используется для получения json-файла со справочной информацией, содержащей список словарей с id модели и словарём её метрик: ice_conc_mae, ice_drift_speed_mae, ice_drift_speed_rmse, ise_thickness_rmse, если работоспособность сервиса не нарушена, иначе возвращает код ошибки и ее описание.
  9. Функция get_model_architectures() — используется для получения json-файла со справочной информацией, содержащей словарь с id модели и описанием её архитектуры и если работоспособность сервиса не нарушена, иначе возвращает код ошибки и ее описание.
  10. Функция get_datasets() — используется для получения json-файла со справочной информацией, содержащей словарь с id датасета и словарём его метаданных со следующими ключами: названием, описанием, словарём с источниками данных, словарём с используемыми переменными из этих источников, словарём со ссылками на эти источники, словарём с временными разрешениями источников и словарём с пространственными разрешениями источников. Если работоспособность сервиса нарушена, то функция возвращает код ошибки и ее описание.
  11. Функция login(email: str, password: str) — используется для авторизации пользователя в системе. Значения email и password передаются в функцию в виде строк. Если работоспособность сервиса нарушена, то функция возвращает код ошибки и ее описание.
  12. Функция logout() — используется для выхода пользователя из системы в текущей сессии. Если работоспособность сервиса нарушена, то функция возвращает код ошибки и ее описание.
  13. Функция register(email: str, password: str, username: str) — используется для регистрации пользователя с соответствующими почтой, паролем и ником в системе. Значения email, password и username передаются в функцию в виде строк. Если работоспособность сервиса нарушена, то функция возвращает код ошибки и ее описание.
  14. Функция get_ping(email: str, password: str, username: str) — используется для проверки качества и скорости соединения с сервером, на котором развернут сервис. Если работоспособность сервиса нарушена, то функция возвращает код ошибки и ее описание.
Во второй по счёту ячейке с кодом приведены примеры исполнения функций login(), get_root(), get_forecast_info(), get_model_metrics(), get_model_architectures(), get_datasets(). Результаты исполнения выведены в под ячейкой.
В третьей, четвёртой и пятой ячейках с кодом приведены время работы функции get_last_forecst(), get_forecast_on_the_date('2024-06-15') и get_last_forecast() соответственно. Результаты выведены под ячейками.
2.2 Отрисовка результатов
Раздел содержит две ячейки с кодом. В первой по счёту ячейке описана функция plot_results(predictions, mask, colormap, result_path, dates, var), сохраняющая результаты прогнозов переменной var из predictions по пути result_path за указанные даты dates в формате *.png. Во второй по счёту ячейке с кодом описано получение прогноза за последнюю известную дату, получение метаинформации о прогнозе и сохранение результатов прогнозирования в виде картинок в формате *.png, содержащих отдельные переменные в директорию ./results. Формат имени картинок выглядит следующим образом {YYYY-MM-DD}_{var_name}.png.