Package: azure-ai-anomalydetector
Cognitive Services Anomaly Detector client library for PythonAnomaly Detectoris an AI service with a set of APIs, which enables you to monitor and detect anomalies in your time series data with little machine learning (ML) knowledge, either batch validation or real-time inference.Getting startedPrerequisitesPython 3.7 or later is required to use this package.You need anAzure subscriptionto use this package.An existing Cognitive Services Anomaly Detector instance.Install the packagepython-mpipinstallazure-ai-anomalydetectorNote: This version of the client library defaults to the3.0.0b6version of the service.This table shows the relationship between SDK versions and supported API versions of the service:SDK versionSupported API version of service3.0.0b61.13.0.0b4, 3.0.0b51.1-preview-13.0.0b31.1-preview3.0.0b1, 3.0.0b21.0Authenticate the clientGet the endpointYou can find the endpoint for your Anomaly Detector service resource using theAzure PortalorAzure CLI:# Get the endpoint for the Anomaly Detector service resourceazcognitiveservicesaccountshow--name"resource-name"--resource-group"resource-group-name"--query"properties.endpoint"Get the API KeyYou can get theAPI Keyfrom the Anomaly Detector service resource in the Azure Portal.
Alternatively, you can useAzure CLIsnippet below to get the API key of your resource.azcognitiveservicesaccountkeyslist--resource-group<your-resource-group-name>--name<your-resource-name>Create a AnomalyDetectorClient with an API Key CredentialOnce you have the value for the API key, you can pass it as a string into an instance ofAzureKeyCredential. Use the key as the credential parameter
to authenticate the client:fromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.anomalydetectorimportAnomalyDetectorClientcredential=AzureKeyCredential("<api_key>")client=AnomalyDetectorClient(endpoint="https://<resource-name>.cognitiveservices.azure.com/",credential=credential)Key conceptsWith the Anomaly Detector, you can either detect anomalies in one variable usingUnivariate Anomaly Detection, or detect anomalies in multiple variables withMultivariate Anomaly Detection.FeatureDescriptionUnivariate Anomaly DetectionDetect anomalies in one variable, like revenue, cost, etc. The model was selected automatically based on your data pattern.Multivariate Anomaly DetectionDetect anomalies in multiple variables with correlations, which are usually gathered from equipment or other complex system. The underlying model used is Graph attention network.Univariate Anomaly DetectionThe Univariate Anomaly Detection API enables you to monitor and detect abnormalities in your time series data without having to know machine learning. The algorithms adapt by automatically identifying and applying the best-fitting models to your data, regardless of industry, scenario, or data volume. Using your time series data, the API determines boundaries for anomaly detection, expected values, and which data points are anomalies.Using the Anomaly Detector doesn't require any prior experience in machine learning, and the REST API enables you to easily integrate the service into your applications and processes.With the Univariate Anomaly Detection, you can automatically detect anomalies throughout your time series data, or as they occur in real-time.FeatureDescriptionStreaming detectionDetect anomalies in your streaming data by using previously seen data points to determine if your latest one is an anomaly. This operation generates a model using the data points you send, and determines if the target point is an anomaly. By calling the API with each new data point you generate, you can monitor your data as it's created.Batch detectionUse your time series to detect any anomalies that might exist throughout your data. This operation generates a model using your entire time series data, with each point analyzed with the same model.Change points detectionUse your time series to detect any trend change points that exist in your data. This operation generates a model using your entire time series data, with each point analyzed with the same model.Multivariate Anomaly DetectionTheMultivariate Anomaly DetectionAPIs further enable developers by easily integrating advanced AI for detecting anomalies from groups of metrics, without the need for machine learning knowledge or labeled data. Dependencies and inter-correlations between up to 300 different signals are now automatically counted as key factors. This new capability helps you to proactively protect your complex systems such as software applications, servers, factory machines, spacecraft, or even your business, from failures.With the Multivariate Anomaly Detection, you can automatically detect anomalies throughout your time series data, or as they occur in real-time. There are three processes to use Multivariate Anomaly Detection.Training: Use Train Model API to create and train a model, then use Get Model Status API to get the status and model metadata.Inference:Use Async Inference API to trigger an asynchronous inference process and use Get Inference results API to get detection results on a batch of data.You could also use Sync Inference API to trigger a detection on one timestamp every time.Other operations: List Model API and Delete Model API are supported in Multivariate Anomaly Detection model for model management.Thread safetyWe guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.ExamplesThe following section provides several code snippets covering some of the most common Anomaly Detector service tasks, including:Univariate Anomaly Detection - Batch detectionUnivariate Anomaly Detection - Streaming detectionUnivariate Anomaly Detection - Detect change pointsMultivariate Anomaly DetectionBatch detectionfromazure.ai.anomalydetectorimportAnomalyDetectorClientfromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.anomalydetector.modelsimport*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")client=AnomalyDetectorClient(ANOMALY_DETECTOR_ENDPOINT,AzureKeyCredential(SUBSCRIPTION_KEY))series=[]data_file=pd.read_csv(TIME_SERIES_DATA_PATH,header=None,encoding="utf-8",parse_dates=[0])forindex,rowindata_file.iterrows():series.append(TimeSeriesPoint(timestamp=row[0],value=row[1]))request=UnivariateDetectionOptions(series=series,granularity=TimeGranularity.DAILY,)ifany(response.is_anomaly):print("An anomaly was detected at index:")fori,valueinenumerate(response.is_anomaly):ifvalue:print(i)else:print("No anomalies were detected in the time series.")Streaming Detectionfromazure.ai.anomalydetectorimportAnomalyDetectorClientfromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.anomalydetector.modelsimport*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")client=AnomalyDetectorClient(ANOMALY_DETECTOR_ENDPOINT,AzureKeyCredential(SUBSCRIPTION_KEY))series=[]data_file=pd.read_csv(TIME_SERIES_DATA_PATH,header=None,encoding="utf-8",parse_dates=[0])forindex,rowindata_file.iterrows():series.append(TimeSeriesPoint(timestamp=row[0],value=row[1]))request=UnivariateDetectionOptions(series=series,granularity=TimeGranularity.DAILY,)print("Detecting the anomaly status of the latest data point.")ifresponse.is_anomaly:print("The latest point is detected as anomaly.")else:print("The latest point is not detected as anomaly.")Detect change pointsfromazure.ai.anomalydetectorimportAnomalyDetectorClientfromazure.core.credentialsimportAzureKeyCredentialfromazure.ai.anomalydetector.modelsimport*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")client=AnomalyDetectorClient(ANOMALY_DETECTOR_ENDPOINT,AzureKeyCredential(SUBSCRIPTION_KEY))series=[]data_file=pd.read_csv(TIME_SERIES_DATA_PATH,header=None,encoding="utf-8",parse_dates=[0])forindex,rowindata_file.iterrows():series.append(TimeSeriesPoint(timestamp=row[0],value=row[1]))request=UnivariateChangePointDetectionOptions(series=series,granularity=TimeGranularity.DAILY,)ifany(response.is_change_point):print("An change point was detected at index:")fori,valueinenumerate(response.is_change_point):ifvalue:print(i)else:print("No change point were detected in the time series.")Multivariate Anomaly Detection SampleTo see how to use Anomaly Detector library to conduct Multivariate Anomaly Detection, see thissample.To get more details of Anomaly Detector package, refer to thisazure.ai.anomalydetector package.TroubleshootingGeneralAnomaly Detector client library will raise exceptions defined inAzure Core.LoggingThis library uses the standardlogginglibrary for logging.Basic information about HTTP sessions (URLs, headers, etc.) is logged atINFOlevel.DetailedDEBUGlevel logging, including request/response bodies andunredactedheaders, can be enabled on the client or per-operation with thelogging_enablekeyword argument.See full SDK logging documentation with exampleshere.Optional ConfigurationOptional keyword arguments can be passed in at the client and per-operation level.
The azure-corereference documentationdescribes available configurations for retries, logging, transport protocols, and more.Next stepsThese code samples show common scenario operations with the Azure Anomaly Detector library. More samples can be found under thesamplesdirectory.Univariate Anomaly Detection - Batch Detection:sample_detect_entire_series_anomaly.pyUnivariate Anomaly Detection - Streaming Detection:sample_detect_last_point_anomaly.pyUnivariate Anomaly Detection - Change Point Detection:sample_detect_change_point.pyMultivariate Anomaly Detection:sample_multivariate_detect.pyAdditional documentationFor more extensive documentation on Azure Anomaly Detector, see theAnomaly Detector documentationon docs.microsoft.com.ContributingThis project welcomes contributions and suggestions. Most contributions require
you to agree to a Contributor License Agreement (CLA) declaring that you have
the right to, and actually do, grant us the rights to use your contribution.
For details, visitCLA homepage.When you submit a pull request, a CLA-bot will automatically determine whether
you need to provide a CLA and decorate the PR appropriately (e.g., label,
comment). Simply follow the instructions provided by the bot. You will only
need to do this once across all repos using our CLA.This project has adopted theMicrosoft Open Source Code of Conduct. For more information,
see the Code of Conduct FAQ or contactopencode@microsoft.comwith any
additional questions or comments.