Core API

Core

Core methods and base class definitions

class motif.core.ContourClassifier

This class is an interface for all the contour classifier algorithms included in motif. Each classifer must inherit from it and implement the following methods:

• predict
• fit
• threshold

threshold should return a float whose determines the positive class threshold (e.g. score >= threshold : positive class, score < threshold : negative class)

Attributes

threshold

Property for setting threshold between classes

Methods

fit(X, Y)	Method for fitting the model
get_id()	Method to get the id of the extractor type
predict(X)	Method for predicting labels from input
score(y_predicted, y_target[, y_prob])	Compute metrics on classifier predictions

fit(X, Y)

Method for fitting the model

classmethod get_id()

Method to get the id of the extractor type

predict(X)

Method for predicting labels from input

score(y_predicted, y_target, y_prob=None)

Compute metrics on classifier predictions

Parameters:

y_predicted : np.array [n_samples]

Predicted class labels

y_target : np.array [n_samples]

Target class labels

y_prob : np.array [n_samples] or None, default=None

predicted probabilties. If None, auc is not computed

Returns:

scores : dict

dictionary of scores for the following metrics: accuracy, matthews correlation coefficient, precision, recall, f1, support, confusion matrix, auc score

threshold

Property for setting threshold between classes

class motif.core.ContourDecoder

This class is an interface for all the contour decoder algorithms included in motif. Each decoder must inherit from it and implement the following methods:

• decode
• get_id

Methods

decode(ctr, Y)	Decode the output of the contour classifier.
get_id()	Method to get the id of the decoder type

decode(ctr, Y)

Decode the output of the contour classifier.

Parameters:

ctr : Contours

An instance of a Contours object

Y : np.array [n_contours]

Predicted contour scores.

Returns:

times : np.ndarray

Array of time stamps

freqs : np.ndarray

Array of f0 values in Hz

classmethod get_id()

Method to get the id of the decoder type

class motif.core.ContourExtractor

This class is an interface for all the contour extraction algorithms included in motif. Each extractor must inherit from it and implement the following method:

• compute_contours

Additionally, two private helper functions are provided:

• preprocess
• postprocess

These are meant to do common tasks for all the extractors and they should be called inside the process method if needed.

Some methods may call a binary in the background, which creates a csv file. The csv file is loaded into memory and the file is deleted, unless clean=False. When recompute=False, this will first look for an existing precomputed contour file and if successful will load it directly.

Attributes

audio_samplerate	Property to get the sample rate of the output contours
min_contour_len	Property to get the minimum length of a contour in seconds
sample_rate	Property to get the sample rate of the output contours

Methods

compute_contours(input_filepath)	Method for computing features for given file
get_id()	Method to get the id of the extractor type

audio_samplerate

Property to get the sample rate of the output contours

compute_contours(input_filepath)

Method for computing features for given file

classmethod get_id()

Method to get the id of the extractor type

min_contour_len

Property to get the minimum length of a contour in seconds

sample_rate

Property to get the sample rate of the output contours

class motif.core.Contours(index, times, freqs, salience, sample_rate, audio_filepath=None, audio_duration=None)

Class containing information about all contours in a single audio file.

Attributes

nums	(list) Ordered list of contour numbers
index_mapping	(dict) Mapping from contour number to the indices into times/freqs/salience where the contour is active
index	(array) array of contour numbers
times	(array) array of contour times
freqs	(array) array of contour frequencies
salience	(array) array of contour salience values
_features	(dict) Mapping from contour number to computed features. Will not be set until the compute_features method is run
_labels	(dict) Mapping from contour number to computed ground truth labels.
_overlaps	(dict) Mapping from contour number to computed overlap with ground truth
_scores	(dict) Mapping from contour number to computed classifier score

Methods

compute_labels(annotation_fpath[, ...])	Compute overlaps with an annotation and labels for each contour.
contour_freqs(index)	Get the frequency values for a particular contour number.
contour_salience(index)	Get the salience values for a particular contour number.
contour_times(index)	Get the time stamps for a particular contour number.
coverage(annotation_fpath[, single_f0])	Compute how much the set of contours covers the annotation
save(output_fpath)	Save extracted contours to a csv file.
save_contours_subset(output_fpath, output_nums)	Save extracted contours where score >= threshold to a csv file.
to_multif0_format()	Convert contours to multi-f0 format.

