# Calibration 分析流程

注意

此文档已过时，推荐阅读最新版本

一、校准流程初始化
- 1 读取编码并初始化分析流程
- 2 创建校准项目列表 (analysislist)
二、执行校准流程
三、结果文件输出

说明

示例来源：下述所有示例说明的数据来源为《PCS校准检测盒》CPC-0001。
参数来源：Database (DB)、calibration.json、static.json、instrument.json、common.json
参数来源格式说明：

数据库.表.列名：例如 DB.cartridge.analysis_type_id，表示该参数是获取自数据库Database中Cartridge表对应的 analysis_type_id 列。
数据库.表：例如 DB. analysis_type，表示该参数是获取自数据库 Database 中 Analysis_type 表。
Cartridge Info.spray_voltag_pos|neg ：竖线 “｜”，表示 “或”

# 一、校准流程初始化

# 1 读取编码并初始化分析流程

环节概述:将试剂盒插入进样口后，设备自动读取当前试剂盒绑定的编码 (Cartridge Code)。点击一键检测后，在数据库中查询所对应的分析类型，并初始化对应的分析流程。
参数来源:试剂盒RFID绑定的编号、DB.cartridge.analysis_type_id、DB.analysis_type

示例说明

内容	对应值
试剂盒RFID绑定的编码	CPC-0001
cartridge.analysis_type_id	2
analysis_type	Calibration

# 2 创建校准项目列表 (analysis_list_)

环节概述：创建本次校准流程需要执行的校准项目。
参数来源：
质量校准 calibration.json/parameters.mass_calibration.enable = 1 (默认开启)

# 二、执行校准流程

# 1 获取分析参数analysis_params

环节概述：获取质量校准所需的参数；根据上次校准的历史记录，设置进样量的相关参数；设置系统极性为POS
参数来源：calibration.json/parameters.mass_calibration
参数说明：参见MOS Doc / Guide / 方法参数配置指南
进样量相关参数设置：
上次校准进样量(lastest_inj_size) ：根据进样量历史记录(mass_calibration.inj_size_history)，排序后取中位数
上次校准进样量上限(latest_inj_size_max_) ：上次校准进样量 + 10 (mass_calibration.inj_size_window = 10) 该参数介于20-60之间，若计算值大于60时，取60作为上限。
上次校准进样量下限(latest_inj_size_min_) ：上次校准进样量 - 10 (mass_calibration.inj_size_window = 10) 该参数介于20-60之间，若计算值小于20时，取20作为下限。

# 2 分析参数核查

# 2.1 标准峰核查

环节概述：判断符合扫描范围的标准峰数量是否少于3个。
参数来源：analysis_params_.algorithms.calib_mass_axis.std_peak_list
参数内容：[74.096, 130.159, 242.284, 354.409, 455.29, 466.535, 578.66, 690.785]
判断依据：遍历std_peak_list中的每个标准峰，并判断该标准峰是否在扫描范围之内(50～1000)，并将符合的标准峰添加至标准峰列表(std_peak_list_in_range)中。
判断结果：
标准峰数量 < 3，流程停止并报错CalibMassInRangeStdPeaksError (5001，默认配置文件不会出现此异常)
标准峰数量 ≥ 3，继续核查两个主峰(242.284, 466.535)是否在扫描范围之内

# 2.2 主峰核查

环节概述：检查主峰是否在扫描范围之内。
参数来源：analysis_params_.algorithms.calib_mass_axis.std_peak_1 & std_peak_2
参数说明：std_peak_1 = 242.284，std_peak_2 = 466.535
核查依据：判断两个主峰是否在扫描范围之内(50～1000)
核查结果：
二者均在扫描范围之内，则继续执行后续流程；
主峰1不在扫描范围内，则将标准峰列表(std_peak_list_in_range)中的第二个标准峰作为主峰，继续执行后续流程；
主峰2不在扫描范围内，则将标准峰列表(std_peak_list_in_range)中的最后一个标准峰作为主峰，继续执行后续流程。

# 3 质量轴校准 (3轮校准)

# 3.1 执行DRE流程

DRE参数整合

