MTCFeatures.MTCFeatureLoader¶

class MTCFeatures.MTCFeatureLoader(jsonpath)¶

Class for loading and processing melody sequences.

Parameters: jsonpath (string) – Either the filename of a .jsonl file containing melody sequences, or one of the predefined names 'MTC-ANN-2.0.1', 'MTC-FS-INST-2.0', or 'ESSEN'. If the filename ends with .gz, the data file is assumed to be gzipped.

jsonpath¶

The filename of a .jsonl file containing melody sequences. If the filename ends with .gz, the file is gunzipped first.

Type: string

filterBank¶

A dictionary of (lambda) functions to be used to filter the sequences. The keys are the names of the filters. A filter can be applied with the applyFilter or applyFilters methods. The filerBank is initially populated with a number of predefined filters. A filter can be added to the filterBank with the registerFilter method.

Type: dictionary

featureExtractors¶

A dictionary of (lambda) functions that compute new features from existing features.

Type: dictionary

NoneReplacers¶

A dictionary of (lambda) functions, each taking a list of feature values and returning the list with all occurrences of None replaced with a value. The keys are names of features. The NoneReplacers dict is used by the method replaceNone. For each feature for which a NoneReplacer is present in the NoneReplacers dictionary, this NoneReplacer is applied.

Type: dictionary

__init__(jsonpath)¶: Initialize self. See help(type(self)) for accurate signature.

Methods

`__init__`(jsonpath)	Initialize self.
`addMTCFeatureExtractors`()
`addMTCFilters`()
`addNoneReplacers`()
`applyFeatureExtractor`(name[, seq_iter])	Apply a Feature Extractor.
`applyFilter`(mfilter[, invert, seq_iter])	Apply a melody filter.
`applyFilters`(filter_list[, seq_iter])	Apply a chain of filters.
`concatAllFeatures`([name, seq_iter])
`extractFeature`(name, func, feats[, seq_iter])
`getFeatureNames`()	Get the names of the features present in the Melody Sequences.
`head`([n, seq_iter])	Yields the first n melodies.
`maxClassSizeFilter`(classfeature[, maxsize, …])	Keep only melodies in tune families with <= `maxsize` members.
`merge_sequences`(from_file[, seq_iter])	Merges features from provided file.
`minClassSizeFilter`(classfeature[, minsize, …])	Keep only melodies in tune families with >= `minsize` members.
`randomSel`([n, seq_iter])	Returns a random sample of n melodies.
`registerFeatureExtractor`(name, func, feats)	Store a Feature Extractor.
`registerFilter`(name, mfilter)	Store a filter in filterBank.
`replaceNone`([seq_iter])	Replace None values with sensible fall back values.
`selectFeatures`(featlist[, seq_iter])	Feature filter.
`sequences`()	Yields the list of melodies from the file jsonpath.
`tail`([n, seq_iter])	Returns the last n melodies.
`writeJSON`(json_out_path, seq_iter)	Writes a list of melodies to a .jsonl file

applyFeatureExtractor(name, seq_iter=None)¶

Apply a Feature Extractor.

Parameters

name (string) – name with which the feature extractor was registered.
seq_iter (iterable or None, default=None) – iterable over melody sequences. If None, take the sequences from jsonpath.

Yields

sequence – Melody Sequence with extracted feature included.

applyFilter(mfilter, invert=False, seq_iter=None)¶

Apply a melody filter. Only keep those melodies that are passed by the filter.

Parameters

mfilter (string or tuple) – Name of the filter as registered in filterBank. If the filter has arguments, this should be a tuple of the filter name and the arguments.
invert (bool, default=False) – If True, invert the filter. Only keep those melodies for which the condition is False.
seq_iter (iterable or None, default=None) – iterable over melody sequences. If None, take the sequences from jsonpath.

Yields

sequence – Melody Sequence that is passed by the filter.

applyFilters(filter_list, seq_iter=None)¶

Apply a chain of filters. Only keep those melodies that are passed by all filters.

Example

from MTCFeatures import MTCFeatureLoader
fsinst_dl = MTCFeatureLoader('MTC-FS-INST-2.0')
vocal_seqs = fsinst_dl.applyFilters([
    {'mfilter':'freemeter', 'invert':True},
    {'mfilter':"vocal"},
    {'mfilter':("afteryear",1850)} ]
)

Now vocal_seqs is an iterator over all vocal melodies published after 1850 that do not have free meter,

Parameters

filter_list (**kwargs for applyFilter) – Chains a number of applyFilter calls with **kwargs as provided.
seq_iter (iterable or None, default=None) – iterable over melody sequences. If None, take the sequences from jsonpath.

Yields

sequence – Melody Sequence that is passed by the filter.

getFeatureNames()¶

Get the names of the features present in the Melody Sequences.

