more_changepoint_features#

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

Create changepoint-based features from a binary changepoint array.

Four column groups always, two more when source is given, 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.

  • Prominence and asymmetry — with source, the signal the mask was detected on: one column per window of _shape_at_candidates(), how deep the candidate sits below the lower of its two neighbouring hills, and how much more the signal moves after it than before. Every frame reads its nearest candidate’s value, so between candidates the columns are steps, and a trial with no candidate reads 0. In the signal’s own units, so unlike the four above they are normalised.

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 (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 (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.

  • source (ndarray | None) – The signal the mask marks candidates on, on the same time axis; enables the prominence and asymmetry columns.

  • windows (Sequence[float] | None) – Half-widths of the shape columns, in samples; None is default_windows() of the horizon. Ignored without source.

Return type:

ndarray

Returns:

2D array of shape (T, 1 + len(sigmas) + 3) — the binary mask, one proximity column per sigma, since, until, then length — plus 2 * len(windows) columns (all prominences, then all asymmetries) when source is given.