vis

workflow Module

Deprecated since version 3.0.0: The WorkflowManager is deprecated as of VIS 3.0.0 and will be entirely removed in VIS 4.0. It was an important part of VIS in earlier versions but the iterative caching strategy implemented in VIS 3.0 obviates the need for the WorkflowManager and so it is being phased out for simplicity. Most of its functionality still works with VIS 3.0, however, it is no longer being maintained or supported.

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)[source]

Bases: object

Warning: The WorkflowManager is deprecated as of VIS 3.0 and will be entirely removed in VIS 4.0. Most of its functionality still works with VIS 3.0 but this is not guaranteed and it is no longer being supported in development.

Parameters:pathnames (list or tuple of string or IndexedPiece) – 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 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'>
load(instruction='pieces', pathname=None)[source]

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

Use load() with an instruction other than '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 (str) – The type of data to load. Defaults to 'pieces'.
  • pathname (str) – The pathname of the data to import; not required for the 'pieces' instruction.
Raises:

RuntimeError if the instruction is not recognized.

Instructions

Note

only 'pieces' is implemented at this time.

  • 'pieces', to import all pieces, collect metadata, and run NoteRestIndexer
  • 'hdf5' to load data from a previous output().
  • 'stata' to load data from a previous output().
  • 'pickle' to load data from a previous output().
metadata(index, field, value=None)[source]

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 len() of this WorkflowManager.
  • field (str) – The name of the field to be accessed or modified.
  • value (object) – 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
Raises:

TypeError if field is not a string.
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)[source]

Output the results of the most recent call to run(), saved in a file. This method handles both visualizations and symbolic output formats.

Note

For LiliyPond output, you must have called run() with count frequency set to False.

Note

If count frequency is set to False for CSV, Stata, Excel, or HTML output, the top_x and threshold parameters are ignored.

Parameters:
  • instruction (str) – The type of visualization to output.
  • pathname (str) – The pathname for the output. The default is 'test_output/output_result. Do not include a file-type “extension,” since we add this automatically. For the LilyPond experiment, if there are multiple pieces in the WorkflowManager, we append the piece’s index to the pathname.
  • top_x (integer) – This is the “X” in “only show the top X results.” The default is None. Does not apply to the LilyPond experiment.
  • threshold (integer) – If a result is strictly less than this number, it will be left out. The default is None. This is ignored for the 'LilyPond' instruction. Does not apply to the LilyPond experiment.
Returns:

The pathname(s) of the outputted visualization(s). Requesting a histogram always returns a single string; requesting a score (or some scores) always returns a list. The other formats will return a list if the count frequency setting is False.
Return type:

str or [str]
Raises:

RuntimeError for unrecognized instructions.
Raises:

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

RuntiemError if a call to R encounters a problem.
Raises:

RuntimeError with LilyPond output, if we think you called run() with count frequency set to True.

Instructions:

  • 'histogram': a histogram. Currently equivalent to the 'R histogram' instruction.
  • 'LilyPond': each score with annotations for analyzed objects.
  • 'R histogram': a histogram with ggplot2 in R. Currently equivalent to the 'histogram' instruction. In the future, this will be used to distinguish histograms
    produced with R from those produced with other libraries, like matplotlib or bokeh.
  • 'CSV': output a Series or DataFrame to a CSV file.
  • 'Stata': output a Stata file for importing to R.
  • 'Excel': output an Excel file for Peter Schubert.
  • 'HTML': output an HTML table, as used by the VIS Counterpoint Web App.

Note

We try to prevent you from requesting LilyPond output if you called run() with count frequency set to True by raising a RuntimeError if count frequency is True, or the number of pieces is not the same as the number of results. It is still possible to call run() with count frequency set to True in a way we will not detect. However, this always causes output() to fail. The error will probably be a TypeError that says object of type 'numpy.float64' has no len().

run(instruction)[source]

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

Parameters:instruction (str) – The experiment to run (refer to “List of Experiments” below).
Returns:The result of the experiment.
Return type:pandas.Series or pandas.DataFrame or a list of lists of pandas.Series. If 'count frequency' is set to False, the return type will be a list of lists of series wherein the containing list has each piece in the experiment as its elements (even if there is only one piece in the experiment, this will be a list of length one). The contained lists contain the results of the experiment for each piece where each element in the list corresponds to a unique voice combination in an unlabelled and unpredictable fashion. Finally each series corresponds the experiment results for a given voice combination in a given piece.
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

  • '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 combinations', all two-part combinations are included.
  • '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)[source]

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 (str) – 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. This 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 str 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: Determines the way unisons that arise from sustained notes in the lowest voice are represented. Note that if the FilterByOffsetIndexer is used, the continuer won’t get used. The default is ‘dynamic quality’ which sets to ‘P1’ if interval quality is set to True, and ‘1’ if it is set to False. This is given directly to the NGramIndexer. Refer to 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 '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.
vis.workflow.split_part_combo(key)[source]

Split a comma-separated list of two integer part names into a tuple of the integers.

Parameters:key (str) – String with the part names.
Returns:The indices of parts referred to by the key.
Return type:tuple of int 
>>> split_part_combo('5,6')
(5, 6)
>>> split_part_combo('234522,98100')
(234522, 98100)
>>> var = split_part_combo('1,2')
>>> split_part_combo(str(var[0]) + ',' + str(var[1]))
(1, 2)