compute_labels(annotation_fpath, overlap_threshold=0.5, single_f0=True)

Compute overlaps with an annotation and labels for each contour.

Parameters:

annotation_fpath : str

Path to annotation file.

overlap_threshold : float, default=0.5

The minimum amount of overlap with the annotation for a contour to be labeled as a positive example; between 0 and 1.

contour_freqs(index)

Get the frequency values for a particular contour number.

Parameters:

index : int

contour number

Returns:

contour_frequencies : array

array of contour frequency values

contour_salience(index)

Get the salience values for a particular contour number.

Parameters:

index : int

contour number

Returns:

contour_salience : array

array of contour salience values

contour_times(index)

Get the time stamps for a particular contour number.

Parameters:

index : int

contour number

Returns:

contour_times : array

array of contour times

coverage(annotation_fpath, single_f0=True)

Compute how much the set of contours covers the annotation

Parameters:

annotation_fpath : str

Path to annotation file.

single_f0 : bool

True for a file containing a single pitch per time stamp False for a file containing possibly multiple pitches / time stamp

Returns:

scores : dict

Dictionary of mutlipitch scores.

save(output_fpath)

Save extracted contours to a csv file.

Parameters:

output_fpath : str

Path to save output csv file.

save_contours_subset(output_fpath, output_nums)

Save extracted contours where score >= threshold to a csv file.

Parameters:

output_fpath : str

Path to save output csv file.

output_nums : list

List of contour numbers to save

to_multif0_format()

Convert contours to multi-f0 format.

Returns:

times : np.array

uniform time stamps

freqs : list of lists

Each row has the form [time, freq1, freq2, ...] Each row may have any number of frequencies.

class motif.core.FeatureExtractor

This class is an interface for all the feature extraction combinations included in motif. Each feature set must inherit from it and implement the following methods:

• get_feature_vector

  This should return a flat numpy array

• feature_names

  This should return a list of the same length as the above numpy array of what each dimension is. Can be as simple as an index, can be identfiers such as [‘vibrato rate’, ‘vibrato extent’]

Attributes

feature_names

Set the array of features names.

Methods

compute_all(ctr)	Compute features for all contours.
get_feature_vector(times, freqs, salience, ...)	Method for computing features for a given contour
get_id()	Method to get the id of the feature type

compute_all(ctr)

Compute features for all contours.

Parameters:

ctr : Contour

Instance of Contour object

Returns:

features : np.array [n_contours, n_features]

Feature matrix, ordered by contour number

feature_names

Set the array of features names.

get_feature_vector(times, freqs, salience, sample_rate)

Method for computing features for a given contour

classmethod get_id()

Method to get the id of the feature type

class motif.core.MetaContourClassifier

Meta-class to register the available classifiers.

Methods

__call__(...) <==> x(...)
mro(() -> list)	return a type’s method resolution order

class motif.core.MetaContourDecoder

Meta-class to register the available decoders.

Methods

__call__(...) <==> x(...)
mro(() -> list)	return a type’s method resolution order

class motif.core.MetaContourExtractor

Meta-class to register the available extractors.

Methods

__call__(...) <==> x(...)
mro(() -> list)	return a type’s method resolution order

class motif.core.MetaFeatureExtractor

Meta-class to register the available contour features.

Methods

__call__(...) <==> x(...)
mro(() -> list)	return a type’s method resolution order

Plot

Run

Code for running the full pipeline

motif.run.get_classify_module(classifier_id)

Obtains a configured Classifier given an algorithm identificator.

Parameters:

classifier_id : str

Classifier algorithm identificator (e.g., random_forest, mv_gaussian).

Returns:

module : object

Object containing the selected Classifier module. None if no extract module is needed.

motif.run.get_extract_module(extract_id)

Obtains a configured ContourExtractor given an algorithm identificator.

Parameters:

extract_id : str

Extract algorithm identificator (e.g., salamon, hll).

Returns:

module : object

Object containing the selected ContourExtractor module. None if no extract module is needed.

motif.run.get_features_module(feature_id)

Obtains a configured ContourFeatures given an algorithm identificator.

