# **EEMs-toolkit**

EEMs-toolkit是一个可以在Python上对三维荧光（EEM）进行平行因子分析（PARAFAC）的工具包，功能大致类似于MATLAB的drEEM toolbox。





## 开发环境

Python版本3.9.6，采用的额外的包及版本见下表：

|     包     |  版本  |
| :--------: | :----: |
|   numpy    | 1.24.1 |
|   pandas   | 1.5.2  |
| matplotlib | 3.6.2  |
|   scipy    | 1.9.3  |
|  tensorly  | 0.7.0  |
|   tlviz    | 0.1.6  |
|   joblib   | 1.2.0  |

------
## 安装EEMs-toolkit
```python
pip install EEMs-toolkit==0.1.0
```


## 功能简介

1. 数据导入

   - 样本日志导入
   - 样本导入
   - 空白导入
   - 紫外光谱导入

2. 预处理

   - 扣除空白

     原始数据：

     ![image-20230119210013034](/Example/pictures/image-20230119210013034.png)

     

     去除空白：

     ![image-20230119210117607](/Example/pictures/image-20230119210117607.png)

   - 去除不需要的波长部分

     ![image-20230119210214514](/Example/pictures/image-20230119210214514.png)

   - 拉曼单位化

     ![image-20230119210258801](/Example/pictures/image-20230119210258801.png)

   - 稀释因子校正

   - 内滤效应校正

     ![image-20230119210344367](/Example/pictures/image-20230119210344367.png)

   - 去除瑞丽（Rayleigh）散射和拉曼（Raman）散射

     ![image-20230119210434896](/Example/pictures/image-20230119210434896.png)

   - 缺失值插值

     ![image-20230119210529378](/Example/pictures/image-20230119210529378.png)

   - 荧光矩阵平滑（高斯核）

3. PARAFAC分析

   - 采用非负约束计算不同组分数的模型

   - 绘制异常样本测试图

     ![image-20230119210653963](/Example/pictures/image-20230119210653963.png)

   - 去除异常样本

   - 重新计算模型，运行分半分析（S4C4T2）

   - 确认组分数（核一致性图，因子相似度图）

     ![image-20230119210738168](/Example/pictures/image-20230119210738168.png)

     ![image-20230119210756988](/Example/pictures/image-20230119210756988.png)

4. 结果展示

   - 核一致性和方差解释率

   - 因子相似度

     ![image-20230119210858476](/Example/pictures/image-20230119210858476.png)

   - 分半分析结果

     ![image-20230119211156840](/Example/pictures/image-20230119211156840.png)

   - 组分图绘制

     ![image-20230119211432900](/Example/pictures/image-20230119211432900.png)

   - 载荷图绘制

     ![image-20230119211450807](/Example/pictures/image-20230119211450807.png)

   - 模型结果导出，包括FMax，Em loadings，Ex loadings，组分图数据

5. 其他功能

   - 预处理后样本数据导出

   - OpenFluor文件导出，可上传对比数据库

   - 区域积分（FRI）计算，结果导出
   - 荧光指数（Fluorescence index、Freshness index、Humification index，Biological index）计算，结果导出
   - 光谱斜率SR计算，结果导出

------



## 测试示例

使用drEEM toolbox中demofiles.zip里的**EEMs、Abs1cm、BlankEEMs**进行演示。**不同代码块代表不同的Python文件**。