环节概述：整合DRE参数，用于执行DRE扫描流程。
参数来源：DB.cartridge、calibration.json/parameters.mass_calibration.dre
参数说明：参见MOS Doc / Guide / 方法参数配置指南
示例说明：

内容	对应值	来源
polarity	POS	代码默认
spray_voltage	4500	DB.cartridge.spray_voltage_pos
dre_mode	TIC	calibration.json/parameters.mass_calibration.dre
dual_point_mode	0	calibration.json/parameters.mass_calibration.dre
max_times	10	calibration.json/parameters.mass_calibration.dre
average	1	calibration.json/parameters.mass_calibration.dre
delay	0	calibration.json/parameters.mass_calibration.dre
inj_lmco_mz	50	calibration.json/parameters.mass_calibration.dre
method_type	MS1	calibration.json/parameters.mass_calibration.dre
min_step_size	0.01	calibration.json/parameters.mass_calibration.dre
notch_enable	0	calibration.json/parameters.mass_calibration.dre
notch_mz_tol	0.5	calibration.json/parameters.mass_calibration.dre
targeted_tic	9000	calibration.json/parameters.mass_calibration.dre
targeted_tic_max	12000	calibration.json/parameters.mass_calibration.dre
targeted_tic_min	3000	calibration.json/parameters.mass_calibration.dre
update_inj_size	1	calibration.json/parameters.mass_calibration.dre
inj_size_init	latest_inj_size	首轮DRE的初始进样量为代码计算，计算方式见上文；第2、3轮DRE的初始进样量为上一轮DRE最佳谱图的进样量。
inj_size_max	latest_inj_size_max_	代码计算，计算方式见上文。
inj_size_min	latest_inj_size_min_	代码计算，计算方式见上文。

执行DRE扫描流程
判断DRE返回的结果状态
环节概述：判断DRE流程的结果状态
判断结果：

DRE结果失败，停止校准流程；
DRE结果成功，继续执行后续流程。

# 3.2 校准质量轴

DRE谱图寻峰
参数来源：
calibration.json/parameters.mass_calibration.algorithms.peak_picking_mass_ms1
示例说明：

内容	对应值
mass_bin_pts	500
max_count	1000
min_intensity_abs	8E3
min_intensity_rel	0
top_count	30

获取方法参数和谱图参数
环节概述：
获取DRE谱图采集时所用的方法参数和谱图参数。
参数来源：
方法参数 (scan_method):
calibration.json/parameters.mass_calibration.dre.method & static.json/parameters.method_parameters_default & dre.json/parameters/method
谱图参数 (spec_parameters):
instrument.json/parameters.spec_params

示例说明 (方法参数)：

内容	对应值	来源
method_type	MS1	calibration.json/parameters.mass_calibration.dre.method
polarity	POS	代码默认
spray_voltage	4500	DB.cartridge.spray_voltage_pos
inj_size	DRE_best_inj_size	DRE_result
inj_lmco_mz	50	calibration.json/parameters.mass_calibration.dre.method
scan_mass_start	50	dre.json/parameters/method
scan_mass_end	1000	dre.json/parameters/method
scan_speed	1	dre.json/parameters/method
pt_per_th	100	static.json/parameters/method_parameters_default
scan_q	0.75	static.json/parameters/method_parameters_default
trap_q	0.3	static.json/parameters/method_parameters_default
average	1	calibration.json/parameters.mass_calibration.dre.method
delay	0	calibration.json/parameters.mass_calibration.dre.method
repeat	1	代码默认

