时间序列¶

TimeSeries 是 darts 中的主要类。它表示单变量或多变量时间序列，可以是确定性的或随机的。

值存储在一个形状为 (时间, 维度, 样本) 的数组中，其中 dimensions 是多变量序列的维度（或“分量”、“列”），samples 是随机序列的样本。

定义

dimensions = 1 的序列是单变量的，而 dimensions > 1 的序列是多变量的。
samples = 1 的序列是确定性的，而 samples > 1 的序列是

随机性的（或概率性的）。

每个序列还存储一个 time_index，其中包含日期时间（pandas.DateTimeIndex）或整数索引（pandas.RangeIndex）。

TimeSeries 保证

具有单调递增的时间索引，没有间隔（没有缺失的日期）
只包含数字类型
具有不同的分量/列名
具有明确定义的频率（date offset aliases 用于 DateTimeIndex，或步长用于 RangeIndex）
具有与其分量一致的静态协变量，或者没有静态协变量
具有与其分量一致的层级结构，或者没有层级结构

TimeSeries 可以包含全局或分量特定的静态协变量数据。darts 中的静态协变量是指外部与时间无关的数据，某些模型可以使用这些数据来帮助改进预测。请阅读我们的协变量用户指南和 TimeSeries 文档，了解有关协变量的更多信息。

class darts.timeseries.TimeSeries(xa, copy=True)[source]¶

基类: object

从（格式正确的）DataArray 创建一个 TimeSeries。建议使用工厂方法来创建 TimeSeries。

另请参阅

TimeSeries.from_dataframe: 从 DataFrame 创建（pandas.DataFrame, polars.DataFrame, 以及其他后端）。
TimeSeries.from_group_dataframe: 从 pandas.DataFrame 按组创建多个 TimeSeries。
TimeSeries.from_series: 从 Series 创建（pandas.Series, polars.Series, 以及其他后端）。
TimeSeries.from_values: 从 numpy.ndarray 创建。
TimeSeries.from_times_and_values: 从时间索引和 numpy.ndarray 创建。
TimeSeries.from_csv: 从 CSV 文件创建。
TimeSeries.from_json: 从 JSON 文件创建。
TimeSeries.from_xarray: 从 xarray.DataArray 创建。

属性

`bottom_level_components`	此序列的底层分量名称，如果序列没有层级结构，则为 None。
`bottom_level_series`	包含此序列的底层分量的序列，顺序与它们在序列中出现的顺序相同，如果序列没有层级结构，则为 None。
`columns`	分量的名称，作为 Pandas Index。
`components`	分量的名称，作为 Pandas Index。
`dtype`	序列值的 dtype。
`duration`	此时间序列的持续时间（作为时间差或整数）。
`freq`	序列的频率。
`freq_str`	序列的频率字符串表示。
`has_datetime_index`	此序列是否使用 DatetimeIndex 索引（否则使用 RangeIndex 索引）。
`has_hierarchy`	此序列是否具有层级结构。
`has_metadata`	此序列是否包含元数据。
`has_range_index`	此序列是否使用 RangeIndex 索引（否则使用 DatetimeIndex 索引）。
`has_static_covariates`	此序列是否包含静态协变量。
`hierarchy`	此 TimeSeries 的层级结构（如果有）。
`is_deterministic`	此序列是否为确定性。
`is_probabilistic`	此序列是否为随机性（=概率性）。
`is_stochastic`	此序列是否为随机性。
`is_univariate`	此序列是否为单变量。
`metadata`	此 TimeSeries 的元数据（如果有）。
`n_components`	序列中包含的分量（维度）数量。
`n_samples`	序列中包含的样本数量。
`n_timesteps`	序列中的时间步数量。
`shape`	序列的形状 (n_timesteps, n_components, n_samples)。
`static_covariates`	返回序列中包含的静态协变量，作为 pandas DataFrame。
`time_dim`	此时间序列的时间维度名称。
`time_index`	此时间序列的时间索引。
`top_level_component`	此序列的顶层分量名称，如果序列没有层级结构，则为 None。
`top_level_series`	包含此序列的单个顶层分量的单变量序列，如果序列没有层级结构，则为 None。
`width`	序列的“宽度”（= 分量数量）。

方法

`add_datetime_attribute`(attribute[, one_hot, ...])	构建一个新序列，其中包含一个（或多个）附加分量，这些分量包含序列时间索引的属性。
`add_holidays`(country_code[, prov, state, tz])	向当前序列添加一个二进制单变量分量，该分量在对应所选国家/地区假期的每个索引处等于 1，否则等于 0。
`all_values`([copy])	返回一个维度为 (时间, 分量, 样本) 的三维数组，其中包含此序列所有样本的值。
`append`(other)	沿时间轴将另一个序列附加到此序列。
`append_values`(values)	将新值附加到当前的 TimeSeries，扩展其时间索引。
`astype`(dtype)	将此序列转换为具有所需 dtype 的新序列。
`concatenate`(other[, axis, ignore_time_axis, ...])	沿给定轴将另一个时间序列连接到当前时间序列。
`copy`()	创建此序列的副本。
`cumsum`()	返回时间序列沿时间轴的累积和。
`data_array`([copy])	返回此序列底层的 `xarray.DataArray` 表示。
`diff`([n, periods, dropna])	返回一个差分时间序列。
`drop_after`(split_point)	删除提供的 split_point 时间点之后的所有内容（包括该时间点）。
`drop_before`(split_point)	删除提供的 split_point 时间点之前的所有内容（包括该时间点）。
`drop_columns`(col_names)	返回一个新的 `TimeSeries` 实例，其中已删除指定的列/分量。
`end_time`()	序列的结束时间。
`first_value`()	此单变量序列的第一个值。
`first_values`()	此可能的多变量序列的第一个值（每个分量）。
`from_csv`(filepath_or_buffer[, time_col, ...])	从单个 CSV 文件构建一个确定性的 TimeSeries 实例。
`from_dataframe`(df[, time_col, value_cols, ...])	从 DataFrame 中选定的列构建一个确定性的 TimeSeries 实例。
`from_group_dataframe`(df, group_cols[, ...])	从 DataFrame 中按选定列分组构建 TimeSeries 实例列表。
`from_json`(json_str[, static_covariates, ...])	从 `TimeSeries` 的 JSON 字符串表示形式构建序列（使用 `TimeSeries.to_json()` 生成）。
`from_pickle`(path)	读取序列化的 `TimeSeries`。
`from_series`(pd_series[, fill_missing_dates, ...])	从 Series 构建一个单变量确定性 TimeSeries。
`from_times_and_values`(times, values[, ...])	从时间索引和值数组构建序列。
`from_values`(values[, columns, fillna_value, ...])	从值数组构建一个整数索引序列。
`from_xarray`(xa[, fill_missing_dates, freq, ...])	从 xarray DataArray 返回一个 TimeSeries 实例。
`gaps`([mode])	计算并返回 TimeSeries 中间隔的函数。
`get_index_at_point`(point[, after])	将时间轴索引上的点转换为整数索引，范围在 (0, len(series)-1) 内。
`get_timestamp_at_point`(point)	将点转换为 pandas.Timestamp（如果是 Datetime 索引）或整数（如果是 Int64 索引）。
`has_same_time_as`(other)	检查此序列是否与 other 具有相同的时间索引。
`head`([size, axis])	返回包含前 size 个点的时间序列。
`is_within_range`(ts)	检查给定的时间戳或整数是否在此时间序列的时间间隔内。
`kurtosis`(**kwargs)	返回一个确定性的 `TimeSeries`，其中包含此随机 `TimeSeries` 每个分量（跨样本）的峰度。
`last_value`()	此单变量序列的最后一个值。
`last_values`()	此可能的多变量序列的最后一个值（每个分量）。
`longest_contiguous_slice`([max_gap_size, mode])	返回此确定性序列的最大 TimeSeries 片段，该片段不包含大于 max_gap_size 的间隔（连续的 NaN 值）。
`map`(fn)	将函数 fn 应用于包含此序列值的底层 NumPy 数组。
`max`([axis])	返回一个包含在指定轴上计算的最大值的 `TimeSeries`。
`mean`([axis])	返回一个包含在指定轴上计算的平均值的 `TimeSeries`。
`median`([axis])	返回一个包含在指定轴上计算的中位数的 `TimeSeries`。
`min`([axis])	返回一个包含在指定轴上计算的最小值的 `TimeSeries`。
`plot`([new_plot, central_quantile, ...])	绘制序列。
`prepend`(other)	前置（即添加到开头）
`prepend_values`(values)	前置（即添加到开头）
`quantile`(quantile, **kwargs)	返回一个确定性的 `TimeSeries`，其中包含此随机 `TimeSeries` 每个分量（跨样本）的所需单个分位数。
`quantile_df`([quantile])	返回一个 Pandas DataFrame，其中包含每个分量（跨样本）所需的单个分位数。
`quantile_timeseries`([quantile])	返回一个确定性的 `TimeSeries`，其中包含此随机 `TimeSeries` 每个分量（跨样本）的所需单个分位数。
`quantiles_df`([quantiles])	返回一个 Pandas DataFrame，其中包含每个分量（跨样本）所需的多个分位数。
`random_component_values`([copy])	返回一个形状为 (时间, 分量) 的二维数组，其中包含从此序列样本中随机均匀抽取的一个样本的值。
`resample`(freq[, method, method_kwargs])	使用给定频率构建重新索引的 `TimeSeries`。
`rescale_with_value`(value_at_first_step)	返回一个新的 `TimeSeries`，它是此序列的倍数，使得第一个值为 value_at_first_step。
`shift`(n)	将此 TimeSeries 的时间轴移动 n 个时间步。
`skew`(**kwargs)	返回一个确定性的 `TimeSeries`，其中包含此随机 `TimeSeries` 每个分量（跨样本）的偏度。
`slice`(start_ts, end_ts)	返回一个新的 TimeSeries，开始时间晚于 start_ts，结束时间早于 end_ts。
`slice_intersect`(other)	返回此序列的 `TimeSeries` 片段，其时间索引已与 other 序列的时间索引相交。
`slice_intersect_times`(other[, copy])	返回此序列的时间索引，其时间索引已与 other 序列的时间索引相交。
`slice_intersect_values`(other[, copy])	返回此序列的切片值，其时间索引已与 other 序列的时间索引相交。
`slice_n_points_after`(start_ts, n)	返回一个新的 TimeSeries，从 start_ts 开始（包括），最多包含 n 个点。
`slice_n_points_before`(end_ts, n)	返回一个新的 TimeSeries，在 end_ts 结束（包括），最多包含 n 个点。
`split_after`(split_point)	在提供的 split_point 之后将序列分成两部分。
`split_before`(split_point)	在提供的 split_point 之前将序列分成两部分。
`stack`(other)	将具有相同时间索引的另一个单变量或多变量 TimeSeries 堆叠到当前 TimeSeries 的顶部（沿分量轴）。
`start_time`()	序列的开始时间。
`static_covariates_values`([copy])	返回一个维度为 (分量, 静态变量) 的二维数组，其中包含 TimeSeries 的静态协变量值。
`std`([ddof])	返回一个确定性的 `TimeSeries`，其中包含此随机 `TimeSeries` 每个分量（跨样本）的标准差。
`strip`([how])	返回此确定性时间序列的 `TimeSeries` 片段，其中移除了序列开头和结尾包含 NaN 的条目。
`sum`([axis])	返回一个包含在指定轴上计算的总和的 `TimeSeries`。
`tail`([size, axis])	返回序列的最后 size 个点。
`to_csv`(args, *kwargs)	将此确定性序列写入 CSV 文件。
`to_dataframe`([copy, backend, time_as_index, ...])	以给定的 backend 返回此时间序列的 DataFrame 表示。
`to_json`()	返回此确定性序列的 JSON 字符串表示形式。
`to_pickle`(path[, protocol])	以 pickle 格式保存此序列。
`to_series`([copy, backend])	以给定的 backend 返回此时间序列的 Series 表示。
`univariate_component`(index)	检索序列中的一个分量，并将其作为新的单变量 `TimeSeries` 实例返回。
`univariate_values`([copy, sample])	返回一个形状为 (时间,) 的一维 Numpy 数组，其中包含此单变量序列在一个 sample 的值。
`values`([copy, sample])	返回一个形状为 (时间, 分量) 的二维数组，其中包含此序列在一个 sample 的值。
`var`([ddof])	返回一个确定性的 `TimeSeries`，其中包含此随机 `TimeSeries` 每个分量（跨样本）的方差。
`window_transform`(transforms[, treat_na, ...])	对此 `TimeSeries` 应用移动/滚动、扩展或指数加权窗口转换。
`with_columns_renamed`(col_names, col_names_new)	返回一个新的 `TimeSeries` 实例，具有新的列/分量名称。
`with_hierarchy`(hierarchy)	为 TimeSeries 添加层级结构。
`with_metadata`(metadata)	为 TimeSeries 添加元数据。
`with_static_covariates`(covariates)	返回一个新的 TimeSeries 对象，其中添加了静态协变量。
`with_times_and_values`(times, values[, ...])	返回一个新的 `TimeSeries`，类似于此序列，但具有新的指定值。
`with_values`(values)	返回一个新的 `TimeSeries`，类似于此序列，但具有新的指定值。

