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()
ormir_eval.io.load_labeled_intervals()
. Thei
th interval spans timeintervals[i, 0]
tointervals[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()
. Thei
th interval spans timeintervals[i, 0]
tointervals[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 labelend_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 prefixlabel_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
andest
, we seek the largest set of correspondences(ref[i], est[j])
such thatdistance(ref[i], est[j]) <= window
, and eachref[i]
andest[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)
whereref[i]
matchesest[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()
. Thei
th interval spans timeintervals[i, 0]
tointervals[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.