indexers Package¶

`indexers` Package¶

`interval` Module¶

Index intervals. Use the IntervalIndexer to find vertical (harmonic) intervals between two parts. Use the HorizontalIntervalIndexer to find horizontal (melodic) intervals in the same part.

class vis.analyzers.indexers.interval.HorizontalIntervalIndexer(score, settings=None)[source]¶

Bases: vis.analyzers.indexers.interval.IntervalIndexer

Use music21.interval.Interval to create an index of the horizontal (melodic) intervals in a single part.

You should provide the result of NoteRestIndexer.

default_settings = {'horiz_attach_later': False}¶

possible_settings = ['horiz_attach_later']¶

This setting applies to the HorizontalIntervalIndexer in addition to the settings available from the IntervalIndexer.

Parameters:	'horiz_attach_later' (boolean) – If `True`, the offset for a horizontal interval is the offset of the later note in the interval. The default is `False`, which gives horizontal intervals the offset of the first note in the interval.

run()[source]¶

Make a new index of the piece.

Returns:	The new indices. Refer to the example below.
Return type:	`pandas.DataFrame`

Example:

>>> the_score = music21.converter.parse('sibelius_5-i.mei')
>>> the_score.parts[5]
(the first clarinet Part)
>>> the_notes = NoteRestIndexer(the_score).run()
>>> the_notes['noterest.NoteRestIndexer']['5']
(the first clarinet Series)
>>> the_intervals = HorizontalIntervalIndexer(the_notes).run()
>>> the_intervals['interval.HorizontalIntervalIndexer']['5']
(Series with melodic intervals of the first clarinet)

class vis.analyzers.indexers.interval.IntervalIndexer(score, settings=None)[source]¶

Bases: vis.analyzers.indexer.Indexer

Use music21.interval.Interval to create an index of the vertical (harmonic) intervals between two-part combinations.

You should provide the result of the NoteRestIndexer. However, to increase your flexibility, the constructor requires only a list of Series. You may also provide a DataFrame exactly as outputted by the NoteRestIndexer.

default_settings = {u'simple or compound': u'compound', u'quality': False}¶: A dict of default settings for the IntervalIndexer.

possible_settings = [u'simple or compound', u'quality']¶

A list of possible settings for the IntervalIndexer.

Parameters:	u'simple or compound' (unicode) – Whether intervals should be represented in their single-octave form (either `u'simple'` or `u'compound'`). u'quality' (boolean) – Whether to display an interval’s quality.

required_score_type = 'pandas.Series'¶

run()[source]¶

Make a new index of the piece.

Returns:	A `DataFrame` of the new indices. The columns have a `MultiIndex`; refer to the example below for more details.
Return type:	`pandas.DataFrame`

Example:

>>> the_score = music21.converter.parse('sibelius_5-i.mei')
>>> the_score.parts[5]
(the first clarinet Part)
>>> the_notes = NoteRestIndexer(the_score).run()
>>> the_notes['noterest.NoteRestIndexer']['5']
(the first clarinet Series)
>>> the_intervals = IntervalIndexer(the_notes).run()
>>> the_intervals['interval.IntervalIndexer']['5,6']
(Series with vertical intervals between first and second clarinet)

vis.analyzers.indexers.interval.indexer_nq_comp(ecks)[source]¶

Used internally by the IntervalIndexer and HorizontalIntervalIndexer.

Call real_indexer() with settings to print compound intervals without quality.

vis.analyzers.indexers.interval.indexer_nq_simple(ecks)[source]¶

Used internally by the IntervalIndexer and HorizontalIntervalIndexer.

Call real_indexer() with settings to print simple intervals without quality.

vis.analyzers.indexers.interval.indexer_qual_comp(ecks)[source]¶

Used internally by the IntervalIndexer and HorizontalIntervalIndexer.

Call real_indexer() with settings to print compound intervals with quality.

vis.analyzers.indexers.interval.indexer_qual_simple(ecks)[source]¶

Used internally by the IntervalIndexer and HorizontalIntervalIndexer.

Call real_indexer() with settings to print simple intervals with quality.

vis.analyzers.indexers.interval.real_indexer(simultaneity, simple, quality)[source]¶

Used internally by the IntervalIndexer and HorizontalIntervalIndexer.

Parameters:	simultaneity (list of basestring) – A two-item iterable with the note names for the higher and lower parts, respectively. simple (boolean) – Whether intervals should be reduced to their single-octave version. quality (boolean) – Whether the interval’s quality should be prepended.
Returns:	`'Rest'` if one or more of the parts is `'Rest'`; otherwise, the interval between the parts.
Return type:	unicode string

