预测异常模型

一个 ForecastingAnomalyModel 封装了 Darts 预测模型和一个或多个异常评分器，通过比较实际值与模型预测值的偏差来计算异常得分。

类 darts.ad.anomaly_model.forecasting_am.ForecastingAnomalyModel(model, scorer)[source]

基类：AnomalyModel

基于预测的异常检测模型

预测模型必须是 GlobalForecastingModel 的实例，它可以已经拟合或尚未拟合。基本假设是，在没有异常的情况下，model 应该能够准确预测序列。因此，建议提供一个已经拟合并评估过的模型，使其能够在没有异常的序列上正常工作；或者确保简单调用模型的 fit() 方法足以在没有异常的序列上将其训练到令人满意的性能。调用 score() 时，将使用预训练的模型生成预测。

只有在调用 fit() 时将 allow_model_training 设置为 True，对异常模型调用 fit() 才会拟合底层的预测模型。此外，调用 fit() 也将拟合所有可拟合的评分器（如果有的话）。

参数

  • model (GlobalForecastingModel) – Darts 预测模型的一个实例。

  • scorer (Union[AnomalyScorer, Sequence[AnomalyScorer]]) – 一个或多个评分器，用于比较实际时间序列和预测时间序列以获得异常得分 TimeSeries。如果给定 N 个评分器的列表，异常模型将调用每个评分器并输出 N 个异常得分 TimeSeries 的列表。

属性

scorers_are_trainable

任何评分器是否可训练。

scorers_are_univariate

任何评分器是否为单变量。

方法

eval_metric(anomalies, series[, ...])

计算模型计算出的异常得分的准确性。

fit(series[, past_covariates, ...])

拟合底层的预测模型（如果适用）以及所有可拟合的评分器（如果有的话）。

predict_series(series[, past_covariates, ...])

计算底层预测模型在 series 上本可以获得的过去预测结果。

score(series[, past_covariates, ...])

计算给定序列的异常得分。

show_anomalies(series[, past_covariates, ...])

绘制异常模型的结果。
eval_metric(anomalies, series, past_covariates=None, future_covariates=None, forecast_horizon=1, start=None, start_format='value', num_samples=1, verbose=False, show_warnings=True, enable_optimization=True, metric='AUC_ROC')[source]

计算模型计算出的异常得分的准确性。

使用预测模型预测 series，并将评分器应用于预测时间序列和给定的目标时间序列。根据评分器给出的异常得分，返回与阈值无关的度量指标的得分。

参数

  • anomalies (Union[TimeSeries, Sequence[TimeSeries]]) – 地面真相二元异常序列（或序列）（1 表示异常，0 表示非异常）。

  • series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于预测异常的序列（或序列）。

  • past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，过去观察到的协变量序列（或序列）。这仅适用于支持过去协变量的模型。

  • future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，未来已知协变量序列（或序列）。这仅适用于支持未来协变量的模型。

  • forecast_horizon (int) – 预测的时间范围。

  • start (Union[Timestamp, float, int, None]) – 计算未来时间点第一个预测值的时间点。此参数支持 3 种不同的数据类型：float、int 和 pandas.Timestamp。对于 float，参数将被视为时间序列中应在第一个预测点之前的部分比例。对于 int，参数将被视为 series 时间索引的整数索引，该索引将用作第一个预测时间。对于 pandas.Timestamp，此时间戳将直接用于确定第一个预测时间。

  • start_format (Literal[‘position’, ‘value’]) – 定义 start 格式。仅当 start 为整数且 series 使用 pd.RangeIndex 索引时有效。如果设置为 ‘position’，start 对应于第一个预测点在索引中的位置，范围从 (-len(series), len(series) - 1)。如果设置为 ‘value’，start 对应于第一个预测点在索引中的值/标签。如果该值不在 series 的索引中，将引发错误。默认值：‘value’

  • num_samples (int) – 从概率模型中采样预测的次数。对于确定性模型，必须为 1。

  • verbose (bool) – 是否打印进度。

  • show_warnings (bool) – 是否显示与过去预测优化或参数 start 和 train_length 相关的警告。

  • enable_optimization (bool) – 是否在支持和可用时使用优化版本的 historical_forecasts。默认值：True。

  • metric (Literal[‘AUC_ROC’, ‘AUC_PR’]) – 要使用的度量函数的名称。必须是 “AUC_ROC”（接收者操作特征曲线下面积）和 “AUC_PR”（基于得分的平均精度）之一。默认值：“AUC_ROC”。

