Библиотека прогнозных моделей DSM

Общая информация

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

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

Рассматриваемый пул моделей прогнозирования включает в себя устойчивые предиктивные модели, ансамблевые модели и модели селективного выбора:

• Модель усреднения по предыдущим дням в разные недели;
• Модель усреднения данных в последовательности предыдущих N дней;
• Модель Хольта-Винтерса;
• Модель SARIMA;
• Авторегрессионная модель с рекурсивным фильтром;
• Модель извлечения признаков с линейной регрессией;
• Модель извлечения признаков с нелинейной регрессией;
• Ансамблевая модель с линейной регрессией;
• Ансамблевая модель с нелинейной регрессией;
• Выбор модели с наименьшей ошибкой прошлого дня;
• Выбор модели с наименьшей ошибкой по нескольким дням;
• Выбор модели с помощью нейронной сети.

Быстрый старт

1. Предполагается что на целевой машине уже установлен Python версии 3.10
2. Создание виртуального окружения при помощи poetry poetry позволяет произвести кроссплатформенную установку приложения при этом избежать возможных конфликтов Установка стандартная, либо с использованием pip

for Linux: curl -sSL https://install.python-poetry.org | python3 -
for Windows: (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
pip install poetry

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

poetry install --no-root --extras docs
poetry shell # Активация виртуального окружения

3. Сборка пакета для локального размещения

poetry build

После чего сборка проекта будет размещена в dist текущего каталога

ls -l dist/

4. Размещение в репозитории PyPi Для размещения в публичном репозитории у Вас должна быть настроена учетная запись на ресурсе: https://pypi.org, нужно предварительно получить API-токен, а также должен быть настроен сам poetry. Ниже приводится последовательность команд для этого

poetry config repositories.testpypi https://test.pypi.org/legacy/ # настройка 
poetry config pypi-token.pypi your-api-token                      # настройка 
poetry publish --build

5. Документирование библиотеки

mkdir DSM/docs
cd DSM/docs
poetry run sphinx-build -b html . build 

При синхронизации с удаленной веткой development автоматически происходит выгрузка документации по DSM на http://eco-grant-ai.devops-03.hse.perm.ru

from DSM import dsm_timeseries
from DSM import SDaysAVR
from DSM import rmse

6. Определяется входная структура данных (используется pd.DataFrame или dsm_structure)

df = pd.read_csv('some_file.csv')

или

df = dsm_structure(
    name = 'some_name',
    data = pd_df,
    value_column_name = 'some_name'   
)

Также могут быть добавлены необязательные параметры (см. "Используемый формат данных") 7. Построение прогноза осуществляется как:

result = model.predict(
    df,
    datetime_column_name='time_column_name', 
    value_column_name='value_column_name', 
    day_points=count_day_points, 
    method='All'
)

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

В результате описанных действий будет построен базовый краткосрочный-суточный прогноз.

Используемый формат данных

Структура входных данных для модели должна иметь формат Padas DataFrame или внутреннюю структуру dsm_timeseries

1. В случае использования Pandas DataFrame классический фрейм с определенными столбцами времени и таргета для прогноза, пример:

   time	value
   2023-01-01 00:00:00	5.824310
   2023-01-01 01:00:00	7.003579
   2023-01-01 02:00:00	6.759247
   2023-01-01 03:00:00	4.314874
   2023-01-01 04:00:00	8.952418
   где:

   time - имя стобца с временной меткой типа datetime64[ns]

   value - имя столбца таргета типа float64

2. Для создания объекта dsm_timeseries используются входные данные форматов: pd.DataFrame или np.ndarray. Использование структуры несет следующие преимущества:

   1. Автоматическая проверка типов данных ключевых столбцов;
   2. Автоматический расчет временного интервала между значениями;
   3. Полная совместимость с моделями библиотеки

Подробную информацию о структуре dsm_timeseries см. "Структура"

Структура библиотеки

Публичная версия библиотеки DSM содержит 6 основных модулей:

1. Utils - утилиты для предобработки входных данных, содержит методы:
   • загрузки данных из файлов csv/xlsx
   • методы заполнения пропущенных значений
   • трансформации в доли ПДК
   • преобразования временных меток данных
2. Structures - модуль, предоставляющий обертку для стандартных структур данных для работы с функционалом библиотеки:
   • Представлен структурой dsm_timeseries
3. Models - модуль базовых моделей прогнозирования, содержит модели прогнозирования значений концентраций вредных веществ в точке контроля. Реализованный список моделей:
   • S Days AVR
   • T Days AVR
   • HW
   • SARIMA
   • STA
   • Day Features LR
   • Day Features NN
4. Ensemble - модуль ансамблевых моделей прогнозирования. Содержит методы построения ансамблей из базовых моделей. Реализованный список моделей:
   • EM LR
   • EM NN
5. Model_selection - модуль селективных моделей прогнозирования. Содержит методы селективного выбора из результатов базовых моделей. Список реализованных моделей:
   • Naive Selector
   • S Days Selector
   • NN Selector
6. Metrics - модуль расчета метрик для прогноза. Содержит методы расчета метрик качества регрессии - полученного прогноза. Список реализованных метрик:
   • RMSE
   • MAPE
   • RSQUARE

Описание используемых моделей

T Days AVR

Модель усреднения по предыдущим дням в разные недели. Не имеет тренировочного периода и базируется на раннее известных данных.

from DSM import TDaysAVR

S Days AVR

Модель усреднения данных в последовательности предыдущих N дней. Не имеет тренировочного периода и базируется на раннее известных данных.

from DSM import SDaysAVR

HW

Модель Хольта-Винтерса. Модель тройного экспоненциального сглаживания с ориентацией на сезонные периоды. Имеет период обучения.

from DSM import HW

SARIMA

Модель SARIMA (Seasonal Autoregressive Integrated Moving Average), сезонная модель авторегрессии и скользящего среднего с интеграцией, представляет собой расширение модели ARIMA, включающее в себя компоненты для учета сезонности.

from DSM import SARIMA

Является надстройкой над statsmodels.SARIMAX

STA

Авторегрессионная модель с рекурсивным фильтром. Имеет период обучения. Использует RLS-фильтр для подбора весов.

from DSM import STA

Day Features LR

Модель извлечения признаков с линейной регрессией. Использует кастомную генерацию признаков для совершения прогноза. Имеет период обучения. Для подбора весов используется линейная регрессия (RLS-фильтр).

from DSM import DayFeaturesLR

Day Features NN

Модель извлечения признаков с нелинейной регрессией. Использует кастомную генерацию признаков для совершения прогноза. Имеет период обучения. Для подбора весов используется многослойный персептрон (MLP) с использованием keras.

from DSM import DayFeaturesNN

EM LR

Ансамблевая модель с линейной регрессией. Использует результаты базовых моделей из DSM.models. Подбор коэффициентов прогнозов осуществляется с помощью линейной регрессии (RLS-фильтр).

from DSM import EMLR

EM NN

Ансамблевая модель с нелинейной регрессией. Использует результаты базовых моделей из DSM.models. Подбор коэффициентов прогнозов осуществляется с помощью многослойнего персептрона (MLP).

from DSM import EMNN

Naive Selector

Выбор модели с наименьшей ошибкой прошлого дня. Подбор наилучшего прогноза для текущего дня на основе результатов предыдущего. Использует результаты базовых моделей из DSM.models.

from DSM import NaiveSelector

S Days Selector

Выбор модели с наименьшей ошибкой по нескольким дням. Подбор наилучшего прогноза для текущего дня на основе результатов предыдущих N дней. Использует результаты базовых моделей из DSM.models.

from DSM import SDaysSelector

NN Selector

Выбор модели с помощью нейронной сети. Подбор наилучшего прогноза для текущего дня на основе результатов классификации. Использует результаты базовых моделей из DSM.models.

from DSM import NNSelector

Структура

Структура dsm_timeseries определена в DSM.structures.

Создание структуры возможно из pd.DataFrame или нескольких np.ndarray, представляющих одномерные массивы для каждого типа обязательных столбцов: время и значение.

Параметры для определения структуры:

1. name: наименование датасета (str)
2. data: исходные данные прогноза - фрейм с временем и значением (pd.DataFrame) или np.ndarray со значениями таргета и дополнительными параметрами прогноза (например, погода)
3. value_column_name (опционально): в случае использования pd.DataFrame - наименование столбца таргета (str)
4. interval (опционально): интервал между значениями, определяется в формате (m,h,d), например: 20m, 1h, 1d (str)
5. time_column_name (опционально): в случае использования pd.DataFrame, наименование столбца с временной меткой (str)
6. value_column_index (опционально): в случае использования np.ndarray, индекс столбца таргета, в случае размерности более 1, остальные столбцы используются как дополнительные признаки (int)
7. datetime_arr (опционально): в случае использования np.ndarray, список временных меток. Проверяется строгое совпадение с размерностью данных таргета (list)