paddlets.datasets.tsdataset

TSDatasetPaddleTS 中一个主要的类结构,用于表示绝大多数的时序样本数据,并作为PaddleTS其他算子的输入以及输出对象。TSDataset 包涵两类时序数据:

  1. 待预测目标:表示希望被预测的时序序列

  2. 协变量:无需被预测的时间序列,协变量的加入通常用于辅助提高模型预测的效果

TSDataset支持的时序样本数据可以分为:

  1. 单变量数据,只包含单列的预测目标,同时可以包涵单列或者多列协变量

  2. 多变量数据,包涵多列预测目标,同时可以包涵单列或者多列协变量

我们将非预测目标变量定义为协变量,在时序数据中,协变量可分为以下三种:

  1. 观测协变量 (observed_cov)

    指只能在历史中观察到的变量数据,例如测量的温度

  2. 可预知协变量 (known_cov)

    指可在预测未来时间已知的变量,例如天气预报

  3. 静态协变量 (static_cov)

    指整个时间范围内保持不变的变量

一个 TSDataset 对象由一个或者多个 TimeSeries 对象构成,每个 TimeSeries 可分别代表target(待预测目标), observed_covariate(观测协变量)以及known_covariate(可预知协变量)。

class TimeSeries(data: Union[DataFrame, Series], freq: Union[int, str])[源代码]

基类:object

TimeSeries 是用于表示时序数据的最小粒度。可以分别代表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

sort_columns(ascending: bool = True)[源代码]

对data的columns进行排序

参数

ascending (bool) – 升序或降序排序

drop_tail_nan()[源代码]

Drop trailing consecutive Nan values

to_json() str[源代码]

TimeSeries转换成json数据

返回

str

classmethod load_from_json(json_data: str, **json_load_kwargs) TimeSeries[源代码]

基于Json数据构建完整TSDataset

参数
  • json_data (str) – panas.DataFrame数据对象

  • **json_load_kwargs – 传json.loads()的可选参数

返回

TimeSeries

to_categorical(col: Optional[Union[List[str], str]] = None)[源代码]

将对应列的属性修改成分类类型的数据,也就是int类型,等同于astype(np.int64)

参数

col (Optional[Union[str, List[str]]]) – column名称

to_numeric(col: Optional[Union[List[str], str]] = None)[源代码]

将对应列的属性修改成数值类型的数据,也就是float类型,等同于astype(np.float32)

参数

col (Optional[Union[str, List[str]]]) – column名称

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)[源代码]

基类:object

TSDatasetPaddleTS 中一个主要的类结构,用于表示绝大多数的时序样本数据,并作为PaddleTS其他算子的输入以及输出对象。TSDataset 包涵两类时序数据:

  1. 待预测目标:表示希望被预测的时序序列

  2. 协变量:无需被预测的时间序列,协变量的加入通常用于辅助提高模型预测的效果

TSDataset支持的时序样本数据可以分为:

  1. 单变量数据,只包含单列的预测目标,同时可以包涵单列或者多列协变量

  2. 多变量数据,包涵多列预测目标,同时可以包涵单列或者多列协变量

我们将非预测目标变量定义为协变量,在时序数据中,协变量可分为以下三种:

  1. 观测协变量 (observed_cov)

    指只能在历史中观察到的变量数据,例如测量的温度

  2. 可预知协变量 (known_cov)

    指可在预测未来时间已知的变量,例如天气预报

  3. 静态协变量 (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_static_cov() Optional[dict][源代码]
返回

static_cov

返回类型

dict|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

copy() TSDataset[源代码]

返回一份拷贝的数据

返回

TSDataset

save(file: str)[源代码]

保存对象到文件

参数

file (str) – 文件路径

classmethod load(file: str) TSDataset[源代码]

从文件中获取对象

参数

file (str) – 文件路径

返回

TSDataset

to_json() str[源代码]

TSDataset转换成json数据

返回

str

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

sort_columns(ascending: bool = True)[源代码]

对所有元素的columns进行分别排序

参数

ascending (bool) – 升序或降序排序

to_categorical(col: Optional[Union[List[str], str]] = None)[源代码]

将对应列的属性修改成分类类型的数据,也就是int类型,等同于astype(np.int64)

参数

col (Optional[Union[str, List[str]]]) – column名称

to_numeric(col: Optional[Union[List[str], str]] = None)[源代码]

将对应列的属性修改成数值类型的数据,也就是float类型,等同于astype(np.float32)

参数

col (Optional[Union[str, List[str]]]) – column名称