add_datetime_attribute(attribute, one_hot=False, cyclic=False, tz=None)[source]¶

构建一个新序列，其中包含一个（或多个）附加分量，这些分量包含序列时间索引的属性。

附加分量由 attribute 指定，例如“工作日”、“天”或“月”。

这仅适用于确定性时间序列（即，由 1 个样本组成）。

注意

所有编码均强制使用 0 索引，请参阅 datetime_attribute_timeseries() 了解更多信息。

参数

attribute – 将作为新列基础的 pd.DatatimeIndex 属性。
one_hot (bool) – 布尔值，指示是否将指定属性添加为独热编码（导致更多列）。
cyclic (bool) – 布尔值，指示是否将指定属性添加为循环编码。与独热编码互斥，仅启用其中一个。（添加 2 列，对应于 sin 和 cos 变换）。
tz (Optional[str, None]) – 可选参数，计算属性之前将时间索引转换到的时区。

返回

由 attribute 增强的新 TimeSeries 实例。

返回类型

TimeSeries

add_holidays(country_code, prov=None, state=None, tz=None)[source]¶

向当前序列添加一个二进制单变量分量，该分量在对应所选国家/地区假期的每个索引处等于 1，否则等于 0。

TimeSeries 的频率是日。

可用的国家/地区可以在这里找到。

这仅适用于确定性时间序列（即，由 1 个样本组成）。

参数

country_code (str) – 国家/地区 ISO 代码
prov (Optional[str, None]) – 省份
state (Optional[str, None]) – 州/邦
tz (Optional[str, None]) – 可选参数，计算属性之前将时间索引转换到的时区。

返回

一个新的 TimeSeries 实例，用二进制假日分量增强。

返回类型

TimeSeries

all_values(copy=True)[source]¶

返回一个维度为 (时间, 分量, 样本) 的三维数组，其中包含此序列所有样本的值。

参数: copy (bool) – 是否返回值的副本，否则返回一个视图。除非您知道自己在做什么，否则请将其保留为 True。
返回: 组成时间序列的值。
返回类型: numpy.ndarray

append(other)[source]¶

沿时间轴将另一个序列附加到此序列。

参数: other (Self) – 第二个 TimeSeries。
返回: 通过将第二个 TimeSeries 附加到第一个 TimeSeries 获得的新 TimeSeries。
返回类型: TimeSeries

另请参阅

TimeSeries.concatenate: 沿给定轴连接另一个序列。
TimeSeries.prepend: 前置（即添加到开头）沿时间轴的另一个序列。

append_values(values)[source]¶

将新值附加到当前的 TimeSeries，扩展其时间索引。

参数: values (ndarray) – 要附加的值数组。
返回: 一个附加了新值的新 TimeSeries
返回类型: TimeSeries

astype(dtype)[source]¶

将此序列转换为具有所需 dtype 的新序列。

参数: dtype (Union[str, dtype]) – NumPy dtype (np.float32 或 np.float64)
返回: 具有所需 dtype 的 TimeSeries。
返回类型: TimeSeries

property bottom_level_components: Optional[list[str]]¶

此序列的底层分量名称，如果序列没有层级结构，则为 None。

返回类型: Optional[list[str], None]

property bottom_level_series: Optional[list[typing_extensions.Self]]¶

包含此序列的底层分量的序列，顺序与它们在序列中出现的顺序相同，如果序列没有层级结构，则为 None。

如果有多个底层分量，返回的序列是多变量的。

返回类型: Optional[list[Self], None]

property columns: Index¶

分量的名称，作为 Pandas Index。

返回类型: Index

property components: Index¶

分量的名称，作为 Pandas Index。

返回类型: Index

concatenate(other, axis=0, ignore_time_axis=False, ignore_static_covariates=False, drop_hierarchy=True, drop_metadata=False)[source]¶

沿给定轴将另一个时间序列连接到当前时间序列。

参数

other (TimeSeries) – 要连接到此时间序列的另一个时间序列
axis (str or int) – 连接时间序列的轴。['time'，'component' 或 'sample'；默认值：0 (time)]
ignore_time_axis (bool, default False) – 当某些时间序列的时间轴发生变化时忽略错误。请注意，这可能会产生意外结果。
ignore_static_covariates (bool) – 是否忽略静态协变量连接的所有要求，并且仅将当前 (self) 时间序列的静态协变量转移到连接的时间序列。仅在 axis=1 时有效。
drop_hierarchy (bool) – 当 axis=1 时，是否丢弃层级结构信息。默认为 True。当为 False 时，层级结构也将被“连接”（通过合并层级结构字典），如果结果序列的分量名称与合并后的层级结构不匹配，可能会导致问题。当 axis=0 或 axis=2 时，始终保留第一个序列的层级结构。
drop_metadata (bool) – 是否丢弃连接时间序列的元数据信息。默认为 False。当为 False 时，连接的序列将继承当前 (self) 时间序列的元数据。

返回

连接的时间序列

返回类型

TimeSeries

另请参阅

concatenate: 沿给定轴连接多个序列的函数。

注意

沿 time 维度连接时，当前序列标记结果序列的开始日期，而其他序列的时间索引将被忽略。

copy()[source]¶

创建此序列的副本。

返回: 此时间序列的副本。
返回类型: TimeSeries

cumsum()[source]¶

返回时间序列沿时间轴的累积和。

返回: 一个新的 TimeSeries，其中包含累积求和的值。
返回类型: TimeSeries

data_array(copy=True)[source]¶

返回此序列底层的 xarray.DataArray 表示。

参数: copy (bool) – 是否返回序列的副本。除非您知道自己在做什么，否则请将其保留为 True。
返回: 此时间序列底层的 xarray DataArray。
返回类型: xarray.DataArray

diff(n=1, periods=1, dropna=True)[source]¶

返回一个差分时间序列。这通常用于使时间序列平稳。

参数

n (Optional[int, None]) – 可选参数，一个正整数，表示差分步数（默认值 = 1）。例如，n=2 计算二阶差分。
periods (Optional[int, None]) – 可选参数，用于计算差分的移位周期。例如，periods=12 计算时间 t 和时间 t-12 之间的差值。
dropna (Optional[bool, None]) – 是否在每个差分步骤后丢弃缺失值。如果设置为 False，则相应的前 periods 个时间步将填充 NaN。

返回

一个新的 TimeSeries，其中包含差分后的值。

返回类型

TimeSeries

drop_after(split_point)[source]¶

删除提供的 split_point 时间点之后的所有内容（包括该时间点）。时间戳可能不在序列中。如果在序列中，则该时间戳将被删除。

参数: split_point (Union[Timestamp, float, int]) – 表示截止时间的时间戳。
返回: 一个新的 TimeSeries，位于 ts 之后。
返回类型: TimeSeries

drop_before(split_point)[source]¶

丢弃指定时间点 split_point 之前的所有数据（包括该时间点）。该时间戳可能不在时间序列中。如果存在，该时间戳将被丢弃。

参数: split_point (Union[Timestamp, float, int]) – 表示截止时间的时间戳。
返回: 一个新的 TimeSeries，位于 ts 之后。
返回类型: TimeSeries

drop_columns(col_names)[source]¶

返回一个新的 TimeSeries 实例，其中已删除指定的列/分量。

参数: col_names (Union[list[str], str]) – 字符串或字符串列表，对应于要丢弃的列名。
返回: 一个新的 TimeSeries 实例，其中已丢弃指定的列。
返回类型: TimeSeries

property dtype¶: 时间序列值的 dtype（数据类型）。

property duration: Union[Timedelta, int]¶

此时间序列的持续时间（作为时间差或整数）。

返回类型: Union[Timedelta, int]

end_time()[source]¶

序列的结束时间。

返回: 包含 TimeSeries 最后时间的 timestamp（如果按 DatetimeIndex 索引）或整数（如果按 RangeIndex 索引）。
返回类型: Union[pandas.Timestamp, int]

first_value()[source]¶

此单变量序列的第一个值。

返回: 这个单变量确定性时间序列的第一个值。
返回类型: float

first_values()[source]¶

此可能的多变量序列的第一个值（每个分量）。

返回: 这个确定性时间序列的每个分量的第一个值。
返回类型: np.ndarray

property freq: Union[DateOffset, int]¶

时间序列的频率。如果时间序列使用 pd.DatetimeIndex 索引，则为 pd.DateOffset 类型。如果时间序列使用 pd.RangeIndex 索引，则为整数（步长）。

返回类型: Union[DateOffset, int]

property freq_str: str¶

序列的频率字符串表示。

返回类型: str

classmethod from_csv(filepath_or_buffer, time_col=None, value_cols=None, fill_missing_dates=False, freq=None, fillna_value=None, static_covariates=None, hierarchy=None, metadata=None, **kwargs)[source]¶

从单个 CSV 文件构建一个确定性 TimeSeries 实例。可以使用一列表示时间（如果不存在，时间索引将为 RangeIndex），并可以使用 value_cols 列表中的列作为该时间序列的值。

参数

filepath_or_buffer – CSV 文件的路径或文件对象；与 pandas.read_csv 函数的参数一致。
time_col (Optional[str, None]) – 时间列名。如果设置，该列将转换为 pandas DatetimeIndex（如果包含时间戳）或 RangeIndex（如果包含整数）。如果未设置，将使用 pandas RangeIndex。
value_cols (Union[str, list[str], None]) – 表示要从 CSV 文件中提取的值列（一个或多个）的字符串或字符串列表。如果设置为 None，将使用 CSV 文件中的所有列（除了 time_col，如果指定）。
fill_missing_dates (Optional[bool, None]) – 可选，布尔值，指示是否用 NaN 值填充缺失的日期（或整数索引的情况下的索引）。这需要提供 freq 或能够从提供的时间戳推断频率。更多信息请参阅 _fill_missing_dates()。
freq (Union[str, int, None]) – 可选，字符串或整数，表示基础索引的频率。如果缺失某些日期且 fill_missing_dates 设置为 True，这对于填充缺失值很有用。如果为字符串，表示 pandas DatetimeIndex 的频率（有关支持的频率的更多信息，请参阅 offset aliases）。如果为整数，表示 pandas Index 或 pandas RangeIndex 的步长。
fillna_value (Optional[float, None]) – 可选，用于填充缺失值 (NaNs) 的数值。
static_covariates (Union[Series, DataFrame, None]) – 可选，添加到 TimeSeries 的静态协变量集。可以是 pandas Series 或 pandas DataFrame。如果为 Series，索引表示静态变量。协变量全局“应用于” TimeSeries 的所有分量。如果为 DataFrame，列表示静态变量，行表示单变量/多变量 TimeSeries 的分量。如果为单行 DataFrame，协变量全局“应用于” TimeSeries 的所有分量。如果为多行 DataFrame，行数必须与 TimeSeries 的分量数（即 CSV 文件中的列数）匹配。这允许对特定分量的静态协变量进行控制。
hierarchy (Optional[dict, None]) –
可选，描述时间序列分组的字典。键是分量名称，对于给定的分量名称 c，值是 c“所属”的分量名称列表。例如，如果存在一个 total 分量，分为两个部门 d1 和 d2，以及两个区域 r1 和 r2，以及四个产品 d1r1（属于部门 d1 和区域 r1）、d2r1、d1r2 和 d2r2，则层次结构将编码如下。
```
hierarchy={
    "d1r1": ["d1", "r1"],
    "d1r2": ["d1", "r2"],
    "d2r1": ["d2", "r1"],
    "d2r2": ["d2", "r2"],
    "d1": ["total"],
    "d2": ["total"],
    "r1": ["total"],
    "r2": ["total"]
}
```
层次结构可用于协调预测（使不同层级的预测总和一致），请参阅分层协调。
metadata (Optional[dict, None]) – 可选，一个字典，包含要添加到 TimeSeries 的元数据。
**kwargs – 可选参数，将传递给 pandas.read_csv 函数。