Parameters:

feature_id : str

Feature algorithm identificator (e.g., bitteli, melodia).

Returns:

module : object

Object containing the selected ContourFeatures module. None if no extract module is needed.

motif.run.get_module(module_id, module_registry)

Obtains a configured ContourFeatures given an algorithm identificator.

Parameters:

module_id : str

Module identificator (e.g., bitteli, melodia).

module_registry : dict

Dictionary of module_ids to class instances

Returns:

module : object

Object containing the selected module. None if no module is needed.

motif.run.process_with_labels(contour_extractor, feature_extractor, file_pairs)

Obtains a configured Classifier given an algorithm identificator.

Parameters:

classifier_id : str

Classifier algorithm identificator (e.g., random_forest, mv_gaussian).

Returns:

module : object

Object containing the selected Classifier module. None if no extract module is needed.

Utils

Utility methods for motif

motif.utils.format_annotation(new_times, annot_times, annot_freqs)

Format an annotation file and resample to a uniform timebase.

Parameters:

new_times : np.array

Times to resample to

annot_times : np.array

Annotation time stamps

annot_freqs : np.array

Annotation frequency values

Returns:

ref_cent : np.array

Annotation frequencies in cents at the new timescale

ref_voicing : np.array

Annotation voicings at the new timescale

motif.utils.format_contour_data(frequencies)

Convert contour frequencies to cents + voicing.

Parameters:

frequencies : np.array

Contour frequency values

Returns:

est_cent : np.array

Contour frequencies in cents

est_voicing : np.array

Contour voicings

motif.utils.get_snippet_idx(snippet, full_array)

Find the indices of full_array where snippet is present. Assumes both snippet and full_array are ordered.

Parameters:

snippet : np.array

Array of ordered time stamps

full_array : np.array

Array of ordered time stamps

Returns:

idx : np.array

Array of booleans indicating where in full_array snippet is present.

motif.utils.load_annotation(annotation_fpath, n_freqs=1, to_array=True, rm_zeros=False, delimiter=', ')

Load an annotation from a csv file.

Parameters:

annotation_fpath : str

Path to annotation file.

n_freqs : int or None

Number of frequencies to read, or None to use max

to_array : bool

If True, returns annot_freqs as a numpy array If False, returns annot_freqs as a list of lists.

Returns:

annot_times : array

Annotation time stamps

annot_freqs : array

Annotation frequency values

motif.utils.validate_contours(index, times, freqs, salience)

Check that contour input is well formed.

Parameters:

index : np.array

Array of contour numbers

times : np.array

Array of contour times

freqs : np.array

Array of contour frequencies

salience : np.array

Array of contour saliences

sample_rate : float

Contour sample rate.

audio_filepath : str

Path to audio file contours were extracted from

Contour Extractors

HLL

HLL method for extracting contours.

class motif.contour_extractors.hll.HLL(hop_size=8192, n_octaves=6, bins_per_octave=12, min_note='E1', peak_thresh=0.4, filter_scale=2.0, wait=2, avg_filt_len=12, pre_max=3, post_max=3, pre_avg=3, post_avg=3, delta=0.02, n_harmonics=5, f_cutoff=30, tracking_gain=0.0005, min_contour_len_samples=11025, amplitude_threshold=0.001, tracking_update_threshold=70.0)

Bases: motif.core.ContourExtractor

HLL method for extracting contours.

Parameters:

hop_size : int, default=8192

Seed detection CQT hop size.

bins_per_octave : int, default=12

Number of seed detection CQT bins per octave.

min_note : str, default=’E1’

Minimum seed detection CQT note.

peak_thresh : float, default=0.4

Seed detection peak picking threshold.

filter_scale : float, defualt=2.0

CQT filter scale.

wait : int >= 0, default=2

Peak-picking number of samples to wait after picking a peak.

avg_filt_len : int >= 0, default=12

Peak-picking average filter length.

pre_max : int >= 0, default=3

Peak-picking num samples before n over which max is computed

post_max : int >= 1, default=3

Peak-picking num samples after n over which max is computed

pre_avg : int >= 0, default=3

Peak-picking num samples before n over which mean is computed

post_avg : int >= 1, default=3

Peak-picking num samples after n over which mean is computed

