models Package

models Package

aggregated_pieces Module

The model representing data from multiple IndexedPiece instances.

class vis.models.aggregated_pieces.AggregatedPieces(pieces=None)

Bases: object

Hold data from multiple IndexedPiece instances.

class Metadata

Bases: object

Used internally by AggregatedPieces ... at least for now.

Hold aggregated metadata about the IndexedPieces in an AggregatedPiece. Every list has no duplicate entries.

• composers: list of all the composers in the IndexedPieces
• dates: list of all the dates in the IndexedPieces
• date_range: 2-tuple with the earliest and latest dates in the IndexedPieces
• titles: list of all the titles in the IndexedPieces
• locales: list of all the locales in the IndexedPieces
• pathnames: list of all the pathnames in the IndexedPieces

composers

date_range

dates

locales

pathnames

titles

AggregatedPieces.get_data(independent_analyzers, aggregated_experiments, settings=None, data=None)

Get the results of an Experimenter run on all the IndexedPiece objects. You must specify all indexers and experimenters to be run to get the results you want.

The same settings dict will be given to all experiments and indexers.

If you want the results from all IndexedPiece objects separately, provide an empty list as the aggregated_experiments argument.

Either the first analyzer in independent_analyzers should use a music21.stream.Score or you must provide an argument for data that is the output from a previous call to this instance’s get_data() method.

Examples

Run analyzer A then B on each piece individually, then provide a list of those results to Experimenter C then D::

>>> pieces.get_data([A, B], [C, D])

Run analyzer A then B on each piece individually, then return a list of those results::

>>> pieces.get_data([A, B])

Run experimenter A then B on the results of a previous get_data() call::

>>> piece.get_data([], [C, D], data=previous_results)

Note

The analyzers in the independent_analyzers argument are run with get_data() from the IndexedPiece objects themselves. Thus any exceptions raised there may also be raised here.

Parameters:

• independent_analyzers (list of types) – The analyzers to run on each piece before aggregation, in the order you want to run them. For no independent analyzers, use [] or None.
• aggregated_experiments (list of types) – The Experimenters to run on aggregated data of all pieces, in the order you want to run them.
• settings (dict) – Settings to be used with the analyzers.
• data (pandas.DataFrame or list of DataFrame) – Input data for the first analyzer to run. If this argument is not None, you must provide the output from a previous call to get_data() of this instance.

Returns:

Either one pandas.DataFrame with all experimental results or a list of DataFrame objects, each with the experimental results for one piece.

Raises:

TypeError if an analyzer is invalid or cannot be found.

AggregatedPieces.metadata(field)

Get a metadatum about the IndexedPieces stored in this AggregatedPieces.

If only some of the stored IndexedPieces have had their metadata initialized, this method returns incompelete metadata. Missing data will be represented as None in the list, but it will not appear in date_range unless there are no dates. If you need full metadata, we recommend running an Indexer that requires a Score object on all the IndexedPieces (like vis.analyzers.indexers.noterest.NoteRestIndexer).

Valid fields are:

• 'composers: list of all the composers in the IndexedPieces
• 'dates: list of all the dates in the IndexedPieces
• 'date_range: 2-tuple with the earliest and latest dates in the IndexedPieces
• 'titles: list of all the titles in the IndexedPieces
• 'locales: list of all the locales in the IndexedPieces
• 'pathnames: list of all the pathnames in the IndexedPieces

Parameters:field (basestring) – The name of the field to be accessed or modified. Returns:The value of the requested field or None, if accessing a non-existant field or a field that has not yet been initialized in the IndexedPieces. Return type:object or None Raises:TypeError if field is not a basestring.

indexed_piece Module

This model represents an indexed and analyzed piece of music.

class vis.models.indexed_piece.IndexedPiece(pathname, opus_id=None)

Bases: object

Hold indexed data from a musical score.

get_data(analyzer_cls, settings=None, data=None, known_opus=False)