返回类型

Union[dict[str, float], dict[str, Sequence[float]], Sequence[dict[str, float]], Sequence[dict[str, Sequence[float]]]]

返回值

  • Dict[str, float] – 针对单个单变量 series 的结果度量字典，键表示异常评分器，值表示度量值。

  • Dict[str, Sequence[float]] – 与 Dict[str, float] 相同，但用于多变量 series，以及独立处理序列分量/列的异常评分器（取决于评分器的性质或如果 component_wise=True）。

  • Sequence[Dict[str, float]] – 与 Dict[str, float] 相同，但用于单变量序列的序列。

  • Sequence[Dict[str, Sequence[float]]] – 与 Dict[str, float] 相同，但用于多变量序列的序列。

fit(series, past_covariates=None, future_covariates=None, allow_model_training=False, forecast_horizon=1, start=None, start_format='value', num_samples=1, verbose=False, show_warnings=True, enable_optimization=True, **model_fit_kwargs)[source]

拟合底层的预测模型（如果适用）以及所有可拟合的评分器（如果有的话）。

在给定时间序列上训练预测模型（如果尚未拟合且 allow_model_training 为 True）和可拟合的评分器（如果有的话）。

我们使用训练好的预测模型来计算输入 series 的历史预测。然后，评分器将根据这些预测以及输入 series 进行训练。

参数

  • series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于训练的序列（或序列）（通常假设无异常）。

  • past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，过去观察到的协变量序列（或序列）。这仅适用于支持过去协变量的模型。

  • future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，未来已知协变量序列（或序列）。这仅适用于支持未来协变量的模型。

  • allow_model_training (bool) – 是否应该在给定序列上拟合预测模型。如果为 False，则模型必须已经拟合。

  • forecast_horizon (int) – 预测的时间范围。

  • start (Union[Timestamp, float, int, None]) – 计算未来时间点第一个预测值的时间点。此参数支持 3 种不同的数据类型：float、int 和 pandas.Timestamp。对于 float，参数将被视为时间序列中应在第一个预测点之前的部分比例。对于 int，参数将被视为 series 时间索引的整数索引，该索引将用作第一个预测时间。对于 pandas.Timestamp，此时间戳将直接用于确定第一个预测时间。

  • start_format (Literal[‘position’, ‘value’]) – 定义 start 格式。仅当 start 为整数且 series 使用 pd.RangeIndex 索引时有效。如果设置为 ‘position’，start 对应于第一个预测点在索引中的位置，范围从 (-len(series), len(series) - 1)。如果设置为 ‘value’，start 对应于第一个预测点在索引中的值/标签。如果该值不在 series 的索引中，将引发错误。默认值：‘value’

  • num_samples (int) – 从概率模型中采样预测的次数。对于确定性模型，必须为 1。

  • verbose (bool) – 是否打印进度。

  • show_warnings (bool) – 是否显示与过去预测优化或参数 start 和 train_length 相关的警告。

  • enable_optimization (bool) – 是否在支持和可用时使用优化版本的 historical_forecasts。默认值：True。

  • model_fit_kwargs – 传递给预测模型 fit() 方法的参数。

返回值

已拟合模型

返回类型

self

predict_series(series, past_covariates=None, future_covariates=None, forecast_horizon=1, start=None, start_format='value', num_samples=1, verbose=False, show_warnings=True, enable_optimization=True)[source]

计算底层预测模型在 series 上本可以获得的过去预测结果。

如果可能（并非所有模型都支持），则将 retrain 设置为 False。如果设置为 True，则将始终在整个可用历史上重新训练模型，

