# Руководство администратора системы предиктивной аналитики

## Определения и сокращения
* БД - база данных
* ВСП - внутрисменные простои
* ГТМ - геолого-технологические мероприятия
* МВ - модель выживаемости
* ПО - программное обеспечение
* СПА - система предиктивной аналитики
* СУБД - система управления базами данных
* ЭЦН - электроцентробежный насос
* API - application programming interface (интерфейс прикладного программиста)
* AFT - accelerated failure time model (модель ускоренного времени отказа)

## Назначение и общее описание системы
Система предиктивной аналитики (СПА) предназначена для прогнозирования остановок и отказов скважинного оборудования (в частности, ЭЦН), а также для выявления аномалий в его работе с целью предотвращения остановок и отказов. Прогнозирование осуществляется на основе специализированных математических и статистических методов, применяемых к данным о работе оборудования и других параметров, характеризующих работу скважин за длительный период времени. Разделяют фазы (этапы) обучения моделей и прогнозирования (инференса) на основе обученных моделей. На этапе обучения моделям предъявляется большой объём данных за длительный период времени, содержащий информацию о произошедших искомых событиях (остановках и отказах). На этапе прогнозирования модель принимает на вход новую информацию о работе скважинного оборудования и выдаёт оценку риска наступления искомых событий (остановок и отказов). Как правило, исходные "сырые" данные до использования в процессе обучения моделей требуют предварительной обработки (препроцессинга). Для повышения качества прогнозирования используется технология генерации новых признаков (дополнительных переменных, extra variables) - feature engineering.
Для повышения качества прогнозирования в данной СПА был обучен комплекс моделей, имеющих различные гипер-параметры (горизонт планирования).

## Хранение исходного кода модулей СПА
Для хранения исходного кода программных скриптов всех подсистем СПА был создан объединённый репозиторий с помощью системы контроля версий git. Создан закрытый репозиторий в сервисе GitHub, его адрес - https://github.com/Piligrim2121/predictive-analytics-system. Для доступа к репозиторию требуется приглашение от его администратора.

## Структура системы
СПА построена по модульному принципу и включает 4 подсистемы:
* подсистема предварительной обработки исходных "сырых" данных и генерации дополнительных признаков (переменных). Включает несколько модулей (скриптов) на языке Python.
* подсистема расчёта прогноза. Включает один скрипт на языке R.
* подсистема интеграции с внешними системами - API для передачи результатов прогнозирования, например, в АРМ технолога. Включает набор скриптов на языке Python. Для реализации REST API используется микро-фреймворк Flask.
* служебная подсистема для настройки, автоматического запуска модулей и системного журналирования. Включает несколько скриптов на языке Python.

### Структура БД системы
В качестве СУБД используется Microsoft SQL Server 2019.
Структура таблиц и взаимосвязей между ними показана на диаграмме:
Ссылка на исходное изображение - https://drive.google.com/file/d/1-hiHbW98Hb5kyMXep4cQS9Mk-9VMPWWt/view?usp=share_link
Перечень таблиц и описание их назначения приведены в списке ниже:
* Model - справочник моделей, хранит название модели, горизонт прогнозирования (в днях), метрики качества прогнозирования (f1, accuracy), рассчитанные при последнем обучении
* ModelData - данные для моделей по аномалиям
* HistoryBestModel - перечень моделей, показавших наилучшее качество прогнозирования (для различных причин остановок и отказов)
* Prediction - результаты прогнозирования за каждые сутки, полученные различными моделями
* PredictType - тип прогнозируемого события (отказ, остановка, аномалия)
* Reason - справочник причин остановок и отказов (с указанием типа прогнозируемого события)
* Scale - данные по шкалам (пороговые значения зелёной, жёлтой и красной зон) для каждой модели
* ParameterModelCoef - коэффициенты параметров для различных моделей с указанием условий применения
* Parameter - перечень параметров, их описание и теги
* ParameterType - тип параметра (телеметрия, ВСП, доп.переменные, погода)
* ParameterAVGData - предобработанные значения параметров с указанием кода скважины и даты расчёта
* Well - перечень скважин с указанием их кодов в различных системах (АСОДУ, АРМтех и др.)
* Weather - погодные данные, полученные с сервиса ГисМетео (температура, давление, точка росы)
* SchedulerSettings - настройки планировщика заданий (название, описание, команда для выполнения, время запуска (часы, минуты), флаг активности)
* SystemLog - системный журнал (дата и время, уровень логгирования, тип события, имя скрипта, сообщение)
* VSP - данные о внутрисменных простоях
* GTM - данные о проведённых геолого-технологических мероприятиях (ГТМ)
* Outliners - граничные значения для удаления выбросов по различным параметрам
* ENC - данные о замене ЭЦН
* SKV - данные по датам ввода скважин в эксплуатаию