1. 数据导入&预处理

   ```python
   # -*- coding = utf-8 -*-
   from EEM_toolkit import EEMs_Dataset, read_sample_log, read_eems, read_abs, read_blank
   import pickle
   
   """
   读取的目录到时候根据自己文件保存的地方进行修改
   此例文件太多，读取文件耗时，为了不重复读取，将数据读取再预处理后保存到本地
   预处理中内滤效应校正和拉曼单位化可以不用做，取决于自己的需要
   去除散射再插值是为了能够进行PARAFAC，这里不支持包含nan的计算，而不去除散射则会影响计算结果
   建议分别在去除散射和插值之后浏览所有EEM，观察设置去除的散射宽度是否合适
   """
   sample_log = read_sample_log(r'd:\Documents\PycharmProjects\parafac\Example\SampleLog.xlsx')
   Abs, Abs_wave = read_abs(sample_log, r'd:\Documents\PycharmProjects\parafac\Example\abs')
   blank = read_blank(sample_log, r'd:\Documents\PycharmProjects\parafac\Example\blank')
   c, fl = read_eems(d, r'd:\Documents\PycharmProjects\parafac\Example\eem')
   
   x, ex, em = c
   Data = EEMs_Dataset(x, ex, em, file_list=fl)
   Data.plot_eem_by1()
   Data.minus_the_blank(blank)
   # Data.plot_eem_by1()
   Data.raman_areal(blank)
   Data.sub_dataset([], Data.ex < 250, Data.em > 600)
   # Data.plot_eem_by1()
   Data.inner_effect_correct(Abs_wave, Abs)
   # Data.plot_eem_by1()
   Data.cut_ray_scatter([15, 15], [20, 15])
   Data.cut_ram_scatter([15, 15], [10, 10])
   # Data.plot_eem_by1()
   Data.miss_value_interpolation()
   # Data.plot_eem_by1()
   with open('eem_data.pickle', 'wb') as f:
       pickle.dump(Data, f)
   
   ```

2. 开始分析

   ```python
   import pickle
   
   """
   1. 导入刚才预处理好并保存的数据，加载变量
   """
   with open('eem_data.pickle', 'rb') as f:
       data = pickle.load(f)
   """
   2. （浏览所有样本，记录明显存在异常，即与其他样本显著不同或存在测试问题的样本编号）
   """
   # data.plot_eem_by1()
   """
   3. 进行不同组分数的PARAFAC计算
   """
   data.multi_non_parafac_cal([2, 6])
   """
   4. 查看异常样本测试图，尝试不同的组分数，观察其异常样本（即位于图右方和上方的样本，冒号前为样本编号），记录其样本编号
   """
   for i in range(2, 6 + 1):
       data.plot_outlier_test(i)
   
   ```

   ```python
   import pickle
   
   """
   5. 去除异常样本后，重新进行不同组分数的PARAFAC计算，此处为简化过程，只去除了部分异常样本，主要为看起来显著不同的样本。实际进行操作时建议去除异常样本后重新建立模型查看异常样本测试图，反复记录异常样本编号再去除，直到其leverage基本不大于0.3，这样后续分析成功率更高，无论去除了多少样本，冒号前面的样本编号不会发生变化，每次记录后添加到最开始去除异常样本的位置即可
   """
   with open('eem_data.pickle', 'rb') as f:
       data = pickle.load(f)
   data.sub_dataset([90, 110, 111, 112, 113, 114, 186, 187, 188, 189])
   data.multi_non_parafac_cal([2, 6])
   # for i in range(2, 6 + 1):
   #     data.plot_outlier_test(i)
   """
   6. 后续步骤只有一个目的，确定组分数。首先进行分半分析，这会在窗口中打印出每个组分的因子相似度及是否经过相似度检验。也可以画图查看不同组分数的因子相似度，在0.95之上可认为是一致的。再综合考虑核一致性（不总是可靠）、不同组分数的模型残差，选择相对较好的组分数（因子相似度高、核一致性高、残差为随机分布，不存在明显的峰），事实上在这一步一般人就会选择满足相似度的最大组分数，而在drEEM中，满足此条件的模型可认为是经过验证的，可以结束此过程得到结果了
   """
   data.split_analysis([2, 6])
   data.plot_factor_similarity()
   data.plot_core_consistency_and_explanation()
   for i in range(2, 6 + 1):
       data.plot_residual_error(i)
   """
   7. 确定组分数，后面的步骤只剩出图和数据导出（如果需要）：分半分析图、组分图、载荷图、（FMax图）
   """
   fac = 6
   #  出图
   data.plot_split_result(fac)
   data.plot_fingers(fac)
   data.plot_loadings(fac)
   # data.plot_fmax(fac)
   #  导出数据
   data.parafac_result_output(fac)
   # data.eems_output()
   # data.open_fluor(fac)
   
   ```

   





