sci-find-peaks

A Rust port of SciPy's find_peaks function, designed to match SciPy's behavior exactly.

Overview

This crate provides a signal processing utility for finding peaks in 1D data. It is a direct port of the scipy.signal.find_peaks function from the SciPy library.

Why use this crate?

• Exact Parity: If you are porting Python code to Rust and need your peak detection to behave exactly like SciPy (down to floating point comparisons and edge cases), this is the crate for you.
• Performance: Written in pure Rust, offering the safety and performance benefits of the language.
• Familiar API: The FindPeaksOptions struct mirrors the arguments of the Python function (height, threshold, distance, prominence, width, etc.).

Features

• Find Local Maxima: Efficiently identifies local peaks in 1D arrays.
• Filter by Height: Select peaks based on absolute height properties.
• Filter by Threshold: Select peaks based on vertical distance to immediate neighbors.
• Filter by Distance: Enforce minimum horizontal distance between peaks.
• Filter by Prominence: Calculate and filter by topographic prominence.
• Filter by Width: Calculate and filter by peak width (at relative heights).
• Plateau Detection: Correctly handles flat tops (plateaus) in signals.

Installation

Add this to your Cargo.toml:

[dependencies]
sci-find-peaks = "0.1.0"

Usage

Here is a simple example of how to use the library:

use sci_find_peaks::{find_peaks, FindPeaksOptions};

fn main() {
    // 1. Define your signal
    let x = vec![0.0, 1.0, 0.0, 2.0, 0.0, 3.0, 0.0, 2.0, 0.0, 1.0, 0.0];

    // 2. Configure options (mimics scipy.signal.find_peaks arguments)
    let options = FindPeaksOptions {
        height: Some((Some(1.0), None)), // Min height of 1.0
        distance: Some(2),               // Min distance of 2 samples
        ..FindPeaksOptions::default()
    };

    // 3. Run the algorithm
    let result = find_peaks(&x, &options).unwrap();

    // 4. Access results
    println!("Found {} peaks at indices: {:?}", result.peaks.len(), result.peaks);
    
    if let Some(heights) = result.properties.peak_heights {
        println!("Peak heights: {:?}", heights);
    }
}

Visualization Example

To see the library in action and verify the output visually, you can run the included example which generates a plot using the plotters crate.

1. Clone the repository.
2. Run the example:

cargo run --example visualize

This will generate a file named peaks_plot.png showing the signal, detected peaks, and calculated widths.

License

This project is licensed under the MIT License.