# 排列特征重要性
#### 功能介绍
支持用户传入一批数据样本，并据此计算各个特征的排列重要性（permutation importance）。
基本原理为，对输入的数据样本，首先完成一次推理，将评估指标作为baseline。将数据的某一特征在行数据之间随机混淆，评估预测效果，并计算指标的下降值，并以此评估特征的重要性。当混淆某一列特征，导致预测效果与baseline有较大下降时，则说明此列特征重要性较高。此处使用accuracy作为分类任务的评估指标。
注意：输入的数据需包含预测目标列的真值，且数量大于1000，以便更精确地计算预测效果指标。
另外，融合推荐分类预测大模型提供两种特征重要性，分别为模型权重特征重要性和排列特征重要性，对两种特征重要性的详细说明参见《用户指南》"使用API调用预测大模型 \> 排列特征重要性"部分。
**注意：**极简模式不提供排列特征重要性接口，即极简模式的模型不可调用该接口
#### 授权信息
账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/productdesc-pangulm/pangulm_01_0020.html)。
#### URI
POST /perm-feat-importance
获取URI方式请参见[请求URI](https://support.huaweicloud.com/api-pangulm/pangulm_05_0004.html)。
#### 请求参数
使用[Token认证](https://support.huaweicloud.com/api-pangulm/pangulm_05_0009.html#pangulm_05_0009__section94702116509)方式的请求Header参数见[表1]。
 表1请求Header参数（Token认证） 
| 参数           | 是否必选 | 参数类型   | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
|:---|:---|:---|:---|
| X-Auth-Token | 是    | String | **参数解释：** 用户Token。 用于获取操作API的权限。如[图4](https://support.huaweicloud.com/api-pangulm/pangulm_05_0009.html#pangulm_05_0009__fig10797003103)中响应消息头中X-Subject-Token的值即为Token。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 |
| Content-Type | 是    | String | **参数解释：** 发送的实体的MIME类型。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** application/json                                                                                                                                                                       |
   
使用[API Key认证](https://support.huaweicloud.com/api-pangulm/pangulm_05_0009.html#pangulm_05_0009__section148602501261)方式的请求Header参数见[表2]。
 表2请求Header参数（API Key认证） 
| 参数             | 是否必选 | 参数类型   | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
|:---|:---|:---|:---|
| X-Apig-AppCode | 是    | String | **参数解释：** API Key值。 用于获取操作API的权限。[API Key认证](https://support.huaweicloud.com/api-pangulm/pangulm_05_0009.html#pangulm_05_0009__section148602501261)响应消息头中X-Apig-AppCode的值即为API Key。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 |
| Content-Type   | 是    | String | **参数解释：** 发送的实体的MIME类型。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** application/json                                                                                                                                                                                        |
   
表3请求Body参数 
| 参数      | 是否必选 | 参数类型  | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|:---|:---|:---|:---|
| data    | 是    | Array | **参数解释：** 含义和[表3](https://support.huaweicloud.com/api-pangulm/pangulm_05_0057.html#pangulm_05_0057__request_CreateDemoInfoRequestBody)中的data参数相同。 **约束限制：** 排列特征重要性接口除提供各特征名及特征值外，还需提供预测目标列的列名及其真值（即示例中的target项），且数据数量大于1000，以便准确计算预测效果指标。 **取值范围：** 输入数据中的一组数据。 **默认取值：** 不涉及                                                                                                                                                                                                                                                                                       |
| fi_args | 是    | Dict  | **参数解释：** 特征重要性的参数，包含num_shuffle_sets、sample_num字段。 **约束限制：** num_shuffle_sets，非必填，Integer类型，代表采样混洗次数，越大则结果越准确，但耗时更高。 sample_num，非必填，Integer类型，代表单次采样混洗数据量，越大则结果越准确，但耗时更高。 **取值范围：** - num_shuffle_sets，要求\>=1，建议\>=5  - sample_num，要求\>=1000，建议\>=3500   **默认取值：** num_shuffle_sets，默认值为1。 sample_num，默认值为1000，当用户不传入此参数，或大于data数量时，直接使用全部数据，不进行采样。 |
   
#### 响应参数
**状态码： 200**
表4响应Body参数 
| 参数                 | 参数类型  | 描述                                                                                                                                                                                                                                                                                                                     |
|:---|:---|:---|
| feature_importance | Array | **参数解释：** 降序排列的各特征重要性，每项为\[特征名, 特征重要性分值\]。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 |
| cost_time          | Long  | **参数解释：** 计算耗时。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及                |
   
**状态码： 400**
表5响应Body参数 
| 参数         | 参数类型   | 描述    |
|:---|:---|:---|
| error_code | String | 错误码。  |
| error_msg  | String | 错误信息。 |
   
#### 请求示例
```
{
  "data": [
    {
      "feature_1": xx,
      "feature_2": xx,
      ...
      "feature_n": xx,
      "target": 0,
    },
    ...
    {
      "feature_1": xx,
      "feature_2": xx,
      ...
      "feature_n": xx,
      "target": 1
    }
  ],
  "fi_args":{"num_shuffle_sets": 1,
    "sample_num": 1000
  }
}
```
此处data列表的长度至少为1000，建议通过以下代码根据csv文件生成请求体（DATA_NUM为从csv文件中采样数据的数量）：
```
import random
import json
import pandas as pd
ENCODING_TYPE = "utf-8"
DATA_NUM = 1200
data_path = "path/to/xxx.csv"
df = pd.read_csv(data_path, encoding=ENCODING_TYPE)
data_list = df.to_dict("records")
data_list = random.sample(data_list, DATA_NUM)
request_data = {
    "data": data_list,
    "fi_args": {
        "num_shuffle_sets": 1,
        "sample_num": 1000,
    }
}
request_str = json.dumps(request_data)
print(request_str)
```
#### 响应示例
```
{
  "cost_time": 4.322,
  "feature_importance": [
      ["feature_2", 0.15]
       ...
      ["feature_17",0.001]
  ]
}
```
#### 状态码
请参见[状态码](https://support.huaweicloud.com/api-pangulm/pangulm_05_0019.html)。
#### 错误码
请参见[错误码](https://support.huaweicloud.com/api-pangulm/pangulm_05_0020.html)。