PulseAD
Forecast-based deviation detection. Uses GradientCastFM internally to predict expected values and flags significant deviations in real-time.
What is PulseAD?
PulseAD is a forecast-based anomaly detector. It uses GradientCastFM internally to predict what values should look like, then flags data points that deviate significantly from those predictions.
The detection logic is simple but powerful: an anomaly is flagged when both the percentage deviation exceeds a threshold AND the absolute value exceeds a minimum. This dual-threshold approach reduces false positives from noisy low-volume metrics.
PulseAD is ideal for monitoring metrics with regular patterns where you want to catch sudden drops or spikes that indicate problems.
How It Works
anomaly = (percent_delta > threshold) AND (value > minimum)Features
Configurable Thresholds
Set percentage deviation and minimum value thresholds to match your metric characteristics. Balance sensitivity with false positive reduction.
Per-Dimension Overrides
Different metrics need different thresholds. Set stricter limits for critical metrics and relaxed limits for volatile ones.
Multi-Metric Monitoring
Monitor multiple metrics in a single API call. Each dimension is evaluated independently with its own threshold configuration.
Real-Time Detection
Low-latency detection suitable for real-time monitoring. Pass a sliding window of data and get instant anomaly alerts.
Detailed Results
Get actual vs predicted values, deviation percentages, and which threshold triggered. Full context for investigation.
Pandas Integration
Results can be converted to DataFrames for easy analysis and visualization. Seamless integration with data workflows.
Code Examples
from gradientcast import GradientCastPulseAD
ad = GradientCastPulseAD(api_key="your-api-key")
result = ad.detect(
time_series_data={
"user_count": [
{"timestamp": "01/01/2025, 12:00 AM", "value": 1500000.0},
{"timestamp": "01/01/2025, 01:00 AM", "value": 1520000.0},
{"timestamp": "01/01/2025, 02:00 AM", "value": 1480000.0},
{"timestamp": "01/01/2025, 03:00 AM", "value": 1510000.0},
{"timestamp": "01/01/2025, 04:00 AM", "value": 1530000.0},
{"timestamp": "01/01/2025, 05:00 AM", "value": 800000.0}, # Anomaly!
]
}
)
if result.has_anomaly:
for anomaly in result.anomalies:
print(f"{anomaly.dimension}: {anomaly.percent_delta} deviation")
print(f" Actual: {anomaly.actual_value}, Predicted: {anomaly.predicted_value}")Best For
- Metrics with regular, predictable patterns
- Detecting sudden drops or spikes
- Threshold-based alerting systems
- High-volume metrics (user counts, requests)
- Service health monitoring
- Revenue and transaction monitoring
PulseAD vs DenseAD
| Feature | PulseAD | DenseAD |
|---|---|---|
| Detection Method | Forecast-based deviation | Pattern-based density |
| Best For | Sudden drops/spikes | Complex pattern anomalies |
| Thresholds | Explicit (you configure) | Learned (contamination rate) |
| Severity Levels | Binary (anomaly/not) | Low/Medium/High/Critical |
| Data Requirements | 10+ points | 25+ points |
| Latency | Lower (uses FM) | Very low (no FM call) |