Partilhar via

series_uv_change_points_fl()

  • Artigo

Aplica-se a: ✅Azure Data Explorer

A função series_uv_change_points_fl() é uma UDF (função definida pelo usuário) que localiza pontos de alteração em séries temporais chamando a API de Detecção de Anomalias Univariadas, parte dos Serviços Cognitivos do Azure. A função aceita um conjunto limitado de séries temporais como matrizes dinâmicas numéricas, o limite de detecção de ponto de alteração e o tamanho mínimo da janela de tendência estável. Cada série temporal é convertida no formato JSON necessário e a posta no ponto de extremidade de serviço do Detector de Anomalias. A resposta de serviço contém matrizes dinâmicas de pontos de alteração, sua respectiva confiança e a sazonalidade detectada.

Observação

Considere usar a função nativa series_decompose_anomalies(), que é mais escalável e é executada mais rapidamente.

Pré-requisitos

Sintaxe

T | invoke series_uv_change_points_fl( y_series [, score_threshold [, trend_window [, tsid]]])

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome Digitar Obrigatória Descrição
y_series string ✔️ O nome da coluna da tabela de entrada que contém os valores da série a ser detectada por anomalias.
score_threshold real Um valor que especifica a confiança mínima para declarar um ponto de alteração. Cada ponto cuja confiança está acima do limite é definido como um ponto de alteração. Valor padrão: 0,9
trend_window Número inteiro Um valor que especifica o tamanho mínimo da janela para cálculo robusto de alterações de tendência. Valor padrão: 5
tsid string O nome da coluna da tabela de entrada que contém a ID da série temporal. Pode ser omitido ao analisar uma única série temporal.

Definição de função

Você pode definir a função inserindo seu código como uma função definida por consulta ou criando-a como uma função armazenada em seu banco de dados, da seguinte maneira:

Defina a função usando a instrução let a seguir. Nenhuma permissão é necessária. Na definição de função a seguir, substitua YOUR-AD-RESOURCE-NAME no uri e YOUR-KEY no Ocp-Apim-Subscription-Key cabeçalho pelo nome e pela chave do recurso do Detector de Anomalias.

Importante

Uma instrução let não pode ser executada sozinha. Ele deve ser seguido por uma instrução de expressão tabular. Para executar um exemplo funcional de series_uv_change_points_fl(), consulte Exemplo.

let series_uv_change_points_fl=(tbl:(*), y_series:string, score_threshold:real=0.9, trend_window:int=5, tsid:string='_tsid')
{
    let uri = 'https://YOUR-AD-RESOURCE-NAME.cognitiveservices.azure.com/anomalydetector/v1.0/timeseries/changepoint/detect';
    let headers=dynamic({'Ocp-Apim-Subscription-Key': h'YOUR-KEY'});
    let kwargs = bag_pack('y_series', y_series, 'score_threshold', score_threshold, 'trend_window', trend_window);
    let code = ```if 1:
        import json
        y_series = kargs["y_series"]
        score_threshold = kargs["score_threshold"]
        trend_window = kargs["trend_window"]
        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, "threshold":score_threshold, "stableTrendWindow": trend_window}     # auto-detect period, or we can force 'period': 84
            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, change_point=series_add(0, ResponseBody.isChangePoint), confidence=ResponseBody.confidenceScores
        | extend _tsid=toscalar(_tsid)
       )
};
// Write your query to use the function here.

Exemplo

O exemplo a seguir usa o operador invoke para executar a função.

Para usar uma função definida por consulta, invoque-a após a definição da função inserida.

let series_uv_change_points_fl=(tbl:(*), y_series:string, score_threshold:real=0.9, trend_window:int=5, tsid:string='_tsid')
{
    let uri = 'https://YOUR-AD-RESOURCE-NAME.cognitiveservices.azure.com/anomalydetector/v1.0/timeseries/changepoint/detect';
    let headers=dynamic({'Ocp-Apim-Subscription-Key': h'YOUR-KEY'});
    let kwargs = bag_pack('y_series', y_series, 'score_threshold', score_threshold, 'trend_window', trend_window);
    let code = ```if 1:
        import json
        y_series = kargs["y_series"]
        score_threshold = kargs["score_threshold"]
        trend_window = kargs["trend_window"]
        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, "threshold":score_threshold, "stableTrendWindow": trend_window}     # auto-detect period, or we can force 'period': 84
            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, change_point=series_add(0, ResponseBody.isChangePoint), confidence=ResponseBody.confidenceScores
        | extend _tsid=toscalar(_tsid)
       )
};
let ts = range x from 1 to 300 step 1
| extend y=iff(x between (100 .. 110) or x between (200 .. 220), 20, 5)
| extend ts=datetime(2021-01-01)+x*1d
| extend y=y+4*rand()
| summarize ts=make_list(ts), y=make_list(y)
| extend sid=1;
ts
| invoke series_uv_change_points_fl('y', 0.8, 10, 'sid')
| join ts on $left._tsid == $right.sid
| project-away _tsid
| project-reorder y, *      //  just to visualize the anomalies on top of y series
| render anomalychart with(xcolumn=ts, ycolumns=y, confidence, anomalycolumns=change_point)

Saída

O gráfico a seguir mostra os pontos de alteração em uma série temporal.

Gráfico mostrando pontos de alteração em uma série temporal.