Get the results of an Experimenter or Indexer run on this IndexedPiece.

Parameters:

• analyzer_cls (list of type) – The analyzers to run, in the order they should be run.
• settings (dict) – Settings to be used with the analyzers.
• data (list of pandas.Series or pandas.DataFrame) – Input data for the first analyzer to run. If the first indexer uses a Score, you should leave this as None.
• known_opus (boolean) – Whether the caller knows this file will be imported as a music21.stream.Opus object. Refer to the “Note about Opus Objects” below.

Returns:

Results of the analyzer.

Return type:

pandas.DataFrame or list of pandas.Series

Raises:

TypeError if the analyzer_cls is invalid or cannot be found.

Raises:

RuntimeError if the first analyzer class in analyzer_cls does not use Score objects, and data is None.

Raises:

OpusWarning if the file imports as a music21.stream.Opus object and known_opus is False.

Raises:

OpusWarning if known_opus is True but the file does not import as an Opus.

Note about Opus Objects

Correctly importing Opus objects is a little awkward because we only know a file imports to an Opus after we import it, but an Opus should be treated as multiple IndexedPiece objects.

We recommend you handle Opus objects like this:

1. Try to call get_data() on the IndexedPiece.
2. If get_data() raises an OpusWarning, the file contains an Opus.
3. Call get_data() again with the known_opus parameter set to True.
4. get_data() will return multiple IndexedPiece objects, each corresponding to a Score held in the Opus.
5. Then call get_data() on the new IndexedPiece objects to get the results initially desired.

Refer to the source code for vis.workflow.WorkflowManager.load() for an example implementation.

metadata(field, value=None)

Get or set metadata about the piece.

Note

Some metadata fields may not be available for all pieces. The available metadata fields depend on the specific file imported. Unavailable fields return None. We guarantee real values for pathname, title, and parts.

Parameters:

• field (basestring) – The name of the field to be accessed or modified.
• value (object or None) – If not None, the value to be assigned to field.

Returns:

The value of the requested field or None, if assigning, or if accessing a non-existant field or a field that has not yet been initialized.

Return type:

object or None (usually a basestring)

Raises:

TypeError if field is not a basestring.

Raises:

AttributeError if accessing an invalid field (see valid fields below).

Metadata Field Descriptions

All fields are taken directly from music21 unless otherwise noted.

Metadata Field	Description
alternativeTitle	A possible alternate title for the piece; e.g. Bruckner’s Symphony No. 8 in C minor is known as “The German Michael.”
anacrusis	The length of the pick-up measure, if there is one. This is not determined by music21.
composer	The author of the piece.
composers	If the piece has multiple authors.
date	The date that the piece was composed or published.
localeOfComposition	Where the piece was composed.
movementName	If the piece is part of a larger work, the name of this subsection.
movementNumber	If the piece is part of a larger work, the number of this subsection.
number	Taken from music21.
opusNumber	Number assigned by the composer to the piece or a group containing it, to help with identification or cataloguing.
parts	A list of the parts in a multi-voice work. This is determined partially by music21.
pathname	The filesystem path to the music file encoding the piece. This is not determined by music21.
title	The title of the piece. This is determined partially by music21.

Examples

>>> piece = IndexedPiece('a_sibelius_symphony.mei')
>>> piece.metadata('composer')
'Jean Sibelius'
>>> piece.metadata('date', 1919)
>>> piece.metadata('date')
1919
>>> piece.metadata('parts')
['Flute 1'{'Flute 2'{'Oboe 1'{'Oboe 2'{'Clarinet 1'{'Clarinet 2', ... ]

exception vis.models.indexed_piece.OpusWarning

Bases: exceptions.RuntimeWarning

The OpusWarning is raised by IndexedPiece.get_data() when known_opus is False but the file imports as a music21.stream.Opus object, and when known_opus is True but the file does not import as a music21.stream.Opus object.

Internally, the warning is actually raised by IndexedPiece._import_score().