audiomate.corpus.utils

Relabeling

exception audiomate.corpus.utils.relabeling.UnmappedLabelsException(message)

audiomate.corpus.utils.relabeling.find_missing_projections(label_list, projections)

Finds all combinations of labels in label_list that are not covered by an entry in the dictionary of projections. Returns a list containing tuples of uncovered label combinations or en empty list if there are none. All uncovered label combinations are naturally sorted.

Each entry in the dictionary of projections represents a single projection that maps a combination of labels (key) to a single new label (value). The combination of labels to be mapped is a tuple of naturally sorted labels that apply to one or more segments simultaneously. By defining a special wildcard projection using (‘**’,) is is not required to specify a projection for every single combination of labels.

Parameters:

• label_list (audiomate.corpus.assets.LabelList) – The label list to relabel
• projections (dict) – A dictionary that maps tuples of label combinations to string labels.

Returns:

List of combinations of labels that are not covered by any projection

Return type:

List

Example

>>> ll = assets.LabelList(labels=[
...     assets.Label('b', 3.2, 4.5),
...     assets.Label('a', 4.0, 4.9),
...     assets.Label('c', 4.2, 5.1)
... ])
>>> find_missing_projections(ll, {('b',): 'new_label'})
[('a', 'b'), ('a', 'b', 'c'), ('a', 'c'), ('c',)]

audiomate.corpus.utils.relabeling.load_projections(projections_file)

Loads projections defined in the given projections_file.

The projections_file is expected to be in the following format:

old_label_1 | new_label_1
old_label_1 old_label_2 | new_label_2
old_label_3 |

You can define one projection per line. Each projection starts with a list of one or multiple old labels (separated by a single whitespace) that are separated from the new label by a pipe (|). In the code above, the segment labeled with old_label_1 will be labeled with new_label_1 after applying the projection. Segments that are labeled with old_label_1 and old_label_2 concurrently are relabeled to new_label_2. All segments labeled with old_label_3 are dropped. Combinations of multiple labels are automatically sorted in natural order.

Parameters:projections_file (str) – Path to the file with projections Returns:Dictionary where the keys are tuples of labels to project to the key’s value Return type:dict

Example

>>> load_projections('/path/to/projections.txt')
{('b',): 'foo', ('a', 'b'): 'a_b', ('a',): 'bar'}

audiomate.corpus.utils.relabeling.relabel(label_list, projections)

Relabel an entire LabelList using user-defined projections. Labels can be renamed, removed or overlapping labels can be flattened to a single label per segment.

Each entry in the dictionary of projections represents a single projection that maps a combination of labels (key) to a single new label (value). The combination of labels to be mapped is a tuple of naturally sorted labels that apply to one or more segments simultaneously. By defining a special wildcard projection using (‘**’,) is is not required to specify a projection for every single combination of labels.

This method raises a UnmappedLabelsException if a projection for one or more combinations of labels is not defined.

Parameters:

• label_list (audiomate.corpus.assets.LabelList) – The label list to relabel
• projections (dict) – A dictionary that maps tuples of label combinations to string labels.

Returns:

New label list with remapped labels

Return type:

audiomate.corpus.assets.LabelList

Raises:

UnmappedLabelsException – If a projection for one or more combinations of labels is not defined.

Example

>>> projections = {
...     ('a',): 'a',
...     ('b',): 'b',
...     ('c',): 'c',
...     ('a', 'b',): 'a_b',
...     ('a', 'b', 'c',): 'a_b_c',
...     ('**',): 'b_c',
... }
>>> label_list = assets.LabelList(labels=[
...     assets.Label('a', 3.2, 4.5),
...     assets.Label('b', 4.0, 4.9),
...     assets.Label('c', 4.2, 5.1)
... ])
>>> ll = relabel(label_list, projections)
>>> [l.value for l in ll]
['a', 'a_b', 'a_b_c', 'b_c', 'c']

Label Encoding