返回

从输入构建的单变量或多变量确定性 TimeSeries。

返回类型

TimeSeries

示例

>>> from darts import TimeSeries
>>> TimeSeries.from_csv("data.csv", time_col="time")

classmethod from_dataframe(df, time_col=None, value_cols=None, fill_missing_dates=False, freq=None, fillna_value=None, static_covariates=None, hierarchy=None, metadata=None)[source]¶

从 DataFrame 的选定列构建一个确定性 TimeSeries 实例。必须有一列（或 DataFrame 索引）表示时间，并且必须有一个 value_cols 列列表表示该时间序列的值。

参数

df (Union[ForwardRef, ForwardRef, ForwardRef]) – DataFrame，或任何可以转换为 narwhals DataFrame 的对象（例如 pandas.DataFrame, polars.DataFrame, …）。更多信息请参阅 narwhals 文档。
time_col (Optional[str, None]) – 时间列名。如果设置，该列将转换为 pandas DatetimeIndex（如果包含时间戳）或 RangeIndex（如果包含整数）。如果未设置，将使用 DataFrame 索引。在这种情况下，DataFrame 必须包含一个 pandas DatetimeIndex、pandas RangeIndex 或可以转换为 RangeIndex 的 pandas Index。最好索引没有空洞；或者设置 fill_missing_dates 在某些情况下可以解决这些问题（用 NaN 填充空洞，或用提供的 fillna_value 数值填充）。
value_cols (Union[list[str], str, None]) – 表示要从 DataFrame 中提取的值列（一个或多个）的字符串或字符串列表。如果设置为 None，将使用整个 DataFrame。
fill_missing_dates (Optional[bool, None]) – 可选，布尔值，指示是否用 NaN 值填充缺失的日期（或整数索引的情况下的索引）。这需要提供 freq 或能够从提供的时间戳推断频率。更多信息请参阅 _fill_missing_dates()。
freq (Union[str, int, None]) –
可选，字符串或整数，表示基础索引的频率。如果缺失某些日期且 fill_missing_dates 设置为 True，这对于填充缺失值很有用。如果为字符串，表示 pandas DatetimeIndex 的频率（有关支持的频率的更多信息，请参阅 offset aliases）。如果为整数，表示 pandas Index 或 pandas RangeIndex 的步长。
fillna_value (Optional[float, None]) – 可选，用于填充缺失值 (NaNs) 的数值。
static_covariates (Union[Series, DataFrame, None]) – 可选，添加到 TimeSeries 的静态协变量集。可以是 pandas Series 或 pandas DataFrame。如果为 Series，索引表示静态变量。协变量全局“应用于” TimeSeries 的所有分量。如果为 DataFrame，列表示静态变量，行表示单变量/多变量 TimeSeries 的分量。如果为单行 DataFrame，协变量全局“应用于” TimeSeries 的所有分量。如果为多行 DataFrame，行数必须与 TimeSeries 的分量数（即 value_cols 中的列数）匹配。这允许对特定分量的静态协变量进行控制。
hierarchy (Optional[dict, None]) –
可选，描述时间序列分组的字典。键是分量名称，对于给定的分量名称 c，值是 c“所属”的分量名称列表。例如，如果存在一个 total 分量，分为两个部门 d1 和 d2，以及两个区域 r1 和 r2，以及四个产品 d1r1（属于部门 d1 和区域 r1）、d2r1、d1r2 和 d2r2，则层次结构将编码如下。
```
hierarchy={
    "d1r1": ["d1", "r1"],
    "d1r2": ["d1", "r2"],
    "d2r1": ["d2", "r1"],
    "d2r2": ["d2", "r2"],
    "d1": ["total"],
    "d2": ["total"],
    "r1": ["total"],
    "r2": ["total"]
}
```
层次结构可用于协调预测（使不同层级的预测总和一致），请参阅分层协调。
metadata (Optional[dict, None]) – 可选，一个字典，包含要添加到 TimeSeries 的元数据。

返回

从输入构建的单变量或多变量确定性 TimeSeries。

返回类型

TimeSeries

示例

>>> import pandas as pd
>>> from darts import TimeSeries
>>> from darts.utils.utils import generate_index
>>> # create values and times with daily frequency
>>> data = {"vals": range(3), "time": generate_index("2020-01-01", length=3, freq="D")}
>>> # create from `pandas.DataFrame`
>>> df = pd.DataFrame(data)
>>> series = TimeSeries.from_dataframe(df, time_col="time")
>>> # shape (n time steps, n components, n samples)
>>> series.shape
(3, 1, 1)

>>> # or from `polars.DataFrame` (make sure Polars is installed)
>>> import polars as pl
>>> df = pl.DataFrame(data)
>>> series = TimeSeries.from_dataframe(df, time_col="time")
>>> series.shape
(3, 1, 1)

classmethod from_group_dataframe(df, group_cols, time_col=None, value_cols=None, static_cols=None, metadata_cols=None, fill_missing_dates=False, freq=None, fillna_value=None, drop_group_cols=None, n_jobs=1, verbose=False)[source]¶

从 DataFrame 的选定列分组构建 TimeSeries 实例列表。必须有一列（或 DataFrame 索引）表示时间，必须使用 group_cols 列列表按组提取各个 TimeSeries，并且必须使用 value_cols 列列表表示各个时间序列的值。来自 group_cols 和 static_cols 列的值作为静态协变量添加到生成的 TimeSeries 对象中。可以使用 my_series.static_covariates 查看这些协变量。与 group_cols 不同，static_cols 只添加静态值，不用于提取 TimeSeries 组。

参数

df (DataFrame) – DataFrame。
group_cols (Union[list[str], str]) – 表示用于从 DataFrame 中提取各个 TimeSeries 组的列（一个或多个）的字符串或字符串列表。
time_col (Optional[str, None]) – 时间列名。如果设置，该列将转换为 pandas DatetimeIndex（如果包含时间戳）或 RangeIndex（如果包含整数）。如果未设置，将使用 DataFrame 索引。在这种情况下，DataFrame 必须包含一个 pandas DatetimeIndex、pandas RangeIndex 或可以转换为 RangeIndex 的 pandas Index。请注意，索引必须表示每个独立时间序列组的实际索引（可以包含非唯一值）。最好索引没有空洞；或者设置 fill_missing_dates 在某些情况下可以解决这些问题（用 NaN 填充空洞，或用提供的 fillna_value 数值填充）。
value_cols (Union[str, list[str], None]) – 表示要从 DataFrame 中提取的值列（一个或多个）的字符串或字符串列表。如果设置为 None，将使用整个 DataFrame。
static_cols (Union[str, list[str], None]) – 表示 DataFrame 中应作为静态协变量附加到生成的 TimeSeries 组的静态变量列（一个或多个）的字符串或字符串列表。与 group_cols 不同，DataFrame 不按这些列进行分组。使用每组每列的第一个遇到的值（假设每列每组只有一个唯一值）。静态协变量可以作为支持它的所有 Darts 模型的输入特征。
metadata_cols (Union[str, list[str], None]) – 与 static_cols 相同，但作为元数据附加到生成的 TimeSeries 组。元数据永远不会被底层 Darts 模型使用。
fill_missing_dates (Optional[bool, None]) – 可选，布尔值，指示是否用 NaN 值填充缺失的日期（或整数索引的情况下的索引）。这需要提供 freq 或能够从提供的时间戳推断频率。更多信息请参阅 _fill_missing_dates()。
freq (Union[str, int, None]) –
可选，字符串或整数，表示基础索引的频率。如果缺失某些日期且 fill_missing_dates 设置为 True，这对于填充缺失值很有用。如果为字符串，表示 pandas DatetimeIndex 的频率（有关支持的频率的更多信息，请参阅 offset aliases）。如果为整数，表示 pandas Index 或 pandas RangeIndex 的步长。
fillna_value (Optional[float, None]) – 可选，用于填充缺失值 (NaNs) 的数值。
drop_group_cols (Union[str, list[str], None]) – 可选，字符串或字符串列表，包含要从静态协变量中排除的 group_cols 列。
n_jobs (Optional[int, None]) – 可选，整数，表示要运行的并行作业数。行为与 joblib.Parallel 类相同。
verbose (Optional[bool, None]) – 可选，布尔值，指示是否显示进度条。

返回

DataFrame 中每个组包含一个单变量或多变量确定性 TimeSeries 的列表。

返回类型

List[TimeSeries]

示例

>>> import pandas as pd
>>> from darts import TimeSeries
>>> from darts.utils.utils import generate_index
>>>
>>> # create a DataFrame with two series that have different ids,
>>> # values, and frequencies
>>> df_1 = pd.DataFrame({
>>>     "ID": [0] * 3,
>>>     "vals": range(3),
>>>     "time": generate_index("2020-01-01", length=3, freq="D")}
>>> )
>>> df_2 = pd.DataFrame({
>>>     "ID": [1] * 6,
>>>     "vals": range(6),
>>>     "time": generate_index("2020-01-01", length=6, freq="h")}
>>> )
>>> df = pd.concat([df_1, df_2], axis=0)
>>>
>>> # extract the series by "ID" groups from the DataFrame
>>> series_multi = TimeSeries.from_group_dataframe(
>>>     df,
>>>     group_cols="ID",
>>>     time_col="time"
>>> )
>>> len(series_multi), series_multi[0].shape, series_multi[1].shape
(2, (3, 1, 1), (6, 1, 1))

classmethod from_json(json_str, static_covariates=None, hierarchy=None, metadata=None)[source]¶

从 TimeSeries 的 JSON 字符串表示形式构建序列（使用 TimeSeries.to_json() 生成）。

目前仅支持确定性时间序列（即，由 1 个样本构成）。

参数

json_str (str) – 要转换的 JSON 字符串。
static_covariates (Union[Series, DataFrame, None]) – 可选，添加到 TimeSeries 的静态协变量集。可以是 pandas Series 或 pandas DataFrame。如果为 Series，索引表示静态变量。协变量全局“应用于” TimeSeries 的所有分量。如果为 DataFrame，列表示静态变量，行表示单变量/多变量 TimeSeries 的分量。如果为单行 DataFrame，协变量全局“应用于” TimeSeries 的所有分量。如果为多行 DataFrame，行数必须与 TimeSeries 的分量数（即 value_cols 中的列数）匹配。这允许对特定分量的静态协变量进行控制。
hierarchy (Optional[dict, None]) –
可选，描述时间序列分组的字典。键是分量名称，对于给定的分量名称 c，值是 c“所属”的分量名称列表。例如，如果存在一个 total 分量，分为两个部门 d1 和 d2，以及两个区域 r1 和 r2，以及四个产品 d1r1（属于部门 d1 和区域 r1）、d2r1、d1r2 和 d2r2，则层次结构将编码如下。
```
hierarchy={
    "d1r1": ["d1", "r1"],
    "d1r2": ["d1", "r2"],
    "d2r1": ["d2", "r1"],
    "d2r2": ["d2", "r2"],
    "d1": ["total"],
    "d2": ["total"],
    "r1": ["total"],
    "r2": ["total"]
}
```
层次结构可用于协调预测（使不同层级的预测总和一致），请参阅分层协调。
metadata (Optional[dict, None]) – 可选，一个字典，包含要添加到 TimeSeries 的元数据。

