models Package

models Package

aggregated_pieces Module

The model representing data from multiple IndexedPiece instances.

class vis.models.aggregated_pieces.AggregatedPieces(pieces=None, metafile=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(ind_analyzer=None, combined_experimenter=None, settings=None, data=None)

Get the results of an Indexer or an Experimenter run on all the IndexedPiece objects either individually, or all together. If settings are provided, the same settings dict will be used throughout.

In VIS, analyzers are broken down into two categories: Indexers which associate observations with a specific moment in a piece, and Experimenters which still work with musical observations, but do not associate them with a specific moment in a specific IndexedPiece. For example, the noterest.NoteRestIndexer associates each note and rest with a time point in a given IndexedPiece, but if we then use the frequency.FrequencyExperimenter to count the number of times each type of note or rest happens, these counts will not and cannot be associated with a specific time point.

All VIS Indexers and most Experimenters run on each piece individually, and so if these results are desired, the analyzer in question should be assigned to the ind_analyzer argument. The barchart.RBarChart and aggregator.ColumnAggregator experimenters often combine the data of several pieces together. The frequency.FrequencyExperimenter can also be used this way. If this is the desired behavior, supply the appropriate Experimenter as the combined_experimenter argument.

Examples

Note

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

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

Parameters:

• ind_analyzer (str or VIS Indexer or Experimenter class.) – The analyzer to run.
• settings (dict) – Settings to be used with the analyzer. Only use if necessary.
• data (Depends on the requirement of the analyzer designated by the analyzer_cls argument. Usually a list of pandas.DataFrame.) – Input data for the analyzer to run. If this is provided for an indexer that normally caches its results (such as the NoteRestIndexer, the DurationIndexer, etc.), the results will not be cached since it is uncertain if the input passed in the data argument was calculated on this indexed_piece.

Returns:

Results of the analyzer.

Return type:

Depending on the analyzer_cls, either a pandas.DataFrame or more often a list of pandas.DataFrame.

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 :param field: The name of the field to be accessed or modified. :type field: str :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 str.

indexed_piece Module

This model represents an indexed and analyzed piece of music.

vis.models.indexed_piece.Importer(location, metafile=None)

Import the file, website link, or directory of files designated by location to music21 format.

Parameters:location (str) – Location of the file to import on the local disk. Returns:An IndexedPiece or an AggregatedPieces object if the file passed imports as a music21.stream.Score or music21.stream.Opus object respectively. Return type:A new IndexedPiece or AggregatedPieces object.

class vis.models.indexed_piece.IndexedPiece(pathname='', opus_id=None, score=None, metafile=None, username=None, password=None)

Bases: object

Hold indexed data from a musical score, and the score itself. IndexedPiece objects are VIS’s basic representations of a piece of music and also a container for metadata and analyses about that piece. An IndexedPiece object should be created by passing the pathname of a symbolic notation file to the Importer() method in this file. The Importer() will return an IndexedPiece object as long as the piece did not import as an opus. In this case Importer() will return an AggregatedPieces object. Information about an IndexedPiece object from an indexer or an experimenter should be requested via the get_data() method. If you want to access the full music21 score object of a VIS IndexedPiece object, access the _score attribute of the IndexedPiece object. See the examples below:

Examples # Creat an IndexedPiece object from vis.models.indexed_piece import Importer ip = Importer(‘path_to_file.xml’)

# Get the results of an indexer or experimenter (noterest and dissonance indexers shown) noterest_results = ip.get_data(‘noterest’) dissonance_results = ip.get_data(‘dissonance’)

# Access the full music21 score object of the file ip._score

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

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

Parameters:

• analyzer_cls (str or VIS Indexer or Experimenter class.) – The analyzer to run.
• settings (dict) – Settings to be used with the analyzer. Only use if necessary.
• data (Depends on the requirement of the analyzer designated by the analyzer_cls argument. Usually a pandas.DataFrame or a list of pandas.Series.) – Input data for the analyzer to run. If this is provided for an indexer that normally caches its results (such as the NoteRestIndexer, the DurationIndexer, etc.), the results will not be cached since it is uncertain if the input passed in the data argument was calculated on this indexed_piece.

Returns:

Results of the analyzer.

Return type:

Usually pandas.DataFrame or list of pandas.Series.

Raises:

RuntimeWarning 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.

load_url(url)

measure_index(dataframe)

Multi-indexes the index of the passed dataframe by adding the measures to the offsets. The passed dataframe should be of an indexer’s results, not an experimenters. Also adds index labels. Note that this method currently does not work with midi files, because VIS cannot detect measures in midi files since they are not encoded in midi. Also note that this method should ideally only be used at the end of a set of analysis steps, because there is no guarantee that the resultant multi-indexed dataframe will not cause problems if passed to a subsequent indexer.

Example from vis.models.indexed_piece import Importer() # Make an IndexedPiece object out of a symbolic notation file: ip = Importer(‘path_to_file.xml’) # Get some results from an indexer (not an experimenter): df = ip.get_data(‘horizontal_interval’) # Multi-index the dataframe index by adding the measure informaiton: ip.measure_index(df)

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 (str) – 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 string)

Raises:

TypeError if field is not a string.

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().

vis.models.indexed_piece.auth_get(url, csrftoken, sessionid)

Use a csrftoken and sessionid to request a url on the elvisdatabase.

vis.models.indexed_piece.login_edb(username, password)

Return csrf and session tokens for a login.