mir_eval.util

Useful functionality required across the task submodules, such as preprocessing, validation, and common computations.

mir_eval.util.index_labels(labels, case_sensitive=False)

Convert a list of string identifiers into numerical indices.

Parameters:
labelslist of strings, shape=(n,)

A list of annotations, e.g., segment or chord labels from an annotation file.

case_sensitivebool

Set to True to enable case-sensitive label indexing (Default value = False)

Returns:
indiceslist, shape=(n,)

Numerical representation of labels

index_to_labeldict

Mapping to convert numerical indices back to labels. labels[i] == index_to_label[indices[i]]

mir_eval.util.generate_labels(items, prefix='__')

Given an array of items (e.g. events, intervals), create a synthetic label for each event of the form ‘(label prefix)(item number)’

Parameters:
itemslist-like

A list or array of events or intervals

prefixstr

This prefix will be prepended to all synthetically generated labels (Default value = ‘__’)

Returns:
labelslist of str

Synthetically generated labels

mir_eval.util.intervals_to_samples(intervals, labels, offset=0, sample_size=0.1, fill_value=None)

Convert an array of labeled time intervals to annotated samples.

Parameters:
intervalsnp.ndarray, shape=(n, d)

An array of time intervals, as returned by mir_eval.io.load_intervals() or mir_eval.io.load_labeled_intervals(). The i th interval spans time intervals[i, 0] to intervals[i, 1].

labelslist, shape=(n,)

The annotation for each interval

offsetfloat > 0

Phase offset of the sampled time grid (in seconds) (Default value = 0)

sample_sizefloat > 0

duration of each sample to be generated (in seconds) (Default value = 0.1)

fill_valuetype(labels[0])

Object to use for the label with out-of-range time points. (Default value = None)

Returns:
sample_timeslist

list of sample times

sample_labelslist

array of labels for each generated sample

Notes

Intervals will be rounded down to the nearest multiple of sample_size.

mir_eval.util.interpolate_intervals(intervals, labels, time_points, fill_value=None)

Assign labels to a set of points in time given a set of intervals.

Time points that do not lie within an interval are mapped to fill_value.

Parameters:
intervalsnp.ndarray, shape=(n, 2)

An array of time intervals, as returned by mir_eval.io.load_intervals(). The i th interval spans time intervals[i, 0] to intervals[i, 1].

Intervals are assumed to be disjoint.

labelslist, shape=(n,)

The annotation for each interval

time_pointsarray_like, shape=(m,)

Points in time to assign labels. These must be in non-decreasing order.

fill_valuetype(labels[0])

Object to use for the label with out-of-range time points. (Default value = None)

Returns:
aligned_labelslist

Labels corresponding to the given time points.

Raises:
ValueError

If time_points is not in non-decreasing order.

mir_eval.util.sort_labeled_intervals(intervals, labels=None)

Sort intervals, and optionally, their corresponding labels according to start time.

Parameters:
intervalsnp.ndarray, shape=(n, 2)

The input intervals

labelslist, optional

Labels for each interval

Returns:
intervals_sorted or (intervals_sorted, labels_sorted)

Labels are only returned if provided as input

mir_eval.util.f_measure(precision, recall, beta=1.0)

Compute the f-measure from precision and recall scores.

Parameters:
precisionfloat in (0, 1]

Precision

recallfloat in (0, 1]

Recall

betafloat > 0

Weighting factor for f-measure (Default value = 1.0)

Returns:
f_measurefloat

The weighted f-measure

mir_eval.util.intervals_to_boundaries(intervals, q=5)

Convert interval times into boundaries.

Parameters:
intervalsnp.ndarray, shape=(n_events, 2)

Array of interval start and end-times

qint

Number of decimals to round to. (Default value = 5)

Returns:
boundariesnp.ndarray

Interval boundary times, including the end of the final interval

mir_eval.util.boundaries_to_intervals(boundaries)

Convert an array of event times into intervals

Parameters:
boundarieslist-like

List-like of event times. These are assumed to be unique timestamps in ascending order.

Returns:
intervalsnp.ndarray, shape=(n_intervals, 2)

Start and end time for each interval

mir_eval.util.adjust_intervals(intervals, labels=None, t_min=0.0, t_max=None, start_label='__T_MIN', end_label='__T_MAX')

Adjust a list of time intervals to span the range [t_min, t_max].

Any intervals lying completely outside the specified range will be removed.

Any intervals lying partially outside the specified range will be cropped.

If the specified range exceeds the span of the provided data in either direction, additional intervals will be appended. If an interval is appended at the beginning, it will be given the label start_label; if an interval is appended at the end, it will be given the label end_label.

Parameters:
intervalsnp.ndarray, shape=(n_events, 2)

Array of interval start and end-times

labelslist, len=n_events or None

List of labels (Default value = None)

t_minfloat or None

Minimum interval start time. (Default value = 0.0)

t_maxfloat or None

Maximum interval end time. (Default value = None)

start_labelstr or float or int

Label to give any intervals appended at the beginning (Default value = ‘__T_MIN’)

end_labelstr or float or int

Label to give any intervals appended at the end (Default value = ‘__T_MAX’)

Returns:
new_intervalsnp.ndarray

Intervals spanning [t_min, t_max]

new_labelslist

List of labels for new_labels

mir_eval.util.adjust_events(events, labels=None, t_min=0.0, t_max=None, label_prefix='__')

Adjust the given list of event times to span the range [t_min, t_max].

Any event times outside of the specified range will be removed.