返回

从 JSON 字符串转换的时间序列对象。

返回类型

TimeSeries

示例

>>> from darts import TimeSeries
>>> json_str = (
>>>     '{"columns":["vals"],"index":["2020-01-01","2020-01-02","2020-01-03"],"data":[[0.0],[1.0],[2.0]]}'
>>> )
>>> series = TimeSeries.from_json("data.csv")
>>> series.shape
(3, 1, 1)

classmethod from_pickle(path)[source]¶

读取序列化的 TimeSeries。

参数: path (string) – 指向将加载的 pickle 文件的路径。
返回: 从文件加载的时间序列对象。
返回类型: TimeSeries

注意

Xarray 文档 [1] 建议不要将 pickle 用作长期数据存储。

参考资料

1: http://xarray.pydata.org/en/stable/user-guide/io.html#pickle

classmethod from_series(pd_series, fill_missing_dates=False, freq=None, fillna_value=None, static_covariates=None, metadata=None)[source]¶

从 Series 构建一个单变量确定性 TimeSeries。

该序列必须包含一个 pandas DatetimeIndex、pandas RangeIndex 或可以转换为 RangeIndex 的 pandas Index 作为索引。最好索引没有空洞；或者设置 fill_missing_dates 在某些情况下可以解决这些问题（用 NaN 填充空洞，或用提供的 fillna_value 数值填充）。

参数

pd_series (NativeSeries) –
Series，或任何可以转换为 narwhals Series 的对象（例如 pandas.Series, …）。更多信息请参阅 narwhals 文档。
fill_missing_dates (Optional[bool, None]) – 可选，布尔值，指示是否用 NaN 值填充缺失的日期（或整数索引的情况下的索引）。这需要提供 freq 或能够从提供的时间戳推断频率。更多信息请参阅 _fill_missing_dates()。
freq (Union[str, int, None]) –
可选，字符串或整数，表示基础索引的频率。如果缺失某些日期且 fill_missing_dates 设置为 True，这对于填充缺失值很有用。如果为字符串，表示 pandas DatetimeIndex 的频率（有关支持的频率的更多信息，请参阅 offset aliases）。如果为整数，表示 pandas Index 或 pandas RangeIndex 的步长。
fillna_value (Optional[float, None]) – 可选，用于填充缺失值 (NaNs) 的数值。
static_covariates (Union[Series, DataFrame, None]) – 可选，添加到 TimeSeries 的静态协变量集。可以是 pandas Series 或单行 pandas DataFrame。如果为 Series，索引表示静态变量。如果为 DataFrame，列表示静态变量，单行表示单变量 TimeSeries 分量。
metadata (Optional[dict, None]) – 可选，一个字典，包含要添加到 TimeSeries 的元数据。

返回

从输入构建的单变量确定性 TimeSeries。

返回类型

TimeSeries

示例

>>> import pandas as pd
>>> from darts import TimeSeries
>>> from darts.utils.utils import generate_index
>>> # create values and times with daily frequency
>>> vals, times = range(3), generate_index("2020-01-01", length=3, freq="D")
>>>
>>> # create from `pandas.Series`
>>> pd_series = pd.Series(vals, index=times)
>>> series = TimeSeries.from_series(pd_series)
>>> series.shape
(3, 1, 1)

classmethod from_times_and_values(times, values, fill_missing_dates=False, freq=None, columns=None, fillna_value=None, static_covariates=None, hierarchy=None, metadata=None)[source]¶

从时间索引和值数组构建序列。

参数

times (Union[DatetimeIndex, RangeIndex, Index]) – 一个 pandas DateTimeIndex、RangeIndex 或可以转换为 RangeIndex 的 Index，表示时间序列的时间轴。最好索引没有空洞；或者设置 fill_missing_dates 在某些情况下可以解决这些问题（用 NaN 填充空洞，或用提供的 fillna_value 数值填充）。
values (ndarray) – TimeSeries 的 NumPy 数组值。接受二维数组（用于确定性序列）和三维数组（用于概率序列）。在前一种情况下，维度应为 (时间, 分量)，后一种情况下应为 (时间, 分量, 样本)。
fill_missing_dates (Optional[bool, None]) – 可选，布尔值，指示是否用 NaN 值填充缺失的日期（或整数索引的情况下的索引）。这需要提供 freq 或能够从提供的时间戳推断频率。更多信息请参阅 _fill_missing_dates()。
freq (Union[str, int, None]) –
可选，字符串或整数，表示基础索引的频率。如果缺失某些日期且 fill_missing_dates 设置为 True，这对于填充缺失值很有用。如果为字符串，表示 pandas DatetimeIndex 的频率（有关支持的频率的更多信息，请参阅 offset aliases）。如果为整数，表示 pandas Index 或 pandas RangeIndex 的步长。
columns (Union[ForwardRef, ndarray, ForwardRef, ForwardRef, SequenceNotStr, range, None]) – 基础 pandas DataFrame 将使用的列。
fillna_value (Optional[float, None]) – 可选，用于填充缺失值 (NaNs) 的数值。
static_covariates (Union[Series, DataFrame, None]) – 可选，添加到 TimeSeries 的静态协变量集。可以是 pandas Series 或 pandas DataFrame。如果为 Series，索引表示静态变量。协变量全局“应用于” TimeSeries 的所有分量。如果为 DataFrame，列表示静态变量，行表示单变量/多变量 TimeSeries 的分量。如果为单行 DataFrame，协变量全局“应用于” TimeSeries 的所有分量。如果为多行 DataFrame，行数必须与 TimeSeries 的分量数（即 values 中的列数）匹配。这允许对特定分量的静态协变量进行控制。
hierarchy (Optional[dict, None]) –
可选，描述时间序列分组的字典。键是分量名称，对于给定的分量名称 c，值是 c“所属”的分量名称列表。例如，如果存在一个 total 分量，分为两个部门 d1 和 d2，以及两个区域 r1 和 r2，以及四个产品 d1r1（属于部门 d1 和区域 r1）、d2r1、d1r2 和 d2r2，则层次结构将编码如下。
```
hierarchy={
    "d1r1": ["d1", "r1"],
    "d1r2": ["d1", "r2"],
    "d2r1": ["d2", "r1"],
    "d2r2": ["d2", "r2"],
    "d1": ["total"],
    "d2": ["total"],
    "r1": ["total"],
    "r2": ["total"]
}
```
层次结构可用于协调预测（使不同层级的预测总和一致），请参阅分层协调。
metadata (Optional[dict, None]) – 可选，一个字典，包含要添加到 TimeSeries 的元数据。

返回

从输入构建的 TimeSeries。

返回类型

TimeSeries

示例

>>> import numpy as np
>>> from darts import TimeSeries
>>> from darts.utils.utils import generate_index
>>> # create values and times with daily frequency
>>> vals, times = np.arange(3), generate_index("2020-01-01", length=3, freq="D")
>>> series = TimeSeries.from_times_and_values(times=times, values=vals)
>>> series.shape
(3, 1, 1)

classmethod from_values(values, columns=None, fillna_value=None, static_covariates=None, hierarchy=None, metadata=None)[source]¶

从值数组构建一个整数索引序列。该序列将具有整数索引 (RangeIndex)。

参数

values (ndarray) – TimeSeries 的 NumPy 数组值。接受二维数组（用于确定性序列）和三维数组（用于概率序列）。在前一种情况下，维度应为 (时间, 分量)，后一种情况下应为 (时间, 分量, 样本)。
columns (Union[ForwardRef, ndarray, ForwardRef, ForwardRef, SequenceNotStr, range, None]) – 基础 pandas DataFrame 将使用的列。
fillna_value (Optional[float, None]) – 可选，用于填充缺失值 (NaNs) 的数值。
static_covariates (Union[Series, DataFrame, None]) – 可选，添加到 TimeSeries 的静态协变量集。可以是 pandas Series 或 pandas DataFrame。如果为 Series，索引表示静态变量。协变量全局“应用于” TimeSeries 的所有分量。如果为 DataFrame，列表示静态变量，行表示单变量/多变量 TimeSeries 的分量。如果为单行 DataFrame，协变量全局“应用于” TimeSeries 的所有分量。如果为多行 DataFrame，行数必须与 TimeSeries 的分量数（即 values 中的列数）匹配。这允许对特定分量的静态协变量进行控制。
hierarchy (Optional[dict, None]) –
可选，描述时间序列分组的字典。键是分量名称，对于给定的分量名称 c，值是 c“所属”的分量名称列表。例如，如果存在一个 total 分量，分为两个部门 d1 和 d2，以及两个区域 r1 和 r2，以及四个产品 d1r1（属于部门 d1 和区域 r1）、d2r1、d1r2 和 d2r2，则层次结构将编码如下。
```
hierarchy={
    "d1r1": ["d1", "r1"],
    "d1r2": ["d1", "r2"],
    "d2r1": ["d2", "r1"],
    "d2r2": ["d2", "r2"],
    "d1": ["total"],
    "d2": ["total"],
    "r1": ["total"],
    "r2": ["total"]
}
```
层次结构可用于协调预测（使不同层级的预测总和一致），请参阅分层协调。
metadata (Optional[dict, None]) – 可选，一个字典，包含要添加到 TimeSeries 的元数据。

返回

从输入构建的 TimeSeries。

返回类型

TimeSeries

示例

>>> import numpy as np
>>> from darts import TimeSeries
>>> from darts.utils.utils import generate_index
>>> vals = np.arange(3)
>>> series = TimeSeries.from_times_and_values(times=times, values=vals)
>>> series.shape
(3, 1, 1)

classmethod from_xarray(xa, fill_missing_dates=False, freq=None, fillna_value=None)[source]¶

返回从 xarray DataArray 构建的 TimeSeries 实例。DataArray 的维度必须按 (时间, 分量, 样本) 的顺序排列。时间维可以有任意名称，但分量和样本必须分别命名为“component”和“sample”。

第一维（时间）和第二维（分量）必须被索引（即，有坐标）。时间必须使用 pandas DatetimeIndex、pandas RangeIndex 或可以转换为 RangeIndex 的 pandas Index 进行索引。最好索引没有空洞；或者设置 fill_missing_dates 在某些情况下可以解决这些问题（用 NaN 填充空洞，或用提供的 fillna_value 数值填充）。

如果两个分量具有相同的名称或不是字符串，此方法将通过在具有相同名称的第 N 列后附加形式为“<name>_N”的后缀来消除分量名称的歧义。静态协变量和层次结构（如果存在）中的分量名称*不会*被消除歧义。

参数

xa (DataArray) – xarray DataArray。
fill_missing_dates (Optional[bool, None]) – 可选，布尔值，指示是否用 NaN 值填充缺失的日期（或整数索引的情况下的索引）。这需要提供 freq 或能够从提供的时间戳推断频率。更多信息请参阅 _fill_missing_dates()。
freq (Union[str, int, None]) –
可选，字符串或整数，表示基础索引的频率。如果缺失某些日期且 fill_missing_dates 设置为 True，这对于填充缺失值很有用。如果为字符串，表示 pandas DatetimeIndex 的频率（有关支持的频率的更多信息，请参阅 offset aliases）。如果为整数，表示 pandas Index 或 pandas RangeIndex 的步长。
fillna_value (Optional[float, None]) – 可选，用于填充缺失值 (NaNs) 的数值。

返回

从输入构建的单变量或多变量确定性 TimeSeries。

返回类型

TimeSeries

示例

>>> import xarray as xr
>>> import numpy as np
>>> from darts.timeseries import DIMS
>>> from darts import TimeSeries
>>> from darts.utils.utils import generate_index
>>>
>>> # create values with the required dimensions (time, component, sample)
>>> vals = np.random.random((3, 1, 1))
>>> # create time index with daily frequency
>>> times = generate_index("2020-01-01", length=3, freq="D")
>>> columns = ["vals"]
>>>
>>> # create xarray with the required dimensions and coordinates
>>> xa = xr.DataArray(
>>>     vals,
>>>     dims=DIMS,
>>>     coords={DIMS[0]: times, DIMS[1]: columns}
>>> )
>>> series = TimeSeries.from_xarray(xa)
>>> series.shape
(3, 1, 1)