This module contains code to convert label-lists to vector representations. This is for example used when training a classifier and the labels act as target values. Then they can be converted to a numerical representation using Encoders.

class audiomate.corpus.utils.label_encoding.Encoder

An encoder is used to create a numerical vector representation from labels.

encode(utterance, label_list_idx='default')

Encode the given utterance.

Parameters:

• utterance (Utterance) – The utterance to encode.
• label_list_idx (str) – The name of the label-list to use for encoding. Only labels of this label-list are considered.

Returns:

The array containing the encoded labels. (num_frames x num_labels)

Return type:

np.ndarray

class audiomate.corpus.utils.label_encoding.FrameOneHotEncoder(labels, frame_settings, sr=None)

The FrameOneHotEncoder is used to encode the labels per frame. It creates a matrix with dimension num-frames x len(labels). The vector (2nd dim) has an entry for every label in the passed labels-list. If the sequence contains a given label within a frame it is set to 1.

Parameters:

• labels (list) – List of labels (str) which should be included in the vector representation.
• frame_settings (FrameSettings) – Frame settings to use.
• sr (int) – The sampling rate used, if None it is assumed the native sampling rate from the file is used.

Example

>>> from audiomate.corpus import assets
>>> from audiomate.utils import units import
>>> ll = assets.LabelList(labels=[
>>>     assets.Label('music', 0, 2),
>>>     assets.Label('speech', 2, 5),
>>>     assets.Label('noise', 4, 6),
>>>     assets.Label('music', 6, 8)
>>> ])
>>> labels = ['speech', 'music', 'noise']
>>> fs = units.FrameSettings(16000, 16000)
>>> encoder = FrameOneHotEncoder(labels, frame_settings=fs)
>>> encoder.encode(ll)
array([
    [0, 1, 0],
    [0, 1, 0],
    [1, 0, 0],
    [1, 0, 0],
    [1, 0, 1],
    [0, 0, 1],
    [0, 1, 0],
    [0, 1, 0]
])

encode(utterance, label_list_idx='default')

Encode the given utterance.

Parameters:

• utterance (Utterance) – The utterance to encode.
• label_list_idx (str) – The name of the label-list to use for encoding. Only labels of this label-list are considered.

Returns:

The array containing the encoded labels. (num_frames x num_labels)

Return type:

np.ndarray

class audiomate.corpus.utils.label_encoding.FrameOrdinalEncoder(labels, frame_settings, sr=None)

The FrameOrdinalEncoder is used to encode the labels per frame. It creates a vector with length num-frames. For every frame sets the index of the label that is present for that frame. If multiple labels are present the longest within the frame. If multiple labels have the same length the smaller index is selected, hence the passed labels list acts as a priority.

Parameters:

• labels (list) – List of labels (str) which should be included in the vector representation.
• frame_settings (FrameSettings) – Frame settings to use.
• sr (int) – The sampling rate used, if None it is assumed the native sampling rate from the file is used.

Example

>>> from audiomate.corpus import assets
>>> from audiomate.utils import units import
>>> ll = assets.LabelList(labels=[
>>>     assets.Label('music', 0, 2),
>>>     assets.Label('speech', 2, 5),
>>>     assets.Label('noise', 4, 6),
>>>     assets.Label('music', 6, 8)
>>> ])
>>> labels = ['speech', 'music', 'noise']
>>> fs = units.FrameSettings(16000, 16000)
>>> encoder = FrameOrdinalEncoder(labels, frame_settings=fs)
>>> encoder.encode(ll)
array([1,1,0,0,0,2,1,1])

encode(utterance, label_list_idx='default')

Encode the given utterance.

Parameters:

• utterance (Utterance) – The utterance to encode.
• label_list_idx (str) – The name of the label-list to use for encoding. Only labels of this label-list are considered.

Returns:

The array containing the encoded labels. (num_frames x num_labels)

Return type:

np.ndarray

Exceptions

exception audiomate.corpus.utils.relabeling.UnmappedLabelsException(message)