f_measure

F-measure metrics: overall beat F-measure and per-position (downbeat) F-measure.

Consumes the labeled beat list produced by musicality.postprocess.readout() (or raw reference annotations) — this is the “does the final output line up with the ground truth” evaluation, distinct from musicality.metrics.frame_accuracy.frame_accuracy(), which is a cheap per-epoch training signal on raw frame probabilities.

Functions

beat_f_measure(ref_times, est_times[, ...])

F-measure between two sets of event times, matched within a tolerance window.

downbeat_f_measures(ref_times, ...[, ...])

F-measure for the "1" (downbeat) and "last" (position group_size) positions, computed separately.
beat_f_measure(ref_times, est_times, tolerance=0.07, trim=True)[source]

F-measure between two sets of event times, matched within a tolerance window.

Thin wrapper around mir_eval.beat.f_measure — usable for the beat channel directly, and for the “1”/”4” channels by passing only the events of that position (see downbeat_f_measures()).

Parameters:

  • ref_times (ndarray) – Reference event times, in seconds.

  • est_times (ndarray) – Estimated event times, in seconds.

  • tolerance (float) – Matching window, in seconds (mir_eval’s default is 0.07).

  • trim (bool) – If True, drop events before 5s from both sets first — mir_eval’s standard convention, so an algorithm isn’t penalised for not having locked onto the tempo yet. Meaningful for full-track evaluation; pass False for short clips (e.g. the ~10s training clips), where trimming would discard most of the signal.

Returns:

F-measure in [0, 1].

Return type:

float

downbeat_f_measures(ref_times, ref_positions, pred_events, tolerance=0.07, trim=True, group_size=4)[source]

F-measure for the “1” (downbeat) and “last” (position group_size) positions, computed separately.

Note

Only positions 1 and group_size are ever scored. Positions 2..group_size-1 are invisible to this metric even under the softmax head, which predicts all of them — an error that turns a “2” into a “3” cannot register. That is why musicality.metrics.position_accuracy.position_accuracy()’s position_acc is the headline bar-position metric and these two are reported alongside it rather than in place of it.

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() — a list of {"time": float, "beat_in_bar": int | None}.

  • tolerance (float) – Passed to beat_f_measure().

  • trim (bool) – Passed to beat_f_measure().

  • group_size (int) – Beats per group — 4 for bar position (default), 8 for phrase position. Determines which reference/predicted position counts as “last”.

Returns:

(f_one, f_last).

Return type:

tuple[float, float]