# mir_eval.io

Functions for loading annotations from files in different formats.

mir_eval.io.load_delimited(filename, converters, delimiter='\\s+', comment='#')

  Load data from an annotation file where columns are delimited. The number of columns is inferred from the length of the provided converters list.

  Parameters:
    filename str or os.Pathlike

      Path to the annotation file

    converters list of functions

      Each entry in column `n` of the file will be cast by the function `converters[n]`.

    delimiter str

      Separator regular expression. By default, lines will be split by any amount of whitespace.

    comment str or None

      Comment regular expression. Any lines beginning with this string or pattern will be ignored.

      Setting to None disables comments.

  Returns:
    columns tuple of lists

      Each list in this tuple corresponds to values in one of the columns in the file.

  Examples

      >>> # Load in a one-column list of event times (floats)
      >>> load_delimited('events.txt', [float])
      >>> # Load in a list of labeled events, separated by commas
      >>> load_delimited('labeled_events.csv', [float, str], ',')

mir_eval.io.load_events(filename, delimiter='\\s+', comment='#')

  Import time-stamp events from an annotation file. The file should consist of a single column of numeric values corresponding to the event times. This is primarily useful for processing events which lack duration, such as beats or onsets.

  Parameters:
    filename str or os.Pathlike

      Path to the annotation file

    delimiter str

      Separator regular expression. By default, lines will be split by any amount of whitespace.

    comment str or None

      Comment regular expression. Any lines beginning with this string or pattern will be ignored.

      Setting to None disables comments.

  Returns:
    event_times np.ndarray

      array of event times (float)

mir_eval.io.load_labeled_events(filename, delimiter='\\s+', comment='#')

  Import labeled time-stamp events from an annotation file. The file should consist of two columns; the first having numeric values corresponding to the event times and the second having string labels for each event. This is primarily useful for processing labeled events which lack duration, such as beats with metric beat number or onsets with an instrument label.

  Parameters:
    filename str or os.Pathlike

      Path to the annotation file

    delimiter str

      Separator regular expression. By default, lines will be split by any amount of whitespace.

    comment str or None

      Comment regular expression. Any lines beginning with this string or pattern will be ignored.

      Setting to None disables comments.

  Returns:
    event_times np.ndarray

      array of event times (float)

    labels list of str

      list of labels

mir_eval.io.load_intervals(filename, delimiter='\\s+', comment='#')

  Import intervals from an annotation file. The file should consist of two columns of numeric values corresponding to start and end time of each interval. This is primarily useful for processing events which span a duration, such as segmentation, chords, or instrument activation.

  Parameters:
    filename str or os.Pathlike

      Path to the annotation file

    delimiter str

      Separator regular expression. By default, lines will be split by any amount of whitespace.

    comment str or None

      Comment regular expression. Any lines beginning with this string or pattern will be ignored.

      Setting to None disables comments.

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

      array of event start and end times

mir_eval.io.load_labeled_intervals(filename, delimiter='\\s+', comment='#')

  Import labeled intervals from an annotation file. The file should consist of three columns: Two consisting of numeric values corresponding to start and end time of each interval and a third corresponding to the label of each interval. This is primarily useful for processing events which span a duration, such as segmentation, chords, or instrument activation.

  Parameters:
    filename str or os.Pathlike

      Path to the annotation file

    delimiter str

      Separator regular expression. By default, lines will be split by any amount of whitespace.

    comment str or None

      Comment regular expression. Any lines beginning with this string or pattern will be ignored.

      Setting to None disables comments.

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

      array of event start and end time

    labels list of str

      list of labels

mir_eval.io.load_time_series(filename, delimiter='\\s+', comment='#')

  Import a time series from an annotation file. The file should consist of two columns of numeric values corresponding to the time and value of each sample of the time series.

  Parameters:
    filename str or os.Pathlike

      Path to the annotation file

    delimiter str

      Separator regular expression. By default, lines will be split by any amount of whitespace.

    comment str or None

      Comment regular expression. Any lines beginning with this string or pattern will be ignored.

      Setting to None disables comments.

  Returns:
    times np.ndarray

      array of timestamps (float)

    values np.ndarray

      array of corresponding numeric values (float)

