add python sdk sample (#13338)

* add python sample

* add change point

* update anomaly detector sample code

* update readme

* update readme for samples

* update MANIFEST.in

* fix pr

Co-authored-by: yongxingwu <[email protected]>
Co-authored-by: Xia Zhu <[email protected]>

sdk/anomalydetector/azure-ai-anomalydetector/MANIFEST.in

@@ -1,4 +1,5 @@
 recursive-include tests *.py *.yaml
+recursive-include samples *.py *.md
 include *.md
 include azure/__init__.py
 include azure/ai/__init__.py

sdk/anomalydetector/azure-ai-anomalydetector/samples/README.md

@@ -0,0 +1,59 @@
+---
+page_type: sample
+languages:
+  - python
+products:
+  - azure
+  - azure-cognitive-services
+  - azure-anomaly-detector
+urlFragment: anomalydetector-samples
+---
+
+# Samples for Azure Anomaly Detector client library for Python
+
+These code samples show common scenario operations with the Anomaly Detector client library.
+
+These sample programs show common scenarios for the Anomaly Detector client's offerings.
+
+|**File Name**|**Description**|
+|----------------|-------------|
+|[sample_detect_entire_series_anomaly.py][sample_detect_entire_series_anomaly] |Detecting anomalies in the entire time series.|
+|[sample_detect_last_point_anomaly.py][sample_detect_last_point_anomaly] |Detecting the anomaly status of the latest data point.|
+|[sample_detect_change_point.py][sample_detect_change_point] |Detecting change points in the entire time series.|
+
+## Prerequisites
+* Python 2.7 or 3.5 or higher is required to use this package.
+* The Pandas data analysis library.
+* You must have an [Azure subscription][azure_subscription] and an
+[Azure Anomaly Detector account][azure_anomaly_detector_account] to run these samples.
+
+## Setup
+
+1. Install the Azure Anomaly Detector client library for Python with [pip][pip]:
+
+```bash
+pip install azure-ai-anomalydetector
+```
+
+2. Clone or download this sample repository
+3. Open the sample folder in Visual Studio Code or your IDE of choice.
+
+## Running the samples
+
+1. Open a terminal window and `cd` to the directory that the samples are saved in.
+2. Set the environment variables specified in the sample file you wish to run.
+3. Follow the usage described in the file, e.g. `python sample_detect_entire_series_anomaly.py`
+
+## Next steps
+
+Check out the [API reference documentation][python-fr-ref-docs] to learn more about
+what you can do with the Azure Anomaly Detector client library.
+
+[pip]: https://pypi.org/project/pip/
+[azure_subscription]: https://azure.microsoft.com/free/cognitive-services
+[azure_anomaly_detector_account]: https://ms.portal.azure.com/#create/Microsoft.CognitiveServicesAnomalyDetector
+[python-fr-ref-docs]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-cognitiveservices-anomalydetector/0.3.0/index.html
+
+[sample_detect_entire_series_anomaly]: ./sample_detect_entire_series_anomaly.py
+[sample_detect_last_point_anomaly]: ./sample_detect_last_point_anomaly.py
+[sample_detect_change_point]: ./sample_detect_change_point.py

sdk/anomalydetector/azure-ai-anomalydetector/samples/sample_data/request-data.csv

@@ -0,0 +1,47 @@
+2018-03-01T00:00:00Z,32858923
+2018-03-02T00:00:00Z,29615278
+2018-03-03T00:00:00Z,22839355
+2018-03-04T00:00:00Z,25948736
+2018-03-05T00:00:00Z,34139159
+2018-03-06T00:00:00Z,33843985
+2018-03-07T00:00:00Z,33637661
+2018-03-08T00:00:00Z,32627350
+2018-03-09T00:00:00Z,29881076
+2018-03-10T00:00:00Z,22681575
+2018-03-11T00:00:00Z,24629393
+2018-03-12T00:00:00Z,34010679
+2018-03-13T00:00:00Z,33893888
+2018-03-14T00:00:00Z,33760076
+2018-03-15T00:00:00Z,33093515
+2018-03-16T00:00:00Z,29945555
+2018-03-17T00:00:00Z,22676212
+2018-03-18T00:00:00Z,25262514
+2018-03-19T00:00:00Z,33631649
+2018-03-20T00:00:00Z,34468310
+2018-03-21T00:00:00Z,34212281
+2018-03-22T00:00:00Z,38144434
+2018-03-23T00:00:00Z,34662949
+2018-03-24T00:00:00Z,24623684
+2018-03-25T00:00:00Z,26530491
+2018-03-26T00:00:00Z,35445003
+2018-03-27T00:00:00Z,34250789
+2018-03-28T00:00:00Z,33423012
+2018-03-29T00:00:00Z,30744783
+2018-03-30T00:00:00Z,25825128
+2018-03-31T00:00:00Z,21244209
+2018-04-01T00:00:00Z,22576956
+2018-04-02T00:00:00Z,31957221
+2018-04-03T00:00:00Z,33841228
+2018-04-04T00:00:00Z,33554483
+2018-04-05T00:00:00Z,32383350
+2018-04-06T00:00:00Z,29494850
+2018-04-07T00:00:00Z,22815534
+2018-04-08T00:00:00Z,25557267
+2018-04-09T00:00:00Z,34858252
+2018-04-10T00:00:00Z,34750597
+2018-04-11T00:00:00Z,34717956
+2018-04-12T00:00:00Z,34132534
+2018-04-13T00:00:00Z,30762236
+2018-04-14T00:00:00Z,22504059
+2018-04-15T00:00:00Z,26149060
+2018-04-16T00:00:00Z,35250105

sdk/anomalydetector/azure-ai-anomalydetector/samples/sample_detect_change_point.py

@@ -0,0 +1,84 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+"""
+FILE: sample_detect_change_point.py
+
+DESCRIPTION:
+    This sample demonstrates how to detect entire series change points.
+
+Prerequisites:
+     * The Anomaly Detector client library for Python
+     * A .csv file containing a time-series data set with
+        UTC-timestamp and numerical values pairings.
+        Example data is included in this repo.
+
+USAGE:
+    python sample_detect_change_point.py
+
+    Set the environment variables with your own values before running the sample:
+    1) ANOMALY_DETECTOR_KEY - your source Form Anomaly Detector API key.
+    2) ANOMALY_DETECTOR_ENDPOINT - the endpoint to your source Anomaly Detector resource.
+"""
+
+import os
+from azure.ai.anomalydetector import AnomalyDetectorClient
+from azure.ai.anomalydetector.models import DetectRequest, TimeSeriesPoint, TimeGranularity, \
+    AnomalyDetectorError
+from azure.core.credentials import AzureKeyCredential
+import pandas as pd
+
+
+class DetectChangePointsSample(object):
+
+    def detect_change_point(self):
+        SUBSCRIPTION_KEY = os.environ["ANOMALY_DETECTOR_KEY"]
+        ANOMALY_DETECTOR_ENDPOINT = os.environ["ANOMALY_DETECTOR_ENDPOINT"]
+        TIME_SERIES_DATA_PATH = os.path.join("./sample_data", "request-data.csv")
+
+        # Create an Anomaly Detector client
+
+        # <client>
+        client = AnomalyDetectorClient(AzureKeyCredential(SUBSCRIPTION_KEY), ANOMALY_DETECTOR_ENDPOINT)
+        # </client>
+
+        # Load in the time series data file
+
+        # <loadDataFile>
+        series = []
+        data_file = pd.read_csv(TIME_SERIES_DATA_PATH, header=None, encoding='utf-8', parse_dates=[0])
+        for index, row in data_file.iterrows():
+            series.append(TimeSeriesPoint(timestamp=row[0], value=row[1]))
+        # </loadDataFile>
+
+        # Create a request from the data file
+
+        # <request>
+        request = DetectRequest(series=series, granularity=TimeGranularity.daily)
+        # </request>
+
+        # detect change points throughout the entire time series
+
+        # <detectChangePoint>
+        print('Detecting change points in the entire time series.')
+
+        try:
+            response = client.detect_change_point(request)
+        except AnomalyDetectorError as e:
+            print('Error code: {}'.format(e.error.code), 'Error message: {}'.format(e.error.message))
+        except Exception as e:
+            print(e)
+
+        if any(response.is_change_point):
+            print('An change point was detected at index:')
+            for i, value in enumerate(response.is_change_point):
+                if value:
+                    print(i)
+        else:
+            print('No change point were detected in the time series.')
+        # </detectChangePoint>
+
+
+if __name__ == '__main__':
+    sample = DetectChangePointsSample()
+    sample.detect_change_point()

sdk/anomalydetector/azure-ai-anomalydetector/samples/sample_detect_entire_series_anomaly.py

@@ -0,0 +1,84 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+"""
+FILE: sample_detect_entire_series_anomaly.py
+
+DESCRIPTION:
+    This sample demonstrates how to detect entire series anomalies.
+
+Prerequisites:
+     * The Anomaly Detector client library for Python
+     * A .csv file containing a time-series data set with
+        UTC-timestamp and numerical values pairings.
+        Example data is included in this repo.
+
+USAGE:
+    python sample_detect_entire_series_anomaly.py
+
+    Set the environment variables with your own values before running the sample:
+    1) ANOMALY_DETECTOR_KEY - your source Form Anomaly Detector API key.
+    2) ANOMALY_DETECTOR_ENDPOINT - the endpoint to your source Anomaly Detector resource.
+"""
+
+import os
+from azure.ai.anomalydetector import AnomalyDetectorClient
+from azure.ai.anomalydetector.models import DetectRequest, TimeSeriesPoint, TimeGranularity, \
+    AnomalyDetectorError
+from azure.core.credentials import AzureKeyCredential
+import pandas as pd
+
+
+class DetectEntireAnomalySample(object):
+
+    def detect_entire_series(self):
+        SUBSCRIPTION_KEY = os.environ["ANOMALY_DETECTOR_KEY"]
+        ANOMALY_DETECTOR_ENDPOINT = os.environ["ANOMALY_DETECTOR_ENDPOINT"]
+        TIME_SERIES_DATA_PATH = os.path.join("./sample_data", "request-data.csv")
+
+        # Create an Anomaly Detector client
+
+        # <client>
+        client = AnomalyDetectorClient(AzureKeyCredential(SUBSCRIPTION_KEY), ANOMALY_DETECTOR_ENDPOINT)
+        # </client>
+
+        # Load in the time series data file
+
+        # <loadDataFile>
+        series = []
+        data_file = pd.read_csv(TIME_SERIES_DATA_PATH, header=None, encoding='utf-8', parse_dates=[0])
+        for index, row in data_file.iterrows():
+            series.append(TimeSeriesPoint(timestamp=row[0], value=row[1]))
+        # </loadDataFile>
+
+        # Create a request from the data file
+
+        # <request>
+        request = DetectRequest(series=series, granularity=TimeGranularity.daily)
+        # </request>
+
+        # detect anomalies throughout the entire time series, as a batch
+
+        # <detectAnomaliesBatch>
+        print('Detecting anomalies in the entire time series.')
+
+        try:
+            response = client.detect_entire_series(request)
+        except AnomalyDetectorError as e:
+            print('Error code: {}'.format(e.error.code), 'Error message: {}'.format(e.error.message))
+        except Exception as e:
+            print(e)
+
+        if any(response.is_anomaly):
+            print('An anomaly was detected at index:')
+            for i, value in enumerate(response.is_anomaly):
+                if value:
+                    print(i)
+        else:
+            print('No anomalies were detected in the time series.')
+        # </detectAnomaliesBatch>
+
+
+if __name__ == '__main__':
+    sample = DetectEntireAnomalySample()
+    sample.detect_entire_series()

sdk/anomalydetector/azure-ai-anomalydetector/samples/sample_detect_last_point_anomaly.py

@@ -0,0 +1,81 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+"""
+FILE: sample_detect_last_point_anomaly.py
+
+DESCRIPTION:
+    This sample demonstrates how to detect last series point whether is anomaly.
+
+Prerequisites:
+     * The Anomaly Detector client library for Python
+     * A .csv file containing a time-series data set with
+        UTC-timestamp and numerical values pairings.
+        Example data is included in this repo.
+
+USAGE:
+    python sample_detect_last_point_anomaly.py
+
+    Set the environment variables with your own values before running the sample:
+    1) ANOMALY_DETECTOR_KEY - your source Form Anomaly Detector API key.
+    2) ANOMALY_DETECTOR_ENDPOINT - the endpoint to your source Anomaly Detector resource.
+"""
+
+import os
+from azure.ai.anomalydetector import AnomalyDetectorClient
+from azure.ai.anomalydetector.models import DetectRequest, TimeSeriesPoint, TimeGranularity, \
+    AnomalyDetectorError
+from azure.core.credentials import AzureKeyCredential
+import pandas as pd
+
+
+class DetectLastAnomalySample(object):
+
+    def detect_last_point(self):
+        SUBSCRIPTION_KEY = os.environ["ANOMALY_DETECTOR_KEY"]
+        ANOMALY_DETECTOR_ENDPOINT = os.environ["ANOMALY_DETECTOR_ENDPOINT"]
+        TIME_SERIES_DATA_PATH = os.path.join("./sample_data", "request-data.csv")
+
+        # Create an Anomaly Detector client
+
+        # <client>
+        client = AnomalyDetectorClient(AzureKeyCredential(SUBSCRIPTION_KEY), ANOMALY_DETECTOR_ENDPOINT)
+        # </client>
+
+        # Load in the time series data file
+
+        # <loadDataFile>
+        series = []
+        data_file = pd.read_csv(TIME_SERIES_DATA_PATH, header=None, encoding='utf-8', parse_dates=[0])
+        for index, row in data_file.iterrows():
+            series.append(TimeSeriesPoint(timestamp=row[0], value=row[1]))
+        # </loadDataFile>
+
+        # Create a request from the data file
+
+        # <request>
+        request = DetectRequest(series=series, granularity=TimeGranularity.daily)
+        # </request>
+
+        # Detect the anomaly status of the latest data point
+
+        # <latestPointDetection>
+        print('Detecting the anomaly status of the latest data point.')
+
+        try:
+            response = client.detect_last_point(request)
+        except AnomalyDetectorError as e:
+            print('Error code: {}'.format(e.error.code), 'Error message: {}'.format(e.error.message))
+        except Exception as e:
+            print(e)
+
+        if response.is_anomaly:
+            print('The latest point is detected as anomaly.')
+        else:
+            print('The latest point is not detected as anomaly.')
+        # </latestPointDetection>
+
+
+if __name__ == '__main__':
+    sample = DetectLastAnomalySample()
+    sample.detect_last_point()