Metadata-Version: 2.1
Name: k2health
Version: 0.0.5
Summary: K2data内部的设备健康分析模板工具包
Home-page: https://www.k2data.com.cn
Author: K2data
Author-email: admin@k2data.com.cn
License: MIT License
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pandas
Requires-Dist: openpyxl
Requires-Dist: scikit-learn

# K2Health
K2Health是[K2Assets](https://www.k2data.com.cn/K2A)提供的设备健康模板开发包（以下简称SDK），它提供了一套分析流程，协助数据分析师利用从设备采集的时序数据构造数学模型，进而对设备健康状况进行评分。

## 一、安装

安装SDK最新版本：
```
pip install -U k2health
```

本文档中使用到的样例文件：
- 样例数据文件：[baoming_sample_data.csv.zip](https://gitlab.kstonedata.k2/data_analysis/k2_magic/raw/dev/tests/k2health/sampledata/baoming_sample_data.csv.zip)
- 样例参数表文件：[baoming_config.xlsx](https://gitlab.kstonedata.k2/data_analysis/k2_magic/raw/dev/tests/k2health/sampledata/baoming_config.xlsx)


## 二、使用SDK

### 2.1 SDK概述
在SDK中`Pipeline`类代表整个分析流程，它由多个分析步骤组成，每个步骤也对应的类名如下：
- 数据清洗： `DataCleaner`
- 工况识别： `ConditionPartitioner`
- 模型训练： `ModelTrainer`
- 残差分析： TODO
- 健康评分： TODO

用户通过`参数表文件`向分析流程提供必要的配置参数，例如哪些测点作为要预测的测点、使用何种数学模型做预测等等。`参数表文件`是一个Excel格式的文件，它包含四个sheet，每个sheet代表一组参数用于不同的分析步骤：
- 测点配置：`point_config`
- 设备信息：`device_config`
- 设备树：`device_tree`
- 模型配置：`model_config`

我们期望在大多数情况下，通过调整参数表中的配置，就可以满足设备健康分析的要求并达到较好的效果。

### 2.2 使用默认分析

默认方式是指按`Pipeline`所定义的顺序执行每个分析步骤，并且每个步骤使用的处理逻辑也是默认的。示例代码如下：

```
from k2health.pipeline import *

config_file = "./health/sampledata/baoming_config.xlsx"

point_config = pd.read_excel(config_file, sheet_name='point_config')
x_col = ['motor_current', 'inlet_temperature', 'oil_temperature', 'total_inlet_flow', 'total_power']
y_col = ['motor_bearing_D_temperature', 'motor_bearing_D_vibX', 'motor_bearing_D_vibY',
         'motor_bearing_ND_temperature', 'motor_bearing_ND_vibX', 'motor_bearing_ND_vibY']
cleaner = DataCleaner(point_config, y_col, x_col)

device_config = pd.read_excel(config_file, sheet_name='device_config')
device_tree = pd.read_excel(config_file, sheet_name='device_tree')
partitioner = ConditionPartitioner(device_config, device_tree)

model_config_sheet = pd.read_excel(config_file, sheet_name='model_config')
trainer = ModelTrainer(y_col, model_config_sheet)

# 使用默认的数据处理器
pipeline = Pipeline(
    cleaner=cleaner,
    partitioner=partitioner,
    trainer=trainer
)

data = pd.read_csv("./health/sampledata/baoming_sample_data.csv")
pipeline.process(data)
```

### 2.3 定制化分析

定制化方式是指在每个分析步骤基础上增加额外的处理逻辑，或者重写原有的处理逻辑，以满足特定的业务需求。此时用户需要开发自己的分析步骤类，并将它放到分析流程里。

例如希望在默认的数据清洗完成后，额外对数据再做一次填充空值的处理。实现步骤如下：

1、首先创建一个继承`DataCleaner`的子类`CustomDataCleaner`，实现`process`方法：

```
class CustomDataCleaner(DataCleaner):
    def process(self, data: DataFrame) -> DataFrame:
        # 先进行默认处理
        data = super().process(data)  
        
        # 再进行定制处理
        data = data.fillna(-1)
        return data
```

2、在分析流程里引用`CustomDataCleaner`：

```
from k2health.pipeline import *

config_file = "./health/sampledata/baoming_config.xlsx"

point_config = pd.read_excel(config_file, sheet_name='point_config')
x_col = ['motor_current', 'inlet_temperature', 'oil_temperature', 'total_inlet_flow', 'total_power']
y_col = ['motor_bearing_D_temperature', 'motor_bearing_D_vibX', 'motor_bearing_D_vibY',
         'motor_bearing_ND_temperature', 'motor_bearing_ND_vibX', 'motor_bearing_ND_vibY']

# 使用定制的分析步骤
cleaner = CustomDataCleaner(point_config, y_col, x_col)

device_config = pd.read_excel(config_file, sheet_name='device_config')
device_tree = pd.read_excel(config_file, sheet_name='device_tree')
partitioner = ConditionPartitioner(device_config, device_tree)

model_config_sheet = pd.read_excel(config_file, sheet_name='model_config')
trainer = ModelTrainer(y_col, model_config_sheet)

pipeline = Pipeline(
    cleaner=cleaner,
    partitioner=partitioner,
    trainer=trainer
)

data = pd.read_csv("./health/sampledata/baoming_sample_data.csv")
pipeline.process(data)
```

