DSM_hse_perm_ru 0.2
Библиотека прогнозных моделей DSM
Requires Python: <4.0,>=3.10

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

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

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

## Быстрый старт
1. Предполагается что на целевой машине уже установлен Python версии 3.10
2. Создание виртуального окружения при помощи poetry
poetry позволяет произвести кроссплатформенную установку приложения при этом избежать возможных конфликтов
Установка стандартная, либо с использованием pip
<pre>
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
</pre>

2. Установка зависимостей сборка пакета, выполняется в соответствии с набором указанных в pyproject.toml, который содержит информацию о проекте. Предваритльно переходим в каталог с этим файлом.
```bash
poetry install --no-root --extras docs
poetry shell # Активация виртуального окружения
```

3. Сборка пакета для локального размещения
```bash
poetry build
```
После чего сборка проекта будет размещена в dist текущего каталога 
```bash
ls -l dist/
```
4. Размещение в репозитории PyPi
Для размещения в публичном репозитории у Вас должна быть настроена учетная запись на ресурсе: https://pypi.org, а также 
должен быть настроен сам poetry. Ниже приводится последовательность команд для этого
```bash
poetry config repositories.testpypi https://test.pypi.org/legacy/ # настройка 
poetry publish -r testpypi --username YOUR_USERNAME --password YOUR_PASSWORD --build
```
5. Документирование библиотеки
```bash
poetry run sphinx-quickstart 
# далее следуем инструкциям пакета документирования 
```
```python
from DSM import dsm_timeseries
from DSM import SDaysAVR
from DSM import rmse
```
6. Определяется входная структура данных (используется pd.DataFrame или dsm_structure)
```python
df = pd.read_csv('some_file.csv')
```
или 
```python
df = dsm_structure(
    name = 'some_name',
    data = pd_df,
    value_column_name = 'some_name'   
)
```
Также могут быть добавлены необязательные параметры (см. "Используемый формат данных")
7. Построение прогноза осуществляется как:
```python
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. <b>Utils</b> - утилиты для предобработки входных данных, содержит методы:
    - загрузки данных из файлов csv/xlsx
    - методы заполнения пропущенных значений
    - трансформации в доли ПДК
    - преобразования временных меток данных
2. <b>Structures</b> - модуль, предоставляющий обертку для стандартных структур данных для работы с функционалом библиотеки:
    - Представлен структурой dsm_timeseries
3. <b>Models</b> - модуль базовых моделей прогнозирования, содержит модели прогнозирования значений концентраций вредных веществ в точке контроля. Реализованный список моделей:
    - S Days AVR
    - T Days AVR
    - HW
    - SARIMA
    - STA
    - Day Features LR
    - Day Features NN
4. <b>Ensemble</b> - модуль ансамблевых моделей прогнозирования. Содержит методы построения ансамблей из базовых моделей. Реализованный список моделей:
    - EM LR
    - EM NN
5. <b>Model_selection</b> - модуль селективных моделей прогнозирования. Содержит методы селективного выбора из результатов базовых моделей. Список реализованных моделей:
    - Naive Selector
    - S Days Selector
    - NN Selector
6. <b>Metrics</b> - модуль расчета метрик для прогноза. Содержит методы расчета метрик качества регрессии - полученного прогноза. Список реализованных метрик:
    - RMSE
    - MAPE
    - RSQUARE
## Описание используемых моделей
#### T Days AVR
Модель усреднения по предыдущим дням в разные недели. Не имеет тренировочного периода и базируется на раннее известных данных.

```python
from DSM import TDaysAVR
```
#### S Days AVR
Модель усреднения данных в последовательности предыдущих N дней. Не имеет тренировочного периода и базируется на раннее известных данных.

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

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

```python
from DSM import SARIMA
```
Является надстройкой над statsmodels.SARIMAX
#### STA
Авторегрессионная модель с рекурсивным фильтром. Имеет период обучения. Использует RLS-фильтр для подбора весов.

```python
from DSM import STA
```
#### Day Features LR
Модель извлечения признаков с линейной регрессией. Использует кастомную генерацию признаков для совершения прогноза. Имеет период обучения. Для подбора весов используется линейная регрессия (RLS-фильтр).

```python
from DSM import DayFeaturesLR
```
#### Day Features NN
Модель извлечения признаков с нелинейной регрессией. Использует кастомную генерацию признаков для совершения прогноза. Имеет период обучения. Для подбора весов используется многослойный персептрон (MLP) с использованием keras.

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

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

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

```python
from DSM import NaiveSelector
```
#### S Days Selector
Выбор модели с наименьшей ошибкой по нескольким дням. Подбор наилучшего прогноза для текущего дня на основе результатов предыдущих N дней. Использует результаты базовых моделей из DSM.models.

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

```python
from DSM import NNSelector
```
## Структура
Структура dsm_timeseries определена в DSM.structures. 

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

Параметры для определения структуры:
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)

## Документация
Все методы и функции библиотеки документированы с использованием docstrings.

Подключена возможность сбора документации с использованием Sphinx:
1. Установить Sphinx в базовый интерпретатор
```bash
pip install sphinx
```
2. Сборка документации из основной директории библиотеки:
```bash
sphinx-build -b html docs/source docs/build
```
3. Собранная документация в формате html будет перемещена в docs/build
```bash
cd docs/build
```