paddlets.datasets.tsdataset
TSDataset 是 PaddleTS 中一个主要的类结构,用于表示绝大多数的时序样本数据,并作为PaddleTS其他算子的输入以及输出对象。TSDataset 包涵两类时序数据:
待预测目标:表示希望被预测的时序序列
协变量:无需被预测的时间序列,协变量的加入通常用于辅助提高模型预测的效果
TSDataset支持的时序样本数据可以分为:
单变量数据,只包含单列的预测目标,同时可以包涵单列或者多列协变量
多变量数据,包涵多列预测目标,同时可以包涵单列或者多列协变量
我们将非预测目标变量定义为协变量,在时序数据中,协变量可分为以下三种:
- 观测协变量 (observed_cov)
指只能在历史中观察到的变量数据,例如测量的温度
- 可预知协变量 (known_cov)
指可在预测未来时间已知的变量,例如天气预报
- 静态协变量 (static_cov)
指整个时间范围内保持不变的变量
一个 TSDataset 对象由一个或者多个 TimeSeries 对象构成,每个 TimeSeries 可分别代表target(待预测目标), observed_covariate(观测协变量)以及known_covariate(可预知协变量)。
- class TimeSeries(data: Union[DataFrame, Series], freq: Union[int, str])[源代码]
基类:
objectTimeSeries 是用于表示时序数据的最小粒度。可以分别代表target, observed_covariate 或者known_covariate 其中一种类型。TimeSeries本身可以是单变量或者多变量。
- 参数
data (DataFrame|Series) – 样本数据,可以是目标变量或者协变量
freq (str|int) – 样本数据频率,用于调整data以及配合fillna进行空行填充
- 返回
None
- classmethod load_from_dataframe(data: Union[DataFrame, Series], time_col: Optional[str] = None, value_cols: Optional[Union[List[str], str]] = None, freq: Optional[Union[str, int]] = None, drop_tail_nan: bool = False, dtype: Optional[Union[type, Dict[str, type]]] = None) TimeSeries[源代码]
基于DataFrame构建TimeSeries
- 参数
data (DataFrame|Series) – 样本数据,可以是目标变量或者协变量
time_col (str|None) – 时间列,可以是DatetimeIndex或者RangeIndex类型,如果为None,将index作为时间列
value_cols (list|str|None) – data中需要选取的数据,如果不指定,数据中所有列(除时间列外)都会被导入
freq (str|int|None) – 样本数据频率,用于调整data以及配合fillna进行空行填充
drop_tail_nan (bool) – 是否删除时序尾部连续的nan值,如果设置为True, 则会自动删除尾部的Nan值
dtype (np.dtype|type|dict) – 数据类型,可以是numpy.dtype|Python type或者是dict类型,直接调用df.astype使用,numpy.dtype|Python type代表对所有列做变换, dict代表对某一列或者几列做转换
- 返回
构建完成的TimeSeries数据
- property time_index
the time index
- property columns
数据的列信息
- property start_time: Union[Timestamp, int]
时序数据中第一个时间点
- property end_time: Union[Timestamp, int]
时序数据中最后一个时间点
- property data
包含的DataFrame类型的成员
- property freq
时序频率
- property dtypes: Series
数据类型
- astype(dtype: Union[dtype, type, Dict[str, Union[dtype, type]]])[源代码]
转换数据类型,注意这里不会返回一个新的数据,而是在原始数据集上修改
- 参数
dtype (np.dtype|type|dict) – 数据类型,可以是numpy.dtype|Python type或者是dict类型,直接调用df.astype使用,numpy.dtype|Python type代表对所有列做变换, dict代表对某一列或者几列做转换
- 引发
TypeError –
KeyError –
- to_dataframe(copy: bool = True) DataFrame[源代码]
TimeSeries转换成DataFrame数据
- 参数
copy (bool) – 返回拷贝或者引用
- 返回
pd.DataFrame
- to_numpy(copy: bool = True) ndarray[源代码]
TimeSeries转换成np.ndarray数据
- 参数
copy (bool) – True代表拷贝数据,False代表不拷贝数据即使设置了False,这里也可能会全量拷贝数据(例如当data中type类型不统一),使用的时候需要注意这里的性能消耗参考:https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_numpy.html
- 返回
np.ndarray
- get_index_at_point(point: Union[Timestamp, str, float, int], after=True) int[源代码]
将具体的时间点基于time_index转换成具体的index
- 参数
point (pd.Timestamp|float|int) – 时间点,支持三种类型:pd.Timestamp|str:只有当time_index类型是pd.DatatimeIndex的时候生效,返回对应的index,str会强制转换成pd.Timestamp;float:代表从头开始的比例,0到1之间,如0.8; int:直接返回具体的数值,不做转换
after (bool) – 如果提供的pandas时间戳不在时间序列索引中,是否返回下一个时间戳或上一个时间戳的索引
- 返回
index
- 返回类型
int
- 引发
ValueError –
TypeError –
- split(split_point: Union[Timestamp, str, float, int], after=True) Tuple[TimeSeries, TimeSeries][源代码]
基于split_point拆分数据
- 参数
split_point (pd.Timestamp|float|int) – 数据拆分的时间点,支持三种类型:pd.Timestamp|str:只有当time_index类型是pd.DatatimeIndex的时候生效,返回对应的index,str会强制转换成pd.Timestamp;float:代表第一份数据的拆分比例,0到1之间,如0.8,代表第一份数据占总量的80%,第二份20%;int:代表第一份数据的数据量。split_point点的数据如果存在,会包涵在第一份数据中
after (bool) – 如果提供的pandas时间戳不在时间序列索引中,是否返回下一个时间戳或上一个时间戳的索引
- 返回
Tuple[“TimeSeries”, “TimeSeries”]
- 引发
ValueError –
TypeError –
- copy() TimeSeries[源代码]
返回一份拷贝的数据
- 返回
TimeSeries
- classmethod concat(tss: List[TimeSeries], axis: int = 0, drop_duplicates: bool = True, keep: str = 'first') TimeSeries[源代码]
基于axis维度实现TimeSeries对象的连接
- 参数
tss (list[TimeSeries]) – TimeSeries元素列表,要求所有TimeSeries freq保持一致,当axis=1的时候,要求time_col不重复;axis=0的时候,要求所有columns不重复
axis (int) – 合并的维度,1是横向合并,0代表纵向合并
drop_duplicates (bool) – 是否对重复index的行进行删除,默认删除
keep (str) – 当对concat的时序数据有重复index并设置删除,保留第一个或者最后一个重复时序的数据
- 返回
TimeSeries
- 引发
ValueError –
- reindex(index, fill_value=nan, *args, **kwargs) TimeSeries[源代码]
对TimeSeries进行reindex
- 参数
index – array-like类型,重新设定的index,要求不能重复
fill_value – 用于填充缺失点的值
args – 其他传递给`DataFrame.reindex`的可选参数
kwargs – 其他传递给`DataFrame.reindex`的可选参数
- 返回
TimeSeries
- 引发
ValueError –
- classmethod load_from_json(json_data: str, **json_load_kwargs) TimeSeries[源代码]
基于Json数据构建完整TSDataset
- 参数
json_data (str) – panas.DataFrame数据对象
**json_load_kwargs – 传json.loads()的可选参数
- 返回
TimeSeries
- class TSDataset(target: Optional[TimeSeries] = None, observed_cov: Optional[TimeSeries] = None, known_cov: Optional[TimeSeries] = None, static_cov: Optional[dict] = None, fill_missing_dates: bool = False, fillna_method: str = 'pre', fillna_window_size: int = 10)[源代码]
基类:
objectTSDataset是 PaddleTS 中一个主要的类结构,用于表示绝大多数的时序样本数据,并作为PaddleTS其他算子的输入以及输出对象。TSDataset 包涵两类时序数据:待预测目标:表示希望被预测的时序序列
协变量:无需被预测的时间序列,协变量的加入通常用于辅助提高模型预测的效果
TSDataset支持的时序样本数据可以分为:
单变量数据,只包含单列的预测目标,同时可以包涵单列或者多列协变量
多变量数据,包涵多列预测目标,同时可以包涵单列或者多列协变量
我们将非预测目标变量定义为协变量,在时序数据中,协变量可分为以下三种:
- 观测协变量 (observed_cov)
指只能在历史中观察到的变量数据,例如测量的温度
- 可预知协变量 (known_cov)
指可在预测未来时间已知的变量,例如天气预报
- 静态协变量 (static_cov)
指整个时间范围内保持不变的变量
一个
TSDataset对象由一个或者多个TimeSeries对象构成,每个TimeSeries可分别代表target(待预测目标), observed_covariate(观测协变量)以及known_covariate(可预知协变量)。- 参数
target (TimeSeries|None) – 代表预测目标列,可能包涵多个预测目标
observed_cov (TimeSeries|None) – 代表观测协变量
known_cov (TimeSeries|None) – 代表已知协变量
static_cov (dict|None) – 静态协变量
fill_missing_dates (bool) – 是否进行缺失值填充
fillna_method (str) – 默认为pre前项补全。共有7种补全数据缺失值的方法,包括:max: 使用局部窗口最大值补全缺失值信息。min: 使用局部窗口最小值补全缺失值信息。avg: 使用局部窗口均值补全缺失值信息。median: 使用局部窗口中位数数值补全缺失值信息。pre: 使用前向数据补全数据信息。back: 使用后项数据补全数据信息。zero: 使用0值补全数据信息
fillna_window_size – 局部窗口长度,默认为10
- classmethod load_from_csv(filepath_or_buffer: str, group_id: Optional[str] = None, time_col: Optional[str] = None, target_cols: Optional[Union[List[str], str]] = None, label_col: Optional[Union[List[str], str]] = None, observed_cov_cols: Optional[Union[List[str], str]] = None, feature_cols: Optional[Union[List[str], str]] = None, known_cov_cols: Optional[Union[List[str], str]] = None, static_cov_cols: Optional[Union[List[str], str]] = None, freq: Optional[Union[str, int]] = None, fill_missing_dates: bool = False, fillna_method: str = 'pre', fillna_window_size: int = 10, drop_tail_nan: bool = False, dtype: Optional[Union[type, Dict[str, type]]] = None, **kwargs) Union[TSDataset, List[TSDataset]][源代码]
基于CSV文件构建TSDataset
- 参数
filepath_or_buffer (str) – csv文件或者文件对象地址, 通过`pandas.read_csv` 方法的构建
group_id (str|None) – 用于区分不同组的时序数据集,如果只有一个时序数据集,请不要传递此参数或将其设置为常量列的名称。如果提供了group_id,函数将返回长度等于len(group_id.unique())的TSDataset列表。例如:设备负载检测样本文件中包含了多个设备的数据,其中ID列用于区分不同的设备。在这种情况下,设置group_id=ID。
time_col (str|None) – 时间列,可以是DatetimeIndex或者RangeIndex类型,如果为None,将index作为时间列
target_cols (list|str|None) – 代表目标变量列名
label_col (list|str|None) – 代表异常检测场景数据下label的列名,注意,该参数不可以和target_col同时传递
observed_cov_cols (list|str|None) – 代表观测协变量列名
feature_cols (list|str|None) – 代表异常检测场景数据下特征的列名,注意,该参数不可以和observed_cov_col同时传递
known_cov_cols (list|str|None) – 代表已知协变量列名
static_cov_cols (list|str|None) – 静态协变量列名,需要同一列中全部数值一致
freq (str|int|None) – 样本数据频率,用于调整data以及配合fillna进行空行填充
fill_missing_dates (bool) – 是否进行缺失值填充
fillna_method (str) – 默认为pre前项补全。共有7种补全数据缺失值的方法,包括:max: 使用局部窗口最大值补全缺失值信息。min: 使用局部窗口最小值补全缺失值信息。avg: 使用局部窗口均值补全缺失值信息。median: 使用局部窗口中位数数值补全缺失值信息。pre: 使用前向数据补全数据信息。back: 使用后项数据补全数据信息。zero: 使用0值补全数据信息
fillna_window_size (int) – 局部窗口长度,默认为10
drop_tail_nan (bool) – 是否删除时序尾部连续的nan值,如果设置为True, 则会自动删除尾部的Nan值
dtype (np.dtype|type|dict) – 数据类型,可以是numpy.dtype|Python type或者是dict类型,直接调用df.astype使用,numpy.dtype|Python type代表对所有列做变换, dict代表对某一列或者几列做转换
kwargs – 传递给 pandas.read_csv 方法的可选参数
- 返回
Union[TSDataset, List[TSDataset]]
- classmethod load_from_dataframe(df: DataFrame, group_id: Optional[str] = None, time_col: Optional[str] = None, target_cols: Optional[Union[List[str], str]] = None, label_col: Optional[Union[List[str], str]] = None, observed_cov_cols: Optional[Union[List[str], str]] = None, feature_cols: Optional[Union[List[str], str]] = None, known_cov_cols: Optional[Union[List[str], str]] = None, static_cov_cols: Optional[Union[List[str], str]] = None, freq: Optional[Union[str, int]] = None, fill_missing_dates: bool = False, fillna_method: str = 'pre', fillna_window_size: int = 10, drop_tail_nan: bool = False, dtype: Optional[Union[type, Dict[str, type]]] = None) Union[TSDataset, List[TSDataset]][源代码]
基于pandas.DataFrame构建完整TSDataset
- 参数
df (pd.DataFrame) – panas.DataFrame数据对象
group_id (str|None) – 用于区分不同组的时序数据集,如果只有一个时序数据集,请不要传递此参数或将其设置为常量列的名称。如果提供了group_id,函数将返回长度等于len(group_id.unique())的TSDataset列表。例如:设备负载检测样本文件中包含了多个设备的数据,其中ID列用于区分不同的设备。在这种情况下,设置group_id=ID。
time_col (str|None) – 时间列,可以是DatetimeIndex或者RangeIndex类型,如果为None,将index作为时间列
target_cols (list|str|None) – 代表目标变量列名
label_col (list|str|None) – 代表异常检测场景数据下label的列名,注意,该参数不可以和target_col同时传递
observed_cov_cols (list|str|None) – 代表观测协变量列名
feature_cols (list|str|None) – 代表异常检测场景数据下特征的列名,注意,该参数不可以和observed_cov_col同时传递
known_cov_cols (list|str|None) – 代表已知协变量列名
static_cov_cols (list|str|None) – 静态协变量列名,需要同一列中全部数值一致
freq (str|int|None) – 样本数据频率,用于调整data以及配合fillna进行空行填充
fill_missing_dates (bool) – 是否进行缺失值填充
fillna_method (str) – 默认为pre前项补全。共有7种补全数据缺失值的方法,包括:max: 使用局部窗口最大值补全缺失值信息。min: 使用局部窗口最小值补全缺失值信息。avg: 使用局部窗口均值补全缺失值信息。median: 使用局部窗口中位数数值补全缺失值信息。pre: 使用前向数据补全数据信息。back: 使用后项数据补全数据信息。zero: 使用0值补全数据信息
fillna_window_size (int) – 局部窗口长度,默认为10
drop_tail_nan (bool) – 是否删除时序尾部连续的nan值,如果设置为True, 则会自动删除尾部的Nan值
dtype (np.dtype|type|dict) – 数据类型,可以是numpy.dtype|Python type或者是dict类型,直接调用df.astype使用,numpy.dtype|Python type代表对所有列做变换, dict代表对某一列或者几列做转换
- 返回
Union[TSDataset, List[TSDataset]]
- to_dataframe(copy: bool = True) DataFrame[源代码]
TSDataset转换成DataFrame数据
- 参数
copy (bool) – True代表拷贝数据,False代表不拷贝数据,注意这里是浅拷贝,对于数序数据而言通常没有问题
- 返回
pd.DataFrame
- to_numpy(copy: bool = True) ndarray[源代码]
TSDataset转换成np.ndarray数据
- 参数
copy (bool) – True代表拷贝数据,False代表不拷贝数据即使设置了False,这里也可能会全量拷贝数据(例如当data中type类型不统一),使用的时候需要注意这里的性能消耗参考:https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_numpy.html
- 返回
np.ndarray
- get_target() Optional[TimeSeries][源代码]
- 返回
target
- 返回类型
TimeSeries|None
- get_label() Optional[TimeSeries][源代码]
- 返回
target
- 返回类型
TimeSeries|None
- get_observed_cov() Optional[TimeSeries][源代码]
- 返回
observed_cov
- 返回类型
TimeSeries|None
- get_feature() Optional[TimeSeries][源代码]
- 返回
observed_cov
- 返回类型
TimeSeries|None
- get_known_cov() Optional[TimeSeries][源代码]
- 返回
known_cov
- 返回类型
TimeSeries|None
- get_all_cov() Optional[TimeSeries][源代码]
- 返回
融合了observed_cov以及konw_cov的数据
- 返回类型
pd.DataFrame|None
- set_target(target: TimeSeries)[源代码]
- 参数
target (TimeSeries) – New target
- 返回
None
- 引发
ValueError –
- set_label(label: TimeSeries)[源代码]
- 参数
label (TimeSeries) – New label
- 返回
None
- 引发
ValueError –
- set_observed_cov(observed_cov: TimeSeries)[源代码]
- 参数
observed_cov (TimeSeries) – New observed_cov
- 返回
None
- 引发
ValueError –
- set_feature(feature: TimeSeries)[源代码]
- 参数
feature (TimeSeries) – New feature
- 返回
None
- 引发
ValueError –
- set_known_cov(known_cov: TimeSeries)[源代码]
- 参数
known_cov (TimeSeries) – New known_cov
- 返回
None
- 引发
ValueError –
- set_static_cov(static_cov: dict, append: bool = True)[源代码]
- 参数
static_cov (dict) – New static_cov
append (bool) – True代表在原有static_cov基础上添加,False代表直接全部替换原有的static_cov
- 返回
None
- 引发
ValueError –
- property target: Optional[TimeSeries]
Returns: TimeSeries|None: target
- property label: Optional[TimeSeries]
Returns: TimeSeries|None: target
- property observed_cov: Optional[TimeSeries]
Returns: TimeSeries|None: observed_cov
- property feature: Optional[TimeSeries]
Returns: TimeSeries|None: observed_cov
- property known_cov: Optional[TimeSeries]
Returns: TimeSeries|None: known_cov
- property static_cov: Optional[dict]
Returns: dict|None: static_cov
- split(split_point: Union[Timestamp, str, float, int], after=True) Tuple[TSDataset, TSDataset][源代码]
基于split_point拆分数据, 仅当self._target不为None的时候生效
- 参数
split_point (pd.Timestamp|float|int) – 数据拆分的时间点,支持三种类型:pd.Timestamp|str:只有当time_index类型是pd.DatatimeIndex的时候生效,返回对应的index,str会强制转换成pd.Timestamp;float:代表第一份数据的拆分比例,0到1之间,如0.8,代表第一份数据占总量的80%,第二份20%;int:代表第一份数据的数据量。split_point点的数据如果存在,会包涵在第一份数据中
after (bool) – 如果提供的pandas时间戳不在时间序列索引中,是否返回下一个时间戳或上一个时间戳的索引
- 返回
Tuple[“TSDataset”, “TSDataset”]
- 引发
ValueError –
TypeError –
- get_item_from_column(column: Union[str, int]) Union[TimeSeries, dict][源代码]
基于column名称返回其对应的类型的结合,包括target, observed_cov, known_cov, static_cov
- 参数
column (str) – column名称
- 返回
Union[“TimeSeries”, dict]
- 引发
ValueError –
- set_column(column: Union[str, int], value: Union[Series, str, int], type: str = 'known_cov')[源代码]
设置某列columns的列元素, 支持新增和修改
- 参数
column (str|int) – column名称
value (pd.Series|str|int) – columns列内容,其index必须和目标属性的index相同,仅仅当columns是static_cov类型的时候,value才可以是int或者str
type (str) – 设置的column类型,仅当新增的时候起作用,默认新增是known_cov类型,类型是target,known_cov, observed_cov, static_cov
- 返回
None
- 引发
ValueError –
- drop(columns: Union[str, int, List[Union[str, int]]])[源代码]
删除columns的列元素
- 参数
columns (str|int|List) – columns名称
- 返回
None
- 引发
ValueError –
- plot(columns: Union[List[str], str] = None, add_data: Union[List[TSDataset], TSDataset] = None, labels: Union[List[str], str] = None, low_quantile: float = 0.05, high_quantile: float = 0.95, central_quantile: float = 0.5, **kwargs) pyplot[源代码]
画图函数,对Dataframe.plot()的包装
- 参数
columns (str|List) – 指定打印的columns名称, columns为None时默认打印target
add_data (List|TSDataset) – 添加数据进行联合打印, 默认为None
labels (str|List) – 为添加数据增加自定义标签,自定义标签的长度应该等于添加数据的数量
central_quantile (float) – 中心分位- 概率区间的中心点,默认为0.5分位。(此参数只会在概率预测结果打印中用到)
low_quantile (float) – 低分位- 概率区间的下界,默认为0.05分位。(此参数只会在概率预测结果打印中用到)
high_quantile (float) – 高分位- 概率区间的上界,默认为0.95分位。(此参数只会在概率预测结果打印中用到)
**kwargs – 传入Dataframe.plot()的可选参数
- 返回
matplotlib.pyplot object
- 引发
ValueError –
- classmethod load_from_json(json_data: str, **json_load_kwargs) TSDataset[源代码]
基于CSV文件构建完整TSDataset
- 参数
json_data (str) – panas.DataFrame数据对象
**json_load_kwargs – 传json.loads()的可选参数
- 返回
TSDataset
- property columns: dict
返回所有列名(除static外)
- 返回
key是columns名称,value是类型,包括target, known_cov, observed_cov
- 返回类型
dict
- property freq
TSDataset数据频率
- classmethod concat(tss: List[TSDataset], axis: int = 0, drop_duplicates=True, keep='first') TSDataset[源代码]
用于合并两个数据集,target、known_cov以及observe_cov按照df规则合并,static按照dict合并
- 参数
tss (list[TimeSeries]) – TSDataset元素列表,要求所有TSDataset freq保持一致,当axis=1的时候,要求time_col不重复;axis=0的时候,要求所有columns不重复
axis (int) – 合并的维度,1是横向合并,0代表纵向合并
drop_duplicates (bool) – 是否对重复index的行进行删除,默认删除
keep (str) – 当对concat的时序数据有重复index并设置删除,保留第一个或者最后一个重复时序的数据
- 返回
TSDataset
- 引发
ValueError –
- astype(dtype: Union[dtype, type, Dict[str, Union[dtype, type]]])[源代码]
转换数据类型,注意这里不会返回一个新的数据,而是在原始数据集上修改
- 参数
dtype (Union[np.dtype, type, Dict[str, Union[np.dtype, type]]]) – 数据类型,可以是numpy.dtype|Python type或者是dict类型,直接调用df.astype使用,numpy.dtype|Python type代表对所有列做变换, dict代表对某一列或者几列做转换
- 引发
TypeError –
KeyError –
- property dtypes: Series
返回列类型
- 返回
<column name, dtype>
- 返回类型
pd.Series