series_uv_anomalies_fl()

  • [アーティクル]

関数series_uv_anomalies_fl()は、Azure Cognitive Services の一部である Univariate Anomaly Detection API を呼び出すことによって時系列の異常を検出するユーザー定義関数 (UDF) です。 この関数は、限られた時系列のセットを、数値動的配列と必要な異常検出感度レベルとして受け入れます。 各時系列が必要な JSON 形式に変換され、Anomaly Detector サービス エンドポイントに投稿されます。 サービス応答には、高/低/すべての異常の動的配列、モデル化されたベースライン時系列、その通常の高/低境界 (高/低境界の上下の値が異常)、検出された季節性が含まれています。

Note

ネイティブ関数series_decompose_anomalies()の使用を検討してください。これはよりスケーラブルで、より高速に実行できます。

前提条件

次の関数の例では、 ヘッダーの uri と YOUR-KEY の をOcp-Apim-Subscription-Key、Anomaly Detectorリソース名とキーに置き換えますYOUR-AD-RESOURCE-NAME。

構文

T | invoke series_uv_anomalies_fl(y_series [,sensitivity [,tsid]])

構文規則について詳しく知る。

パラメーター

名前 型 必須 説明
y_series string ✔️ 異常検出される系列の値を含む入力テーブル列の名前。
sensitivity 整数 (integer) [0-100] の範囲の整数で、異常検出の感度を指定します。 0 は最も感度の低い検出であり、100 は最も感度が高く、予期されるベースラインからの小さな偏差でも異常とタグ付けされることを示しています。 既定値: 85
tsid string 時系列 ID を含む入力テーブル列の名前。 1 つの時系列を分析する場合は省略できます。

関数の定義

関数を定義するには、次のように、コードをクエリ定義関数として埋め込むか、データベースに格納されている関数として作成します。

次の let ステートメントを使用して関数を定義します。 権限は必要ありません。

重要

let ステートメントは単独では実行できません。 その後に 表形式の式ステートメントを記述する必要があります。 の動作例 series_uv_anomalies_fl()を実行するには、「 例」を参照してください。

let series_uv_anomalies_fl=(tbl:(*), y_series:string, sensitivity:int=85, tsid:string='_tsid')
{
    let uri = 'https://YOUR-AD-RESOURCE-NAME.cognitiveservices.azure.com/anomalydetector/v1.0/timeseries/entire/detect';
    let headers=dynamic({'Ocp-Apim-Subscription-Key': h'YOUR-KEY'});
    let kwargs = bag_pack('y_series', y_series, 'sensitivity', sensitivity);
    let code = ```if 1:
        import json
        y_series = kargs["y_series"]
        sensitivity = kargs["sensitivity"]
        json_str = []
        for i in range(len(df)):
            row = df.iloc[i, :]
            ts = [{'value':row[y_series][j]} for j in range(len(row[y_series]))]
            json_data = {'series': ts, "sensitivity":sensitivity}     # auto-detect period, or we can force 'period': 84. We can also add 'maxAnomalyRatio':0.25 for maximum 25% anomalies
            json_str = json_str + [json.dumps(json_data)]
        result = df
        result['json_str'] = json_str
    ```;
    tbl
    | evaluate python(typeof(*, json_str:string), code, kwargs)
    | extend _tsid = column_ifexists(tsid, 1)
    | partition by _tsid (
       project json_str
       | evaluate http_request_post(uri, headers, dynamic(null))
       | project period=ResponseBody.period, baseline_ama=ResponseBody.expectedValues, ad_ama=series_add(0, ResponseBody.isAnomaly), pos_ad_ama=series_add(0, ResponseBody.isPositiveAnomaly)
       , neg_ad_ama=series_add(0, ResponseBody.isNegativeAnomaly), upper_ama=series_add(ResponseBody.expectedValues, ResponseBody.upperMargins), lower_ama=series_subtract(ResponseBody.expectedValues, ResponseBody.lowerMargins)
       | extend _tsid=toscalar(_tsid)
      )
};
// Write your query to use the function here.

例

次の例では、 invoke 演算子 を使用して関数を実行します。

を使用して series_uv_anomalies_fl() 異常を検出する

クエリ定義関数を使用するには、埋め込み関数定義の後にそれを呼び出します。