`lilypond` Module¶

Indexers related to producing LilyPond-format output from the VIS Framework. Also refer to the vis.analyzers.experimenters.lilypond module.

class vis.analyzers.indexers.lilypond.AnnotationIndexer(score, settings=None)[source]¶

Bases: vis.analyzers.indexer.Indexer

From any other index, put _\markup{""} around it.

required_score_type = 'pandas.Series'¶

run()[source]¶

Make a new index of the piece.

Returns:	A list of the new indices. The index of each `Series` corresponds to the index of the `Part` used to generate it, in the order specified to the constructor. Each element in the `Series` is a `basestring`.
Return type:	`pandas.DataFrame`

vis.analyzers.indexers.lilypond.annotation_func(obj)[source]¶

Used by AnnotationIndexer to make a “markup” command for LilyPond scores.

Parameters:	obj (`pandas.Series` of `unicode`) – A single-element `Series` with the string to wrap in a “markup” command.
Returns:	The thing in a markup.
Return type:	`unicode`

`ngram` Module¶

Indexer to find k-part any-object n-grams.

class vis.analyzers.indexers.ngram.NGramIndexer(score, settings=None)[source]¶

Bases: vis.analyzers.indexer.Indexer

Indexer that finds k-part n-grams from other indices.

The indexer requires at least one “vertical” index, and supports “horizontal” indices that seem to “connect” instances in the vertical indices. Although we use “vertical” and “horizontal” to describe these index types, because the class is an abstraction of two-part interval n-grams, you can supply any information as either type of index. If you want one-part melodic n-grams for example, you should supply the relevant interval information as the “vertical” component.

There is no relationship between the number of index types, though there must be at least one “vertical” index.

The 'horizontal' and 'vertical' settings determine which columns of the score DataFrame are included in the n-gram output. They are added to the n-gram in the order specified, so if the 'vertical' setting is [('noterest.NoteRestIndexer', '1'), ('noterest.NoteRestIndexer', '0')], this will put the lower part (with index '1') before the higher part (with index '0'). Note that both the indexer’s name and the part-combination name must be included.

This is an example minimum settings dictionary for making interval 3-grams::

{'vertical': [('interval.IntervalIndexer', '0,1')],
 'horizontal': [('interval.HorizontalIntervalIndexer', '1')],
 'n': 3}

In the output, groups of “vertical” events are normally enclosed in brackets, while groups of “horizontal” events are enclosed in parentheses. For cases where there is only one index in a particular direction, you can avoid printing the brackets or parentheses by setting the 'mark singles' setting to False (the default is True).

If you want n-grams to terminate when finding one or several particular values, you can specify this with the 'terminator' setting.

To show that a horizontal event continues, we use '_' by default, but you can set this separately, for example to 'P1' '0', as seems appropriate. Note that the default WorkflowManager overrides this setting by dynamically adjusting for interval quality, and also offers a 'continuer' setting of its own, which is passed to this indexer.

You can also use the NGramIndexer to collect “stacks” of single vertical events. If you provide indices of intervals above a lowest part, for example, these “stacks” become the figured bass signature of a single moment. Set 'n' to 1 for this feature. Horizontal events are obviously ignored in this case.

default_settings = {'horizontal': [], 'continuer': '_', 'mark_singles': True, 'terminator': []}¶

possible_settings = ['horizontal', 'vertical', 'n', 'mark_singles', 'terminator', 'continuer']¶

A list of possible settings for the NGramIndexer.

Parameters:

'horizontal' (list of (basestring, basestring) tuples) – Selectors for the parts to consider as “horizontal.”
'vertical' (list of (basestring, basestring) tuples) – Selectors for the parts to consider as “vertical.”
'n' (int) – The number of “vertical” events per n-gram.
'mark_singles' (bool) – Whether to use delimiters around a direction’s events when there is only one event in that direction (e.g., the “horizontal” maps only the activity of a single voice). (You may also use 'mark singles').
'terminator' (list of basestring) – Do not find an n-gram with a vertical item that contains any of these values.
'continuer' (basestring) – When there is no “horizontal” event that corresponds to a vertical event, this is printed instead, to show that the previous “horizontal” event continues.

required_score_type = 'pandas.DataFrame'¶

run()[source]¶

Make an index of k-part n-grams of anything.

Returns:	A single-column `DataFrame` with the new index.

`noterest` Module¶