delta : float >= 0, default=0.02

Peak-picking threshold offset for mean

n_harmonics : int, default=5

Number of HLL harmonics.

f_cutoff : float, default=30

HLL cutoff frequency in Hz.

tracking_gain : float, default=0.0005

HLL tracking gain.

min_contour_len_samples : int, default=11025

HLL minimum number of samples in a single contour.

amplitude_threshold : float, default=0.001

HLL minimum amplitude threshold.

tracking_update_threshold : float, default=70.0

HLL tracking update threshold.

Attributes

hop_size	(int) Seed detection CQT hop size.
n_cqt_bins	(int) Number of seed detection CQT bins.
bins_per_octave	(int) Number of seed detection CQT bins per octave.
min_note	(str) Minimum seed detection CQT note.
med_filt_len	(int) Seed detection frequency band median filter length.
peak_thresh	(float) Seed detection peak picking threshold.
pre_max	(int >= 0) Peak-picking number of samples before n over which max is computed
post_max	(int >= 1) Peak-picking number of samples after n over which max is computed
pre_avg	(int >= 0) Peak-picking number of samples before n over which mean is computed
post_avg	(int >= 1) Peak-picking number of samples after n over which mean is computed
delta	(float >= 0) Peak-picking threshold offset for mean
wait	(int >= 0) Peak-picking number of samples to wait after picking a peak
n_harmonics	(int) Number of HLL harmonics.
f_cutoff	(float) HLL cutoff frequency in Hz.
tracking_gain	(float) HLL tracking gain.
min_contour_len_samples	(int) HLL minimum number of samples in a single contour.
amplitude_threshold	(float) HLL minimum amplitude threshold.
tracking_update_threshold	(float) HLL tracking update threshold.

Methods

compute_contours(audio_filepath)	Compute contours using Harmonic Locked Loops.
get_id()	Identifier of this extractor.
get_seeds(audio_filepath)	Get the seeds file to pass to the HLL tracker.

audio_samplerate

Sample rate of preprocessed audio.

Returns:

audio_samplerate : float

Number of samples per second.

compute_contours(audio_filepath)

Compute contours using Harmonic Locked Loops. This calls a binary in the background, which creates a csv file. The csv file is loaded into memory and the file is deleted.

Parameters:

audio_filepath : str

Path to audio file.

Returns:

Instance of Contours object

classmethod get_id()

Identifier of this extractor.

Returns:

id : str

Identifier of this extractor.

get_seeds(audio_filepath)

Get the seeds file to pass to the HLL tracker.

Parameters:

audio_filepath : str

Path to audio file.

Returns:

seeds_fpath : str

Path to the seeds output file.

min_contour_len

Minimum allowed contour length.

Returns:

min_contour_len : float

Minimum allowed contour length in seconds.

sample_rate

Sample rate of output contours

Returns:

sample_rate : float

Number of samples per second.

Peak Streaming

Salamon’s method for extracting contours

class motif.contour_extractors.peak_stream.PeakStream(max_freq=3000.0, hop_length=128, win_length=2048, n_fft=8192, h_range=[1, 2, 3, 4, 5], h_weights=[1, 0.5, 0.25, 0.25, 0.25], interpolation_type='linear', pitch_cont=80, max_gap=0.01, amp_thresh=0.9, dev_thresh=0.9, preprocess=True, use_salamon_salience=False)

Bases: motif.core.ContourExtractor

Peak streaming based contour extraction as in [R11]

[R11]

Salamon, Justin and Gómez, Emilia, and Bonada, Jordi. “Sinusoid extraction and salience function design for predominant melody estimation.” 14th International Conference on Digital Audio Effects (DAFX11), Paris, France, 2011.

Parameters:

hop_length : int, default=128

Number of samples between frames.

win_length : int, default=2048

The window size in samples.

n_fft : int, default=8192

The fft size in samples.

h_range : list, default=[1, 2, 3, 4, 5]

The list of harmonics to use in salience function.

h_weights : list, default=[1, 0.5, 0.25, 0.25, 0.25]

The list of weights to apply to each harmonic in salience function.

pitch_cont : float, default=80

Pitch continuity threshold in cents.

max_gap : float, default=0.01

