数据分析机器学习数据科学【免费下载链接】KatsKats, a kit to analyze time series data, a lightweight, easy-to-use, generalizable, and extendable framework to perform time series analysis, from understanding the key statistics and characteristics, detecting change points and anomalies, to forecasting future trends.项目地址https://gitcode.com/gh_mirrors/ka/Kats点击查看免费下载本篇技术指南围绕 Kats 开源时间序列分析框架仓库gh_mirrors/ka/Kats中kats.detectors.detector_consts模块展开系统讲解 Kats 所有变化点检测与异常检测器如StatSigDetectorModel、BOCPDetectorModel、CUSUMDetectorModel等共享的五个核心构件SingleSpike、ChangePointInterval、PercentageChange、ConfidenceBand与AnomalyResponse。读完本文你将掌握这些数据对象的字段定义、属性语义、统计计算原理t 检验、FDR 多重校正、Delta 方法置信区间以及它们在检测流水线中的实际调用方式从而能够读懂并扩展任意基于DetectorModel基类的检测器实现。模块定位检测器家族的统一地基kats/detectors/detector_consts.py源码并不实现任何具体的检测算法而是为整个kats.detectors包提供共享的数据结构与统计工具。从模块被引用的范围可以直观看到它的地位kats/detectors/detector.py中的抽象基类DetectorModel直接以AnomalyResponse作为fit_predict与predict的返回类型detector.pybocpd_model.py、cusum_model.py、interval_detector.py、multivariate_detector.py、outlier_detector.py、prophet_detector.py、threshold_detector.py、rolling_stats_model.py、distribution_distance_model.py等十余个检测器均从该模块导入AnomalyResponse与ConfidenceBand作为统一输出载体stat_sig_detector.py则几乎完整使用模块中的四个类ChangePointInterval描述控制/测试区间PercentageChange完成统计显著性计算AnomalyResponse承载滚动窗口检测结果。因此该模块是理解 Kats 检测器体系内部协议的第一站无论使用哪种检测算法最终都会以AnomalyResponse的形态返回结果而区间统计比较则依赖ChangePointInterval与PercentageChange。SingleSpike单点尖峰记录SingleSpike是模块中最小的数据对象用于描述时间序列中一个被判定为尖峰的数据点attr.s(auto_attribsTrue) class SingleSpike: time: datetime # 尖峰发生时间 value: float # 尖峰处的原始观测值 n_sigma: float # 该点对应的 z-score偏离均值的标准差倍数 property def time_str(self) - str: return datetime.strftime(self.time, %Y-%m-%d)字段语义清晰n_sigma记录了该点在区间内的标准化得分z-score供下游判断尖峰强度。属性time_str将时间格式化为%Y-%m-%d字符串便于日志输出与展示。对应测试见 test_detector_consts.py构造SingleSpike(timespike_time, value1.0, n_sigma3.0)后断言time_str返回2020-03-01。ChangePointInterval区间数据容器与尖峰检测ChangePointInterval是模块中最基础也最重要的数据容器表示一段[start_time, end_time)的时间窗口并负责从TimeSeriesData中裁剪出落在区间内的数据计算区间的均值、样本方差按 z-score 阈值自动检测区间内的尖峰。字段与默认值字段类型默认值说明start_timedatetime必填区间起点含end_timedatetime必填区间终点不含previous_intervalOptional[ChangePointInterval]NoneinitFalse前一个历史区间用于构建比较链_all_spikes列表/列表的列表NoneinitFalse尖峰缓存懒加载spike_std_thresholdfloat2.0initFalse尖峰判定的 z-score 阈值data_dfOptional[pd.DataFrame]NoneinitFalse裁剪后的数据_ts_colsList[str][value]initFalse单变量时为[value]多变量时为各序列列名num_seriesint1序列数量1 表示单变量data 属性自动裁剪与多变量适配data的 setter 会判断输入是否为多变量时间序列data.is_univariate()并据此更新_ts_cols与num_series随后将TimeSeriesData转为 DataFrame并把时间列规范化为datetime最后按start_time time end_time裁剪data.setter def data(self, data: TimeSeriesData) - None: if not data.is_univariate(): self._ts_cols list(data.value.columns) self.num_series len(self._ts_cols) all_data_df data.to_dataframe() all_data_df.columns [time] self._ts_cols all_data_df[time] pd.to_datetime(all_data_df[time]) all_data_df all_data_df.loc[ (all_data_df.time self.start_time) (all_data_df.time self.end_time) ] self.data_df all_data_df对应的 getter 在单变量时返回df.value.values一维数组多变量时返回df[self._ts_cols].values二维数组。测试test_start_end_date验证了裁剪行为15 个点的序列赋给[prev_start, prev_end)区间后data恰好返回前 9 个点test_detector_consts.py。均值与方差mean_val与variance_val两个属性为后续统计检验提供基础统计量。注意variance_val使用np.var(vals, ddof1)样本方差代码注释明确说明这是为了与 t 检验使用的样本标准差保持一致detector_consts.py。多变量时返回逐序列的数组。数据为空时返回0.0单变量或零数组。extend_data增量扩展区间数据def extend_data(self, data: TimeSeriesData) - None: new_data_df data.to_dataframe() new_data_df.columns [time] self._ts_cols df self.data_df if df is not None: new_data_df pd.concat([df, new_data_df], copyFalse) self.data_df new_data_df.loc[ (new_data_df.time self.start_time) (new_data_df.time self.end_time) ]该方法将新数据拼接到现有数据之后并再次按区间边界裁剪。测试test_extend_length_except_last_point与test_extend_length验证了三种场景扩展后恰好多一个点、扩展到完整序列、甚至把end_time延伸到超出数据范围结果不受影响见 test_detector_consts.py。spikes基于 z-score 的尖峰检测spikes属性是懒加载的首次访问时调用_detect_spikes()结果缓存到_all_spikes。单变量逻辑如下df[z_score] (df.value - self.mean_val) / np.sqrt(self.variance_val) spike_df df.query(fz_score {self.spike_std_threshold}) return [SingleSpike(timerow[time], valuerow[value], n_sigmarow[z_score]) for counter, row in spike_df.iterrows()]即对区间内每个点计算(x - mean) / sqrt(variance)凡是 z-score 不低于spike_std_threshold默认 2.0的点都被标记为尖峰。多变量时对每个序列列分别计算z_score_{c}并独立筛选返回List[List[SingleSpike]]结构某序列无尖峰时该序列被跳过detector_consts.py。测试UnivariateChangePointIntervalTest构造了一个首点为100.0的序列断言spike_list[0].value 100.0且spike_list[0].time_str等于区间起始日test_detector_consts.py多变量测试则验证 5 个序列各自捕获100 * (i 1)的尖峰test_detector_consts.py。PercentageChange区间差异的统计显著性引擎PercentageChange是模块的统计核心它接收当前区间与历史区间两个ChangePointInterval计算二者的百分比变化、t 分数、p 值、置信区间与显著性结论。它正是StatSigDetectorModel完成控制组control与测试组test比较所依赖的组件。构造参数参数类型默认值说明currentChangePointInterval必填待检测的当前区间previousChangePointInterval必填用于对比的历史区间methodstrfdr_bh多变量 p 值校正方法statsmodelsmultipletests支持的 FDR 方法skip_rescalingboolFalse多变量时是否跳过 p 值缩放StatSigDetectorModel将超长单变量序列转为多变量时会置Trueuse_corrected_scoresboolFalse使用原始 t 分数还是经样本均值标准误修正的 t 分数min_perc_changefloat0.0最小百分比变化阈值绝对值低于该值的分数被裁剪为 0此外alpha固定为0.05detector_consts.py。核心属性一览属性计算公式 / 语义ratio_estimatecurrent.mean_val / previous.mean_val均值之比perc_change(ratio_estimate - 1.0) * 100.0百分比变化perc_change_upper / perc_change_lower由 Delta 方法给出比率上下界后换算为百分比direction百分比变化 0 返回up否则down多变量时逐序列向量化stat_sig置信区间上界 1 且下界 1 时返回False即包含 1无法判定显著否则Truescoret 分数若|perc_change| min_perc_change则裁剪为 0p_value双尾 t 检验 p 值mean_previous历史区间均值作为预测基准值mean_differencecurrent.mean_val - previous.mean_val作为异常幅度ci_upper / ci_lower基于池化标准差与 t 分布分位数构建的置信区间统计实现要点池化标准差_pooled_stddev计算两区间的合并标准差公式为sqrt(((n1-1)*s1² (n2-1)*s2²) / (n1n2-2))当use_corrected_scoresTrue时再乘以sqrt(1/n1 1/n2)得到标准误形式。当任一区间为空或两区间各只有 1 个点时返回0.0detector_consts.py。手动 t 检验_ttest_manual用t (mean_current - mean_previous) / sp_mean、p t.sf(|t|, df) * 2手工计算双尾 p 值。代码注释说明这是为了规避 scipyttest_ind在样本量为 1 时返回nan的问题并指出由于标准差口径不含sqrt(1/n1 1/n2)与 scipy 不同模块始终使用手动实现detector_consts.py。多变量与 FDR 校正_ttest_multivariate对每个序列分别执行ttest_ind(equal_varTrue, nan_policyomit)若skip_rescalingFalse则用statsmodels.multitest.multipletests(p, alpha0.05, methodself.method)对 p 值做多重比较校正默认方法fdr_bhBenjamini-Hochberg 过程再把校正后的 p 值反推为 t 分数保留原始 t 的正负号见 detector_consts.py。Delta 方法置信区间_delta_method通过比率型统计量的 Delta 方法方差近似sigma_sq_ratio再以正态分位数norm.ppf(alpha/2)约 -1.96构建ratio_estimate的上下界代码注释提醒符号看似翻转是因为norm.ppf(0.025)本身为负detector_consts.py。测试中的行为边界UnivariatePercentageChangeTest与MultivariatePercentageChangeTest覆盖了大量行为契约test_detector_consts.py当均值从约 1.0 跳到约 10.0 时stat_sig为True、p_value 0.05、score 1.96、direction up当对比区间均值几乎相同10.0 vs 10.005时上述结论全部为False多变量场景下direction返回全up数组stat_sig与score返回逐序列布尔/数值数组退化场景当控制区间与测试区间各仅含 1 个稀疏数据点时score、ci_lower、ci_upper均为nan测试test_degeneratetest_detector_consts.py。ConfidenceBand 与 AnomalyResponse检测结果的统一出口ConfidenceBand一个极简的dataclass仅包含两条TimeSeriesDatadataclass class ConfidenceBand: lower: TimeSeriesData upper: TimeSeriesData它表示某一时刻序列预测值的置信带下界、上界被AnomalyResponse引用也单独被bocpd_model.py、interval_detector.py、multivariate_detector.py、outlier_detector.py、prophet_detector.py等检测器直接构造使用。AnomalyResponseAnomalyResponse是检测器的最终返回对象统一承载评分、置信带、预测值、异常幅度与显著性标记五类信息构造参数类型说明scoresTimeSeriesData逐时刻的检测分数如 t 统计量confidence_bandOptional[ConfidenceBand]预测置信带可为Nonepredicted_tsOptional[TimeSeriesData]预测的时间序列可为Noneanomaly_magnitude_tsTimeSeriesData异常幅度如与历史均值的差stat_sig_tsOptional[TimeSeriesData]统计显著性标记可为None构造时会根据scores是否单变量自动填充num_series与key_mapping多变量时的各列名见 detector_consts.py。关键方法update(...)追加一个时间点并同时删除最早的一个点滚动窗口语义。_update_ts_slice对每条TimeSeriesData执行ts[1:] 新点的操作多变量时按key_mapping逐列拼接。测试test_update_response_preserves_length与test_update_one_point_forward验证了长度保持不变、旧首点被移除、新末点为传入值test_detector_consts.py。inplace_update(...)语义与update相同但原地更新ts.value.loc[ts.time time]避免重建 DataFrame是StatSigDetectorModel在主循环中使用的版本stat_sig_detector.py。get_last_n(N)返回仅含最后N个时刻的新AnomalyResponseconfidence_band、predicted_ts、stat_sig_ts为None时保持Nonedetector_consts.py。extend(other, validateTrue)将另一个AnomalyResponse追加到当前对象之后逐组件调用TimeSeriesData.extend。若双方在confidence_band、predicted_ts、stat_sig_ts是否为None上不一致抛出ValueErrorvalidateFalse时跳过拼接后的数据校验。测试test_extend_fail_validation与test_extend_mismatch覆盖了这些错误路径test_detector_consts.py。__str__以多行字符串输出各组件的时间、分数、上下置信界、预测值与显著性标记便于日志调试。在检测流水线中的实战串联以 StatSigDetectorModel 为例可以看到这四个类如何协作完成一次完整的滚动显著性检测_init_control_test/_update_control_test依据n_control、n_test与time_unit计算控制/测试区间的起止时间构造两个ChangePointInterval并赋入历史数据stat_sig_detector.py_update_response用这两个区间构造PercentageChange传入use_corrected_scores与min_perc_change多变量版还会传入method与skip_rescaling然后调用response.inplace_update(...)把score、ci_upper/ci_lower、mean_previous、mean_difference、stat_sig逐项写入AnomalyResponsestat_sig_detector.py每个新数据点到达后ChangePointInterval的datasetter 自动完成区间裁剪PercentageChange的mean_val、variance_val、_pooled_stddev等属性提供统计量_delta_method提供置信区间最终以AnomalyResponse输出长度与输入数据等长的检测结果fit_predict返回self.response.get_last_n(self.last_N)。此外MultiStatSigDetectorModel逐序列执行 t 检验并做 FDR 校正methodfdr_bhStatSigDetectorModel在use_corrected_scoresTrue且数据长度超过max_split_ts_length默认 500时会把长单变量序列重组为多变量序列并调用多变量版本此时skip_rescalingTrue以跳过重复的 p 值缩放stat_sig_detector.py——这正是PercentageChange.skip_rescaling参数存在的意义。快速上手示例基于StatSigDetectorModel的官方文档示例可以直接体验这些数据结构的产出完整用法见 stat_sig_detector.pyimport random import pandas as pd from kats.consts import TimeSeriesData from kats.detectors.stat_sig_detector import StatSigDetectorModel n_control, n_test 28, 7 control_time pd.date_range(start2018-01-01, freqD, periods(n_control n_test)) test_time pd.date_range(start2018-02-05, freqD, periodsn_test) control_val [random.normalvariate(100, 10) for _ in range(n_control n_test)] test_val [random.normalvariate(120, 10) for _ in range(n_test)] hist_ts TimeSeriesData(timecontrol_time, valuepd.Series(control_val)) data_ts TimeSeriesData(timetest_time, valuepd.Series(test_val)) ss_detect StatSigDetectorModel(n_controln_control, n_testn_test) anom ss_detect.fit_predict(datadata_ts, historical_datahist_ts) # anom 即 AnomalyResponseanom.scores / anom.confidence_band.upper / # anom.predicted_ts / anom.anomaly_magnitude_ts / anom.stat_sig_ts若要绕过检测器直接使用底层构件可按测试中的方式手工组装test_detector_consts.pyfrom datetime import datetime, timedelta from kats.detectors.detector_consts import ChangePointInterval, PercentageChange start datetime(2020, 3, 1) previous ChangePointInterval(start, start timedelta(days15)) previous.data hist_ts # TimeSeriesData将被自动裁剪到区间内 current ChangePointInterval(start timedelta(days15), start timedelta(days25)) current.data data_ts perc PercentageChange(currentcurrent, previousprevious) print(perc.perc_change) # 百分比变化 print(perc.score, perc.p_value, perc.stat_sig) # t 分数、p 值、显著性小结kats.detectors.detector_consts虽是一个常量与数据结构模块却承载了 Kats 检测体系最重要的契约ChangePointInterval负责区间数据管理并内置 z-score 尖峰检测PercentageChange封装了从 t 检验、FDR 校正到 Delta 方法置信区间的全套统计计算AnomalyResponse则定义了所有检测器的统一输出格式支持滚动更新、截取与拼接。无论是阅读StatSigDetectorModel、BOCPDetectorModel等现有实现还是基于DetectorModel基类编写自定义检测器深入理解本模块都是必经之路。模块源码位于 kats/detectors/detector_consts.py完整的契约测试见 kats/tests/detectors/test_detector_consts.py。赞分享数据分析机器学习数据科学【免费下载链接】KatsKats, a kit to analyze time series data, a lightweight, easy-to-use, generalizable, and extendable framework to perform time series analysis, from understanding the key statistics and characteristics, detecting change points and anomalies, to forecasting future trends.项目地址https://gitcode.com/gh_mirrors/ka/Kats点击查看免费下载相关推荐Vue.js 源码解析Virtual DOM 与 VNode 数据结构详解Vue.js 源码解析Virtual DOM 与 VNode 数据结构详解 Virtual DOM 是 Vue.js 2.x 数据驱动架构的基石模板与数据最文档教程前端Immutable.js性能优化Trie数据结构与结构共享Immutable.js性能优化Trie数据结构与结构共享 Immutable.js通过哈希数组映射TrieHAMT数据结构和精巧的结构共享机制实现了卓越开发框架与应用Atomic Red Team源码解析models.py核心数据结构详解Atomic Red Team源码解析models.py核心数据结构详解 引言为什么models.py是Atomic Red Team的核心 你是否在使用网络安全渗透测试威胁建模上一篇LSPosed框架技术文档下一篇为什么顶级加密项目golang/crypto选择用avo生成x86汇编解密Go汇编的终极工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考