vis

• analyzers Package
  • analyzers Package
  • experimenter Module
  • indexer Module
  • Subpackages
    • experimenters Package
      • experimenters Package
      • aggregator Module
      • frequency Module
      • template Module
    • indexers Package
      • indexers Package
      • interval Module
      • ngram Module
      • noterest Module
      • offset Module
      • repeat Module
      • template Module
• models Package
  • models Package
  • aggregated_pieces Module
  • indexed_piece Module

workflow Module

The workflow module holds the WorkflowManager, which automates several common music analysis patterns for counterpoint. The TemplateWorkflow class is a template for writing new WorkflowManager classes.

class vis.workflow.WorkflowManager(pathnames)

Bases: object

Parameters:pathnames (list of basestring) – A list of pathnames.

The WorkflowManager automates several common music analysis patterns for counterpoint. Use the WorkflowManager with these four tasks:

• load(), to import pieces from symbolic data formats.
• run(), to perform a pre-defined analysis.
• output(), to output a visualization of the analysis results.
• export(), to output a text-based version of the analysis results.

Before you analyze, you may wish to use these methods:

• metadata(), to get or set the metadata of a specific IndexedPiece managed by this WorkflowManager.
• settings(), to get or set a setting related to analysis (for example, whether to display the quality of intervals).

You may also treat a WorkflowManager as a container:

>>> wm = WorkflowManager('piece1.mxl', 'piece2.krn')
>>> len(wm)
2
>>> ip = wm[1]
>>> type(ip)
<class 'vis.models.indexed_piece.IndexedPiece'>

export(form, pathname=None, top_x=None, threshold=None)

Save data from the most recent result of run() to a file.

Parameters:

• form (basestring) – The output format you want.
• pathname (basestring) – The pathname for the output. The default is test_output/output_result. File extensions are applied automatically.
• top_x (int) – This is the “X” in “only show the top X results.” The default is None.
• threshold (int or float) – If a result is strictly less than this number, it won’t be included. The default is None.

Returns:The pathname of the outputted file. Return type:unicode

Raises:RuntimeError for unrecognized instructions. Raises:RuntimeError if run() has never been called.

Formats:

• u'CSV': output a Series or DataFrame to a CSV file.
• u'Stata': output a Stata file for importing to R.
• u'Excel': output an Excel file for Peter Schubert.
• u'HTML': output an HTML table, as used by the vis PyQt4 GUI.

load(instruction, pathname=None)

Import analysis data from long-term storage on a filesystem. This should primarily be used for the u'pieces' instruction, to control when the initial music21 import happens.

Use load() with an instruction other than u'pieces' to load results from a previous analysis run by run().

Note

If one of the files imports as a music21.stream.Opus, the number of pieces and their order will change.

Parameters:

• instruction (basestring) – The type of data to load.
• pathname (basestring) – The pathname of the data to import; not required for the u'pieces' instruction.

Raises:

RuntimeError if the instruction is not recognized.

Instructions

Note

only u'pieces' is implemented at this time.

• u'pieces', to import all pieces, collect metadata, and run NoteRestIndexer
• u'hdf5' to load data from a previous export().
• u'stata' to load data from a previous export().
• u'pickle' to load data from a previous export().

metadata(index, field, value=None)

Get or set a metadata field. The valid field names are determined by IndexedPiece (refer to the documentation for metadata()).

A metadatum is a salient musical characteristic of a particular piece, and does not change across analyses.

Parameters:

• index (int) – The index of the piece to access. The range of valid indices is 0 through one fewer than the return value of calling len() on this WorkflowManager.
• field (basestring) – The name of the field to be accessed or modified.
• value (object or None) – If not None, the new 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

Raises:

TypeError if field is not a basestring.

Raises:

AttributeError if accessing an invalid field.

Raises:

IndexError if index is invalid for this WorkflowManager.

output(instruction, pathname=None, top_x=None, threshold=None)

Create a visualization from the most recent result of run() and save it to a file.

Parameters:

• instruction (basestring) – The type of visualization to output.
• pathname (basestring) – The pathname for the output. The default is 'test_output/output_result. A file extension is applied automatically.
• top_x (int) – This is the “X” in “only show the top X results.” The default is None.
• threshold (number) – If a result is strictly less than this number, it will be left out. The default is None.

Returns:

The pathname of the outputted visualization.

Return type:

unicode

Raises:

NotImplementedError if you use the u'LilyPond' instruction.

Raises:

RuntimeError for unrecognized instructions.

Raises:

RuntimeError if run() has never been called.

Raises:

RuntiemError if a call to R encounters a problem.

Instructions:

• u'R histogram': a histogram with ggplot2 in R.

run(instruction)

Run an experiment’s workflow. Remember to call load() before this method.

Parameters:instruction (basestring) – The experiment to run (refer to “List of Experiments” below). Returns:The result of the experiment. Return type:pandas.Series or pandas.DataFrame Raises:RuntimeError if the instruction is not valid for this WorkflowManager. Raises:RuntimeError if you have not called load(). Raises:ValueError if the voice-pair selection is invalid or unset.

List of Experiments

• u'intervals': find the frequency of vertical intervals in 2-part combinations. All settings will affect analysis except 'n'. No settings are required; if you do not set 'voice combionations', all two-part combinations are included.
• u'interval n-grams': find the frequency of n-grams of vertical intervals connected by the horizontal interval of the lowest voice. All settings will affect analysis. You must set the 'voice combinations' setting. The default value for 'n' is 2.

settings(index, field, value=None)

Get or set a value related to analysis. The valid values are listed below.

A setting is related to this particular analysis, and is not a salient musical feature of the work itself.

Refer to run() for a list of settings required or used by each experiment.

Parameters:

• index (int or None) – The index of the piece to access. The range of valid indices is 0 through one fewer than the return value of calling len() on this WorkflowManager. If value is not None and index is None, you can set a field for all pieces.
• field (basestring) – The name of the field to be accessed or modified.
• value (object or None) – If not None, the new 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

Raises:

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

Raises:

IndexError if index is invalid for this WorkflowManager.

Raises:

ValueError if index and value are both None.

Piece-Specific Settings

Pieces do not share these settings.

• offset interval: If you want to run the FilterByOffsetIndexer, specify a value for this

  setting. To avoid running the FilterByOffsetIndexer, set this to 0. setting that will become the quarterLength duration between observed offsets.

• filter repeats: If you want to run the FilterByRepeatIndexer, set this setting to True.

• voice combinations: If you want to consider certain specific voice combinations, set this setting to a list of a list of iterables. The following value would analyze the highest three voices with each other: '[[0,1,2]]' while this would analyze the every part with the lowest for a four-part piece: '[[0, 3], [1, 3], [2, 3]]'. This should always be a basestring that nominally represents a list (except the special values for 'all' parts at once or 'all pairs').

Shared Settings

All pieces share these settings. The value of index is ignored for shared settings, so it can be anything.

• n: As specified in vis.analyzers.indexers.ngram.NGramIndexer.possible_settings
• continuer: As specified in vis.analyzers.indexers.ngram.NGramIndexer.possible_settings
• interval quality: If you want to display interval quality, set this setting to True.
• simple intervals: If you want to display all intervals as their single-octave equivalents, set this setting to True.
• include rests: If you want to include u'Rest' tokens as vertical intervals, change this setting to True. The default is False.
• count frequency: When set to True (the default), experiments will return the number of occurrences of each token (i.e., “each interval” or “each interval n-gram”). When set to False, the moment-by-moment analysis of each piece is retained. We recommend you only request spreadsheet-formatted output when count frequency is False.