bluepebble.detector

Public detector algorithms, detector metrics helpers, and passive sonar detector entrypoints.

Detector package public API.

class bluepebble.detector.CACFARDetector(num_guard_cells, num_training_cells, threshold_factor, mode='wrap')[source]

Detects signals using a Constant False Alarm Rate (CFAR) algorithm.

This detector adapts its threshold by estimating the noise level from surrounding data cells. For each Cell Under Test (CUT), it calculates the mean of the training cells and multiplies it by a threshold factor to set the detection threshold.

This implementation is a Cell-Averaging CFAR (CA-CFAR).

Variables:

  • num_guard_cells (int) – The number of cells to ignore on each side of the Cell Under Test (CUT). These cells are ignored to prevent signal leakage from the CUT into the noise estimate.

  • num_training_cells (int) – The number of cells to use for noise estimation on each side of the guard cells.

  • threshold_factor (float) – A scaling factor (alpha) used to set the detection threshold above the estimated noise floor.

  • mode (str) – The convolution mode for boundary handling. Can be ‘valid’, ‘same’, or ‘wrap’. Defaults to ‘wrap’.

Parameters:

  • num_guard_cells (int)

  • num_training_cells (int)

  • threshold_factor (float)

  • mode (str)

num_guard_cells: int

The number of cells to ignore on each side of the Cell Under Test (CUT). These cells are ignored to prevent signal leakage from the CUT into the noise estimate

num_training_cells: int

The number of cells to use for noise estimation on each side of the guard cells

threshold_factor: float

A scaling factor (alpha) used to set the detection threshold above the estimatednoise floor

mode: str

The convolution mode for boundary handling (‘valid’, ‘same’, or ‘wrap’)

detect(data)[source]

Detect signals in the data array using the CFAR algorithm.

This method applies the Cell-Averaging CFAR (CA-CFAR) algorithm. It assumes the input data is in decibels (dB) and converts it to linear power for processing, as the averaging is performed on power values.

Parameters:

data (ArrayLike) – One-dimensional signal data (for example SNR) in decibels.

Returns:

Detection matrix of shape (N, 2) with columns [detection_index, detection_value_db]. Returns an empty (0, 2) matrix when no detections are found.

Return type:

DetectionArray

class bluepebble.detector.DetectionAlgorithm[source]

Abstract base class for all detector types.

abstractmethod detect(data)[source]

Detect signals in the data array.

Parameters:

data (ArrayLike) – One-dimensional numeric data to process.

Returns:

Detection matrix of shape (N, 2) with columns [detection_index, detection_value]. Returns an empty (0, 2) matrix when no detections are found.

Return type:

DetectionArray

class bluepebble.detector.OSCFARDetector(num_guard_cells, num_training_cells, rank=1, threshold_factor=1.0)[source]

Detects signals using an Ordered-Statistic (OS) CFAR algorithm.

This detector is more robust to multi-target situations than CA-CFAR. It estimates the noise level by sorting the values in the training cells and selecting the k-th smallest value (the ‘rank’). This value is then scaled by the threshold factor to set the detection threshold.

This implementation uses a ‘wrap’ mode for boundary handling, consistent with the ‘wrap’ mode in the CA-CFAR detector.

Variables:

  • num_guard_cells (int) – The number of cells to ignore on each side of the Cell Under Test (CUT).

  • num_training_cells (int) – The number of cells to use for noise estimation on each side of the guard cells.

  • rank (int) – The k-th smallest value (1-indexed) to select from the sorted training cells. Must be between 1 and (2 * num_training_cells).

  • threshold_factor (float) – A scaling factor (alpha) used to set the detection threshold above the estimated noise floor.

Parameters:

  • num_guard_cells (int)

  • num_training_cells (int)

  • rank (int)

  • threshold_factor (float)

num_guard_cells: int

The number of cells to ignore on each side of the Cell Under Test (CUT).

num_training_cells: int

The number of cells to use for noise estimation on each side of the guard cells.

rank: int

The k-th smallest value (1-indexed) to select from the sorted training cells. Must be between 1 and (2 * num_training_cells).