gaps(mode='all')[source]¶

计算并返回 TimeSeries 中空洞（gap）的函数。仅适用于确定性时间序列（1 个样本）。

参数: mode (Literal[‘all’, ‘any’]) – 仅适用于多变量时间序列。模式定义了如何定义空洞。如果任何列中的 NaN 值应被视为空洞，则设置为 'any'。'all' 只考虑所有列的值均为 NaN 的时间段。默认为 'all'。
返回: 一个 pandas.DataFrame，其中包含此时间序列中每个空洞（底层 DataFrame 中所有值为 NaN 的行）的一行。DataFrame 包含三列，包括空洞的开始和结束时间戳以及空洞的整数长度（如果序列按 DatetimeIndex 索引，则以 self.freq 单位表示）。
返回类型: pd.DataFrame

get_index_at_point(point, after=True)[source]¶

将时间轴索引上的点转换为整数索引，范围在 (0, len(series)-1) 内。

参数

point (Union[Timestamp, float, int]) –
该参数支持 3 种不同的数据类型：pd.Timestamp、float 和 int。

pd.Timestamp 仅适用于使用 pd.DatetimeIndex 索引的序列。在这种情况下，如果提供的时间戳存在于序列时间索引中，返回的点将是该时间戳的索引。如果不存在于时间索引中，如果 after=True，则返回下一个时间戳的索引（如果存在于序列中），否则返回上一个时间戳的索引（如果存在于序列中）。

如果为 float，该参数将被视为时间序列中应位于该点之前的部分比例。

如果为 int 且序列是 datetime 索引，则返回 point 的值。如果为 int 且序列是整数索引，则返回 point 在 RangeIndex 中的索引位置（考虑步长）。
after – 如果提供的时间戳不在时间序列索引中，是否返回下一个时间戳的索引或上一个时间戳的索引。

返回类型

int

get_timestamp_at_point(point)[source]¶

将点转换为 pandas.Timestamp（如果是 Datetime 索引）或整数（如果是 Int64 索引）。

参数: point (Union[Timestamp, float, int]) – 该参数支持 3 种不同的数据类型：float、int 和 pandas.Timestamp。如果为 float，该参数将被视为时间序列中应位于该点之前的部分比例。如果为 int，该参数将被视为 series 时间索引的整数索引。如果不是 series 中的有效索引，将引发 ValueError。如果为 pandas.Timestamp，如果该时间戳存在于序列时间索引中，则返回该点本身，否则将引发 ValueError。
返回类型: Union[Timestamp, int]

property has_datetime_index: bool¶

此序列是否使用 DatetimeIndex 索引（否则使用 RangeIndex 索引）。

返回类型: bool

property has_hierarchy: bool¶

此序列是否具有层级结构。

返回类型: bool

property has_metadata: bool¶

此序列是否包含元数据。

返回类型: bool

property has_range_index: bool¶

此序列是否使用 RangeIndex 索引（否则使用 DatetimeIndex 索引）。

返回类型: bool

has_same_time_as(other)[source]¶

检查此序列是否与 other 具有相同的时间索引。

参数: other (Self) – 另一个时间序列。
返回: 如果两个 TimeSeries 具有相同的索引，则为 True，否则为 False。
返回类型: bool

property has_static_covariates: bool¶

此序列是否包含静态协变量。

返回类型: bool

head(size=5, axis=0)[source]¶

返回包含前 size 个点的时间序列。

参数

size (int, default 5) – 要保留的点数。
axis (str or int, optional, default: 0) – 要切片序列的轴。

返回

沿所需 axis 的前 size 个点组成的序列。

返回类型

TimeSeries

property hierarchy: Optional[dict]¶

此 TimeSeries 的层次结构（如果存在）。如果设置，层次结构编码为一个字典，其键是单独的分量，值是这些分量在层次结构中的父集。

返回类型: Optional[dict, None]

property is_deterministic: bool¶

此序列是否为确定性。

返回类型: bool

property is_probabilistic: bool¶

此序列是否为随机性（=概率性）。

返回类型: bool

property is_stochastic: bool¶

此序列是否为随机性。

返回类型: bool

property is_univariate: bool¶

此序列是否为单变量。

返回类型: bool

is_within_range(ts)[source]¶

检查给定的时间戳或整数是否在此时间序列的时间间隔内。如果提供时间戳，则无需是序列时间索引的元素。

参数: ts (Union[Timestamp, int]) – 要检查的 pandas.Timestamp（如果按 DatetimeIndex 索引）或整数（如果按 RangeIndex 索引）。
返回: ts 是否包含在此时间序列的间隔内。
返回类型: bool

kurtosis(**kwargs)[source]¶

返回一个确定性的 TimeSeries，其中包含此随机 TimeSeries 每个分量（跨样本）的峰度。

仅适用于随机序列（即，多于 1 个样本）。

参数: kwargs – 其他关键字参数将传递给 scipy.stats.kurtosis()。
返回: 包含每个分量峰度的 TimeSeries。
返回类型: TimeSeries

last_value()[source]¶

此单变量序列的最后一个值。

返回: 此单变量确定性时间序列的最后一个值。
返回类型: float

last_values()[source]¶

此可能的多变量序列的最后一个值（每个分量）。

返回: 此确定性时间序列的每个分量的最后一个值。
返回类型: np.ndarray

longest_contiguous_slice(max_gap_size=0, mode='all')[source]¶

返回此确定性序列的最大 TimeSeries 片段，该片段不包含大于 max_gap_size 的间隔（连续的 NaN 值）。

此方法仅适用于确定性序列（即，有 1 个样本）。

参数

max_gap_size (int) – 指示 TimeSerie 可以包含的最大空洞大小。
mode (str) – 仅适用于多变量时间序列。模式定义了如何定义空洞。如果任何列中的 NaN 值应被视为空洞，则设置为 'any'。'all' 只考虑所有列的值均为 NaN 的时间段。默认为 'all'。

返回

构成原始序列中没有或只有有限空洞的最大切片的新序列。

返回类型

TimeSeries

另请参阅

TimeSeries.gaps: 返回 TimeSeries 中的空洞。

map(fn)[source]¶

对包含此序列值的底层 NumPy 数组应用函数 fn。

返回一个新的 TimeSeries 实例。如果 fn 接受 1 个参数，它将简单地应用于形状为 (时间, 分量数, 样本数) 的支持数组。如果它接受 2 个参数，它将重复应用于 (ts, value[ts]) 元组，其中“ts”表示时间戳值，“value[ts]”表示该时间戳下的值数组，形状为 (分量数, 样本数)。

参数: fn (Union[Callable[[number], number], Callable[[Union[Timestamp, int], number], number]]) – 一个函数，它接受一个 NumPy 数组并返回形状相同的 NumPy 数组；例如，lambda x: x ** 2、lambda x: x / x.shape[0] 或 np.log。它也可以是一个函数，接受时间戳和数组，并返回形状相同的新数组；例如，lambda ts, x: x / ts.days_in_month。ts 的类型是 pd.Timestamp（如果序列使用 DatetimeIndex 索引）或整数（如果序列使用 RangeIndex 索引）。
返回: 一个新的 TimeSeries 实例。
返回类型: TimeSeries

max(axis=2)[source]¶

返回一个包含在指定轴上计算的最大值的 TimeSeries。

如果沿时间维度（axis=0）进行缩减，结果 TimeSeries 的长度将为 1，并使用原始 time_index 的第一个条目。如果沿分量维度（axis=1）进行计算，结果的单个分量将被重命名为“components_max”。当应用于样本维度（axis=2）时，返回一个确定性 TimeSeries。

如果 axis=1，静态协变量和层次结构将从序列中丢弃。

参数: axis (int) – 要缩减的轴。默认为计算样本维度，即 axis=2。
返回: 一个新的 TimeSeries，其中 max 已应用于指定轴。
返回类型: TimeSeries

mean(axis=2)[source]¶

返回一个包含在指定轴上计算的平均值的 TimeSeries。

如果沿时间维度（axis=0）进行缩减，结果 TimeSeries 的长度将为 1，并使用原始 time_index 的第一个条目。如果沿分量维度（axis=1）进行计算，结果的单个分量将被重命名为“components_mean”。当应用于样本维度（axis=2）时，返回一个确定性 TimeSeries。

如果 axis=1，静态协变量和层次结构将从序列中丢弃。

参数: axis (int) – 要缩减的轴。默认为计算样本维度，即 axis=2。
返回: 一个新的 TimeSeries，其中 mean 已应用于指定轴。
返回类型: TimeSeries

median(axis=2)[source]¶

返回一个包含在指定轴上计算的中位数的 TimeSeries。

如果沿时间维度（axis=0）进行缩减，结果 TimeSeries 的长度将为 1，并使用原始 time_index 的第一个条目。如果沿分量维度（axis=1）进行计算，结果的单个分量将被重命名为“components_median”。当应用于样本维度（axis=2）时，返回一个确定性 TimeSeries。

如果 axis=1，静态协变量和层次结构将从序列中丢弃。

参数: axis (int) – 要缩减的轴。默认为计算样本维度，即 axis=2。
返回: 一个新的 TimeSeries，其中 median 已应用于指定轴。
返回类型: TimeSeries

property metadata: Optional[dict]¶

此 TimeSeries 的元数据（如果有）。

返回类型: Optional[dict, None]

min(axis=2)[source]¶

返回一个包含在指定轴上计算的最小值的 TimeSeries。

如果沿时间维度（axis=0）进行缩减，结果 TimeSeries 的长度将为 1，并使用原始 time_index 的第一个条目。如果沿分量维度（axis=1）进行计算，结果的单个分量将被重命名为“components_min”。当应用于样本维度（axis=2）时，返回一个确定性 TimeSeries。

如果 axis=1，静态协变量和层次结构将从序列中丢弃。

参数: axis (int) – 要缩减的轴。默认为计算样本维度，即 axis=2。
返回: 一个新的 TimeSeries，其中 min 已应用于指定轴。
返回类型: TimeSeries

property n_components: int¶

序列中包含的分量（维度）数量。

返回类型: int

property n_samples: int¶

序列中包含的样本数量。

返回类型: int

property n_timesteps: int¶

序列中的时间步数量。

返回类型: int

plot(new_plot=False, central_quantile=0.5, low_quantile=0.05, high_quantile=0.95, default_formatting=True, title=None, label='', max_nr_components=10, ax=None, alpha=None, color=None, c=None, *args, **kwargs)[source]¶

绘制序列。

这是 xarray.DataArray.plot() 方法的包装器。

参数

new_plot (bool) – 是否生成一个新的坐标轴进行绘图。另请参阅参数 ax。
central_quantile (Union[float, str]) – 如果序列是随机的（即，有多个样本），则将绘制的“中心”值的分位数（介于 0 和 1 之间）。这将分别应用于每个分量（即，显示分量的边缘分布的分位数）。例如，设置 central_quantile=0.5 将绘制每个分量的中位数。central_quantile 也可以设置为 ‘mean’。
low_quantile (Optional[float, None]) – 用于绘制置信区间下界的分位数。与 central_quantile 类似，这分别应用于每个分量（即，显示边缘分布）。如果 confidence_low_quantile 为 None，则不显示置信区间（默认为 0.05）。
high_quantile (Optional[float, None]) – 用于绘制置信区间上界的分位数。与 central_quantile 类似，这分别应用于每个分量（即，显示边缘分布）。如果 high_quantile 为 None，则不显示置信区间（默认为 0.95）。
default_formatting (bool) – 是否使用 darts 默认方案。
title (Optional[str, None]) – 可选，自定义图表标题。如果为 None，将使用底层 xarray.DataArray 的名称。
label (Union[str, Sequence[str], None]) – 可以是字符串或字符串列表。如果为字符串且序列只有一个分量，则用作该分量的标签。如果为字符串且序列有多个分量，则用作每个分量名称的前缀。如果为与序列中分量数长度相同的字符串列表，则标签将按顺序映射到分量。
max_nr_components (int) – 要绘制的序列的最大分量数。-1 表示将绘制所有分量。
ax (Optional[Axes, None]) – 可选，要在其上绘图的轴。如果为 None 且 new_plot=False，将使用当前轴。如果 new_plot=True，将创建一个新轴。
alpha (Optional[float, None]) – 可选，设置确定性序列的线条透明度，或概率序列的置信区间透明度。
color (Union[str, tuple, Sequence[str, tuple], None]) – 可以是单个颜色或颜色列表。接受任何 matplotlib 颜色（字符串、十六进制字符串、RGB/RGBA 元组）。如果为单个颜色且序列只有一个分量，则用作该分量的颜色。如果为单个颜色且序列有多个分量，则用作每个分量的颜色。如果为与序列中分量数长度相同的颜色列表，则颜色将按顺序映射到分量。
c (Union[str, tuple, Sequence[str, tuple], None]) – color 的别名。
args – plot() 方法的一些位置参数。
kwargs – plot() 方法的一些关键字参数。

