Install & Compatibility
Where this runs
tested against v0.6.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 19.8s · import 0.891s · 476MB
497MB installed
● package 497MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
validate_series
✓ from adtk.data import validate_series
plot
✓ from adtk.visualization import plot
✗ from adtk.visualization import plot_anomalies
The `plot` API was redesigned in v0.6, removing the `plot_anomalies` alias. Use `adtk.visualization.plot` directly.
SeasonalAD
✓ from adtk.detector import SeasonalAD
✗ from adtk.detector.seasonal import SeasonalAD
As of v0.6, all second-order sub-modules were made private. Import directly from top-level modules like `adtk.detector`, `adtk.transformer`, etc.
ClassicSeasonalDecomposition
✓ from adtk.transformer import ClassicSeasonalDecomposition
✗ from adtk.transformer.seasonal import ClassicSeasonalDecomposition
As of v0.6, all second-order sub-modules were made private. Import directly from top-level modules like `adtk.detector`, `adtk.transformer`, etc.
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.
import pandas as pd
from adtk.data import validate_series
from adtk.detector import SeasonalAD
from adtk.visualization import plot
# Create a dummy time series with a seasonal pattern and an anomaly
index = pd.date_range(start='2023-01-01', periods=100, freq='H')
data = [i % 24 for i in range(100)] # Daily seasonality
data[50:55] = [50, 51, 52, 53, 54] # Introduce an anomaly
s_train = pd.Series(data, index=index)
# Validate the series (important for ADTK compatibility)
s_train = validate_series(s_train)
# Initialize and train a SeasonalAD detector
# freq can be 'H' for hourly, 'D' for daily, etc., based on data frequency.
# c is a sensitivity parameter for anomaly detection.
seasonal_ad = SeasonalAD(freq=24, c=3.0)
# Fit the detector to the training data and detect anomalies
anomalies = seasonal_ad.fit_detect(s_train)
# Plot the time series with detected anomalies
plot(s_train, anomaly=anomalies, ts_linewidth=1, anomaly_markersize=5, anomaly_color='red', anomaly_tag='marker')
print("Detected anomalies:")
print(anomalies[anomalies].index)
Debug
Known issues
breakingThe 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`).fixReview 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.
affects: >=0.6.0
breakingIn 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.fixFor `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.
affects: >=0.5.0
gotchaADTK 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.fixAlways 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.
affects: All versions
gotchaVersion 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.fixIf 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`).
affects: <0.6.0 (specifically v0.5.3 to v0.5.5)
gotchaADTK 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.fixFamiliarize 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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'adtk'
This error occurs when the 'adtk' package is not installed in the Python environment.
fixInstall the 'adtk' package using pip: 'pip install adtk'.
ImportError: cannot import name 'validate_series' from 'adtk'
This error occurs when attempting to import a function that does not exist in the 'adtk' module.
fixEnsure that the function name is correct and exists in the 'adtk' module. Refer to the official documentation for the correct import statements.
TypeError: 'NoneType' object is not subscriptable
This error occurs when attempting to subscript a 'NoneType' object, often due to a function returning None instead of an expected iterable.
fixCheck the function's return value to ensure it is not None before attempting to subscript it.
ValueError: Time index is not monotonically increasing
This error occurs when the time index of the time series data is not in a strictly increasing order.
fixSort the time series data by its index to ensure it is monotonically increasing before processing.
AttributeError: module 'adtk' has no attribute 'Detector'
This error occurs when trying to access an attribute or class that does not exist in the 'adtk' module.
fixVerify the correct attribute or class name in the 'adtk' module by consulting the official documentation.
Upgrade
Version history
0.6.2latest on PyPI · released Apr 17, 2020
Audit
Dependencies
numpyrequiredNumerical operations
pandasrequiredTime series data structures and manipulation
matplotlibrequiredVisualization
scikit-learnrequiredMachine learning utilities
statsmodelsrequiredStatistical models, including seasonal decomposition
packagingrequiredDependency management utility
tabulaterequiredTable formatting for output