标准峰和主峰转换及计算标准峰位置偏差值
标准峰转换：
遍历标准峰列表(std_peak_list_in_range)中的每个标准峰，将该标准峰由m/z转换为dac和position的形式，并记录到标准峰表(std_peaks)中。
示例说明：
详细数据形式可在mrz中查看，详细位置为Analysis/result/mass_axis_calib_result/ 0｜1｜2 / mass_axis_calib_data/std_peaks (0、1、2分别为第1、2、3轮轴校准)
主峰转换：
将主峰1(m/z = 242.284)和主峰2(m/z = 466.535) 由m/z转换为position的形式。
计算标准峰位置偏差值：
std_peak_position_delta = calib_mass_shift_max × pt_per_th (首轮位置偏差为16000个位置，第二、三轮位置偏差为1000)
特殊说明：calib_mass_shift_max 源自于instrument.json/parameters.spec_params，出厂默认为160 (质量数)，在第一轮轴校准完成后，直接将该参数设置为10(质量数)。
实测峰表准备
实测峰表准备：
遍历DRE谱图的30个峰，按照position由小到大排序，并记录到实测峰表(peaks)中。
示例说明：
详细数据形式可在mrz中查看，详细位置为Analysis/result/mass_axis_calib_result/ 0｜1｜2 / mass_axis_calib_data/peaks (0、1、2分别为第1、2、3轮轴校准)
最少保留峰数量及最低峰强阈值计算
最少保留峰数量：标准峰数量(std_peaks) + 2 (默认有8个标准峰，实测谱图保留强度排序前10的峰用于后续拟合)
最低峰强阈值：
实测峰数量 ≥ 最少保留峰数量，选择最后一个保留峰的强度作为最低峰强阈值；
实测峰数量 < 最少保留峰数量，选择最后一个实测峰的强度作为最低峰强阈值。
最小拟合峰数量判断
判断依据：判断实测谱图的峰数量是否不小于最小拟合匹配数量(min_fit_number)。
参数来源：analysis_params_.algorithms.calib_mass_axis.min_fit_number = 4
判断结果：
实测峰数量 < 4，流程停止并报错CalibMassAxisPeakNumberError(5021)
实测峰数量 ≥ 4，继续执行后续流程
遍历实测峰表，组合成峰对(peak_1_position, peak_2_position)
1. 计算峰位置偏差
  𝛥 peak_1_position = | std_peak_1_position - peak_1_position | 实测值与理论值的偏差
  𝛥 peak_2_position = | std_peak_2_position - peak_2_position | 实测值与理论值的偏差
  𝛥 position - 𝛥 std_position = abs ( | peak_1_position - peak_2_position | - | std_peak_1_position - std_peak_2_position | ) 实测值两点间距与理论值两点间距的偏差
  以上任意一个偏差值大于标准峰位置偏差值(16000,1000)，则跳过当前峰对。
2. 将 (peak_1_position, std_peak_1_mz) 和 ( peak_2_position, std_peak_2_mz) 进行线性拟合，计算曲线的斜率(slope)和截距(intercept)，从而得到线性拟合公式。
3. 遍历标准峰表，获取当前标准峰的m/z (cur_std_mz)，同时遍历实测峰表，将每个峰的position带入公式，计算出对应的m/z (cur_mz)。计算𝛥mz = | cur_mz - cur_std_mz |并判断
  条件1：当cur_std_mz ≤ std_peak_1_mz，且 𝛥mz < 质量匹配容差(calib_mass_axis.mass_match_tol = 1)或根据mass_match_rel_tol调整的相对容差( |cur_std_mz - std_peak_1_mz| × 0.015)
  条件2：当cur_std_mz 介于 std_peak_1_mz和 std_peak_2_mz之间，且 𝛥mz < 质量匹配容差(calib_mass_axis.mass_match_tol = 1)
  条件3：当cur_std_mz ≥ std_peak_2_mz，且 𝛥mz < 质量匹配容差(calib_mass_axis.mass_match_tol = 1)或根据mass_match_rel_tol调整的相对容差( |cur_std_mz - std_peak_2_mz| × 0.015)
  满足上述任一条件，即认为当前实测峰与当前标准峰匹配，记录到匹配峰对列表中(matched_peak_pair_list)。如果当前标准峰已匹配到其他实测峰，则根据两个实测峰的峰强度，选择最大强度的峰作为匹配峰。
4. 遍历匹配峰对列表(matched_peak_pair_list)，过滤实测峰强度低于最低峰强阈值，统计剩余峰数量
  若剩余峰数量 < 2，忽略本次拟合结果，直接进行下一组峰对的拟合；
  若剩余峰数量 ≥ 2，则将当前峰对(peak, std_peak)及拟合参数信息(fit_num、c0(截距)、c1(斜率)、r2)记录到线性拟合数据列表(liner_fit_data_list)中，继续下一组峰对的拟合。