If the times do not span [t_min, t_max], additional events will be added with the prefix label_prefix.

Parameters:
eventsnp.ndarray

Array of event times (seconds)

labelslist or None

List of labels (Default value = None)

t_minfloat or None

Minimum valid event time. (Default value = 0.0)

t_maxfloat or None

Maximum valid event time. (Default value = None)

label_prefixstr

Prefix string to use for synthetic labels (Default value = ‘__’)

Returns:
new_timesnp.ndarray

Event times corrected to the given range.

mir_eval.util.intersect_files(flist1, flist2)

Return the intersection of two sets of filepaths, based on the file name (after the final ‘/’) and ignoring the file extension.

Parameters:
flist1list

first list of filepaths

flist2list

second list of filepaths

Returns:
sublist1list

subset of filepaths with matching stems from flist1

sublist2list

corresponding filepaths from flist2

Examples

>>> flist1 = ['/a/b/abc.lab', '/c/d/123.lab', '/e/f/xyz.lab']
>>> flist2 = ['/g/h/xyz.npy', '/i/j/123.txt', '/k/l/456.lab']
>>> sublist1, sublist2 = mir_eval.util.intersect_files(flist1, flist2)
>>> print sublist1
['/e/f/xyz.lab', '/c/d/123.lab']
>>> print sublist2
['/g/h/xyz.npy', '/i/j/123.txt']
mir_eval.util.merge_labeled_intervals(x_intervals, x_labels, y_intervals, y_labels)

Merge the time intervals of two sequences.

Parameters:
x_intervalsnp.ndarray

Array of interval times (seconds)

x_labelslist or None

List of labels

y_intervalsnp.ndarray

Array of interval times (seconds)

y_labelslist or None

List of labels

Returns:
new_intervalsnp.ndarray

New interval times of the merged sequences.

new_x_labelslist

New labels for the sequence x

new_y_labelslist

New labels for the sequence y

mir_eval.util.match_events(ref, est, window, distance=None)

Compute a maximum matching between reference and estimated event times, subject to a window constraint.

Given two lists of event times ref and est, we seek the largest set of correspondences (ref[i], est[j]) such that distance(ref[i], est[j]) <= window, and each ref[i] and est[j] is matched at most once.

This is useful for computing precision/recall metrics in beat tracking, onset detection, and segmentation.

Parameters:
refnp.ndarray, shape=(n,)

Array of reference values

estnp.ndarray, shape=(m,)

Array of estimated values

windowfloat > 0

Size of the window.

distancefunction

function that computes the outer distance of ref and est. By default uses |ref[i] - est[j]|

Returns:
matchinglist of tuples

A list of matched reference and event numbers. matching[i] == (i, j) where ref[i] matches est[j].

mir_eval.util.validate_intervals(intervals)

Check that an (n, 2) interval ndarray is well-formed, and raises errors if not.

Parameters:
intervalsnp.ndarray, shape=(n, 2)

Array of interval start/end locations.

mir_eval.util.validate_events(events, max_time=30000.0)

Check that a 1-d event location ndarray is well-formed, and raises errors if not.

Parameters:
eventsnp.ndarray, shape=(n,)

Array of event times

max_timefloat

If an event is found above this time, a ValueError will be raised. (Default value = 30000.)

mir_eval.util.validate_frequencies(frequencies, max_freq, min_freq, allow_negatives=False)

Check that a 1-d frequency ndarray is well-formed, and raises errors if not.

Parameters:
frequenciesnp.ndarray, shape=(n,)

Array of frequency values

max_freqfloat

If a frequency is found above this pitch, a ValueError will be raised. (Default value = 5000.)

min_freqfloat

If a frequency is found below this pitch, a ValueError will be raised. (Default value = 20.)

allow_negativesbool

Whether or not to allow negative frequency values.

mir_eval.util.has_kwargs(function)

Determine whether a function has **kwargs.

Parameters:
functioncallable

The function to test

Returns:
True if function accepts arbitrary keyword arguments.
False otherwise.
mir_eval.util.filter_kwargs(_function, *args, **kwargs)

Given a function and args and keyword args to pass to it, call the function but using only the keyword arguments which it accepts. This is equivalent to redefining the function with an additional **kwargs to accept slop keyword args.

If the target function already accepts **kwargs parameters, no filtering is performed.

Parameters:
_functioncallable

Function to call. Can take in any number of args or kwargs

*args
**kwargs

Arguments and keyword arguments to _function.

mir_eval.util.intervals_to_durations(intervals)

Convert an array of n intervals to their n durations.

Parameters:
intervalsnp.ndarray, shape=(n, 2)

An array of time intervals, as returned by mir_eval.io.load_intervals(). The i th interval spans time intervals[i, 0] to intervals[i, 1].

Returns:
durationsnp.ndarray, shape=(n,)

Array of the duration of each interval.

mir_eval.util.hz_to_midi(freqs)

Convert Hz to MIDI numbers

Parameters:
freqsnumber or ndarray

Frequency/frequencies in Hz

Returns:
midinumber or ndarray

MIDI note numbers corresponding to input frequencies. Note that these may be fractional.

mir_eval.util.midi_to_hz(midi)

Convert MIDI numbers to Hz

Parameters:
midinumber or ndarray

MIDI notes

Returns:
freqsnumber or ndarray

Frequency/frequencies in Hz corresponding to midi

mir_eval.util.deprecated(*, version, version_removed)

Mark a function as deprecated.

Using the decorated (old) function will result in a warning.