ADTK 数据处理(data)方法汇总

ADTK 数据处理(data)方法汇总

一、validate_series验证时间序列：此功能将检查时间序列的一些常见关键问题，如果执行异常检测而不修复它们可能会导致问题。该功能将自动修复其中一些并为其他人引发错误。

将检查并自动修复的问题包括：

1. 时间指数不是单调递增的；
2. 时间索引包含重复的时间戳（通过保留第一个值来修复）；
3. 时间索引属性freq在索引跟随频率时丢失（可选）；
4. 时间序列包括分类（非二进制）标签列（通过将分类标签转换为二进制指标来修复）（可选）。

将检查问题并引发错误包括：

1. 时间序列对象类型错误（必须是 pandas Series 或 DataFrame）；
2. 时间索引对象类型错误（必须是 pandas DatetimeIndex）。

在以下示例中，我们验证具有重复时间点、未排序索引和错过频率的序列。

可选地，该函数可以自动将分类序列转换为二进制序列。

方法调用
adtk.data.validate_series(ts, check_freq=True, check_categorical=False)
参数介绍
ts(pandas Series or DataFrame) -- 要验证的时间序列。
check_freq(bool, optional) -- 是否错过检查时间索引属性频率。默认值：True。
check_categorical(bool, optional) -- 检查时间序列是否包括分类（非二进制）标签列。默认值：False。

二、validate_events验证事件列表：该功能将检查并修复事件列表（时间窗口列表）中的一些常见问题，包括无效的时间窗口、重叠的时间窗口、未排序的事件等。

方法调用
adtk.data.validate_events(event_list, point_as_interval=False)
参数介绍
event_list(list) -- 事件列表，如果事件是瞬时的，则为 pandas Timestamp；如果是闭合时间间隔，则为 pandas Timestamp 的 2 元组。
point_as_interval(bool, optional) -- 是否将所有瞬时事件作为具有相同起点和终点的闭合区间返回。默认值：False。

三、to_events将二进制序列转换为事件列表。

对于有规律频率的序列，默认假设序列中的每个时间项代表一个周期，而不是一个瞬时时间点。用户可以通过设置freq_as_period为 False 来关闭此选项。

当时间点被视为瞬时时间，该函数默认不会合并“连续”点，因为“连续”是连续时间线上的概念。通过设置merge_consecutive为 True，用户可以强制函数返回“连续”时间窗口，其中时间索引中彼此相邻的正时间点被合并到同一事件中。用户应注意此类时间窗口的含义。

方法调用
adtk.data.to_events(labels, freq_as_period=True, merge_consecutive=None)
参数介绍
labels(pandas Series or DataFrame) -- 异常标签的二进制系列。如果是 DataFrame，则每一列都被独立地视为一种异常。
freq_as_period(bool, optional) -- 是否将具有规则频率的时间索引（即时间索引的属性freq不是None）作为时间间隔。默认值：True。
	例如:
		DatetimeIndex(['2017-01-01', '2017-01-02', '2017-01-03'], dtype='datetime64[ns]', freq='D') 具有每日频率。
	    如果freq_as_period=True，则索引中的每个时间点代表当天（24 小时）。否则，每个时间点代表当天00:00:00的瞬时时间实例。
merge_consecutive(bool, optional) -- 是否将连续事件合并到一个时间窗口中。
									 如果不指定，如果输入时间索引有规律的频率并且freq_as_period=True，则自动开启，否则关闭。
									 默认值：None。

四、to_labels沿时间索引将事件列表转换为二进制系列。

与to_events类似，参数freq_as_period控制时间索引中具有规则频率的元素是表示周期还是时刻。如果是一个周期，只要一个事件与其重叠，该周期就被标记为正数。否则，如果事件覆盖了某个时刻，则将其标记为正。

方法调用
adtk.data.to_labels(lists, time_index, freq_as_period=True)
参数介绍
lists(list or dict) -- 事件列表或事件列表的字典。
					   (1) 如果是列表，则为事件列表，如果事件是瞬时的，则为 pandas Timestamp；
					       如果是封闭时间间隔，则为 pandas Timestamp 的 2 元组。
					   (2) 如果是dict，每个键值对代表一个独立的事件列表。
