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)[source]¶ Bases:
object
Hold data from multiple
IndexedPiece
instances.-
class
Metadata
[source]¶ 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)[source]¶ Get the results of an
Indexer
or anExperimenter
run on all theIndexedPiece
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 withget_data()
from theIndexedPiece
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 ofpandas.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 thedata
argument was calculated on this indexed_piece.
Returns: Results of the analyzer.
Return type: Depending on the
analyzer_cls
, either apandas.DataFrame
or more often a list ofpandas.DataFrame
.Returns: Either one
pandas.DataFrame
with all experimental results or a list ofDataFrame
objects, each with the experimental results for one piece.Raises: TypeError
if an analyzer is invalid or cannot be found.
-
AggregatedPieces.
metadata
(field)[source]¶ 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 indate_range
unless there are no dates. If you need full metadata, we recommend running an Indexer that requires aScore
object on all the IndexedPieces (likevis.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 afield that has not yet been initialized in the IndexedPieces.Return type: object or None Raises: TypeError
iffield
is not a str.
-
class
indexed_piece
Module¶
This model represents an indexed and analyzed piece of music.
-
vis.models.indexed_piece.
Importer
(location, metafile=None)[source]¶ 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 anAggregatedPieces
object if the file passed imports as amusic21.stream.Score
ormusic21.stream.Opus
object respectively.Return type: A new IndexedPiece
orAggregatedPieces
object.
-
class
vis.models.indexed_piece.
IndexedPiece
(pathname='', opus_id=None, score=None, metafile=None, username=None, password=None)[source]¶ 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)[source]¶ 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 apandas.DataFrame
or a list ofpandas.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 thedata
argument was calculated on this indexed_piece.
Returns: Results of the analyzer.
Return type: Usually
pandas.DataFrame
or list ofpandas.Series
.Raises: RuntimeWarning
if theanalyzer_cls
is invalid or cannot be found.Raises: RuntimeError
if the first analyzer class inanalyzer_cls
does not useScore
objects, anddata
isNone
.
-
measure_index
(dataframe)[source]¶ 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)[source]¶ 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 returnNone
. We guarantee real values forpathname
,title
, andparts
.Parameters: - field (str) – The name of the field to be accessed or modified.
- value (object or
None
) – If notNone
, the value to be assigned tofield
.
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
iffield
is not a string.Raises: AttributeError
if accessing an invalidfield
(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’, ... ]
-