Threshold (in seconds) for how many values can be taken from S-.

amp_thresh : float, default=0.9

Threshold on how big a peak must be relative to the maximum in its frame.

dev_thresh : float, default=0.9

The maximum number of standard deviations below the mean a peak can be to survive.

preprocess : bool, default=True

If true, normalizes the volume and format of the audio before processing. Otherwise computes contours from original audio.

Attributes

max_freq	(float) The maximum frequency allowed in a contour in Hz.
hop_length	(int) Number of samples between frames.
win_length	(int) The window size in samples.
n_fft	(int) The fft size in samples.
h_range	(list) The list of harmonics to use in salience function.
h_weights	(list) The list of weights to apply to each harmonic in salience function.
interpolation_type	(str) Frequency interpolation type. See scipy.signal.interp1d for details.
pitch_cont	(float) Pitch continuity threshold in cents.
max_gap	(float) Threshold (in seconds) for how many values can be taken from S-.
amp_thresh	(float) Threshold on how big a peak must be relative to the maximum in its frame.
dev_thresh	(float) The maximum number of standard deviations below the mean a peak can be to survive.
preprocess	(bool) If true, normalizes the volume and format of the audio before processing. Otherwise computes contours from original audio.
use_salamon_salience	(bool) If true, uses salamon vamp plugin to compute salience.

Methods

compute_contours(audio_filepath)	Compute contours as in Justin Salamon’s melodia.
get_id()	Identifier of this extractor.

audio_samplerate

Sample rate of preprocessed audio.

Returns:

audio_samplerate : float

Number of samples per second.

compute_contours(audio_filepath)

Compute contours as in Justin Salamon’s melodia. This calls a vamp plugin in the background, which creates a csv file. The csv file is loaded into memory and the file is deleted.

Parameters:

audio_filepath : str

Path to audio file.

Returns:

Instance of Contours object

classmethod get_id()

Identifier of this extractor.

Returns:

id : str

Identifier of this extractor.

min_contour_len

Minimum allowed contour length.

Returns:

min_contour_len : float

Minimum allowed contour length in seconds.

n_gap

The number of time frames within the maximum gap

Returns:

n_gap : float

Number of time frames within the maximum gap.

sample_rate

Sample rate of output contours

Returns:

sample_rate : float

Number of samples per second.

Salamon

Salamon’s method for extracting contours

class motif.contour_extractors.salamon.Salamon

Bases: motif.core.ContourExtractor

Salamon’s method for extracting contours

Attributes

audio_samplerate	Sample rate of preprocessed audio.
min_contour_len	Minimum allowed contour length.
sample_rate	Sample rate of output contours

Methods

compute_contours(audio_filepath)	Compute contours as in Justin Salamon’s melodia.
get_id()	Identifier of this extractor.

audio_samplerate

Sample rate of preprocessed audio.

Returns:

audio_samplerate : float

Number of samples per second.

compute_contours(audio_filepath)

Compute contours as in Justin Salamon’s melodia. This calls a vamp plugin in the background, which creates a csv file. The csv file is loaded into memory and the file is deleted.

Parameters:

audio_filepath : str

Path to audio file.

Returns:

Instance of Contours object

classmethod get_id()

Identifier of this extractor.

Returns:

id : str

Identifier of this extractor.

min_contour_len

Minimum allowed contour length.

Returns:

min_contour_len : float

Minimum allowed contour length in seconds.

sample_rate

Sample rate of output contours

Returns:

sample_rate : float

Number of samples per second.

Feature Extractors

Bitteli

Bitteli feature extractor.

class motif.feature_extractors.bitteli.BitteliFeatures(ref_hz=55.0, poly_degree=5, min_freq=3, max_freq=30, freq_step=0.1, vibrato_threshold=0.25)

Bases: motif.core.FeatureExtractor

Bitteli feature extractor

Attributes

ref_hz	(float) Reference frequency (Hz) for converting to cents.
poly_degree	(int) Polynomial fit degree.
min_freq	(float) Minimum possible vibrato frequency (Hz).
max_freq	(float) Maximum possible vibrato frequency (Hz).
freq_step	(float) Step in Hz between frequencies to search.
vibrato_threshold	(float) Threshold on the average vibrato residual to be considered vibrato.