### Перечень зависимостей модулей
Для запуска модулей СПА, написанных на яызке Python необходимо установить интерпретатор Python версии 3.10 и следующие пакеты (с указанием версий):
* Flask 2.2.2
* Flask-Cors 3.0.10
* Flask-Migrate 3.1.0
* Flask-RESTful 0.3.9
* Flask-SQLAlchemy 2.5.1
* Jinja2 3.1.2
* Mako 1.2.3
* MarkupSafe 2.1.1
* SQLAlchemy 1.4.41
* Werkzeug 2.2.2
* alembic 1.8.1
* aniso8601 9.0.1
* certifi 2022.9.24
* charset-normalizer 2.1.1
* click 8.1.3
* colorama 0.4.5
* et-xmlfile 1.1.0
* greenlet 1.1.3
* idna 3.4
* itsdangerous 2.1.2
* numpy 1.23.3
* openpyxl 3.0.10
* pandas 1.5.0
* pip 22.2.2
* psycopg 3.1.2
* psycopg2 2.9.3
* pyodbc 4.0.34
* python-dateutil 2.8.2
* pytz 2022.2.1
* requests 2.28.1
* setuptools 63.2.0
* six 1.16.0
* tqdm 4.64.1
* typing-extensions 4.3.0
* tzdata 2022.4
* urllib3 1.26.12

Для запуска скриптов прогнозирования на языке R необходимо установить интерпретатор R версии 4.2.1 и следующий набор пакетов:
* reticulate
* rjson
* lubridate
* tidyverse
* survival
* RODBC
* DBI
* odbc
* reshape2
* zoo

