more_changepoint_features#

ethograph.features.changepoints.more_changepoint_features(changepoint_binary, sigmas, distribution='laplacian', horizon=None, scale=None, max_length=None)[source]#

Create changepoint-based features from a binary changepoint array.

Four column groups, in this order (see CP_TRANSFORMS):

  • Binary — the exact changepoint positions (0/1 mask). Example: 0 0 0 0 1 0 0 0 1 0 0 0 0 0

  • Proximity — one column per sigma: a Laplacian (or Gaussian) kernel centred at each changepoint, summed. An isolated changepoint reads 1 at its frame; overlapping kernels add, so a cluster of candidates reads above 1. Nothing is normalised per trial. Example (one sigma): 0 0 0 .3 1 .3 0 .3 1 .3 0 0 0 0

  • Offset — two columns: samples since the previous changepoint and until the next, each clipped at horizon and scaled to [0, 1]. A frame reads which side of its nearest candidate it is on, which the symmetric kernels cannot say; before the first / after the last changepoint the column is saturated (no candidate in reach). Example (horizon 4): since 1 1 1 1 0 .25 .5 .75 0 .25 .5 .75 1 1, until 1 .75 .5 .25 0 .75 .5 .25 0 1 1 1 1 1

  • Length — one column: the length of the candidate segment the frame sits in (cut at every changepoint and at the trial’s ends), as log1p(length) / log1p(max_length), clipped at 1. The offsets already resolve anything shorter than two horizons; this is the long range, where a fragment-prone short segment and a whole bout of rest should not read alike.

Proximity uses a Laplacian kernel by default:

\[\text{prox}(t) = \sum_i \exp\!\left(-\frac{|t - i|}{\sigma}\right)\]

where \(i\) are the changepoint indices and \(\sigma\) controls the peak width. Laplacians have a narrow peak that points directly at the changepoint while their long tails remain visible from far away. Passing multiple sigmas (e.g. [0.5, 3, 5]) yields features at several scales.

scale multiplies every proximity column by \(\exp(-x / \bar{x})\) of that signal, emphasising changepoints where it is low — with speed, the troughs before and after a movement rather than a dip inside one; with an amplitude envelope, the silences between calls. Frames where scale is NaN read 0.

Parameters:

  • changepoint_binary (np.ndarray) – Binary (0/1) array marking changepoint locations.

  • sigmas (Sequence[float]) – Kernel widths (samples) for the proximity columns.

  • distribution (Literal[‘gaussian’, ‘laplacian’]) – "laplacian" (default) or "gaussian" kernel.

  • horizon (float | None) – Reach of the offset columns, in samples; None is default_horizon().

  • scale (np.ndarray | None) – Optional signal on the same time axis that scales the proximity columns.

  • max_length (float | None) – Where the length column saturates, in samples; None is LENGTH_HORIZONS horizons.

Returns:

the binary mask, one proximity column per sigma, since, until, then length.

Return type:

2D array of shape (T, 1 + len(sigmas) + 3)