let series_uv_anomalies_fl=(tbl:(*), y_series:string, sensitivity:int=85, tsid:string='_tsid')
{
    let uri = 'https://YOUR-AD-RESOURCE-NAME.cognitiveservices.azure.com/anomalydetector/v1.0/timeseries/entire/detect';
    let headers=dynamic({'Ocp-Apim-Subscription-Key': h'YOUR-KEY'});
    let kwargs = bag_pack('y_series', y_series, 'sensitivity', sensitivity);
    let code = ```if 1:
        import json
        y_series = kargs["y_series"]
        sensitivity = kargs["sensitivity"]
        json_str = []
        for i in range(len(df)):
            row = df.iloc[i, :]
            ts = [{'value':row[y_series][j]} for j in range(len(row[y_series]))]
            json_data = {'series': ts, "sensitivity":sensitivity}     # auto-detect period, or we can force 'period': 84. We can also add 'maxAnomalyRatio':0.25 for maximum 25% anomalies
            json_str = json_str + [json.dumps(json_data)]
        result = df
        result['json_str'] = json_str
    ```;
    tbl
    | evaluate python(typeof(*, json_str:string), code, kwargs)
    | extend _tsid = column_ifexists(tsid, 1)
    | partition by _tsid (
       project json_str
       | evaluate http_request_post(uri, headers, dynamic(null))
       | project period=ResponseBody.period, baseline_ama=ResponseBody.expectedValues, ad_ama=series_add(0, ResponseBody.isAnomaly), pos_ad_ama=series_add(0, ResponseBody.isPositiveAnomaly)
       , neg_ad_ama=series_add(0, ResponseBody.isNegativeAnomaly), upper_ama=series_add(ResponseBody.expectedValues, ResponseBody.upperMargins), lower_ama=series_subtract(ResponseBody.expectedValues, ResponseBody.lowerMargins)
       | extend _tsid=toscalar(_tsid)
      )
};
let etime=datetime(2017-03-02);
let stime=datetime(2017-01-01);
let dt=1h;
let ts = requests
| make-series value=avg(value) on timestamp from stime to etime step dt
| extend _tsid='TS1';
ts
| invoke series_uv_anomalies_fl('value')
| lookup ts on _tsid
| render anomalychart with(xcolumn=timestamp, ycolumns=value, anomalycolumns=ad_ama)

出力

時系列の異常を示すグラフ。

比較 series_uv_anomalies_fl() とネイティブ series_decompose_anomalies()

次の例では、Univariate Anomaly Detection API を 3 つの時系列でネイティブ series_decompose_anomalies() 関数と比較し、series_uv_anomalies_fl() 関数がデータベースで既に定義されていることを前提としています。

クエリ定義関数を使用するには、埋め込み関数定義の後にそれを呼び出します。

let series_uv_anomalies_fl=(tbl:(*), y_series:string, sensitivity:int=85, tsid:string='_tsid')
{
    let uri = 'https://YOUR-AD-RESOURCE-NAME.cognitiveservices.azure.com/anomalydetector/v1.0/timeseries/entire/detect';
    let headers=dynamic({'Ocp-Apim-Subscription-Key': h'YOUR-KEY'});
    let kwargs = bag_pack('y_series', y_series, 'sensitivity', sensitivity);
    let code = ```if 1:
        import json
        y_series = kargs["y_series"]
        sensitivity = kargs["sensitivity"]
        json_str = []
        for i in range(len(df)):
            row = df.iloc[i, :]
            ts = [{'value':row[y_series][j]} for j in range(len(row[y_series]))]
            json_data = {'series': ts, "sensitivity":sensitivity}     # auto-detect period, or we can force 'period': 84. We can also add 'maxAnomalyRatio':0.25 for maximum 25% anomalies
            json_str = json_str + [json.dumps(json_data)]
        result = df
        result['json_str'] = json_str
    ```;
    tbl
    | evaluate python(typeof(*, json_str:string), code, kwargs)
    | extend _tsid = column_ifexists(tsid, 1)
    | partition by _tsid (
       project json_str
       | evaluate http_request_post(uri, headers, dynamic(null))
       | project period=ResponseBody.period, baseline_ama=ResponseBody.expectedValues, ad_ama=series_add(0, ResponseBody.isAnomaly), pos_ad_ama=series_add(0, ResponseBody.isPositiveAnomaly)
       , neg_ad_ama=series_add(0, ResponseBody.isNegativeAnomaly), upper_ama=series_add(ResponseBody.expectedValues, ResponseBody.upperMargins), lower_ama=series_subtract(ResponseBody.expectedValues, ResponseBody.lowerMargins)
       | extend _tsid=toscalar(_tsid)
      )
};
let ts = demo_make_series2
| summarize TimeStamp=make_list(TimeStamp), num=make_list(num) by sid;
ts
| invoke series_uv_anomalies_fl('num', 'sid', 90)
| join ts on $left._tsid == $right.sid
| project-away _tsid
| extend (ad_adx, score_adx, baseline_adx)=series_decompose_anomalies(num, 1.5, -1, 'linefit')
| project-reorder num, *
| render anomalychart with(series=sid, xcolumn=TimeStamp, ycolumns=num, baseline_adx, baseline_ama, lower_ama, upper_ama, anomalycolumns=ad_adx, ad_ama)

出力

次のグラフは、TS1 の Univariate Anomaly Detection API によって検出された異常を示しています。 [グラフ フィルター] ボックスでは、TS2 または TS3 も選択できます。

時系列で Univariate A P I を使用した異常を示すグラフ。

次のグラフは、TS1 のネイティブ関数によって検出された異常を示しています。

時系列のネイティブ関数を使用した異常を示すグラフ。

この機能はサポートされていません。