Returns: featnames – Names of the features as present in the FIRST melody in source file jsonpath.
Return type: list of strings

head(n=10, seq_iter=None)¶

Yields the first n melodies.

Parameters

n (int, default=10) – the number of sequences to yield.
seq_iter (iterable or None, default=None) – iterable over melody sequences. If None, take the sequences from jsonpath.

Yields

sequence – Melody Sequence

maxClassSizeFilter(classfeature, maxsize=9223372036854775807, seq_iter=None)¶

Keep only melodies in tune families with <= maxsize members.

Parameters

classfeature (string) – name of the feature that is used to group the melodies.
maxsize (int, default=sys.maxsize) – Maximum size of classes to keep.
seq_iter (iterable or None, default=None) – iterable over melody sequences. If None, take the sequences from jsonpath.

Yields

sequence – Melody Sequence for melody in a class with maximum size maxsize.

merge_sequences(from_file, seq_iter=None)¶

Merges features from provided file.

Parameters

from_file (string) – File name of a .jsonl file from which the feature sequences will be imported.
seq_iter (iterable or None, default=None) – iterable over melody sequences. If None, take the sequences from jsonpath.

Yields

sequence – Melody Sequence with features from from_file included.

minClassSizeFilter(classfeature, minsize=0, seq_iter=None)¶

Keep only melodies in tune families with >= minsize members.

Parameters

classfeature (string) – name of the feature that is used to group the melodies.
minsize (int, default=0) – Minimum size of classes to keep.
seq_iter (iterable or None, default=None) – iterable over melody sequences. If None, take the sequences from jsonpath.

Yields

sequence – Melody Sequence for melody in a class with minimum size minsize.

randomSel(n=10, seq_iter=None)¶

Returns a random sample of n melodies.

Parameters

n (int, default=10) – the number of sequences to yield.
seq_iter (iterable or None, default=None) – iterable over melody sequences. If None, take the sequences from jsonpath.

Yields

sequence – Melody Sequence

registerFeatureExtractor(name, func, feats)¶

Store a Feature Extractor.

The feature extractor will be applied for each note separately. The provided func will be called with the values of the indicated features in feats as arguments. and the sequence of computed values will be stored in the features dictionary of the Melody Sequence with name as key.

Example

from MTCFeatures import MTCFeatureLoader
dl = MTCFeatureLoader('MTC-ANN-2.0.1')
dl.registerFeatureExtractor(
    'midi8va',
    lambda x: x+12,
    ['midipitch']
)
seq_iter = dl.applyFeatureExtractor('midi8va')

Parameters

name (string) – name of the feature extractor.
func (function) – (lambda) function taking feature values for one note and computing the value for the new feature.
feats (list of strings) – names of the features that are the input for func.

registerFilter(name, mfilter)¶

Store a filter in filterBank.

Example

from MTCFeatures import MTCFeatureLoader
fsinst_dl = MTCFeatureLoader('MTC-FS-INST-2.0')
dl.registerFilter("vocal", lambda x: x["type"] == "vocal")
dl.registerFilter("afteryear", lambda y: lambda x: x["year"] > y)

Now the filter vocal is registered that passes all melodies with type vocal. And filter afteryear with parameter y is registered that passes all melodies published after year y. The filters can be applied with the method applyFilter

Parameters

name (string) – name of the filter. This will be used as key in the filterBank dictionary.
mfilter (function) – Function that evaluates to True for melodies to be kept.

replaceNone(seq_iter=None)¶

Replace None values with sensible fall back values.

For all features for which a NoneReplacer has been registered, replace the None values with sensible fall back values according to the NoneReplacer.

Parameters: seq_iter (iterable or None, default=None) – iterable over melody sequences. If None, take the sequences from jsonpath.
Yields: sequence – Melody Sequence with None values replaced

selectFeatures(featlist, seq_iter=None)¶

Feature filter. For all melodies, keep only the indicated features.

Parameters

featlist (list of strings) – Names of the features to keep.
seq_iter (iterable or None, default=None) – iterable over melody sequences. If None, take the sequences from jsonpath.

Yields

sequence – Melody Sequence with reduced feature set.

sequences()¶

Yields the list of melodies from the file jsonpath.

Yields: sequence – Melody Sequence

tail(n=10, seq_iter=None)¶

Returns the last n melodies.

Parameters

n (int, default=10) – the number of sequences to yield.
seq_iter (iterable or None, default=None) – iterable over melody sequences. If None, take the sequences from jsonpath.

Yields

sequence – Melody Sequence

static writeJSON(json_out_path, seq_iter)¶

Writes a list of melodies to a .jsonl file

Parameters

json_out_path (string) – Name of the file to write the json representations of the melodies. If the filename ends with .gz, the file is gzipped.
seq_iter (iterable over melody sequences) – Melody sequences to write to the file.