返回

传入的 ax 坐标轴、如果 new_plot=True 则新建的坐标轴，或者现有的坐标轴。

返回类型

matplotlib.axes.Axes

prepend(other)[source]¶

沿着时间轴将另一个序列前置（即添加到开头）到此序列。

参数: other (Self) – 第二个 TimeSeries。
返回: 通过将第二个 TimeSeries 附加到第一个 TimeSeries 获得的新 TimeSeries。
返回类型: TimeSeries

另请参阅

Timeseries.append: 沿着时间轴附加（即添加到末尾）另一个序列。
TimeSeries.concatenate: 沿给定轴连接另一个序列。

prepend_values(values)[source]¶

将新值前置（即添加到开头）到当前 TimeSeries，将其时间索引扩展到过去。

参数: values (ndarray) – 要添加到开头的数组值。
返回: 一个前置了新值的新 TimeSeries。
返回类型: TimeSeries

quantile(quantile, **kwargs)[source]¶

返回一个确定性的 TimeSeries，其中包含此随机 TimeSeries 每个分量（跨样本）的所需单个分位数。

新序列中的分量被命名为“<component>_X”，其中“<component>”是与此分量对应的列名，“X”是分位数的值。分位数列表示此序列分量的边际分布。

仅适用于随机序列（即，多于 1 个样本）。

参数

quantile (float) – 所需的分位数数值。该数值必须表示为小数（介于 0 和 1 之间，包括 0 和 1）。例如，0.5 将返回一个包含每个分量（边际）分布中位数的 TimeSeries。
kwargs – 其他关键字参数被传递给 numpy.quantile()。

返回

包含每个分量所需分位数的 TimeSeries。

返回类型

TimeSeries

quantile_df(quantile=0.5)[source]¶

返回一个 Pandas DataFrame，其中包含每个分量（跨样本）所需的单个分位数。

序列的每个分量都将作为 DataFrame 中的一列出现。列的命名格式为“<component>_X”，其中“<component>”是与该分量对应的列名，“X”是分位数值。分位数列表示此序列分量的边际分布。

仅适用于随机序列（即，多于 1 个样本）。

参数: quantile – 所需的分位数数值。该数值必须表示为小数（介于 0 和 1 之间，包括 0 和 1）。例如，0.5 将返回一个包含每个分量（边际）分布中位数的 DataFrame。
返回: 包含每个分量所需分位数的 Pandas DataFrame。
返回类型: pandas.DataFrame

quantile_timeseries(quantile=0.5, **kwargs)[source]¶

返回一个确定性的 TimeSeries，其中包含此随机 TimeSeries 每个分量（跨样本）的所需单个分位数。

新序列中的分量被命名为“<component>_X”，其中“<component>”是与此分量对应的列名，“X”是分位数的值。分位数列表示此序列分量的边际分布。

仅适用于随机序列（即，多于 1 个样本）。

参数

quantile – 所需的分位数数值。该数值必须表示为小数（介于 0 和 1 之间，包括 0 和 1）。例如，0.5 将返回一个包含每个分量（边际）分布中位数的 TimeSeries。
kwargs – 其他关键字参数被传递给 numpy.quantile()。

返回

包含每个分量所需分位数的 TimeSeries。

返回类型

TimeSeries

quantiles_df(quantiles=(0.1, 0.5, 0.9))[source]¶

返回一个 Pandas DataFrame，其中包含每个分量（跨样本）所需的多个分位数。

序列的每个分量都将作为 DataFrame 中的一列出现。列的命名格式为“<component>_X”，其中“<component>”是与该分量对应的列名，“X”是分位数值。分位数表示此序列分量的边际分布。

仅适用于随机序列（即，多于 1 个样本）。

参数: quantiles (tuple[float]) – 包含所需分位数的元组。数值必须表示为小数（介于 0 和 1 之间，包括 0 和 1）。例如，(0.1, 0.5, 0.9) 将返回一个包含每个分量（边际）分布的 10% 分位数、中位数和 90% 分位数的 DataFrame。
返回: 包含每个分量分位数的 Pandas DataFrame。
返回类型: pandas.DataFrame

random_component_values(copy=True)[source]¶

返回形状为 (时间, 分量) 的 2-D 数组，包含从此序列样本中均匀随机抽取的一个样本的值。

参数: copy (bool) – 是否返回值的副本，否则返回一个视图。除非您知道自己在做什么，否则请将其保留为 True。
返回: 从时间序列中随机抽取的一个样本的值。
返回类型: numpy.ndarray

resample(freq, method='pad', method_kwargs=None, **kwargs)[source]¶

构建一个具有给定频率的重新索引的 TimeSeries。提供的 method 用于聚合/填充重新索引的 TimeSeries 中的空洞，默认为 'pad'。

参数

freq (Union[str, DateOffset]) – 返回的 TimeSeries 中两个相邻条目之间的新时间差。期望 pandas.DateOffset 或 DateOffset 别名。
method (str) – 用于聚合分组值（用于向下采样）或填充空洞（用于向上采样）在重新索引的 TimeSeries 中的方法。更多信息请参阅 xarray DataArrayResample 文档。支持的方法：["all", "any", "asfreq", "backfill", "bfill", "count", "ffill", "first", "interpolate", "last", "max", "mean", "median", "min", "nearest", "pad", "prod", "quantile", "reduce", "std", "sum", "var"]。
method_kwargs (Optional[dict[str, Any], None]) – 指定 method 的附加关键字参数。某些方法需要附加参数。无效的关键字参数将引发 Xarray 的错误。
kwargs – xarray.resample 方法的一些关键字参数，特别是 offset 或 base 用于指示重采样的起始位置，并避免重采样 TimeSeries 的第一个值出现 NaN。更多信息请参阅 xarray resample() 文档。

返回

一个具有给定频率的重新索引的 TimeSeries。

返回类型

TimeSeries

示例

>>> times = pd.date_range(start=pd.Timestamp("20200101233000"), periods=6, freq="15min")
>>> pd_series = pd.Series(range(6), index=times)
>>> ts = TimeSeries.from_series(pd_series)
>>> print(ts.time_index)
DatetimeIndex(['2020-01-01 23:30:00', '2020-01-01 23:45:00',
               '2020-01-02 00:00:00', '2020-01-02 00:15:00',
               '2020-01-02 00:30:00', '2020-01-02 00:45:00'],
               dtype='datetime64[ns]', name='time', freq='15T')
>>> resampled_nokwargs_ts = ts.resample(freq="1h")
>>> print(resampled_nokwargs_ts.time_index)
DatetimeIndex(['2020-01-01 23:00:00', '2020-01-02 00:00:00'],
              dtype='datetime64[ns]', name='time', freq='H')
>>> print(resampled_nokwargs_ts.values())
[[nan]
[ 2.]]
>>> resampled_ts = ts.resample(freq="1h", offset=pd.Timedelta("30min"))
>>> print(resampled_ts.time_index)
DatetimeIndex(['2020-01-01 23:30:00', '2020-01-02 00:30:00'],
              dtype='datetime64[ns]', name='time', freq='H')
>>> print(resampled_ts.values())
[[0.]
[4.]]
>>> resampled_ts = ts.resample(freq="1h", offset=pd.Timedelta("30min"))
>>> downsampled_mean_ts = ts.resample(freq="30min", method="mean")
>>> print(downsampled_mean_ts.values())
[[0.5]
[2.5]
[4.5]]
>>> downsampled_reduce_ts = ts.resample(freq="30min", method="reduce", method_args={"func":np.mean})
>>> print(downsampled_reduce_ts.values())
[[0.5]
[2.5]
[4.5]]

rescale_with_value(value_at_first_step)[source]¶

返回一个新的 TimeSeries，它是此序列的一个倍数，使得第一个值是 value_at_first_step。（注意：value_at_first_step > 1e+24 时可能出现数值误差）。

参数: value_at_first_step (float) – TimeSeries 第一个条目的新值。
返回: 一个新的 TimeSeries，其中第一个值是 value_at_first_step，其他值已相应缩放。
返回类型: TimeSeries

property shape: tuple[int]¶

序列的形状 (n_timesteps, n_components, n_samples)。

返回类型: tuple[int]

shift(n)[source]¶

将此 TimeSeries 的时间轴移动 n 个时间步。

如果 \(n > 0\)，则向未来移动。如果 \(n < 0\)，则向过去移动。

例如，对于 \(n=2\) 和 freq='M'，2013 年 3 月变为 2013 年 5 月。对于 \(n=-2\)，2013 年 3 月变为 2013 年 1 月。

参数: n (int) – 要移动的时间步长（以 self.freq 为单位）。可以是负数。
返回: 一个带有偏移索引的新 TimeSeries。
返回类型: TimeSeries

skew(**kwargs)[source]¶

返回一个确定性的 TimeSeries，其中包含此随机 TimeSeries 每个分量（跨样本）的偏度。

仅适用于随机序列（即，多于 1 个样本）。

参数: kwargs – 其他关键字参数被传递给 scipy.stats.skew()。
返回: 包含每个分量偏度的 TimeSeries。
返回类型: TimeSeries

slice(start_ts, end_ts)[source]¶

返回一个新的 TimeSeries，其开始时间晚于 start_ts 并结束于 end_ts 之前。对于具有 DatetimeIndex 的序列，两端都包含。对于具有 RangeIndex 的序列，end_ts 不包含。

start_ts 和 end_ts 不必存在于序列中。

参数

start_ts (Union[Timestamp, int]) – 指示左侧截止点的时间戳或索引。
end_ts (Union[Timestamp, int]) – 指示右侧截止点的时间戳或索引。

返回

一个新序列，其索引大于或等于 start_ts 且小于或等于 end_ts。

返回类型

TimeSeries

slice_intersect(other)[source]¶

返回此序列的 TimeSeries 片段，其时间索引已与 other 序列的时间索引相交。

此方法通常是非对称的。

参数: other (Self) – 另一个时间序列
返回: 一个新序列，包含此序列在两个时间序列共有的时间跨度内的值。
返回类型: TimeSeries

slice_intersect_times(other, copy=True)[source]¶

返回此序列的时间索引，其时间索引已与 other 序列的时间索引相交。

此方法通常是非对称的。

参数

other (Self) – 另一个时间序列
copy (bool) – 是否返回时间索引的副本，否则返回视图。除非你知道自己在做什么，否则请保持为 True。

返回

此序列在两个时间序列共有的时间跨度内的时间索引。

返回类型

Union[pd.DatetimeIndex, pd.RangeIndex]

slice_intersect_values(other, copy=False)[source]¶

返回此序列的切片值，其时间索引已与 other 序列的时间索引相交。

此方法通常是非对称的。

参数

other (Self) – 另一个时间序列
copy (bool) – 是否返回值的副本，否则返回一个视图。除非您知道自己在做什么，否则请将其保留为 True。

返回

此序列在两个时间序列共有的时间跨度内的值。

返回类型

np.ndarray

slice_n_points_after(start_ts, n)[source]¶

返回一个新的 TimeSeries，从 start_ts 开始（包括），最多包含 n 个点。

提供的 timestamp 将包含在序列中。

参数

start_ts (Union[Timestamp, int]) – 指示分割时间的时间戳或索引。
n (int) – 新 TimeSeries 的最大长度。