time_index(pandas DatatimeIndex) -- 构建标签系列的时间索引。
freq_as_period(bool, optional) -- 是否将具有规则频率的时间索引（即时间索引的属性freq不是None）作为时间间隔。默认值：True。
	例如:
		DatetimeIndex(['2017-01-01', '2017-01-02', '2017-01-03'], dtype='datetime64[ns]', freq='D') 具有每日频率。
	    如果freq_as_period=True，则索引中的每个时间点代表当天（24 小时）。否则，每个时间点代表当天00:00:00的瞬时时间实例。

五、expand_events扩大事件的持续时间。在计算检测结果的质量时，有时轻微的偏移是可以接受的。函数expand_events通过给定因子扩展列表中事件的持续时间，使得评分更宽容。

在下面的例子中，我们有一个与真实异常列表偏移 2 ~ 3 分钟的检测结果。如果我们接受前后偏移 5 分钟，结果的得分更有意义。

方法调用
adtk.data.expand_events(events, left_expand=0, right_expand=0, freq_as_period=True)
参数介绍
events(list, dict, pandas Series, or pandas DataFrame) -- 事件有待扩展。
	举例：
		(1) 如果是列表，则为事件列表，如果事件是瞬时的，则为 pandas Timestamp；
		    如果是封闭时间间隔，则为 pandas Timestamp 的 2 元组。
		(2) 如果是dict，每个键值对代表一个独立的事件列表。
		(3) 如果是 pandas Series，它是二进制的，其中 1 代表事件覆盖这个时间点。
		(4) 如果是 pandas DataFrame，每一列都被视为一个独立的系列。
left_expand(pandas Timedelta, str, or int, optional) -- 时间范围向后扩大。默认值：0。
	举例：
		(1) 如果是str，则必须能够转换成pandas Timedelta 对象。
		(2) 如果是 int，则必须以纳秒为单位。
right_expand(pandas Timedelta, str, or int, optional) -- 时间范围向前扩大。默认值：0。
	举例：
		(1) 如果是str，则必须能够转换成pandas Timedelta 对象。
		(2) 如果是 int，则必须以纳秒为单位。
freq_as_period(bool, optional) -- 是否将具有规则频率的时间索引（即时间索引的属性freq不是None）作为时间间隔。默认值：True。
	例如:
		DatetimeIndex(['2017-01-01', '2017-01-02', '2017-01-03'], dtype='datetime64[ns]', freq='D') 具有每日频率。
	    如果freq_as_period=True，则索引中的每个时间点代表当天（24 小时）。否则，每个时间点代表当天00:00:00的瞬时时间实例。

六、split_train_test将时间序列拆分为训练和测试集以进行交叉验证。在构建时间序列异常检测模型时，将历史序列拆分为训练和测试段是需要的常见操作。函数split_train_test提供了四种拆分模式。用户可以根据具体情况进行选择。

1、将时间序列分成 n_splits 个等长的折叠，根据 train_ratio 将每个折叠分成训练和测试。

2、创建 n_splits 折叠，其中每个折叠从 t_0 开始并在 t_(n/n_splits) 结束，其中 n 从 0 到 n_splits，折叠的第一个 train_ratio 用于训练。

3、创建 n_splits 折叠，其中每个折叠从 t_0 开始。每个折叠最后都有 len(ts)/(1 + n_splits) 个测试点。每个折叠的长度为 n * len(ts)/(1 + n_splits)，其中 n 的范围从 1 到 n_splits。

4、创建 n_splits 折叠，其中每个折叠从 t_0 开始。每个折叠在时间序列的开头都有 n * len(ts)/(1 + n_splits) 个训练点，其中 n 的范围从 1 到 n_splits，其余点是测试点。

方法调用
adtk.data.split_train_test(ts, mode=1, n_splits=1, train_ratio=0.7)
参数介绍
ts(pandas Series or DataFrame) -- 要处理的时间序列。
mode(int, optional) -- 要使用的拆分模式。从 1、2、3 和 4 中选择。默认值：1。
n_splits(int, optional) -- 分割数。默认值：1。
train_ratio(float, optional) -- 训练序列长度与每个折叠之间的比率，仅由模式 1 和 2 使用。默认值：0.7。