Methods

compute_all(ctr)	Compute features for all contours.
get_feature_vector(times, freqs_hz, ...)	Get feature vector for a contour.
get_id()	The FeatureExtractor identifier

compute_all(ctr)

Compute features for all contours.

Parameters:

ctr : Contour

Instance of Contour object

Returns:

features : np.array [n_contours, n_features]

Feature matrix, ordered by contour number

feature_names

Get feature names.

Returns:

feature_names : list

List of feature names.

get_feature_vector(times, freqs_hz, salience, sample_rate)

Get feature vector for a contour.

Parameters:

times : np.array

Contour times

freqs_hz : np.array

Contour frequencies (Hz)

salience : np.array

Contour salience

sample_rate : float

Contour sample rate.

Returns:

feature_vector : np.array

Feature vector.

classmethod get_id()

The FeatureExtractor identifier

Returns:

id : string

class identifier

Cesium

Celsium feature extractor.

class motif.feature_extractors.cesium.CesiumFeatures

Bases: motif.core.FeatureExtractor

Cesium feature extractor

Attributes

feature_names

Get feature names.

Methods

compute_all(ctr)	Compute features for all contours.
get_feature_vector(times, freqs_hz, ...)	Get feature vector for a contour.
get_id()	The FeatureExtractor identifier

compute_all(ctr)

Compute features for all contours.

Parameters:

ctr : Contour

Instance of Contour object

Returns:

features : np.array [n_contours, n_features]

Feature matrix, ordered by contour number

feature_names

Get feature names.

Returns:

feature_names : list

List of feature names.

get_feature_vector(times, freqs_hz, salience, sample_rate)

Get feature vector for a contour.

Parameters:

times : np.array

Contour times

freqs_hz : np.array

Contour frequencies (Hz)

salience : np.array

Contour salience

sample_rate : float

Contour sample rate.

Returns:

feature_vector : np.array

Feature vector.

classmethod get_id()

The FeatureExtractor identifier

Returns:

id : string

class identifier

Melodia

Melodia feature extractor.

class motif.feature_extractors.melodia.MelodiaFeatures(ref_hz=55.0)

Bases: motif.core.FeatureExtractor

Melodia feature extractor

Attributes

ref_hz

(float) Reference frequency (Hz) for converting to cents.

Methods

compute_all(ctr)	Compute features for all contours.
get_feature_vector(times, freqs_hz, ...)	Get feature vector for a contour.
get_id()	The FeatureExtractor identifier

compute_all(ctr)

Compute features for all contours.

Parameters:

ctr : Contour

Instance of Contour object

Returns:

features : np.array [n_contours, n_features]

Feature matrix, ordered by contour number

feature_names

Get feature names.

Returns:

feature_names : list

List of feature names.

get_feature_vector(times, freqs_hz, salience, sample_rate)

Get feature vector for a contour.

Parameters:

times : np.array

Contour times

freqs_hz : np.array

Contour frequencies (Hz)

salience : np.array

Contour salience

sample_rate : float

Contour sample rate.

Returns:

feature_vector : np.array

Feature vector.

classmethod get_id()

The FeatureExtractor identifier

Returns:

id : string

class identifier

Utils

Utility functions for computing contour features. Each of these functions computes single sets of contour features using information such as the times, frequencies, salience, sample rate, etc.

Each function returns a flattened numpy array for easy concatenation.

@author: mariapanteli, rabitt

motif.feature_extractors.utils.get_contour_duration(times)

Get contour duration in seconds

Parameters:

times : np.array

Array of contour times

Returns:

duration : float

Duration in seconds

motif.feature_extractors.utils.get_contour_offset(times)

Get the last time stamp of a contour

Parameters:

times : np.array

Array of contour times

Returns:

offset : float

The contour offset in seconds

motif.feature_extractors.utils.get_contour_onset(times)

Get the first time stamp of a contour

Parameters:

times : np.array

Array of contour times

Returns:

onset : float

The contour onset in seconds

motif.feature_extractors.utils.get_contour_shape_features(times, freqs, sample_rate, poly_degree=5, min_freq=3, max_freq=30, freq_step=0.1, vibrato_threshold=0.25)

Fit contour to a low order polynomial plus sinusoidal vibrato.