返回

一个长度至多为 n，从 start_ts 开始的新 TimeSeries。

返回类型

TimeSeries

slice_n_points_before(end_ts, n)[source]¶

返回一个新的 TimeSeries，在 end_ts 结束（包括），最多包含 n 个点。

提供的 timestamp 将包含在序列中。

参数

end_ts (Union[Timestamp, int]) – 指示分割时间的时间戳或索引。
n (int) – 新 TimeSeries 的最大长度。

返回

一个长度至多为 n，结束于 start_ts 的新 TimeSeries。

返回类型

TimeSeries

split_after(split_point)[source]¶

在提供的 split_point 之后将序列分成两部分。

参数: split_point (Union[Timestamp, float, int]) – 时间戳、浮点数或整数。如果是浮点数，表示包含在第一个 TimeSeries 中的序列比例（必须介于 0.0 和 1.0 之间）。如果是整数，表示执行分割的索引位置。对于通过 pd.DatetimeIndex 索引的 TimeSeries，可以提供 pd.Timestamp。在这种情况下，该 timestamp 将包含在第一个 TimeSeries 中，但不包含在第二个中。timestamp 本身不必出现在原始 TimeSeries 索引中。
返回: 两个时间序列的元组。第一个时间序列包含从开始到 split_point 的样本，第二个包含剩余的样本。
返回类型: Tuple[TimeSeries, TimeSeries]

split_before(split_point)[source]¶

在提供的 split_point 之前将序列分成两部分。

参数: split_point (Union[Timestamp, float, int]) – 时间戳、浮点数或整数。如果是浮点数，表示包含在第一个 TimeSeries 中的序列比例（必须介于 0.0 和 1.0 之间）。如果是整数，表示执行分割前的索引位置。对于通过 pd.DatetimeIndex 索引的 TimeSeries，可以提供 pd.Timestamp。在这种情况下，该 timestamp 将包含在第二个 TimeSeries 中，但不包含在第一个中。timestamp 本身不必出现在原始 TimeSeries 索引中。
返回: 两个时间序列的元组。第一个时间序列包含从开始到 split_point 的样本，第二个包含剩余的样本。
返回类型: Tuple[TimeSeries, TimeSeries]

stack(other)[source]¶

将具有相同时间索引的另一个单变量或多变量 TimeSeries 堆叠到当前 TimeSeries 的顶部（沿分量轴）。

返回一个新的 TimeSeries，包含 self 和 other 的所有分量。

结果 TimeSeries 的时间维度名称将与此 TimeSeries 相同，并且具有相同的样本数量。

参数: other (Self) – 一个与当前 TimeSeries 具有相同索引和相同样本数量的 TimeSeries 实例。
返回: 一个新的多元 TimeSeries 实例。
返回类型: TimeSeries

start_time()[source]¶

序列的开始时间。

返回: 包含 TimeSeries 的第一个时间的时间戳（如果通过 DatetimeIndex 索引），或一个整数（如果通过 RangeIndex 索引）。
返回类型: Union[pandas.Timestamp, int]

property static_covariates: Optional[DataFrame]¶

返回序列中包含的静态协变量作为 pandas DataFrame。列代表静态变量，行代表单/多元序列的分量。

返回类型: Optional[DataFrame, None]

static_covariates_values(copy=True)[source]¶

返回一个维度为 (分量, 静态变量) 的二维数组，其中包含 TimeSeries 的静态协变量值。

参数: copy (bool) – 是否返回值的副本，否则返回视图。只有当所有值具有相同的 dtype 时才能返回视图。除非你知道自己在做什么，否则请保持为 True。
返回: 如果序列具有静态协变量，则返回静态协变量的值，否则返回 None。
返回类型: Optional[numpy.ndarray]

std(ddof=1)[source]¶

返回一个确定性的 TimeSeries，其中包含此随机 TimeSeries 每个分量（跨样本）的标准差。

仅适用于随机序列（即，多于 1 个样本）。

参数: ddof (int) – “自由度差分”：计算中使用的除数是 N - ddof，其中 N 表示元素数量。默认为 1。
返回: 包含每个分量标准差的 TimeSeries。
返回类型: TimeSeries

strip(how='all')[source]¶

返回此确定性时间序列的 TimeSeries 切片，其中移除了序列开头和结尾包含 NaN 的条目。第一次非 NaN 条目之后（包括该条目）和最后一次非 NaN 条目之前（包括该条目）的条目不会被移除。

此方法仅适用于确定性序列（即，有 1 个样本）。

参数: how (str) – 定义是应该移除所有分量都包含 NaN 的条目（'all'）还是任何分量包含 NaN 的条目（'any'）。默认为 'all'。
返回: 一个基于原始序列的新序列，其中开头的和结尾的包含 NaN 的条目已被移除。
返回类型: TimeSeries

sum(axis=2)[source]¶

返回一个包含在指定轴上计算的总和的 TimeSeries。

如果沿着时间维度进行缩减（axis=0），结果 TimeSeries 的长度将为 1，并使用原始 time_index 的第一个条目。如果沿着分量维度进行计算（axis=1），结果的单个分量将被重命名为“components_sum”。当应用于样本维度（axis=2）时，将返回一个确定性的 TimeSeries。

如果 axis=1，静态协变量和层次结构将从序列中丢弃。

参数: axis (int) – 要缩减的轴。默认为计算样本维度，即 axis=2。
返回: 一个新的 TimeSeries，其中对指定轴应用了求和。
返回类型: TimeSeries

tail(size=5, axis=0)[source]¶

返回序列的最后 size 个点。

参数

size (int, default: 5) – 保留的点数
axis (str or int, optional, default: 0 (时间维度)) – 希望显示记录的轴

返回

由所需 axis 上的最后 size 个点组成的序列。

返回类型

TimeSeries

property time_dim: str¶

此时间序列的时间维度名称。

返回类型: str

property time_index: Union[DatetimeIndex, RangeIndex]¶

此时间序列的时间索引。

返回类型: Union[DatetimeIndex, RangeIndex]

to_csv(*args, **kwargs)[source]¶

将此确定性序列写入 CSV 文件。参数列表请参考 pandas.DataFrame.to_csv() [1] 的文档。

参考资料

1: https://pandas.ac.cn/pandas-docs/stable/reference/api/pandas.DataFrame.to_csv.html?highlight=to_csv

to_dataframe(copy=True, backend=Implementation.PANDAS, time_as_index=True, suppress_warnings=False)[source]¶

以给定的 backend 返回此时间序列的 DataFrame 表示。

序列的每个分量都将作为 DataFrame 中的一列出现。如果序列是随机的，样本将作为 DataFrame 的列返回，列名为“component_s#”（例如，对于两个分量和两个样本：'comp0_s0', 'comp0_s1' 'comp1_s0' 'comp1_s1'）。

参数

copy (bool) – 是否返回 DataFrame 的副本。除非你知道自己在做什么，否则请保持为 True。
backend (Union[module, Implementation, str]) –
用于导出 TimeSeries 的后端。请参阅 narwhals 文档以了解所有支持的后端。
time_as_index (bool) – 是否将时间索引设置为 DataFrame 的索引或左侧第一列。仅在 pandas backend 有效。
suppress_warnings (bool) – 是否抑制 DataFrame 创建的警告。

返回

此时间序列在给定 backend 中的 DataFrame 表示形式。

返回类型

DataFrame

to_json()[source]¶

返回此确定性序列的 JSON 字符串表示形式。

目前此函数仅适用于确定性时间序列（即，由 1 个样本组成）。

注意

静态协变量不会在 JSON 字符串中返回。使用 TimeSeries.from_json() 时，可以通过输入参数 static_covariates 添加静态协变量。

返回: 表示时间序列的 JSON 字符串
返回类型: str

to_pickle(path, protocol=5)[source]¶

以 pickle 格式保存此序列。

参数

path (string) – 当前对象将被 pickle 到文件的路径。
protocol (integer, default highest) – pickling 协议。大多数情况下默认是最好的，仅在有向后兼容性问题时使用它。

注意

Xarray 文档 [1] 建议不要使用 pickle 作为长期数据存储。

参考资料

1: http://xarray.pydata.org/en/stable/user-guide/io.html#pickle

to_series(copy=True, backend=Implementation.PANDAS)[source]¶

以给定的 backend 返回此时间序列的 Series 表示。

仅适用于单元确定性序列（即，由 1 个样本组成）。

参数

copy (bool) – 是否返回序列的副本。除非您知道自己在做什么，否则请将其保留为 True。
backend (Union[module, Implementation, str]) –
用于导出 TimeSeries 的后端。请参阅 narwhals 文档以了解所有支持的后端。

返回类型

此单元时间序列在给定 backend 中的 Series 表示形式。

property top_level_component: Optional[str]¶

此序列的顶层分量名称，如果序列没有层级结构，则为 None。

返回类型: Optional[str, None]

property top_level_series: Optional[Self]¶

包含此序列的单个顶层分量的单变量序列，如果序列没有层级结构，则为 None。

返回类型: Optional[Self, None]

univariate_component(index)[source]¶

检索序列中的一个分量，并将其作为新的单变量 TimeSeries 实例返回。

这将删除层级结构（如果存在），并仅保留相关的静态协变量列。

参数: index (Union[str, int]) – 一个从零开始的整数，指示要检索哪个分量。如果分量有名称，这可以是包含分量名称的字符串。
返回: 一个新的单元 TimeSeries 实例。
返回类型: TimeSeries

univariate_values(copy=True, sample=0)[source]¶

返回一个形状为 (时间,) 的 1-D Numpy 数组，包含此单元序列的一个 sample 的值。

参数

copy (bool) – 是否返回值的副本。除非你知道自己在做什么，否则请保持为 True。
sample (int) – 对于随机序列，返回哪个样本的值。默认为 0（第一个样本）。

返回

组成保证为单元的时间序列的值。

返回类型

numpy.ndarray

values(copy=True, sample=0)[source]¶

返回一个形状为 (时间, 分量) 的 2-D 数组，包含此序列的一个 sample 的值。

参数

copy (bool) – 是否返回值的副本，否则返回一个视图。除非您知道自己在做什么，否则请将其保留为 True。
sample (int) – 对于随机序列，返回哪个样本的值。默认为 0（第一个样本）。

返回

组成时间序列的值。

返回类型

numpy.ndarray

var(ddof=1)[source]¶

返回一个确定性的 TimeSeries，其中包含此随机 TimeSeries 每个分量（跨样本）的方差。

仅适用于随机序列（即，多于 1 个样本）。

参数: ddof (int) – “自由度差分”：计算中使用的除数是 N - ddof，其中 N 表示元素数量。默认为 1。
返回: 包含每个分量方差的 TimeSeries。
返回类型: TimeSeries

property width: int¶

序列的“宽度”（= 分量数量）。

返回类型: int

window_transform(transforms, treat_na=None, forecasting_safe=True, keep_non_transformed=False, include_current=True, keep_names=False)[source]¶

对此 TimeSeries 应用移动/滚动、扩展或指数加权窗口转换。

参数

transforms (Union[dict, Sequence[dict]]) –
一个字典或字典列表。每个字典指定不同的窗口变换。

字典可以包含以下键：

"function"

必需。pandas 内建变换函数之一的名称，或者一个可应用于输入序列的可调用函数。pandas 的函数可以在文档中找到。

"mode"

可选。要应用 "function" 的 pandas 窗口模式的名称。选项有“rolling”、“expanding”和“ewm”。如果未提供，Darts 默认为“expanding”。用户自定义函数可以使用“rolling”或“expanding”模式。关于 pandas 窗口操作的更多信息可以在文档中找到。

"components"

可选。一个字符串或字符串列表，指定应应用变换的 TimeSeries 分量。如果未指定，变换将应用于所有分量。

"function_name"

可选。一个字符串，指定在变换输出名称中引用的函数名称。例如，给定用户提供的对分量“comp”上大小为 5 的滚动窗口进行函数变换，默认变换输出名称是“rolling_udf_5_comp”，其中“udf”指“用户自定义函数”。如果指定了 "function_name"，它将替换默认名称“udf”。类似地，"function_name" 将替换输出名称中 pandas 内建变换函数的名称。