参数

  • series (Sequence[TimeSeries]) – 要评分的序列集合。

  • past_covariates (Optional[Sequence[TimeSeries], None]) – 可选，过去观察到的协变量序列或序列集合。这仅适用于支持过去协变量的模型。

  • future_covariates (Optional[Sequence[TimeSeries], None]) – 可选，未来已知协变量序列或序列集合。这仅适用于支持未来协变量的模型。

  • forecast_horizon (int) – 预测的时间范围。

  • start (Union[Timestamp, float, int, None]) – 计算未来时间点第一个预测值的时间点。此参数支持 3 种不同的数据类型：float、int 和 pandas.Timestamp。对于 float，参数将被视为时间序列中应在第一个预测点之前的部分比例。对于 int，参数将被视为 series 时间索引的整数索引，该索引将用作第一个预测时间。对于 pandas.Timestamp，此时间戳将直接用于确定第一个预测时间。

  • start_format (Literal[‘position’, ‘value’]) – 定义 start 格式。仅当 start 为整数且 series 使用 pd.RangeIndex 索引时有效。如果设置为 ‘position’，start 对应于第一个预测点在索引中的位置，范围从 (-len(series), len(series) - 1)。如果设置为 ‘value’，start 对应于第一个预测点在索引中的值/标签。如果该值不在 series 的索引中，将引发错误。默认值：‘value’

  • num_samples (int) – 从概率模型中采样预测的次数。对于确定性模型，必须为 1。

  • verbose (bool) – 是否打印进度。

  • show_warnings (bool) – 是否显示与过去预测优化或参数 start 和 train_length 相关的警告。

  • enable_optimization (bool) – 是否在支持和可用时使用优化版本的 historical_forecasts。默认值：True。

返回值

包含每个序列历史预测的 TimeSeries 序列（使用 last_points_only=True）。

返回类型

Sequence[TimeSeries]

score(series, past_covariates=None, future_covariates=None, forecast_horizon=1, start=None, start_format='value', num_samples=1, verbose=False, show_warnings=True, enable_optimization=True, return_model_prediction=False)[source]

计算给定序列的异常得分。

使用预测模型预测给定的目标时间序列，并将评分器应用于预测值和目标输入时间序列。

参数

  • series (Union[TimeSeries, Sequence[TimeSeries]]) – 要评分的序列（或序列）。

  • past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，过去观察到的协变量序列（或序列）。这仅适用于支持过去协变量的模型。

  • future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，未来已知协变量序列（或序列）。这仅适用于支持未来协变量的模型。

  • forecast_horizon (int) – 预测的时间范围。

  • start (Union[Timestamp, float, int, None]) – 计算未来时间点第一个预测值的时间点。此参数支持 3 种不同的数据类型：float、int 和 pandas.Timestamp。对于 float，参数将被视为时间序列中应在第一个预测点之前的部分比例。对于 int，参数将被视为 series 时间索引的整数索引，该索引将用作第一个预测时间。对于 pandas.Timestamp，此时间戳将直接用于确定第一个预测时间。

  • start_format (Literal[‘position’, ‘value’]) – 定义 start 格式。仅当 start 为整数且 series 使用 pd.RangeIndex 索引时有效。如果设置为 ‘position’，start 对应于第一个预测点在索引中的位置，范围从 (-len(series), len(series) - 1)。如果设置为 ‘value’，start 对应于第一个预测点在索引中的值/标签。如果该值不在 series 的索引中，将引发错误。默认值：‘value’

  • num_samples (int) – 从概率模型中采样预测的次数。对于确定性模型，必须为 1。

  • verbose (bool) – 是否打印进度。

  • show_warnings (bool) – 是否显示与过去预测优化或参数 start 和 train_length 相关的警告。

  • enable_optimization (bool) – 是否在支持和可用时使用优化版本的 historical_forecasts。默认值：True。

  • return_model_prediction (bool) – 是否在返回异常得分的同时返回预测模型的预测值。

返回类型

