README

PHP library for real-time feature detection on sensor data streams. Computes statistical features from raw measurements and applies a suite of detectors to identify trends, anomalies, process shifts, and sensor health issues.

Requirements

PHP 8.4+

Installation

composer require edgetelemetrics/advanced-analytics

Usage

Computing Features

FeatureCalculator computes rolling statistics, regression, EMA, and control limits from raw values:

use EdgeTelemetrics\AdvancedAnalytics\FeatureCalculator;

$calc = new FeatureCalculator();

// Feed measurements one at a time
$features = $calc->compute(20.15);
// Returns: ['raw' => 20.15, 'sma3' => ..., 'mean24h' => ..., 'regression_slope' => ..., ...]

Running Detectors

Each detector implements DetectorInterface and receives a FeatureVector:

use EdgeTelemetrics\AdvancedAnalytics\Features\FeatureVector;
use EdgeTelemetrics\AdvancedAnalytics\Detector\TrendDetector;

$detector = new TrendDetector();

$features['sensor_id'] = 'sensor-1';
$features['datetime'] = '2025-03-01T00:00:00Z';
$features['regression_slope'] = 0.15;
$features['regression_r2'] = 0.85;
$features['direction'] = 1;
$features['stddev'] = 0.5;

$findings = $detector->process(new FeatureVector($features));

foreach ($findings as $finding) {
    echo $finding->getFinding() . ': ' . $finding->getState()->value;
    // "trending_up: pending"
}

Processing a Stream

use EdgeTelemetrics\AdvancedAnalytics\FeatureCalculator;
use EdgeTelemetrics\AdvancedAnalytics\Detector\{EWMADetector, CUSUMDetector, SpikeDetector};

$calc = new FeatureCalculator();
$detectors = [new EWMADetector(), new CUSUMDetector(), new SpikeDetector()];

foreach ($measurements as $m) {
    $features = $calc->compute($m['value']);
    $features['sensor_id'] = $m['sensor_id'];
    $features['datetime'] = $m['datetime'];

    $vector = new FeatureVector($features);

    foreach ($detectors as $detector) {
        foreach ($detector->process($vector) as $finding) {
            // handle finding
        }
    }
}

Detectors

Detector	Detects
`TrendDetector`	Sustained upward/downward trends
`NelsonRulesDetector`	Statistical process control violations (8 Nelson rules)
`EWMADetector`	Subtle process shifts via exponentially weighted moving average
`CUSUMDetector`	Small persistent shifts via cumulative sums
`DriftDetector`	Long-term baseline movement
`SpikeDetector`	Isolated abnormal samples
`StepDetector`	Sudden permanent level changes
`NoiseDetector`	Signal instability / failing probes
`ForecastResidualDetector`	Deviations from linear forecast
`SensorHealthDetector`	Sample gaps, flatlines, stuck sensors

Architecture

Raw Measurements
       |
FeatureCalculator  (rolling stats, regression, EMA, control limits)
       |
  FeatureVector
       |
  Detectors  →  AnalyticalFinding[]

Each detector is stateless or maintains minimal internal state (rolling buffers, accumulators). Detectors declare which features they need via requires().

See architecture/detectors.md for the full pipeline design (behaviour, process, and diagnosis layers).

Testing

composer install
vendor/bin/phpunit

edgetelemetrics / advanced-analytics

Maintainers

Package info

Statistics

Security