Parameters:

times : np.array

Sequence of contour times

freqs : np.array

Sequence of contour frequencies

sample_rate : float

Contour sample rate

poly_degree : float, default=5

Low order polynomial degree

min_freq : float, default=3

The minimum allowed vibrato frequency

max_freq : float, default=30

The maximum allowed vibrato frequency

freq_step : float, default=0.1

The step size between vibrato search frequencies

vibrato_threshold : float, default=0.25

The fitness threshold for a half period to be considered vibrato. Regions with normalized fitness differences below vibrato_threshold are considered to have vibrato.

Returns:

features : np.array

Array of feautres. Elements (in order) are:

• vibrato rate (in Hz)
• vibrato extent (in the same units as freqs)
• vibrato coverage (between 0 and 1)
• vibrato coverage beginning (between 0 and 1)
• vibrato coverage middle (between 0 and 1)
• vibrato coverage end (between 0 and 1)
• 0th polynomial coefficient
• 1st polynomial coefficient
• ...
• Kth polynomial coefficient (K = poly_degree)
• polynomial fit residual
• overall model fit residual

motif.feature_extractors.utils.get_mean(signal)

Get the mean of a signal.

Parameters:

signal : np.array

Array of values

Returns:

mean : float

The mean of the signal

motif.feature_extractors.utils.get_polynomial_fit_features(times, signal, n_deg=5, norm=False)

Fit a signal to a polynomial, return coefficients of polynomial and residual error.

Parameters:

times : np.array

Array of contour times.

signal : np.array

Array of values to fit.

n_deg : int, default=5

Number of polynomial degrees to fit.

norm : bool, default=False

If True, scales the signal to be between 0 and 1 If False, the signal is not altered.

Returns:

poly_coeff : np.array

The coefficients of the polynomial.

poly_approx : np.array

The polynomial approximation of the signal.

residual : np.array

The pointwise difference between the signal and the polynomial.

motif.feature_extractors.utils.get_range(signal)

Get the range of a signal.

Parameters:

signal : np.array

Array of values

Returns:

range : float

The range of the signal

motif.feature_extractors.utils.get_std(signal)

Get the standard deviation of a signal.

Parameters:

signal : np.array

Array of values

Returns:

std : float

The standard deviation of the signal

motif.feature_extractors.utils.get_sum(signal)

Get the sum of a signal.

Parameters:

signal : np.array

Array of values

Returns:

sum : sum of the signal

motif.feature_extractors.utils.get_total_variation(signal)

Get the total variation of a signal.

Parameters:

signal : np.array

Array of values

Returns:

total_variation : float

The total variation of the signal

motif.feature_extractors.utils.hz_to_cents(freq_hz, ref_hz=32.0)

Convert frequency values from Hz to cents

Parameters:

freq_hz : np.array

Array of contour frequencies in Hz

ref_hz : float

Reference frequency in Hz

Returns:

freq_cents : np.array

Array of contour frequencies in cents

motif.feature_extractors.utils.vibrato_essentia(freqs, sample_rate, hop_size=1)

Estimate vibrato parameters as in essentia.

Warning: These features work but aren’t very precise (e.g a perfect 12 Hz sine wav estimates a rate of 9.8).

Parameters:

freqs : np.array

Sequence of contour frequencies

sample_rate : float

Contour sample rate

hop_size : int, default=1

Number of samples to advance each frame

Returns:

features : np.array

Array of feautres. Elements (in order) are:

• vibrato active (1 if active, 0 if not)
• vibrato rate (in Hz, 0 if inactive)
• vibrato extent (in the same units as freqs, 0 if inactive)
• vibrato coverage (between 0 and 1, 0 if inactive)

Contour Classifiers

Multivariate Gaussian

Multivariate Gaussian contour classifier.

class motif.contour_classifiers.mv_gaussian.MvGaussian

Bases: motif.core.ContourClassifier

Multivariate Gaussian contour classifier.

Attributes

rv_pos	(scipy.stats._multivariate.multivariate_normal_gen) A multivariate gaussian modeling the positive class
rv_neg	(scipy.stats._multivariate.multivariate_normal_gen) A multivariate gaussian modeling the negative class
n_feats	(int) The number of features
lmbda	(np.array) Array of length n_features with the optimal lambda.

