SFC Manual

Anomaly Detection

Time Series Anomaly Detection Architecture: Technical Summary 

Core Detection Logic 

The Anomaly Finder for Seasonal Data coordinates anomaly detection in time series data using a set of pluggable Anomaly Data Providers and an Anomaly Detection Service based on ML.NET. Providers supply domain-specific time series data, which is analysed for anomalies (seasonality, change points, spikes) according to configurable settings.  
Results are post-processed, filtered, and cached for efficient retrieval. 
Data Providers can be Presence/Absence, Time Reported, Breaks Reported, Earnings made, Efficiency ... 

API Layer 

The API exposes the anomaly detection functionality via a Web API: 

Get Anomalies Found: 
Accepts parameters to specify single user or All and optionally reset the cache. It instantiates an Anomaly Finder for Seasonal Data, adds the relevant providers, and returns the detected anomalies for the requested scope. 

Get Anomaly Counts Found: 
Returns the count of cached anomalies for a given user or key. 

Get / Update Settings: 
Allows clients to retrieve or update the anomaly detection settings, enabling runtime configuration of detection parameters. 

This controller enables external systems (e.g., frontend dashboards) to query for anomaly results and manage detection settings. 

Background Processing Job 

The Job is a Quartz.NET job that runs anomaly detection in the background on a schedule: 

It checks if anomaly detection is enabled via a database setting. 

If enabled, it creates an Anomaly Finder for Seasonal Data instance, adds providers, and triggers a cache update. 

This job ensures that anomaly detection results are kept up to date in the background, so API queries can return results quickly from cache without recalculating. 

User Interface: Insight Dialog 

The Insight Dialog provides the user interface for presenting anomaly insights to authenticated users in a time series graph interface: 

Floating Action Button (FAB): 
A Kendo UI Floating Action Button displays the current anomaly count found (fetched from the API) and opens the insight dialog when clicked. 

Insight Dialog Window: 
When opened, the dialog fetches anomaly findings from the API and displays them in a Kendo UI chart, allowing users to visualize anomalies over time. 

Navigation: 
Users can step through different insights using "Prev", "Next", "Prev Type", and "Next Type" buttons, viewing details for each anomaly finding. 

Details and Drilldown: 
Clicking on chart notes or data points opens detailed views of the underlying data (e.g., user details for a specific date range) in a new tab. 

Overview/Details Toggle: 
Users can switch between an overview of all insights and detailed views for a specific user or key. 

This UI component provides an interactive and user-friendly way for users to review, explore, and drill into detected anomalies, supporting both high-level monitoring and detailed investigation. 

Summary: 

AnomalyFinderInSeasonalData handles the detection logic and caching. 

AnomalyController provides API endpoints for querying and configuring anomaly detection. 

AnomalyFinderJob keeps anomaly results fresh by running detection on a schedule in the background. 

_InsightDialog presents anomaly insights to users, allowing them to step through findings, visualize anomalies, and drill into the underlying data for further analysis. 

This architecture separates detection, API access, background processing, and user presentation, supporting scalability, configurability, and efficient, actionable insight delivery. 

User Configuration 

The UI provides a settings dialog that allows users to customize the anomaly detection process. This dialog is accessible from the main insight dialog and interacts with the backend via the API. 

Configurable Settings: 

Types to Detect (typesToDetect): 
Users can select which types of anomalies to detect: Spikes, Change Points, and Seasonality. This determines which detection algorithms are run in AnomalyFinderInSeasonalData. 

Data Providers (dataProviders): 
Users can enable or disable specific data providers (e.g., UserCountPerDayProvider, UserTimePerDayProvider, etc.). Only the selected providers will be used to supply data for anomaly detection, allowing users to focus on relevant metrics. 

Training Days (trainDays): 
Specifies the historical window (in days) used to train the anomaly detection models. A longer window may improve detection accuracy for seasonal patterns but could reduce sensitivity to recent changes. 

Detection Days (detectDays): 
Sets the number of recent days to scan for anomalies. Only anomalies detected within this window are considered for presentation, helping users focus on the most recent and actionable insights. 

Presentation Days (showDays): 
Controls how many days of data are shown in the insight dialog charts, providing context around detected anomalies. 

Seasonality Sensitivity (seasonalitySensitivity): 
Adjusts the sensitivity of the seasonality anomaly detector. Higher values make the detector more responsive to subtle seasonal changes, while lower values reduce sensitivity. 

Seasonality Threshold (seasonalityThreshold): 
Sets the threshold for what is considered a significant seasonal anomaly. Lower thresholds may result in more anomalies being flagged. 

Spike Detection Confidence (spikeDetectionConfidence): 
Defines the statistical confidence level for spike detection. Higher confidence reduces false positives but may miss subtle spikes. 

Spike Detection Value History (spikeDetectionValueHistory): 
Determines the window size (number of past values) used to compute the baseline for spike detection. 

Effect on Anomaly Finder for Seasonal Data: 

When a user updates these settings, they are saved via the API and immediately affect how Anomaly Finder operates: 

The selected types and providers directly control which detection routines and data sources are used. 

Training, detection, and presentation windows define the time spans for model training, anomaly search, and chart display. 

Sensitivity, threshold, and confidence parameters are passed to the underlying ML.NET detection algorithms, tuning their behaviour for the user’s needs. 

Only findings matching the current settings (e.g., within the detection window, from enabled providers, and of selected types) are included in the results and shown in the UI. 

This user-driven configuration ensures that anomaly detection is both flexible and relevant, empowering users to tailor the system to their operational context and investigative needs. 

Strategies 

Have tried to separate the ML.Net dependency to a single class/interface to be able to exchange if needed. 

Also separated the domain specific code into providers that can be added, changed or removed. 

Experiences 

The ML code is only 10% of this implementation, the rest is stuff around it to be able to experiment, configure, display and explain findings. 

Data from one customer to another is very different even though in the same domain which makes it hard to know what to expect from the ML models. 

Data must be prepared to make sense to time series models. 

Anomaly findings must be washed with traditional logic in some cases. I have added that domain knowledge responsibility to the provider of the data. 

It is very tempting to add analysers that use “normal” domain knowledge to create findings instead. We have not done that so far to stick with generic ML. 

Created with the Personal Edition of HelpNDoc: Streamline your documentation process with HelpNDoc's WinHelp HLP to CHM conversion feature