### Подсистема предобработки
Программные модули (скрипты), осуществляющие предобработку исходных данных, расположены в подкаталоге data_preprocessing корневой папки СПА (https://github.com/Piligrim2121/predictive-analytics-system/tree/master/data_preprocessing). "Точкой входа" в подсистему является скрипт main.py

#### Список скриптов
* main.py - стартовый скрипт предобработки, запускает другие скрипты
* get_target_7.py - формирует датафрейм с целевой переменной, который используется для формирования датафреймов для других скриптов
* get_model_target.py - обработка данных ВСП
* get_tm_daily_3.py - обработка данных телеметрии
* get_extra_vars.py - генерация доп.переменных
* DB.py - утилитарные функции для работы с БД

### Подсистема прогнозирования
Скрипт расчёта прогнозов, а также файлы сохранённых обученных моделей расположены в папке prediction (https://github.com/Piligrim2121/predictive-analytics-system/tree/master/prediction)

#### Список скриптов
* Models - папка с файлами сохранённых моделей в формате RDS
* Predictor.R - загрузка моделей, выполнение прогнозирования, сохранение результатов в БД

#### Перечень моделей

| № | Тип модели | Тип события | Причина | Имя файла | Горизонт планирования | Описание | F1 | Accuracy |
| - | -------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- |
| 1 | МВ Кокса | Отказ | 7 | failure_main_model_10_days.rds | 10 дней | Прогноз наступления события отказа в течение 10 дней | 0,148 | 0,776 |
| 2 | МВ Кокса | Отказ | 7 | failure_main_model_20_days.rds | 10 дней | Прогноз наступления события отказа в течение 20 дней | 0,361 | 0,845 |
| 3 | МВ Кокса | Отказ | 7 | failure_main_model_30_days.rds | 10 дней | Прогноз наступления события отказа в течение 30 дней | 0,505 | 0,788 |
| 4 | МВ Кокса | Отказ | 7 | failure_main_model_60_days.rds | 10 дней | Прогноз наступления события отказа в течение 60 дней | 0,483 | 0,854 |
| 5 | МВ Кокса | Отказ | 7 | background_model_BakerHughes.rds | 30 дней | В модели используются скважины, у которых установлен ЭЦН - Baker Hughes.<br/> В переменной ecn_manufact отфильтровать по значению 'Baker Hughes' | 0,355 | 0,882 |
| 6 | МВ Кокса | Остановка | 6 | VSP_ZSP_model_10_days.rds | 10 дней | Произойдет остановка по причине 'защита от срыва подачи' в течение наблюдаемого периода | 0,045 | 0,876 |
| 7 | МВ Кокса | Остановка | 6 | VSP_ZSP_model_20_days.rds | 20 дней | Произойдет остановка по причине 'защита от срыва подачи' в течение наблюдаемого периода | 0,081 | 0,821 |
| 8 | МВ Кокса | Остановка | 6 | VSP_ZSP_model_30_days.rds | 30 дней | Произойдет остановка по причине 'защита от срыва подачи' в течение наблюдаемого периода | 0,107 | 0,830 |
| 9 | МВ Кокса | Остановка | 5 | VSP_ZP_model_10_days.rds | 10 дней | Произойдет остановка по причине 'защита от перегруза' в течение наблюдаемого периода | 0,147 | 0,889 |
| 10 | МВ Кокса | Остановка | 5 | VSP_ZP_model_20_days.rds | 20 дней | Произойдет остановка по причине 'защита от перегруза' в течение наблюдаемого периода | 0,154 | 0,828 |
| 11 | МВ Кокса | Остановка | 5 | VSP_ZP_model_30_days.rds | 30 дней | Произойдет остановка по причине 'защита от перегруза' в течение наблюдаемого периода | 0,120 | 0,728 |
| 12 | МВ Кокса | Остановка | 8 | VSP_main_model_10_days.rds | 10 дней | Произойдет остановка по какой-либо целевой причине в течение наблюдаемого периода | 0,126 | 0,581 |
| 13 | МВ Кокса | Остановка | 8 | VSP_main_model_20_days.rds | 20 дней | Произойдет остановка по какой-либо целевой причине в течение наблюдаемого периода | 0,145 | 0,579 |
| 14 | МВ Кокса | Остановка | 8 | VSP_main_model_30_days.rds | 30 дней | Произойдет остановка по какой-либо целевой причине в течение наблюдаемого периода | 0,483 | 0,854 |
| 15 | МВ Кокса | Остановка | 4 | VSP_snizhenie_izolyacii.rds | 30 дней | Произойдет остановка по причине 'снижение изоляции' в течение наблюдаемого периода | 0,380 | 0,800 |
| 16 | МВ AFT Экспоненциальная | Отказ | нет | background_AFT_model_exp_30_days.rds | 30 дней | Произойдет отказ в течение наблюдаемого периода | 0,448 | 0,786 |
| 17 | МВ AFT Вейбулла | Отказ | нет | background_AFT_model_wei_30_day.rds | 30 дней | Произойдет отказ в течение наблюдаемого периода | 0,482 | 0,787 |
| 18 | МВ AFT Логнормальная | Отказ | нет | background_AFT_model_nor_30_days.rds | 30 дней | Произойдет отказ в течение наблюдаемого периода | 0,454 | 0,726 |
| 19 | МВ AFT Логлогистическая | Отказ | нет | background_AFT_model_log_30_days.rds | 30 дней | Произойдет отказ в течение наблюдаемого периода | 0,489 | 0,787 |
| 20 | МВ AFT Экспоненциальная | Отказ | нет | background_AFT_model_exp_60_days.rds | 60 дней | Произойдет отказ в течение наблюдаемого периода | 0,456 | 0,835 |
| 21 | МВ AFT Вейбулла | Отказ | нет | background_AFT_model_wei_60_days.rds | 60 дней | Произойдет отказ в течение наблюдаемого периода | 0,448 | 0,786 |
| 22 | МВ AFT Логнормальная | Отказ | нет | background_AFT_model_nor_60_days.rds | 60 дней | Произойдет отказ в течение наблюдаемого периода | 0,470 | 0,859 |
| 23 | МВ AFT Логлогистическая | Отказ | нет | background_AFT_model_log_60_days.rds | 60 дней | Произойдет отказ в течение наблюдаемого периода | 0,398 | 0,749 |
| 24 | Лог. Регрессия | Отказ | нет | failure_reason_model_r0.rds | нет | Модель определяет причину отказа на скважине (R-0 или неR-0) | 0,398 | 0,749 |

### Подсистема интеграции (API)
Скрипт расчёта прогнозов, а также файлы сохранённых обученных моделей расположены в папке apiflask (https://github.com/Piligrim2121/predictive-analytics-system/tree/master/apiflask)

#### Список скриптов
* api_guide.py - JSON с описанием запросов API и их параметров
* app.py - контроллеры обработки запросов API
* models.py - классы моделей для работы с БД системы
* routing_bd.txt - настройки соединения с БД

### Служебная подсистема
Скрипты, выполняющие служебные функции, расположены в каталоге services проекта СПА (путь в репозитории - https://github.com/Piligrim2121/predictive-analytics-system/tree/master/services).

#### Список скриптов и файлов
* config.json - конфигурационный файл, содержащий настройки подключения к БД, а также путь к исполняемому файлу интерпретатора Python
* StartSystem.py - скрипт для запуска планировщика заданий
* startsystem.bat - пакетный файл ОС Windows для запуска скрипта планировщика

## Интерпретация результатов прогнозирования
В результате прогнозирования остановок и отказов с помощью соответствующих моделей формируется вещественное число, характеризующее степень риска возникновения остановки или отказа.
Для корректной интерпретации полученного значения необходимо произвести ряд операций:
1. умножить вещественное значение, полученное на выходе модели на коэффициент масштабирования, соответствующий данной модели
2. если полученное значение превышает максимальное для данное модели, то берётся максимальное значение
3. полученное значение сравнивается с границами зон (красной, жёлтой):
* если полученное значение лежит в диапазоне от минимального до границы жёлтой зоны, то оно находится в зелёной зоне - риск отказа/остановки минимальный, никаких действий предпринимать не надо.
* если полученное значение лежит в диапазоне от границы жёлтой зоны до границы красной зоны, то оно находится в жёлтой зоне - существует вероятность отказа оборудования, требуется продолжить наблюдение, дополнительно проверить показатели систем.
* если полученное значение лежит в диапазоне от границы красной зоны до максммального значений, то оно находится в красной зоне - высокий риск отказа, необходимо срочно предпринять действия по устранению причин возможного отказа.

### Таблица шкал для различных моделей
| № | № модели | Мин.значение | Макс.значение | Коэф.масштабирования | Граница жёлтой зоны | Граница красной зоны |
| - | -------- | -------- | -------- | -------- | -------- | -------- |
| 1 | 1 | 0 | 125 | 0,4 | 30 | 40 |
| 2 | 2 | 0 | 250 | 0,2 | 30 | 40 |
| 3 | 3 | 0 | 250 | 0,2 | 30 | 40 |
| 4 | 4 | 0 | 250 | 0,2 | 26 | 30 |
| 5 | 12 | 0 | 20 | 2,5 | 20 | 30 |
| 6 | 13 | 0 | 20 | 2,5 | 20 | 30 |
| 7 | 14 | 0 | 20 | 2,5 | 20 | 30 |
| 8 | 6 | 0 | 25 | 2 | NULL | 30 |
| 9 | 7 | 0 | 25 | 2 | NULL | 30 |
| 10 | 8 | 0 | 25 | 2 | NULL | 30 |
| 11 | 9 | 0 | 25 | 2 | NULL | 30 |
| 12 | 10 | 0 | 25 | 2 | NULL | 30 |
| 13 | 11 | 0 | 25 | 2 | NULL | 30 |
| 14 | 15 | 0 | 25 | 2 | NULL | 40 |

### Пример интерпретации результатов
Например, модель № 1 (Прогноз наступления события отказа в течение 10 дней) выдала значение 2,87. Необходимо умножить его на соответствующий коэффициент масштабирования: 2,87\*0,4 = 1,148. Далее необходимо определить в границах какой зоны находится это значение. В данном случае оно лежит между минимальным значением и границой жёлтой зоны. Таким образом, оно находится в зелёной зоне - риск отказа минимальный, никаких действий предпринимать не надо.

Предположим, что та же модель № 1 для другой скважины выдала значение 81,3. После умножения на коэффициент масштабирования (0,4) получаем значение 32,52 - оно находится в диапазоне от границы жёлтой зоны до границы красной. Таким образом, оно находится в жёлтой зоне - существует вероятность отказа оборудования, требуется продолжить наблюдение, дополнительно проверить показатели систем.