find_nearest_turning_points_binary#

ethograph.features.changepoints.find_nearest_turning_points_binary(x, threshold=1, max_value=None, prominence=0.5, distance=2, **kwargs)[source]#

Convert a 1D signal into a binary mask marking boundaries of peak regions.

Identifies peaks in the signal, then finds the nearest “turning points” (where the gradient is near zero) on either side of each peak. These turning points define the boundaries of peak regions. The result is a binary mask where 1 indicates a turning-point boundary.

The algorithm works in four steps:

  1. Compute the gradient of x and find indices where |gradient| < threshold, treating these as candidate turning points (near-stationary regions).

  2. Find peaks in x using scipy.signal.find_peaks with any additional kwargs.

  3. For each peak, select the closest turning point to its left and right.

  4. Add boundaries at NaN transitions in the original signal.

Parameters:

  • x – Input 1D signal.

  • threshold – Maximum absolute gradient value to qualify as a turning point. Lower values select only very flat regions. Default is 1.

  • max_value – If set, discard turning points where x exceeds this value. Useful for ignoring turning points on high plateaus.

  • **kwargs – Passed to scipy.signal.find_peaks (e.g. height, distance, prominence).

Returns:

Binary array of same length as x, with 1 at turning-point boundaries and NaN-transition boundaries, 0 elsewhere.