{"id":6494,"library":"adtk","title":"Anomaly Detection Toolkit (ADTK)","description":"ADTK (Anomaly Detection Toolkit) is a Python package designed for unsupervised and rule-based time series anomaly detection. It provides a modular and intuitive API, offering a collection of common detectors, transformers, and aggregators that can be combined into custom anomaly detection pipelines. Currently at version 0.6.2, ADTK aims to help users build effective models even with limited labeled historical anomaly data, with regular updates and maintenance.","status":"active","version":"0.6.2","language":"en","source_language":"en","source_url":"https://github.com/arundo/adtk","tags":["anomaly detection","time series","unsupervised learning","data science","machine learning","python"],"install":[{"cmd":"pip install adtk","lang":"bash","label":"Install latest stable version"}],"dependencies":[{"reason":"Numerical operations","package":"numpy","optional":false},{"reason":"Time series data structures and manipulation","package":"pandas","optional":false},{"reason":"Visualization","package":"matplotlib","optional":false},{"reason":"Machine learning utilities","package":"scikit-learn","optional":false},{"reason":"Statistical models, including seasonal decomposition","package":"statsmodels","optional":false},{"reason":"Dependency management utility","package":"packaging","optional":false},{"reason":"Table formatting for output","package":"tabulate","optional":false}],"imports":[{"symbol":"validate_series","correct":"from adtk.data import validate_series"},{"note":"The `plot` API was redesigned in v0.6, removing the `plot_anomalies` alias. Use `adtk.visualization.plot` directly.","wrong":"from adtk.visualization import plot_anomalies","symbol":"plot","correct":"from adtk.visualization import plot"},{"note":"As of v0.6, all second-order sub-modules were made private. Import directly from top-level modules like `adtk.detector`, `adtk.transformer`, etc.","wrong":"from adtk.detector.seasonal import SeasonalAD","symbol":"SeasonalAD","correct":"from adtk.detector import SeasonalAD"},{"note":"As of v0.6, all second-order sub-modules were made private. Import directly from top-level modules like `adtk.detector`, `adtk.transformer`, etc.","wrong":"from adtk.transformer.seasonal import ClassicSeasonalDecomposition","symbol":"ClassicSeasonalDecomposition","correct":"from adtk.transformer import ClassicSeasonalDecomposition"}],"quickstart":{"code":"import pandas as pd\nfrom adtk.data import validate_series\nfrom adtk.detector import SeasonalAD\nfrom adtk.visualization import plot\n\n# Create a dummy time series with a seasonal pattern and an anomaly\nindex = pd.date_range(start='2023-01-01', periods=100, freq='H')\ndata = [i % 24 for i in range(100)] # Daily seasonality\ndata[50:55] = [50, 51, 52, 53, 54] # Introduce an anomaly\ns_train = pd.Series(data, index=index)\n\n# Validate the series (important for ADTK compatibility)\ns_train = validate_series(s_train)\n\n# Initialize and train a SeasonalAD detector\n# freq can be 'H' for hourly, 'D' for daily, etc., based on data frequency.\n# c is a sensitivity parameter for anomaly detection.\nseasonal_ad = SeasonalAD(freq=24, c=3.0)\n\n# Fit the detector to the training data and detect anomalies\nanomalies = seasonal_ad.fit_detect(s_train)\n\n# Plot the time series with detected anomalies\nplot(s_train, anomaly=anomalies, ts_linewidth=1, anomaly_markersize=5, anomaly_color='red', anomaly_tag='marker')\n\nprint(\"Detected anomalies:\")\nprint(anomalies[anomalies].index)","lang":"python","description":"This quickstart demonstrates how to use `adtk` to detect seasonal anomalies in a synthetic time series. It involves validating the input series, initializing a `SeasonalAD` detector, fitting it to the data, detecting anomalies, and visualizing the results. Note that for real-world scenarios, you would load your data (e.g., `pd.read_csv`), ensure it has a `DatetimeIndex`, and choose appropriate detector parameters based on your data's characteristics and anomaly types."},"warnings":[{"fix":"Review the official documentation for `adtk.visualization.plot` and update calls accordingly. Replace usage of `adtk.data.resample` with `pandas.DataFrame.resample`. Adjust calls to `adtk.data.split_train_test` for the new output type. Ensure all required parameters are provided to detectors/transformers. Update import statements to directly import from `adtk.detector`, `adtk.transformer`, `adtk.aggregator`, etc.","message":"The API for `adtk.visualization.plot` was redesigned in v0.6. The `adtk.data.resample` module was removed, and the output type of `adtk.data.split_train_test` changed. Several model parameters (e.g., `window` in `LevelShiftAD`, `model` in `MinClusterDetector`) became required instead of optional. Additionally, all second-order sub-modules were made private, requiring imports directly from top-level modules (e.g., `from adtk.detector import SomeDetector`).","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"For `Pipenet`, update the `steps` parameter from a list of steps to a dictionary mapping step names to transformer/detector instances. If using `STL decomposition`, refactor to use `ClassicSeasonalDecomposition` and adjust `SeasonalAD` configurations if necessary.","message":"In v0.5, the `steps` parameter of `adtk.pipe.Pipenet` changed from accepting a list to requiring a dictionary. The `STL decomposition transformer` was removed and replaced with a `ClassicSeasonalDecomposition` transformer, which also affects the `SeasonalAD` detector's options.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"Always pass your time series data through `adtk.data.validate_series()` before using ADTK components. Ensure your `DatetimeIndex` is sorted, free of `NaN`s, and has a consistent frequency or handle these cases explicitly beforehand using pandas utilities.","message":"ADTK requires time series data to be in a specific format: a pandas Series with a `DatetimeIndex`, sorted, without `NaN` values, and with a regular frequency. Not adhering to this format or failing to use `adtk.data.validate_series` can lead to unexpected errors or incorrect anomaly detection results.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If experiencing `statsmodels` related issues with `adtk` versions prior to 0.6.0, either upgrade `adtk` to 0.6.0 or later, or pin your `statsmodels` dependency to a version less than 0.11 (e.g., `statsmodels==0.10.2`).","message":"Version 0.5.3 introduced a temporary requirement for `statsmodels <0.11` to avoid errors. While v0.6.0 later fixed compatibility issues with `statsmodels v0.11`, users on older `adtk` versions (between v0.5.3 and v0.5.5, or potentially older than v0.5.3 without specific fixes) might encounter issues with newer `statsmodels` versions.","severity":"gotcha","affected_versions":"<0.6.0 (specifically v0.5.3 to v0.5.5)"},{"fix":"Familiarize yourself with the different anomaly types described in the ADTK documentation and select the relevant `adtk.detector` and `adtk.transformer` components that address your specific use case. ADTK provides a flexible toolkit, not an automated solution.","message":"ADTK is designed for unsupervised/rule-based anomaly detection and does not automatically select or build an anomaly detection model. Users must understand the specific type of anomaly they want to detect (e.g., outlier, spike, level shift, seasonal pattern violation) and combine the appropriate detectors, transformers, and aggregators to build their model.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Install the 'adtk' package using pip: 'pip install adtk'.","cause":"This error occurs when the 'adtk' package is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'adtk'"},{"fix":"Ensure that the function name is correct and exists in the 'adtk' module. Refer to the official documentation for the correct import statements.","cause":"This error occurs when attempting to import a function that does not exist in the 'adtk' module.","error":"ImportError: cannot import name 'validate_series' from 'adtk'"},{"fix":"Check the function's return value to ensure it is not None before attempting to subscript it.","cause":"This error occurs when attempting to subscript a 'NoneType' object, often due to a function returning None instead of an expected iterable.","error":"TypeError: 'NoneType' object is not subscriptable"},{"fix":"Sort the time series data by its index to ensure it is monotonically increasing before processing.","cause":"This error occurs when the time index of the time series data is not in a strictly increasing order.","error":"ValueError: Time index is not monotonically increasing"},{"fix":"Verify the correct attribute or class name in the 'adtk' module by consulting the official documentation.","cause":"This error occurs when trying to access an attribute or class that does not exist in the 'adtk' module.","error":"AttributeError: module 'adtk' has no attribute 'Detector'"}]}