libspot

A safe Rust wrapper(using FFI) for the libspot time series anomaly detection library.

Installation

cargo add libspot

Quick Start

use libspot::{SpotDetector, SpotConfig, SpotStatus};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create detector with default configuration
    let config = SpotConfig::default();
    let mut detector = SpotDetector::new(config)?;

    // Fit with training data (normal distribution around 5.0)
    let training_data: Vec<f64> = (0..1000)
        .map(|i| 5.0 + (i as f64 * 0.01).sin() * 2.0)
        .collect();
    detector.fit(&training_data)?;

    // Detect anomalies in real-time
    let test_value = 50.0; // This should be an anomaly
    match detector.step(test_value)? {
        SpotStatus::Normal => println!("Normal data point"),
        SpotStatus::Excess => println!("In the tail distribution"),
        SpotStatus::Anomaly => println!("Anomaly detected! 🚨"),
    }

    Ok(())
}

Examples

See the examples directory for more usage examples. You can run the examples with cargo run --example <example_name>:

cargo run --example simple
cargo run --example basic

Correctness & Performance

This wrapper provides identical results to the original C implementation. The basic.rs example processes 50M samples and produces the exact same anomaly counts and thresholds as the reference basic.c implementation:

We run the benchmark with:

• Rust: cargo run -r --example basic(with -r flag to run the example in release mode).
• C: cc -O3 -o /tmp/basic examples/basic.c -Idist/ -Ldist/ -l:libspot.so.2.0b5 -lm && LD_LIBRARY_PATH=dist /tmp/basic(with -O3 flag to compile the example in release mode).

As you can see, the performance is very close. You may get different results due to the different hardware and environment, but the results should be very similar.

License

This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0) to comply with the underlying libspot C library license.

Alternative

For a pure Rust implementation without FFI dependencies, see the libspot-rs crate.