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 theWorkflowManager
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 specificIndexedPiece
managed by thisWorkflowManager
.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 byrun()
.Note
If one of the files imports as a
music21.stream.Opus
, the number of pieces and their order will change.Parameters: Raises: RuntimeError
if theinstruction
is not recognized.Instructions
Note
only
'pieces'
is implemented at this time.
-
metadata
(index, field, value=None)[source]¶ Get or set a metadata field. The valid field names are determined by
IndexedPiece
(refer to the documentation formetadata()
).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 thelen()
of thisWorkflowManager
. - field (str) – The name of the field to be accessed or modified.
- value (object) – If not
None
, the new 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: Raises: TypeError
iffield
is not a string.Raises: AttributeError
if accessing an invalidfield
.Raises: IndexError
ifindex
is invalid for thisWorkflowManager
.- index (int) – The index of the piece to access. The range of valid indices is
-
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()
withcount frequency
set toFalse
.Note
If
count frequency
is set toFalse
for CSV, Stata, Excel, or HTML output, thetop_x
andthreshold
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 theWorkflowManager
, 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 isFalse
.Return type: Raises: RuntimeError
for unrecognized instructions.Raises: RuntimeError
ifrun()
has never been called.Raises: RuntiemError
if a call to R encounters a problem.Raises: RuntimeError
with LilyPond output, if we think you calledrun()
withcount frequency
set toTrue
.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()
withcount frequency
set toTrue
by raising aRuntimeError
ifcount frequency
isTrue
, or the number of pieces is not the same as the number of results. It is still possible to callrun()
withcount frequency
set toTrue
in a way we will not detect. However, this always causesoutput()
to fail. The error will probably be aTypeError
that saysobject 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
orpandas.DataFrame
or a list of lists ofpandas.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 theinstruction
is not valid for thisWorkflowManager
.Raises: RuntimeError
if you have not calledload()
.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'
is2
.
-
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 is0
through one fewer than the return value of callinglen()
on this WorkflowManager. Ifvalue
is notNone
andindex
isNone
, 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 notNone
, the new 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
Raises: AttributeError
if accessing an invalidfield
(see valid fields below).Raises: IndexError
ifindex
is invalid for thisWorkflowManager
.Raises: ValueError
ifindex
andvalue
are bothNone
.Piece-Specific Settings
Pieces do not share these settings.
offset interval
: If you want to run theFilterByOffsetIndexer
, specify a value for this setting. To avoid running theFilterByOffsetIndexer
, set this to0
. This will become thequarterLength
duration between observed offsets.filter repeats
: If you want to run theFilterByRepeatIndexer
, set this setting toTrue
.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 astr
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 invis.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 theNGramIndexer
. Refer topossible_settings
.interval quality
: If you want to display interval quality, set this setting toTrue
.simple intervals
: If you want to display all intervals as their single-octave equivalents, set this setting toTrue
.include rests
: If you want to include'Rest'
tokens as vertical intervals, change this setting toTrue
. The default isFalse
.count frequency
: When set toTrue
(the default), experiments will return the number of occurrences of each token (i.e., “each interval” or “each interval n-gram”). When set toFalse
, the moment-by-moment analysis of each piece is retained. We recommend you only request spreadsheet-formatted output whencount frequency
isFalse
.
- index (int or
-
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)