线性拟合数据列表排序
按照拟合匹配数量(fit_number) 由大到小排序；匹配数量相同时，按R2大小进行排序。
示例说明：
详细数据形式可在mrz中查看，详细位置为Analysis/result/mass_axis_calib_result/ 0｜1｜2 / mass_axis_calib_data/ liner_fit_data (0、1、2分别为第1、2、3轮轴校准)
最佳线性拟合数据选定
判断依据：判断线性拟合数据列表是否唯空
判断结果：
若列表为空，则流程停止并报错CalibMassAxisNoBestLinearFitError(5022)
若列表不为空，将列表中首个拟合数据作为最佳，并继续执行后续流程。
拟合匹配数判断
判断依据：最佳拟合数据的匹配数量大于最小拟合匹配数量(min_fit_number)。
判断结果：
若匹配数量 < 4，则流程停止并报错CalibMassAxisFitNumberError (5023)
若匹配数量 ≥ 4，则继续执行后续流程。
峰位置检查
判断依据：
遍历最佳拟合数据的每组峰对，计算实测峰位置和标准峰位置的偏差( |peak.position - std_peak.position| )，与标准峰位置偏差值(std_peak_position_delta, 16000 | 1000) 进行比较。
判断结果：
若偏差较大，则流程停止并报错CalibMassAxisPeakPositionError (5024)
若偏差在范围内，将最佳拟合数据的所有峰对保存到结果中，并继续执行后续流程。
示例说明：
详细数据形式可在mrz中查看，详细位置为Analysis/result/mass_axis_calib_result/ 0｜1｜2 / mass_axis_calib_data/ matched_peaks (0、1、2分别为第1、2、3轮轴校准)
缺失峰对的继承(仅第2、3轮)
判断依据：当继承功能开启，且本轮匹配峰对的数量小于标准峰数量，同时上轮的匹配峰对数量不为0。
判断结果：
若不能同时满足上述3个条件，则不继承缺失的峰对。
若同时满足上述3个条件，则从上一轮的峰对中选择本轮缺失峰对进行补充(上一轮缺失，本轮同样缺失的无法继承)。
计算average dac (仅第2、3轮)
环节概述：获取本轮和之前所有峰对数据，遍历每个峰对应的dac值，相加后取均值，得到该实测峰的average dac，并记录到averaged_matched_peak_pair列表中。
计算coefs
使用每个峰的average dac进行二项式拟合计算c0、c1、c2
参数来源：
poly_n = 2 analysis_params_.algorithms.calib_mass_axis
scan_q = 0.75 static.json/parameters/method_parameters_default
更新参数
更新与校准相关的谱图参数，用于下一轮质量轴校准。最后一轮质量轴校准完成后，更新参数用于m/z偏差的检验和检测器增益的校准。
calib_mass_shift_max = 10 (设备出厂首次校准时，参数默认为160，在第一轮校准后直接改为10，后续再校准此参数均为10。)
mass_calib.coefs = {poly_fit.c0, poly_fit.c1, poly_fit.c2}
检验m/z偏差 (仅第3轮)
环节概述：
使用更新的参数，将每个实测峰的dac转换为m/z，并与对应的标准峰m/z计算偏差值。取偏差值中的最大值与delta_mz_max(0.3)比较
判断结果：
若m/z偏差 > 0.3，则流程停止并报错CalibMassAxisDeltaMassError(5025)
若m/z偏差 ≤ 0.3，则质量轴校准完成，进行检测器增益的校准。

# 4 检测器增益校准

# 4.1 正模式增益校准

DRE谱图寻峰
环节概述：使用第三轮质量轴校准采集的DRE谱图再次寻峰
参数来源： calibration.json/parameters.mass_calibration.algorithms.peak_picking_mass_ms1
示例说明：

内容	对应值
mass_bin_pts	50
max_count	100000
min_intensity_abs	0.001
min_intensity_rel	0
top_count	100000

