## Dance User Guide
Dance 是一个针对 Dock 模块中由 ensemble docking 产生的对接分数矩阵，进行数据预处理、建模与评估的功能模块。  
庞大的对接分数矩阵可以通过Dance模块快速进行数据清洗、划分并用于机器学习建模过程。

### 数据准备 Data preparation
数据预处理部分。

导入pyCADD.Dance模块的Dancer对象
```python
from pyCADD.Dance import Dancer
dancer = Dancer()
```

添加Ensemble Docking结果矩阵以进行预处理
```python
# 阳性分子的结果矩阵
dancer.add_pos_dataset('your_positive_matrix_path')
# 阴性分子的结果矩阵
dancer.add_neg_dataset('your_negative_matrix_path')
```

如果数据集分子的活性未知，使用add_dataset方法添加数据集，活性标签将被设置为Undefined。
```python
dancer.add_dataset('your_matrix_path')
```

使用prepare_data方法来快速完成数据预处理，包括合并所有添加的数据集，并以0填充缺失值。
```python
dancer.prepare_data()
# 如果不需要填充缺失值 使用
# dancer.prepare_data(fill_na=False)

# 如果需要指定其他值填充缺失值 使用
# dancer.prepare_data(fill_na=True, fill_na_value=0)
```

返回并查看处理完成的合并数据
```python
dancer.get_merged_data()
```

保存数据集到文件 
pickle文件将被保存至dm_reult/data_pickle/
csv文件将被保存至dm_result/data_csv/

```python
# .pkl/.pickle or .csv
dancer.save('your_file_name')
```

### 建模与评估 Modeling and Evaluation
建模与模型评估部分。

导入pyCADD.Dance模块的Matrix与Evaluator对象
```python
from pyCADD.Dance import Matrix, Evaluator
```

载入预处理完成的数据集 并划分训练与测试集
```python
matrix = Matrix.from_pickle('your_file_name')
# 也可以直接输入DataFrame 并指定随机种子
# matrix = Matrix(your_dataframe)
# 训练集与测试集划分 指定测试集比例、随机种子以及标签列名 下为默认值
# matrix.split_train_test_data(test_size=0.25, random_seed=42, label_col='activity')
# 查看训练集与测试集
# train_data = matrix.get_train_data()
# test_data = matrix.get_test_data()
```

使用划分好的数据集建立评估器实例
```python
evaluator = Evaluator(matrix)
```

导入所有需要的模型 并创建模型实例
```python
from sklearn.linear_model import LogisticRegression
# from sklearn.ensemble import RandomForestClassifier
# from xgboost import XGBClassifier

lr = LogisticRegression()
# rf = RandomForestClassifier()
# xgb = XGBClassifier()
```

设定自定义的模型超参数网格空间
pyCADD.Dance提供了LR RF 与 GBT的默认超参数 您也可以自主指定
```python
from pyCADD.Dance.algorithm import default_params
default_lr_params = default_params.LR_DEFAULT_PARAMS
# default_rf_params = default_params.RF_DEFAULT_PARAMS
# default_gbt_params = default_params.GBT_DEFAULT_PARAMS
# your_params_dict = {'params1':params1, 'params2':params2, ...}
```

使用评估器实例执行超参数搜索 并将最佳超参数赋予模型
```python
best_lr_params = evaluator.search_params(lr, default_lr_params)
# best_rf_params = evaluator.search_params(rf, default_rf_params)
# best_gbt_params = evaluator.search_params(gbt, default_gbt_params)

lr.set_params(**best_lr_params)
# rf.set_params(**best_rf_params)
# gbt.set_params(**best_gbt_params)
```

将模型添加至评估器实例中 查看模型参数信息
```python
evaluator.add_clf(lr, 'LR')
# evaluator.add_clf(rf, 'RF')
# evaluator.add_clf(gbt, 'GBT')

evaluator.print_classifier_info()
# 获取所有已添加的模型dict
# evaluator.get_clfs_dict()
```

使用训练集数据执行多重交叉验证 默认使用30次重复的4折交叉验证   
关于 30x4 交叉验证 参阅[论文](https://pubs.acs.org/doi/10.1021/acs.jcim.1c00511)
```python
# 默认评分将使用sklearn.metrics 的 roc_auc_score 函数 可以自定义评分函数
# from sklearn.metrics import roc_auc_score    
cv_results = evaluator.repeat_cv(n_repeats=30, k_folds=4, random_seed=42, 
                                # score_func=roc_auc_score
                                )
# 返回值cv_results为字典类型 并被保存在evaluator.cv_results中 
# 结果同步被保存于当前目录下的cv_results.json文件中
# 执行 n x k次交叉验证 记录了每次的结果及单构象排序的最佳值、均值、最差值及标准误差

# {'best_scp: ...',
# 'mean_scp: ...',
# 'worst_scp: ...',
# 'std_scp: ...',
# 'clf_cv_results: {
#                   'LR' : [...],
#                   '...' : [...],
#                  }
# }

# 使用print_cv_results函数打印交叉验证结果
evaluator.print_cv_results()
```

使用测试集数据执行模型测试 并计算模型的评分
```python
evaluator.testset_eval()
# 结果被保存于当前目录下的testset_eval_results.json文件中
```