threshold_factor: float

A scaling factor (alpha) to apply to the k-th rank value.

detect(data)[source]

Detect signals in the data array using the OS-CFAR algorithm.

This method applies the OS-CFAR algorithm. It assumes the input data is in decibels (dB) and converts it to linear power for processing, as the sorting is performed on power values.

Parameters:

data (ArrayLike) – One-dimensional signal data (for example SNR) in decibels.

Returns:

Detection matrix of shape (N, 2) with columns [detection_index, detection_value_db]. Returns an empty (0, 2) matrix when no detections are found.

Return type:

DetectionArray

class bluepebble.detector.PeakDetector(distance=1)[source]

Finds local maxima (peaks) in a 1D data array.

This class is a wrapper around the scipy.signal.find_peaks function, providing a simple interface for peak detection. It identifies peaks that are separated by a specified minimum distance.

Variables:

distance (int) – The minimum required horizontal distance (in number of samples) between neighbouring peaks.

Parameters:

distance (int)

distance: int

The minimum required horizontal distance (in number of samples) between neighbouring peaks

detect(data)[source]

Find all peaks in the data array.

Parameters:

data (ArrayLike)

Return type:

ndarray[tuple[Any, …], dtype[float64]]

class bluepebble.detector.PassiveSonarDetector(detection_chain, sensor_data_gen, steering_azimuths_rad)[source]

A passive sonar detector that processes beamformed sensor data.

This detector takes PassiveSonarSensorData as input, extracts the beamformed power map, calculates the Signal-to-Noise Ratio (SNR) for each beam, and then runs a chain of detection algorithms to find targets.

The SNR is calculated by estimating noise power as the 10th-percentile of directional power (robust to outliers). Detections are produced with bearing values derived from the provided steering azimuths.

Variables:

  • detection_chain (list[DetectionAlgorithm]) – A list of detection algorithms to apply sequentially to the SNR map.

  • sensor_data_gen (Generator[SensorDataStep, None, None]) – Generator yielding sensor-data batches.

  • steering_azimuths_rad (FloatArray) – An array of steering azimuth angles in radians corresponding to the beams.

Parameters:

  • detection_chain (list[DetectionAlgorithm])

  • sensor_data_gen (Generator[tuple[datetime, Iterable[PassiveSonarSensorData]], None, None])

  • steering_azimuths_rad (ndarray[tuple[Any, ...], dtype[float64]])

detection_chain: list[DetectionAlgorithm]

A list of detection algorithms to apply sequentially.

sensor_data_gen: Generator[tuple[datetime, Iterable[PassiveSonarSensorData]], None, None]

Generator that yields PassiveSonarSensorData objects

steering_azimuths_rad: ndarray[tuple[Any, ...], dtype[float64]]

Array of steering azimuth angles in radians.

property snr_history: ndarray[tuple[Any, ...], dtype[float64]]

Recorded SNR history.

Returns:

Array of shape (num_timesteps, num_beams) containing SNR values. If no history is available an empty array is returned.

Return type:

FloatArray

detections_gen(progress_bar=False, total_timesteps=None, beamformer_output_type='snr_percentile', snr_percentile_val=10)[source]

Generate detections from sensor data.

The generator iterates through sensor_data_gen, computes an SNR map for each beamformed frame, runs the configured detection_chain and yields Stone Soup Detection objects (bearing-only measurements).

Parameters:

  • progress_bar (bool, optional) – If True, wrap the input generator with a progress bar (default is False).

  • total_timesteps (int, optional) – Total number of timesteps for the progress bar. Required if progress_bar is True.

  • beamformer_output_type (str, optional) – Type of beamformer output to use for detection. Options are “snr_percentile” (default), “log_power”, “power”, or “median_power”.

  • snr_percentile_val (int, optional) – Percentile to use for noise power estimation when calculating SNR (default is 10).

Yields:

tuple – A tuple of (timestamp, set[Detection]) for each processed timestep.

Return type:

Generator[tuple[datetime, set[Detection]], None, None]

class bluepebble.detector.SweepResult(param_values, tp, fp, fn, tn, label=None)[source]