Union[TimeSeries, Sequence[TimeSeries], Sequence[Sequence[TimeSeries]]]

返回值

  • TimeSeries – 单个 series 使用单个异常评分器时返回的单个 TimeSeries。

  • Sequence[TimeSeries] – 一个包含 TimeSeries 的序列，用于

    • 单个 series 使用多个异常评分器。

    • 序列集合使用单个异常评分器。

  • Sequence[Sequence[TimeSeries]] – 针对 series 序列集合和多个异常评分器返回的 TimeSeries 序列的序列。外部序列对应系列，内部序列对应评分器。

属性 scorers_are_trainable

任何评分器是否可训练。

属性 scorers_are_univariate

任何评分器是否为单变量。

show_anomalies(series, past_covariates=None, future_covariates=None, forecast_horizon=1, start=None, start_format='value', num_samples=1, verbose=False, show_warnings=True, enable_optimization=True, anomalies=None, names_of_scorers=None, title=None, metric=None, component_wise=False, **score_kwargs)[source]

绘制异常模型的结果。

计算给定序列输入的得分，并按时间显示不同的异常得分。

图形将包含以下内容

  • 序列本身以及预测模型的输出。

  • 每个评分器的异常得分。具有不同窗口的评分器将分开显示。

  • 实际异常（如果提供）。

可以

  • 使用参数 title 为图形添加标题

  • 使用 names_of_scorers 为评分器指定个性化名称

  • 显示每个异常得分的度量结果（AUC_ROC 或 AUC_PR），前提是提供了实际异常。

参数

  • series (TimeSeries) – 用于可视化异常的序列。

  • past_covariates (Optional[TimeSeries, None]) – 可选，过去观察到的协变量序列或序列集合。这仅适用于支持过去协变量的模型。

  • future_covariates (Optional[TimeSeries, None]) – 可选，未来已知协变量序列或序列集合。这仅适用于支持未来协变量的模型。

  • forecast_horizon (int) – 预测的时间范围。

  • start (Union[Timestamp, float, int, None]) – 计算未来时间点第一个预测值的时间点。此参数支持 3 种不同的数据类型：float、int 和 pandas.Timestamp。对于 float，参数将被视为时间序列中应在第一个预测点之前的部分比例。对于 int，参数将被视为 series 时间索引的整数索引，该索引将用作第一个预测时间。对于 pandas.Timestamp，此时间戳将直接用于确定第一个预测时间。

  • start_format (Literal[‘position’, ‘value’]) – 定义 start 格式。仅当 start 为整数且 series 使用 pd.RangeIndex 索引时有效。如果设置为 ‘position’，start 对应于第一个预测点在索引中的位置，范围从 (-len(series), len(series) - 1)。如果设置为 ‘value’，start 对应于第一个预测点在索引中的值/标签。如果该值不在 series 的索引中，将引发错误。默认值：‘value’

  • num_samples (int) – 从概率模型中采样预测的次数。对于确定性模型，必须为 1。

  • verbose (bool) – 是否打印进度。

  • show_warnings (bool) – 是否显示与过去预测优化或参数 start 和 train_length 相关的警告。

  • enable_optimization (bool) – 是否在支持和可用时使用优化版本的 historical_forecasts。默认值：True。

  • anomalies (Optional[TimeSeries, None]) – 异常的地面真相（1 表示异常，0 表示非异常）。

  • names_of_scorers (Union[str, Sequence[str], None]) – 得分的名称。必须是一个列表，其长度等于 anomaly_model 中的评分器数量。

  • title (Optional[str, None]) – 图形的标题。

  • metric (Optional[Literal[‘AUC_ROC’, ‘AUC_PR’], None]) – 可选，要使用的度量函数的名称。必须是 “AUC_ROC”（接收者操作特征曲线下面积）和 “AUC_PR”（基于得分的平均精度）之一。默认值：“AUC_ROC”。

  • component_wise (bool) – 如果为 True，将在多变量异常检测的情况下单独绘制每个分量。

  • score_kwargs – score() 方法的参数。

上一页

过滤异常模型

下一页

异常检测器