confusion

Phase-confusion metric: half-cycle “1” <-> opposite-position swap rate.

Functions

confusion_half_cycle_rate(ref_times, ...[, ...])

Rate of half-cycle phase-parity errors: predicted "1" <-> true position 1 + group_size // 2 (or vice versa).
confusion_half_cycle_rate(ref_times, ref_positions, pred_events, tolerance=0.07, group_size=4)[source]

Rate of half-cycle phase-parity errors: predicted “1” <-> true position 1 + group_size // 2 (or vice versa).

Analogue of the original phrase-tracker plan’s “beat-5 confusion” metric: the failure mode where the model has locked onto the right beat periodicity but the wrong phase — exactly half a group off, so a “1” is mistaken for the position diametrically opposite it in the cycle (bar position 3 when group_size=4; phrase position 5 when group_size=8) and vice versa. This is a different failure from a generic wrong label or a missed detection, which is why it’s measured separately from musicality.metrics.f_measure.downbeat_f_measures().

For each reference beat at position 1 or the opposite position, this finds the nearest predicted event within tolerance seconds. Only beats with a resolved (1 or opposite) match are counted as eligible — a missed detection or an unresolved/off-parity label is a different failure mode and is excluded rather than counted as “not confused”, so it doesn’t dilute the signal this metric is meant to isolate.

Parameters:

  • ref_times (ndarray) – Reference beat times, in seconds, shape (n_beats,).

  • ref_positions (ndarray) – Reference group position (1-group_size) per beat, same shape as ref_times.

  • pred_events (list[dict]) – Predicted beat list, as returned by musicality.postprocess.readout().

  • tolerance (float) – Matching window, in seconds.

  • group_size (int) – Beats per group — 4 for bar position (default), 8 for phrase position. Must be even for “half a cycle” to land on an integer position.

Returns:

Fraction of eligible beats that were swapped, in [0, 1], or None if there were no eligible beats (nothing to measure).

Return type:

float | None