Aggregated detection metrics from a parameter sweep.

Variables:

  • param_values (FloatArray) – The swept parameter values, shape (P,).

  • tp (IntArray) – Total true positives across all timesteps for each parameter value.

  • fp (IntArray) – Total false positives across all timesteps for each parameter value.

  • fn (IntArray) – Total false negatives across all timesteps for each parameter value.

  • tn (IntArray) – Total true negatives across all timesteps for each parameter value.

  • label (str | None) – Human-readable name carried through from SweepSpec, used in plot legends.

Parameters:

  • param_values (ndarray[tuple[Any, ...], dtype[float64]])

  • tp (ndarray[tuple[Any, ...], dtype[int64]])

  • fp (ndarray[tuple[Any, ...], dtype[int64]])

  • fn (ndarray[tuple[Any, ...], dtype[int64]])

  • tn (ndarray[tuple[Any, ...], dtype[int64]])

  • label (str | None)

property precision: ndarray[tuple[Any, ...], dtype[float64]]

TP / (TP + FP).

Defaults to 1 where TP + FP = 0 (no detections issued).

Type:

Positive predictive value

property recall: ndarray[tuple[Any, ...], dtype[float64]]

TP / (TP + FN).

Defaults to 0 where TP + FN = 0 (no positives present).

Type:

Sensitivity / true positive rate

property tpr: ndarray[tuple[Any, ...], dtype[float64]]

True positive rate (alias for recall).

property fpr: ndarray[tuple[Any, ...], dtype[float64]]

FP / (FP + TN).

Defaults to 0 where FP + TN = 0.

Type:

False positive rate

property f1: ndarray[tuple[Any, ...], dtype[float64]]

Harmonic mean of precision and recall.

property auc_roc: float

Area under the ROC curve, computed via trapezoidal integration.

property auc_pr: float

Area under the precision-recall curve, computed via trapezoidal integration.

property best_param: float

Parameter value that maximises Youden’s J statistic (TPR − FPR).

Youden’s J is the vertical distance above the random-classifier diagonal on the ROC curve. The operating point with the highest J gives the best trade-off between sensitivity and specificity for this sweep.

Returns:

The swept parameter value achieving max(TPR − FPR).

Return type:

float

param_at_fpr(target_fpr=0.05)[source]

Parameter value whose operating point is nearest to a given FPR.

Selects the sweep index where |FPR − target_fpr| is minimised, breaking ties by preferring the index with the higher TPR.

Parameters:

target_fpr (float) – Desired false positive rate. Defaults to 0.05.

Returns:

The swept parameter value whose FPR is closest to target_fpr.

Return type:

float

class bluepebble.detector.SweepSpec(detection_chain, algorithm_index, param_name, param_values, label=None)[source]

Specification for a single detection-chain parameter sweep.

Variables:

  • detection_chain (list[DetectionAlgorithm]) – The base detection chain. Deep-copied for each parameter value so the original is never mutated.

  • algorithm_index (int) – Index into detection_chain selecting the algorithm whose parameter is swept (0-based).

  • param_name (str) – Attribute name to sweep (e.g. "threshold_factor").

  • param_values (ArrayLike) – Sequence of values to evaluate, ordered from most permissive to most strict so ROC / PR curves trace in the canonical direction.

  • label (str | None) – Human-readable name used in plot legends. Defaults to "<param_name> sweep" when None.

Parameters:

  • detection_chain (Sequence[DetectionAlgorithm])

  • algorithm_index (int)

  • param_name (str)

  • param_values (ArrayLike)

  • label (str | None)

class bluepebble.detector.ThresholdDetector(threshold)[source]

Detects data points that exceed a predefined scalar threshold.

This detector performs a simple comparison, identifying all indices in an array where the value is greater than the specified threshold.

Variables:

threshold (float) – The value that data points must exceed to be considered a detection.

Parameters:

threshold (float)

threshold: float

The value that data points must exceed to be considered a detection

detect(data)[source]

Detect values in the data array that are above the threshold.

Parameters:

data (ArrayLike)

Return type:

ndarray[tuple[Any, …], dtype[float64]]