Index note and rest objects.

class vis.analyzers.indexers.noterest.NoteRestIndexer(score, settings=None)[source]¶

Bases: vis.analyzers.indexer.Indexer

Index Note and Rest objects in a Part.

Rest objects become 'Rest', and Note objects become the unicode-format version of their :attr:`~music21.note.Note.nameWithOctave attribute.

required_score_type = 'stream.Part'¶

run()[source]¶

Make a new index of the piece.

Returns:	A `DataFrame` of the new indices. The columns have a `MultiIndex`; refer to the example below for more details.
Return type:	`pandas.DataFrame`

Example:

>>> the_score = music21.converter.parse('sibelius_5-i.mei')
>>> the_score.parts[5]
(the first clarinet Part)
>>> the_notes = NoteRestIndexer(the_score).run()
>>> the_notes['noterest.NoteRestIndexer']['5']
(the first clarinet Series)

vis.analyzers.indexers.noterest.indexer_func(obj)[source]¶

Used internally by NoteRestIndexer. Convert Note and Rest objects into a unicode string.

Parameters:	obj (iterable of `music21.note.Note` or `music21.note.Rest`) – An iterable (nominally a `Series`) with an object to convert. Only the first object in the iterable is processed.
Returns:	If the first object in the list is a `music21.note.Rest`, the string `u'Rest'`; otherwise the `nameWithOctave` attribute, which is the pitch class and octave of the `Note`.
Return type:	unicode

Examples:

>>> from music21 import note
>>> indexer_func([note.Note('C4')])
u'C4'
>>> indexer_func([note.Rest()])
u'Rest'

`offset` Module¶

Indexers that modify the “offset” values (floats stored as the “index” of a pandas.Series), potentially adding repetitions of or removing pre-existing events, without modifying the events themselves.

class vis.analyzers.indexers.offset.FilterByOffsetIndexer(score, settings=None)[source]¶

Bases: vis.analyzers.indexer.Indexer

Indexer that regularizes the “offset” values of observations from other indexers.

The Indexer regularizes observations from offsets spaced any, possibly irregular, quarterLength durations apart, so they are instead observed at regular intervals. This has two effects:

events that do not begin at an observed offset will only be included in the output if no other event occurs before the next observed offset
events that last for many observed offsets will be repeated for those offsets

Since elements’ durations are not recorded, the last observation in a Series will always be included in the results. If it does not start on an observed offset, it will be included as the next observed offset—again, whether or not this is true in the actual music. However, the last observation will only ever be counted once, even if a part ends before others in a piece with many parts. See the doctests for examples.

Examples. For all, the quarterLength is 1.0.

When events in the input already appear at intervals of quarterLength, input and output are identical.

offset	0.0	1.0	2.0
input	`a`	`b`	`c`
output	`a`	`b`	`c`

When events in the input appear at intervals of quarterLength, but there are additional elements between the observed offsets, those additional elements are removed.

offset	0.0	0.5	1.0	2.0
input	`a`	`A`	`b`	`c`
output	`a`		`b`	`c`

offset	0.0	0.25	0.5	1.0	2.0
input	`a`	`z`	`A`	`b`	`c`
output	`a`			`b`	`c`

When events in the input appear at intervals of quarterLength, but not at every observed offset, the event from the previous offset is repeated.

offset	0.0	1.0	2.0
input	`a`		`c`
output	`a`	`a`	`c`

When events in the input appear at offsets other than those observed by the specified quarterLength, the “most recent” event will appear.

offset	0.0	0.25	0.5	1.0	2.0
input	`a`	`z`	`A`		`c`
output	`a`			`A`	`c`

When the final event does not appear at an observed offset, it will be included in the output at the next offset that would be observed, even if this offset does not appear in the score file to which the results correspond.

offset	0.0	1.0	1.5	2.0
input	`a`	`b`	`d`
output	`a`	`b`		`d`

The behaviour in this last example can create a potentially misleading result for some analytic situations that consider metre. It avoids another potentially misleading situation where the final chord of a piece would appear to be dissonant because of a suspension. We chose to lose metric and rythmic precision, which would be more profitably analyzed with indexers built for that purpose. Consider this illustration, where the numbers correspond to scale degrees.

offset	410.0	411.0	411.5	412.0
in-S	2	1
in-A	7	5
in-T	4 ———–		3
in-B	5	1
out-S	2	1		1
out-A	7	5		5
out-T	4	4		3
out-B	5	1		1

If we left out the note event appear in the in-A part at offset 411.5, the piece would appear to end with a dissonant sonority!

default_settings = {'method': 'ffill'}¶

possible_settings = ['quarterLength', 'method']¶

A list of possible settings for the FilterByOffsetIndexer.

Parameters:

'quarterLength' (float) – The quarterLength duration between observations desired in the output. This value must not have more than three digits to the right of the decimal (i.e. 0.001 is the smallest possible value).
'method' (str or None) – The value passed as the method kwarg to reindex(). The default is 'ffill', which fills in missing indices with the previous value. This is useful for vertical intervals, but not for horizontal, where you should use None instead.

required_score_type = 'pandas.Series'¶: The FilterByOffsetIndexer uses pandas.Series objects.

run()[source]¶

Regularize the observed offsets for the inputted Series.

Returns: A DataFrame with offset-indexed values for all inputted parts. The pandas indices (holding music21 offsets) start at the first offset at which there is an event in any of the inputted parts. An offset appears every quarterLength until the final offset, which is either the last observation in the piece (if it is divisible by the quarterLength) or the next-highest value that is divisible by quarterLength.

Return type: pandas.DataFrame

`repeat` Module¶

Indexers that consider repetition in any way.

class vis.analyzers.indexers.repeat.FilterByRepeatIndexer(score, settings=None)[source]¶

Bases: vis.analyzers.indexer.Indexer

If the same event occurs many times in a row, remove all occurrences but the one with the lowest offset value (i.e., the “first” event).

Because of how a DataFrame‘s index works, many of the events that would have been filtered will instead be replaced with numpy.NaN. Please be careful that the behaviour of this indexer matches your expectations.

required_score_type = 'pandas.Series'¶

run()[source]¶

Make a new index of the piece, removing any event that is identical to the preceding.

Returns:	A `DataFrame` of the new indices.
Return type:	`pandas.DataFrame`

`template` Module¶

Template for writing a new indexer. Use this class to help write a new :class`Indexer` subclass. The TemplateIndexer does nothing, and should only be used by programmers.

Note

Follow these instructions to write a new Indexer subclass:

Replace my name with yours in the “codeauthor” directive above.
Change the “Filename” and “Purpose” on lines 7 and 8.
Modify the “Copyright” on line 10 or add an additional copyright line immediately below.
Remove the # pylint: disable=W0613 comment just before indexer_func().
Rename the class.
Adjust required_score_type.
Add settings to possible_settings and default_settings, as required.
Rewrite the documentation for __init__().
Rewrite the documentation for run().
Rewrite the documentation for indexer_func().
Write all relevant tests for __init__(), run(), and indexer_func().
Follow the instructions in __init__() to write that method.
Follow the instructions in run() to write that method.
Write a new indexer_func().
Ensure your tests pass, adding additional ones as required.
Finally, run pylint with the VIS style rules.

class vis.analyzers.indexers.template.TemplateIndexer(score, settings=None)[source]¶

Bases: vis.analyzers.indexer.Indexer

Template for an Indexer subclass.

default_settings = {}¶: The default values for settings named in possible_settings. If a setting doesn’t have a value in this constant, then it must be specified to the constructor at runtime, or the constructor should raise a RuntimeException.

possible_settings = [u'fake_setting']¶

This is a list of basestrings that are the names of the settings used in this indexer. Specify the types and reasons for each setting as though it were an argument list, like this:

Parameters:	'fake_setting' (boolean) – This is the description of a fake setting.

required_score_type = 'stream.Part'¶: Depending on how this indexer works, you must provide a DataFrame, a Score, or list of Part or Series objects. Only choose Part or Series if the input will always have single-integer part combinations (i.e., there are no combinations—it will be each part independently).

run()[source]¶

Make a new index of the piece.

Returns:	The new indices. Refer to the note below.
Return type:	`pandas.DataFrame` or list of `pandas.Series`

Important

Please be sure you read and understand the rules about return values in the full documentation for run() and make_return().

vis.analyzers.indexers.template.indexer_func(obj)[source]¶

The function that indexes.

Parameters:	obj (list of objects of the types stored in `TemplateIndexer._types`) – The simultaneous event(s) to use when creating this index. (For indexers using a `Score`).

or

Parameters:	obj (`pandas.Series` of unicode strings) – The simultaneous event(s) to use when creating this index. (For indexers using a `Series`).
Returns:	The value to store for this index at this offset.
Return type:	`unicode`

Table Of Contents

Previous topic

Next topic

This Page

indexers Package¶