mir_eval.io.load_patterns(filename)

  Load the patterns contained in the filename and puts them into a list of patterns, each pattern being a list of occurrence, and each occurrence being a list of (onset, midi) pairs.

  The input file must be formatted as described in MIREX 2013: http://www.music-ir.org/mirex/wiki/2013:Discovery_of_Repeated_Themes_%26_Sections

  Parameters:
    filename str or os.Pathlike

      The input file path containing the patterns of a given piece using the MIREX 2013 format.

  Returns:
    pattern_list list

      The list of patterns, containing all their occurrences, using the following format:

          onset_midi = (onset_time, midi_number)
          occurrence = [onset_midi1, ..., onset_midiO]
          pattern = [occurrence1, ..., occurrenceM]
          pattern_list = [pattern1, ..., patternN]

      where `N` is the number of patterns, `M[i]` is the number of occurrences of the `i` th pattern, and `O[j]` is the number of onsets in the `j`’th occurrence. E.g.:

          occ1 = [(0.5, 67.0), (1.0, 67.0), (1.5, 67.0), (2.0, 64.0)]
          occ2 = [(4.5, 65.0), (5.0, 65.0), (5.5, 65.0), (6.0, 62.0)]
          pattern1 = [occ1, occ2]

          occ1 = [(10.5, 67.0), (11.0, 67.0), (11.5, 67.0), (12.0, 64.0),
                  (12.5, 69.0), (13.0, 69.0), (13.5, 69.0), (14.0, 67.0),
                  (14.5, 76.0), (15.0, 76.0), (15.5, 76.0), (16.0, 72.0)]
          occ2 = [(18.5, 67.0), (19.0, 67.0), (19.5, 67.0), (20.0, 62.0),
                  (20.5, 69.0), (21.0, 69.0), (21.5, 69.0), (22.0, 67.0),
                  (22.5, 77.0), (23.0, 77.0), (23.5, 77.0), (24.0, 74.0)]
          pattern2 = [occ1, occ2]

          pattern_list = [pattern1, pattern2]

mir_eval.io.load_wav(path, mono=True)

  Load a .wav file as a numpy array using `scipy.io.wavfile`.

  Warning

  This function is deprecatred in mir_eval 0.8.1 and will be removed in 0.9.0. We recommend using a dedicated audio IO library such as soundfile instead.

  Parameters:
    path str or os.Pathlike

      Path to a .wav file

    mono bool

      If the provided .wav has more than one channel, it will be converted to mono if `mono=True`. (Default value = True)

  Returns:
    audio_data np.ndarray

      Array of audio samples, normalized to the range [-1., 1.]

    fs int

      Sampling rate of the audio data

mir_eval.io.load_valued_intervals(filename, delimiter='\\s+', comment='#')

  Import valued intervals from an annotation file. The file should consist of three columns: Two consisting of numeric values corresponding to start and end time of each interval and a third, also of numeric values, corresponding to the value of each interval. This is primarily useful for processing events which span a duration and have a numeric value, such as piano-roll notes which have an onset, offset, and a pitch value.

  Parameters:
    filename str or os.Pathlike

      Path to the annotation file

    delimiter str

      Separator regular expression. By default, lines will be split by any amount of whitespace.

    comment str or None

      Comment regular expression. Any lines beginning with this string or pattern will be ignored.

      Setting to None disables comments.

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

      Array of event start and end times

    values np.ndarray, shape=(n_events,)

      Array of values

mir_eval.io.load_key(filename, delimiter='\\s+', comment='#')

  Load key labels from an annotation file. The file should consist of two string columns: One denoting the key scale degree (semitone), and the other denoting the mode (major or minor). The file should contain only one row.

  Parameters:
    filename str or os.Pathlike

      Path to the annotation file

    delimiter str

      Separator regular expression. By default, lines will be split by any amount of whitespace.

    comment str or None

      Comment regular expression. Any lines beginning with this string or pattern will be ignored.

      Setting to None disables comments.

  Returns:
    key str

      Key label, in the form `'(key) (mode)'`

mir_eval.io.load_tempo(filename, delimiter='\\s+', comment='#')

  Load tempo estimates from an annotation file in MIREX format. The file should consist of three numeric columns: the first two correspond to tempo estimates (in beats-per-minute), and the third denotes the relative confidence of the first value compared to the second (in the range [0, 1]). The file should contain only one row.

  Parameters:
    filename str or os.Pathlike

      Path to the annotation file

    delimiter str

      Separator regular expression. By default, lines will be split by any amount of whitespace.

    comment str or None

      Comment regular expression. Any lines beginning with this string or pattern will be ignored.

      Setting to None disables comments.

  Returns:
    tempi np.ndarray, non-negative

      The two tempo estimates

    weight float [0, 1]

      The relative importance of `tempi[0]` compared to `tempi[1]`

mir_eval.io.load_ragged_time_series(filename, dtype=<class 'float'>, delimiter='\\s+', header=False, comment='#')

  Load data from a delimited time series annotation file with a variable number of columns.

  This function assumes that column 0 contains time stamps and columns 1 through n contain values. n may be variable from time stamp to time stamp.

  Parameters:
    filename str or os.Pathlike

      Path to the annotation file

    dtype function

      Data type to apply to values columns.

    delimiter str

      Separator regular expression. By default, lines will be split by any amount of whitespace.

    header bool

      Indicates whether a header row is present or not. By default, assumes no header is present.

    comment str or None

      Comment regular expression. Any lines beginning with this string or pattern will be ignored.

      Setting to None disables comments.

  Returns:
    times np.ndarray

      array of timestamps (float)

    values list of np.ndarray

      list of arrays of corresponding values

  Examples

      >>> # Load a ragged list of tab-delimited multi-f0 midi notes
      >>> times, vals = load_ragged_time_series('multif0.txt', dtype=int,
                                                delimiter='\t')
      >>> # Load a raggled list of space delimited multi-f0 values with a header
      >>> times, vals = load_ragged_time_series('labeled_events.csv',
                                                header=True)