创建同位素峰表
环节概述：遍历isotope_list_list的每个同位素峰m/z，并补充峰强度(intensity = 1)，记录在同位素峰表中。
参数来源：calibration.json/parameters.mass_calibration. isotope_list_list
同位素峰匹配
环节概述：使用上述同位素峰表，在DRE谱图中进行峰匹配，并记录到匹配列表中(matched_peaks)
参数来源：
ms1_mz_tol = 0.5 calibration.json/parameters.mass_calibration.algorithms.fragments_matching_gain
threshold = 0.001 calibration.json/parameters.mass_calibration.algorithms.fragments_matching_gain
fragment_match_any = 0 代码默认
获取实测谱图的analog_data和counting_data
计算analog_area和counting_area
1. 遍历匹配列表中每个峰，获取对应的peak_position和peak_mz
2. 在counting_data中查找该峰的左右边界(idx_left_edge和idx_right_edge)
  idx_left_edge 从峰位置开始向左搜索，直到找到m/z < (peak_mz - ms1_mz_tol) 或者counting_data不再递增的点。
  idx_right_edge 从峰位置开始向右搜索，直到找到m/z > (peak_mz + ms1_mz_tol) 或者counting_data不再递减的点。
3. 根据峰的左右边界，计算每个峰的analog_area和counting_area并分别记录到analog_area_list和counting_area_list中

计算每个峰的gain

遍历counting_area_list，带入公式计算
- gain = q / 1.6e-19 / counting_area
- q = analog_area × current_per_pt × second_ per_pt
- current_per_pt = adc_vref_range / 65536.0 / pre_amp1_gain / pre_amp2_gain
- second_ per_pt = 1.0 / pt_per_th / scan_speed / 1000.0
  参数来源：

参数	来源
adc_vref_range = 2.5	static.json/parameters
pre_amp1_gain = 20000	static.json/parameters
pre_amp2_gain = 10	static.json/parameters
pt_per_th = 100	static.json/parameters.method_parameters_default
scan_speed = 1	static.json/parameters.method_parameters_default

计算均值
环节概述：将每个峰的gain相加，计算gain_mean和标准差gain_psd。将gain_mean记录到detector_gain_history中。
示例说明：
详细数据形式可在mrz中查看，详细位置为Analysis/result/detector_gain_results/ 0｜1 (0、1分别为正模式和负模式)
计算历史平均gain
环节概述：根据detector_gain_history，去掉最大值和最小值，剩余的gain求均值，作为最终正模式的gain。
参数来源：detector_gain_history instrument.json/parameters | parameters_neg .spec_params

# 4.2 负模式增益校准

参数整合
环节概述：负模式的增益校准需要在负模式下采集一张谱图
参数来源：
- method_params 谱图采集的参数与正模式下谱图采集参数相同，其中部分参数需要变更，如下：
  - polarity NEG
  - spray_voltage 3500 数据库中试剂盒信息
  - inj_size 第三轮DRE最佳进样量 × 1.05 (analysis_params_.inj_size_ratio_n2p)
谱图采集
环节概述：使用上述参数，在NEG下采集一张MS1谱图
谱图寻峰
参数来源： calibration.json/parameters.mass_calibration.algorithms.peak_picking_mass_ms1
示例说明：

内容	对应值
mass_bin_pts	50
max_count	100000
min_intensity_abs	0.001
min_intensity_rel	0
top_count	100000

创建同位素峰表
环节概述：将上述实测峰表按照强度进行降序排序，按顺序生成一个同位素列表(包含当前峰的m/z、m/z +1、m/z +2、m/z +3)。最大生成8个同位素列表
执行检测器增益校准的计算
环节概述：负模式检测器增益校准的计算与正模式流程相同。

# 5 新参数保存

环节概述：将校准后的质量轴和检测器增益的参数保存到本地对应文件中。
相关参数：

instrument.json
- calib_timestamp
- calib_mass_shift_max = 10
- detector_gain 将本次正负模式的gain校准分别写入对应位置
- detector_gain_history 将本次正负模式的gain校准分别写入对应的gain校准历史中
- mass_calib.coefs.c0、mass_calib.coefs.c1、mass_calib.coefs.c2
calibration.json
- inj_size_history 将本次第三轮DRE的最佳进样量写入进样量历史中

# 三、结果文件输出

保存报告 (前台界面)
生成report.json (用于提升 STD 查询报告效率的索引，reports.json -> report.json)、MRZ 文件 (核心文件)、PDF 文件 (用于打印) 和 PNG 文件 (用于 STD 点击报告的展示)
分析流程结束，进行下一个检测