提供的所有其他字典项将被视为窗口模式（即 rolling/ewm/expanding）或该模式中特定函数（即 pandas.DataFrame.rolling.mean/std/max/min... 或 pandas.DataFrame.ewm.mean/std/sum）的关键字参数。这允许更灵活地配置变换，例如提供：
- "window"
  
  “rolling”模式的移动窗口大小。如果是整数，则为每个窗口使用的固定观测数。如果是偏移量，则为每个窗口的时间段，数据类型为 pandas.Timedelta，表示固定持续时间。
- "min_periods"
  
  窗口中需要具有值的最小观测数（否则为 NaN）。Darts 重用 pandas 默认值，对于“rolling”和“expanding”模式默认为 1，对于“ewm”模式默认为 0。
- "win_type"
  
  应用于窗口元素的权重类型。如果提供，应为 scipy.signal.windows 之一。
- "center"
  
  True/False 用于将当前时间步长的观测值设置为窗口的中心（当 forecasting_safe 为 True 时，Darts 强制将 "center" 设置为 False）。
- "closed"
  
  "right"/"left"/"both"/"neither" 用于指定窗口的右侧、左侧或两侧是否包含在窗口中，或者都不包含。Darts 默认为 pandas 默认值 "right"。
有关可用函数及其参数的更多信息可以在Pandas 文档中找到。

对于用户提供的函数，变换字典中的额外关键字参数被传递给用户定义的函数。默认情况下，Darts 期望用户定义的函数接收 numpy 数组作为输入。可以通过在变换字典中添加项 "raw": False 来修改此设置。期望函数为每个窗口返回单个值。其他可能的配置可以在 pandas.DataFrame.rolling().apply() 文档和 pandas.DataFrame.expanding().apply() 文档中找到。
treat_na (Union[str, int, float, None]) –
指定如何处理窗口变换在结果 TimeSeries 开头添加的缺失值。默认情况下，Darts 将在结果 TimeSeries 中保留 NaNs。此参数可以是以下之一：
- "dropna"
  
  截断 TimeSeries 并删除包含缺失值的行。如果多列包含不同数量的缺失值，则仅删除最小行数。此操作可能会缩短结果 TimeSeries 的长度。
- "bfill" 或 "backfill"
  
  指定 NaNs 应填充最后一个变换后的有效观测值。如果原始 TimeSeries 以 NaNs 开头，则保留这些 NaNs。当 forecasting_safe 为 True 时，此选项将返回异常以避免未来观测污染过去。
- 整数或浮点数
  
  在这种情况下，NaNs 将用此值填充。所有列都将用相同的提供值填充。
forecasting_safe (Optional[bool, None]) – 如果为 True，Darts 强制结果 TimeSeries 可以安全地用作预测模型的目标或特征。窗口变换不允许在对应的当前时间步长计算中包含未来值。默认为 True。“ewm”和“expanding”模式默认是预测安全的。“rolling”模式在保证 "center": False 时是预测安全的。
keep_non_transformed (Optional[bool, None]) – False 只返回变换后的分量，True 返回所有原始分量以及变换后的分量。默认为 False。如果序列有层级结构，则必须设置为 False。
include_current (Optional[bool, None]) – True 将当前时间步长包含在窗口中，False 将其排除。默认为 True。
keep_names (Optional[bool, None]) – 变换后的分量是否应保留原始分量名称。如果 keep_non_transformed = True 或变换数量大于 1，则必须设置为 False。

返回

返回一个包含变换后分量的新 TimeSeries 实例。如果 keep_non_transformed 为 True，结果 TimeSeries 将包含原始未变换的分量以及变换后的分量。如果输入序列是随机的，所有样本都以相同方式变换。变换后分量的命名约定如下：[窗口模式]_[函数名称]_[窗口大小，如果提供]_[最小周期数，如果非默认]_[原始分量名称]，例如 rolling_sum_3_comp_0（即窗口模式=rolling，函数名称=sum，窗口大小=3，原始分量名称=comp_0）；ewm_mean_comp_1（即窗口模式=ewm，函数名称=mean，原始分量名称=comp_1）；expanding_sum_3_comp_2（即窗口模式=expanding，函数名称=sum，窗口大小=3，原始分量名称=comp_2）。对于用户自定义函数，函数名称 = udf。

返回类型

TimeSeries

with_columns_renamed(col_names, col_names_new)[source]¶

返回一个新的 TimeSeries 实例，具有新的列/分量名称。它还会调整层级结构中的名称（如果存在）。

参数

col_names (Union[list[str], str]) – 对应于要更改的列名的字符串或字符串列表。
col_names_new (Union[list[str], str]) – 对应于新列名的字符串或字符串列表。长度必须与 col_names 相同。

返回

一个新的 TimeSeries 实例。

返回类型

TimeSeries

with_hierarchy(hierarchy)[source]¶

为 TimeSeries 添加层级结构。

参数

hierarchy (dict[str, Union[str, list[str]]]) –

一个字典，将分量映射到其在层级结构中的父级列表。单个父级可以指定为字符串或包含一个字符串的列表。例如，假设序列包含分量 ["total", "a", "b", "x", "y", "ax", "ay", "bx", "by"]，以下字典将编码此图中显示的分组。

hierarchy = {'ax': ['a', 'x'],
             'ay': ['a', 'y'],
             'bx': ['b', 'x'],
             'by': ['b', 'y'],
             'a': ['total'],
             'b': ['total'],
             'x': 'total',  # or use a single string
             'y': 'total'}

返回

一个具有给定层级结构的新 TimeSeries。

返回类型

TimeSeries

with_metadata(metadata)[source]¶

为 TimeSeries 添加元数据。

参数: metadata (Optional[dict, None]) – 一个包含要添加到 TimeSeries 的元数据的字典。
返回: 一个具有给定元数据的新 TimeSeries。
返回类型: TimeSeries

示例

>>> from darts.utils.timeseries_generation import linear_timeseries
>>> series = linear_timeseries(length=3)
>>> # add metadata
>>> metadata = {'name': 'my_series'}
>>> series = series.with_metadata(metadata)
>>> series.metadata
{'name': 'my_series'}

with_static_covariates(covariates)[source]¶

返回一个新的 TimeSeries 对象，其中添加了静态协变量。

静态协变量包含附加到时间序列的数据，但这些数据不随时间变化。

参数: covariates (Union[Series, DataFrame, None]) – 可选地，一组静态协变量添加到 TimeSeries。可以是 pandas Series、pandas DataFrame 或 None。如果为 None，则将静态协变量设置为 None。如果为 Series，索引代表静态变量。然后协变量被全局“应用”到 TimeSeries 的所有分量。如果为 DataFrame，列代表静态变量，行代表单/多元 TimeSeries 的分量。如果为单行 DataFrame，协变量全局“应用”到 TimeSeries 的所有分量。如果为多行 DataFrame，行数必须与 TimeSeries 的分量数匹配。这添加了特定于分量的静态协变量。
返回: 一个具有给定静态协变量的新 TimeSeries。
返回类型: TimeSeries

注意

如果静态协变量变量数量很大（即静态协变量维度非常大），创建 TimeSeries 对象可能会有明显的性能损失，除非协变量已经具有与序列数据相同的 dtype。

示例

>>> import pandas as pd
>>> from darts.utils.timeseries_generation import linear_timeseries
>>> # add global static covariates
>>> static_covs = pd.Series([0., 1.], index=["static_cov_1", "static_cov_2"])
>>> series = linear_timeseries(length=3)
>>> series_new1 = series.with_static_covariates(static_covs)
>>> series_new1.static_covariates
                   static_cov_1  static_cov_2
component
linear              0.0           1.0

>>> # add component specific static covariates
>>> static_covs_multi = pd.DataFrame([[0., 1.], [2., 3.]], columns=["static_cov_1", "static_cov_2"])
>>> series_multi = series.stack(series)
>>> series_new2 = series_multi.with_static_covariates(static_covs_multi)
>>> series_new2.static_covariates
                   static_cov_1  static_cov_2
component
linear              0.0           1.0
linear_1            2.0           3.0

with_times_and_values(times, values, fill_missing_dates=False, freq=None, fillna_value=None)[source]¶

返回一个新的 TimeSeries，类似于此序列，但具有新的指定值。

参数

times (Union[DatetimeIndex, RangeIndex, Index]) – 一个 pandas DateTimeIndex、RangeIndex（或可以转换为 RangeIndex 的 Index），表示时间序列的新时间轴。最好索引没有空洞；或者设置 fill_missing_dates 在某些情况下可以解决这些问题（用 NaN 填充空洞，或用提供的 fillna_value 数字值填充，如果存在）。
values (ndarray) – 带有新值的 Numpy 数组。它必须具有与 times 和分量相同的维度，但可以包含不同数量的样本。
fill_missing_dates (Optional[bool, None]) – 可选，布尔值，指示是否用 NaN 值填充缺失的日期（或整数索引的情况下的索引）。这需要提供 freq 或能够从提供的时间戳推断频率。更多信息请参阅 _fill_missing_dates()。
freq (Union[str, int, None]) –
可选，字符串或整数，表示基础索引的频率。如果缺失某些日期且 fill_missing_dates 设置为 True，这对于填充缺失值很有用。如果为字符串，表示 pandas DatetimeIndex 的频率（有关支持的频率的更多信息，请参阅 offset aliases）。如果为整数，表示 pandas Index 或 pandas RangeIndex 的步长。
fillna_value (Optional[float, None]) – 可选，用于填充缺失值 (NaNs) 的数值。

返回

一个具有新值以及相同索引、静态协变量和层级结构的新 TimeSeries。

返回类型

TimeSeries

with_values(values)[source]¶

返回一个新的 TimeSeries，类似于此序列，但具有新的指定值。

参数: values (ndarray) – 带有新值的 Numpy 数组。它必须具有时间维度和分量维度，但可以包含不同数量的样本。
返回: 一个具有新值以及相同索引、静态协变量和层级结构的新 TimeSeries。
返回类型: TimeSeries

darts.timeseries.concatenate(series, axis=0, ignore_time_axis=False, ignore_static_covariates=False, drop_hierarchy=True, drop_metadata=False)[source]¶

沿着给定轴拼接多个 TimeSeries。

axis 可以是一个整数 (0, 1, 2) 分别表示 (时间, 分量, 样本)，或者，可以是一个字符串表示底层 DataArray 的相应维度。

参数

series (Sequence[TimeSeries]) – 要连接的 TimeSeries 序列
axis (Union[str, int]) – 沿哪个轴连接序列。
ignore_time_axis (bool) – 即使某些序列没有匹配的时间轴，也允许连接。沿分量或样本维度连接时，只要序列长度相同即可（在这种情况下，结果序列将具有提供的第一个序列的时间轴）。沿时间维度连接时，即使时间轴不连续也可以工作（在这种情况下，结果序列将具有与提供的第一个序列的起始时间匹配的起始时间）。默认值：False。
ignore_static_covariates (bool) – 是否忽略静态协变量连接的所有要求，并且仅将 series 中第一个 TimeSeries 元素的静态协变量转移到连接后的 TimeSeries。仅当 axis=1 时有效。
drop_hierarchy (bool) – 当 axis=1 时，是否丢弃层级结构信息。默认为 True。当为 False 时，层级结构也将被“连接”（通过合并层级结构字典），如果结果序列的分量名称与合并后的层级结构不匹配，可能会导致问题。当 axis=0 或 axis=2 时，始终保留第一个序列的层级结构。
drop_metadata (bool) – 是否丢弃连接后的序列的元数据信息。默认为 False。当为 False 时，连接后的序列将继承 series 中第一个 TimeSeries 元素的元数据。

返回

连接后的序列

返回类型

TimeSeries

darts.timeseries.slice_intersect(series)[source]¶

返回一个 TimeSeries 列表，其中所有 series 已沿时间索引进行交集。

参数: series (Sequence[TimeSeries]) – 要进行交集的 TimeSeries 序列
返回: 进行交集后的序列。
返回类型: Sequence[TimeSeries]

额外的实用函数

示例