dsgbr 0.5.0

Dual Savitzky-Golay Baseline Ratio (DSGBR) detects spectral peaks in frequency-domain signals. It is built for dense, noisy power spectra from fluid dynamics, vibration analysis, and related experimental work, where spectra slope over several decades and a fixed prominence threshold either drowns in low-frequency power or misses everything at high frequency.

A ten-harmonic frequency comb in a noisy, sloped synthetic spectrum: all ten harmonics recovered with the default detector parameters, and no detections away from the comb. The weakest harmonics barely clear the noise scatter, and the comb crowds together on the log axis — both regimes where fixed-threshold detectors merge or miss peaks. Generated by examples/readme_figure.py.

Install

pip install dsgbr

For development:

git clone https://github.com/openfluids/dsgbr.git
cd dsgbr
uv pip install -e ".[dev]"

Quick start

import numpy as np
from dsgbr import dsgbr_detector

# Synthetic PSD with known peaks
frequencies = np.linspace(0.001, 1.0, 2048)
psd = np.ones_like(frequencies)
psd[400] = 12.0  # inject a peak
psd[1200] = 8.0  # inject another

peak_f, peak_h = dsgbr_detector(frequencies, psd)
print(f"Detected {peak_f.size} peaks at f = {peak_f}")

The defaults find both peaks. To tune, pass a case_info dictionary with full names or short aliases:

peak_f, peak_h = dsgbr_detector(frequencies, psd, case_info={"RT": 2.5, "SW": 5})

How it works

DSGBR compares the spectrum against a local estimate of its own background, so acceptance is a ratio rather than an absolute height: a peak three times above its surroundings is detected the same way at any frequency, regardless of the slope between them.

flowchart TD
    PSD(["PSD P(f)"]) --> SEARCH["SEARCH
    narrow Savitzky-Golay smooth"]
    PSD --> BASELINE["BASELINE
    wide rolling median"]
    SEARCH --> RATIO{"SEARCH / BASELINE
    ≥ ratio_threshold ?"}
    BASELINE --> RATIO
    RATIO --> SPACING["greedy spacing selection
    (strongest first)"]
    SPACING --> REFINE["refine to raw-PSD maxima"]
    REFINE --> ULF["ultra-low-frequency
    Q-factor guardrail"]
    ULF --> BANDS["band-balanced selection
    (if > max_peaks)"]
    BANDS --> OUT(["peak_frequencies, peak_heights"])

The two series are deliberately different estimators: SEARCH is a narrow Savitzky-Golay smooth that suppresses single-bin noise while keeping peak shapes, and BASELINE is a wide rolling median of the raw PSD, which sits under narrow peaks instead of being dragged up by them. Accepted candidates then pass spacing rules, are repositioned onto the raw PSD, and survive an ultra-low-frequency guardrail that rejects broad leakage bumps near the left edge of the spectrum. The full pipeline, design rationale, and parameter sensitivity study are in docs/algorithm.md.

Validation

Fresh run: uv run python -m benchmarks.compare, 20 evaluation realizations per scenario after per-scenario tuning of scipy.signal.find_peaks on 8 training realizations.

DSGBR leads on the sloped, dense, and noisy scenarios above; parity is expected for flat, well-separated peaks such as clean_tones, and both detectors return no F1 credit on no_peaks. See docs/algorithm.md Parameter sensitivity and benchmarks/ for reproduction.

Configuration

All parameters are set through DetectionConfig or passed as a dictionary via the case_info argument. Short aliases (RT, SW, BWF, etc.) are supported for concise configuration.

Advanced usage

Support series for visualization

from dsgbr import compute_support_series

support = compute_support_series(frequencies, psd, case_info={"RT": 2.0})

# Plot SEARCH vs BASELINE overlay
import matplotlib.pyplot as plt
plt.semilogy(frequencies, support["search_series"], label="SEARCH")
plt.semilogy(frequencies, support["baseline_series"], label="BASELINE")
plt.semilogy(frequencies, support["rthreshold"], "--", label="Threshold")
plt.legend()
plt.show()

Band-balanced peak selection

from dsgbr import select_peaks_by_frequency_bands

# Reduce 100 peaks to 15, spread across frequency bands
sel_f, sel_h = select_peaks_by_frequency_bands(
    peak_frequencies, peak_heights,
    max_peaks=15, strategy="proportional", n_bands=8,
)

Configuration via dataclass

from dsgbr import DetectionConfig

cfg = DetectionConfig(ratio_threshold=2.5, smooth_window=7, max_peaks=10)
print(cfg.to_metadata())

API reference

Examples

See examples/ for runnable scripts:

• basic_usage.py — minimal detection example
• parameter_tuning.py — sweep ratio_threshold, compare peak counts
• visualization.py — SEARCH/BASELINE overlay plot
• readme_figure.py — regenerate the figure at the top of this page

Citation

If you use DSGBR in your research, please cite:

@software{dsgbr2026,
  author = {Frantz, Ricardo},
  title = {{DSGBR}: Dual Savitzky--Golay Baseline Ratio spectral peak detector},
  year = {2026},
  url = {https://github.com/openfluids/dsgbr},
}

License

This project is licensed under Apache-2.0.

As of v0.5.0, this project is licensed under Apache-2.0. Earlier releases remain available under the BSD 3-Clause license that applied at the time of release.

Originally developed by Ricardo A S Frantz. See LICENSE and NOTICE for license terms and attribution notices.

Contributing

Contributions are welcome. Please open an issue to discuss changes before submitting a pull request. Run the full QA suite before submitting:

uv pip install -e ".[dev]"
pre-commit run --all-files
pytest --cov=dsgbr