# 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:
    labels list of strings, shape=(n,)

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

    case_sensitive bool

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

  Returns:
    indices list, shape=(n,)

      Numerical representation of `labels`

    index_to_label dict

      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:
    items list-like

      A list or array of events or intervals

    prefix str

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

  Returns:
    labels list 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:
    intervals np.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]`.

    labels list, shape=(n,)

      The annotation for each interval

    offset float > 0

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

    sample_size float > 0

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

    fill_value type(labels[0])

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

  Returns:
    sample_times list

      list of sample times

    sample_labels list

      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:
    intervals np.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.

    labels list, shape=(n,)

      The annotation for each interval

    time_points array_like, shape=(m,)

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

    fill_value type(labels[0])

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

  Returns:
    aligned_labels list

      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:
    intervals np.ndarray, shape=(n, 2)

      The input intervals

    labels list, 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:
    precision float in (0, 1]

      Precision

    recall float in (0, 1]

      Recall

    beta float > 0

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

  Returns:
    f_measure float

      The weighted f-measure

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

  Convert interval times into boundaries.

  Parameters:
    intervals np.ndarray, shape=(n_events, 2)

      Array of interval start and end-times

    q int

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

  Returns:
    boundaries np.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:
    boundaries list-like

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

  Returns:
    intervals np.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:
    intervals np.ndarray, shape=(n_events, 2)

      Array of interval start and end-times

    labels list, len=n_events or None

      List of labels (Default value = None)

    t_min float or None

      Minimum interval start time. (Default value = 0.0)

    t_max float or None

      Maximum interval end time. (Default value = None)

    start_label str or float or int

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

    end_label str or float or int

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

  Returns:
    new_intervals np.ndarray

      Intervals spanning `[t_min, t_max]`

    new_labels list

      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:
    events np.ndarray

      Array of event times (seconds)

    labels list or None

      List of labels (Default value = None)

    t_min float or None

      Minimum valid event time. (Default value = 0.0)

    t_max float or None

      Maximum valid event time. (Default value = None)

    label_prefix str

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

  Returns:
    new_times np.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:
    flist1 list

      first list of filepaths

    flist2 list

      second list of filepaths

  Returns:
    sublist1 list

      subset of filepaths with matching stems from `flist1`

    sublist2 list

      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_intervals np.ndarray

      Array of interval times (seconds)

    x_labels list or None

      List of labels

    y_intervals np.ndarray

      Array of interval times (seconds)

    y_labels list or None

      List of labels

  Returns:
    new_intervals np.ndarray

      New interval times of the merged sequences.

    new_x_labels list

      New labels for the sequence `x`

    new_y_labels list

      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:
    ref np.ndarray, shape=(n,)

      Array of reference values

    est np.ndarray, shape=(m,)

      Array of estimated values

    window float > 0

      Size of the window.

    distance function

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

  Returns:
    matching list 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:
    intervals np.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:
    events np.ndarray, shape=(n,)

      Array of event times

    max_time float

      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:
    frequencies np.ndarray, shape=(n,)

      Array of frequency values

    max_freq float

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

    min_freq float

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

    allow_negatives bool

      Whether or not to allow negative frequency values.

mir_eval.util.has_kwargs(function)

  Determine whether a function has **kwargs.

  Parameters:
    function callable

      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:
    _function callable

      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:
    intervals np.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:
    durations np.ndarray, shape=(n,)

      Array of the duration of each interval.

mir_eval.util.hz_to_midi(freqs)

  Convert Hz to MIDI numbers

  Parameters:
    freqs number or ndarray

      Frequency/frequencies in Hz

  Returns:
    midi number 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:
    midi number or ndarray

      MIDI notes

  Returns:
    freqs number 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.