Methods

fit(X, Y)	Fit class-dependent multivariate gaussians on the training set.
get_id()	The ContourClassifier identifier
predict(X)	Compute melodiness score.
score(y_predicted, y_target[, y_prob])	Compute metrics on classifier predictions

fit(X, Y)

Fit class-dependent multivariate gaussians on the training set.

Parameters:

x_train_boxcox : np.array [n_samples, n_features_trans]

Transformed training features.

y_train : np.array [n_samples]

Training labels.

Returns:

rv_pos : multivariate normal

multivariate normal for melody class

rv_neg : multivariate normal

multivariate normal for non-melody class

classmethod get_id()

The ContourClassifier identifier

Returns:

id : string

class identifier

predict(X)

Compute melodiness score.

Parameters:

X : np.array [n_samples, n_features]

Features.

Returns:

p : np.array [n_samples]

melodiness scores

score(y_predicted, y_target, y_prob=None)

Compute metrics on classifier predictions

Parameters:

y_predicted : np.array [n_samples]

Predicted class labels

y_target : np.array [n_samples]

Target class labels

y_prob : np.array [n_samples] or None, default=None

predicted probabilties. If None, auc is not computed

Returns:

scores : dict

dictionary of scores for the following metrics: accuracy, matthews correlation coefficient, precision, recall, f1, support, confusion matrix, auc score

threshold

The threshold determining the positive class.

Returns:

threshold : flaot

melodiness scores

Random Forest

Random Forest contour classifier.

class motif.contour_classifiers.random_forest.RandomForest(n_estimators=50, n_jobs=-1, class_weight='balanced', n_iter_search=100, random_state=None)

Bases: motif.core.ContourClassifier

Random Forest contour classifier.

Attributes

n_estimators	(int) Number of trees in the forest
n_jobs	(int) Number of cores to use. -1 uses maximum availalbe
class_weight	(str) How to set class weights.
max_features	(int or None) The maximum number of features that can be used in a single branch.
max_param	(int) Maximum depth value to sweep
param_step	(int) Step size in parameter sweep
clf	(sklearn.ensemble.RandomForestClassifier) Classifier
max_depth	(int) The max_depth parameter chosen by cross validation.

Methods

fit(X, Y)	Train classifier.
get_id()	The ContourClassifier identifier
predict(X)	Compute probability predictions.
predict_discrete_label(X)	Compute discrete class predictions.
score(y_predicted, y_target[, y_prob])	Compute metrics on classifier predictions

fit(X, Y)

Train classifier.

Parameters:

X : np.array [n_samples, n_features]

Training features.

Y : np.array [n_samples]

Training labels

classmethod get_id()

The ContourClassifier identifier

Returns:

id : string

class identifier

predict(X)

Compute probability predictions.

Parameters:

X : np.array [n_samples, n_features]

Features.

Returns:

p : np.array [n_samples]

predicted probabilities

predict_discrete_label(X)

Compute discrete class predictions.

Parameters:

X : np.array [n_samples, n_features]

Features.

Returns:

Y_pred : np.array [n_samples]

predicted classes

score(y_predicted, y_target, y_prob=None)

Compute metrics on classifier predictions

Parameters:

y_predicted : np.array [n_samples]

Predicted class labels

y_target : np.array [n_samples]

Target class labels

y_prob : np.array [n_samples] or None, default=None

predicted probabilties. If None, auc is not computed

Returns:

scores : dict

dictionary of scores for the following metrics: accuracy, matthews correlation coefficient, precision, recall, f1, support, confusion matrix, auc score

threshold

The threshold determining the positive class.

Returns:

threshold : flaot

melodiness scores

Contour Decoders

Maximum

Maximum contour decoder.

class motif.contour_decoders.maximum.MaxDecoder(thresh=0.5, use_salience=False)

Bases: motif.core.ContourDecoder

Maximum contour decoder.

Methods

decode(ctr, Y)
get_id()

Viterbi

Viterbi contour decoder.

class motif.contour_decoders.viterbi.ViterbiDecoder

Bases: motif.core.ContourDecoder

Viterbi contour decoder.

Methods

decode(ctr, Y)
get_id()