hm

Tools for harmony and melody analysis (HM).

contour

Tools for contour calculation and contour reduction.

exception decitala.hm.contour.ContourException

Bases: Exception

decitala.hm.contour.strip_monotonic_pitch_content(pitch_content)

The pitch content extracted in the decitala.search module consists of lists of tuples. This functions strips monotonic pitch content to a single list. If non-monotonic pitch content is provided, the function chooses the lowest pitch.

Parameters

pitch_content (list) – pitch content of the format returned in decitala.search.rolling_hash_search.

Returns

a list of MIDI tones.

Return type

list

>>> pitch_content = [(60,), (61,), (65,)]
>>> strip_monotonic_pitch_content(pitch_content)
[60, 61, 65]

decitala.hm.contour.normalize_pitch_content(data, midi_start=60)

Normalizes a list of MIDI tones to a a starting value.

Parameters

• data (list) – a list of MIDI tones.

• midi_start (int) – the MIDI starting point to which the data are normalized.

Returns

a numpy array of the pitch content, normalized to the starting value.

Return type

numpy.array

>>> normalize_pitch_content(data=[58, 60, 62], midi_start=60)
[60, 62, 64]

decitala.hm.contour.uds_contour(data)

Returns the for “up-down-stay” contour (UDS) of a given list of MIDI tones. Normalized to start at 0.

Parameters

data (list) – a list of MIDI tones.

Returns

a numpy array of the UDS contour of the given data.

Return type

numpy.array

>>> midis = [47, 42, 45, 51, 51, 61, 58]
>>> uds_contour(midis)
[0, -1, 1, 1, 0, 1, -1]

decitala.hm.contour.pitch_contour(pitch_content, as_str=False)

This function returns the contour of given pitch content. It accepts either a list of MIDI tones, or the data returned in the decitala.search module. Like decitala.hm.contour.strip_monotonic_pitch_content, if non-monotonic pitch content is provided, it chooses the lowest pitch.

Parameters

• pitch_content (list) – pitch content from the output of rolling_search.”

• as_str (bool) – whether to return the pitch content as a string (standard format), like "<0 1 1>".

Returns

the contour of the given pitch_content.

Return type

numpy.array or str

>>> pitch_content_1 = [(80,), (91,), (78,), (85,)]
>>> pitch_contour(pitch_content_1)
[1, 3, 0, 2]
>>> pitch_content_2 = [80, 84, 84]
>>> pitch_contour(pitch_content_2, as_str=True)
'<0 1 1>'

decitala.hm.contour.contour_to_neume(contour)

Oversimplified function for checking the associated neume of a given pitch contour. Only two and three onset contours are supported.

Parameters

contour – A pitch contour (iterable).

Returns

The associated neume or None.

Return type

str or None

>>> contour = [1, 0, 1]
>>> contour_to_neume(contour)
'Porrectus'

decitala.hm.contour.contour_class(contour, allow_symmetries=False)

Returns the associated pitch contour class (a letter) from Morris (1993, 220-221) of a contour.

Parameters

• contour – a pitch contour (iterable).

• allow_symmetries (bool) – whether to allow permutations of the given contour to be found. Default is False. Note that X and Y are weird cases for this symmetry. May currently fail (don’t understand it).

Return type

str

>>> contour_class((1, 0, 3, 2))
'X'
>>> contour_class((0, 1, 0), allow_symmetries=False)
'G'
>>> contour_class((0, 0, 1), allow_symmetries=True)
'G'

decitala.hm.contour.prime_contour(contour)

Implementation of Robert Morris’ Contour-Reduction algorithm (Morris, 1993). “The algorithm prunes pitches from a contour until it is reduced to a prime.” (Schultz)

Parameters

contour – A pitch contour (iterable).

Returns

the prime contour of the given pitch contour, along with the depth of the reduction.

Return type

tuple

>>> contour_a = [0, 1]
>>> prime_contour(contour_a)
([0, 1], 0)
>>> contour_b = [0, 4, 3, 2, 5, 5, 1]
>>> prime_contour(contour_b)[0]
[0, 2, 1]

decitala.hm.contour.schultz_prime_contour(contour)

Implementation of Schultz’s (2008) modification of Morris’ contour-reduction algorithm. See the Schultz module for the implementation. (It was complicated enough to warrent its own module…)

Parameters

contour – A pitch contour (iterable).

Returns

the Schultz Prime Contour (SPC) of the given contour, along with the depth of the reduction.

Return type

tuple

>>> nightingale_5 = [2, 5, 3, 1, 4, 4, 4, 0, 0, 0, 0, 0, 0, 0, 0, 0]
>>> spc(nightingale_5)
([1, 2, 0], 3)

hm_utils

General utilities for harmony and melody analysis. Includes implementation of Krumhansl-Schmuckler/Krumhansl-Kessler with the original weights.

exception decitala.hm.hm_utils.HMUtilsException

Bases: Exception

decitala.hm.hm_utils.get_all_coefficients(exclude_major_minor=False, molt_tonic_val=1)

Returns a giant dictionary holding the binary weights for all Modes of Limited Transposition, along with the original KS weights (unless exclude_major_minor=False).

Parameters

• exclude_major_minor (bool) – whether to exclude major/minor weights from the dictionary. Default is False.

• molt_tonic_val (int) – optional value to set the first element of the MOLT to. Default is all scale values set to 1.

decitala.hm.hm_utils.pc_counter(filepath, part_num, return_counts=False)

Returns a dictionary holding the pitch classes in the keys and the sum of the quarter lengths of this pitch class in a given filepath-part combination.

Parameters

• filepath (str) – path to music21-readable file to be parsed.

• part_num (int) – part number in the work to be analyzed.

• return_counts (bool) – whether to return the counts of the detected pitches, instead of the net quarter lengths.

Returns

a dictionary holding the 12 pitch classes in the keys and the counts/proportion in the values.

Return type

dict

decitala.hm.hm_utils.normalize_pc_counter(dict_in)

Normalize a dictionary by the sum of the total values. Meant to be used with the net ql values from decitala.hm.hm_utils.

>>> d = {0: 0, 1: 0.375, 2: 0, 3: 0.25, 4: 0.375,
...     5: 0.375, 6: 0.375, 7: 0, 8: 0.75, 9: 0.25, 10: 0, 11: 0
... }
>>> for pc, norm_val in normalize_pc_counter(d).items():
...     print(pc, norm_val)
0 0.0
1 0.13636363636363635
2 0.0
3 0.09090909090909091
4 0.13636363636363635
5 0.13636363636363635
6 0.13636363636363635
7 0.0
8 0.2727272727272727
9 0.09090909090909091
10 0.0
11 0.0

decitala.hm.hm_utils.pc_dict_to_vector(dict_in)

Function for converting a pitch class dictionary (i.e. a dictionary with keys in range 0-11 and values some integer) to a vector of the associated values; sorted by the key, naturally.

Parameters

dict_in (dict) – a pitch class dictionary.

Returns

numpy array holding the values of the dictionary, ordered by pitch class.

Return type

numpy.array

>>> from decitala.hm import molt
>>> m3t3 = molt.MOLT(mode=3, transposition=3)
>>> dict_in = m3t3.pc_dict()
>>> dict_in
{0: 1, 1: 1, 2: 1, 3: 0, 4: 1, 5: 1, 6: 1, 7: 0, 8: 1, 9: 1, 10: 1, 11: 0}
>>> pc_dict_to_vector(dict_in)
array([1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0])

decitala.hm.hm_utils.diatonic_scale_binary(tonic, mode, as_vector=False)

Function for creating a binary dict (or ordered vector if as_vector=True) of a major or minor scale.

Parameters

• tonic – the tonic of the major or minor scale (str or int)

• mode (str) – "Major" or "Minor".

• as_vector (bool) – whether to return the dictionary as a vector ordered by pitch class.

decitala.hm.hm_utils.note_counter(filepath, part_num)

Simple tool for counting the number of notes (with ties stripped) in a given filepath/part combination.

Parameters

• filepath (str) – path to music21-readable file to be parsed.

• part_num (int) – part number in the work to be analyzed.

Returns

the total count of note objects (with ties stripped).

Return type

int

decitala.hm.hm_utils.KS(pc_vector, coefficients, method='spearman')

Krumhansl-Schumckler algorithm.

Parameters

• pc_vector – a vector of pitch class probabilities, ordered by pitch class.

• coefficients – coefficents used in the correlation calculation.

• method (str) – either ‘pearson’ or ‘spearman’ (the method used for calculating correlation). Default is ‘pearson’.

decitala.hm.hm_utils.KS_diatonic(pc_vector, coefficients, method='pearson', return_tonic=False)

Krumhansl-Schumckler algorithm for diatonic collections. Circulates over the weights. Returns the best match (and its associated pvalue) using either Pearson or Spearman correlation.

Parameters

• pc_vector – a vector of pitch class probabilities, ordered by pitch class.

• coefficients – coefficents used in the correlation calculation.

• method (str) – either ‘spearman’ or ‘pearson’ (the method used for calculating correlation). Default is ‘pearson’.

• return_tonic (bool) – whether to also return the pitch object of the most highly correlated tonic.

decitala.hm.hm_utils.test_all_coefficients(pc_vector, method='pearson', exclude_major_minor=False, molt_tonic_val=1)

Function for calculating the correlation between a given pc_vector and all possible coefficients (binary modes for MOLT and KS coefficients).

Parameters

• pc_vector – a vector of pitch class probabilities, ordered by pitch class.

• method (str) – either ‘spearman’ or ‘pearson’ (the method used for calculating correlation). Default is ‘pearson’.

• exclude_major_minor (bool) – whether to exclude major/minor weights from the calculation. Default is False.

• molt_tonic_val (int) – optional value to set the first element of the MOLT to. Default is all scales values set to 1.

Returns

dictionary holding modes in the keys and the calculated KS correlation in the values.

Return type

dict

molt

Tools for dealing with the Messiaen Modes of Limited Transposition [MOLT] (1944). Includes tool for querying the modes.

“I am … affected by a kind of synopsia, found more in my mind than in my body, which allows me, when I hear music, and equally when I read it, to see inwardly, in the mind’s eye, colors which move with the music, and I sense these colors in an extremely vivid manner… .” (Samuel, 1976)

Color translations come from Håkon Austbø # noqa

exception decitala.hm.molt.MoltException

Bases: Exception

class decitala.hm.molt.MOLT(mode, transposition)

Bases: object

Class representing a Mode of Limited Transposition (Messiaen, 1944), therefore called a MOLT.

>>> m1t2 = MOLT(mode=1, transposition=2)
>>> m1t2
<moiseaux.MOLT mode=1, transposition=2>
>>> m1t2.mode
1
>>> m1t2.transposition
2
>>> m1t2.scale
<music21.scale.ConcreteScale C# Concrete>
>>> for p in m1t2.pitches:
...     print(p)
C#4
D#4
F4
G4
A4
B4
>>> m1t2.color
>>> m1t2.pc_dict()
{0: 0, 1: 1, 2: 0, 3: 1, 4: 0, 5: 1, 6: 0, 7: 1, 8: 0, 9: 1, 10: 0, 11: 1}

classmethod from_str(str_in)

Return a MOLT object from string input of the form "MXTB"

property scale

Returns a music21.scale object consisting of the pitches in the MOLT.

property pitches

Returns the pitches of the MOLT. Comes from the music21.scale.pitches, but overrides to remove the octave duplication.

property color

Returns the associated color of the mode, if it exists.

property is_color_mode

Returns whether the mode is a color mode, i.e. MOLT 2, 3, 4, or 6.

pc_dict(tonic_value=None)

Returns a dictionary for which the keys are the standard pitch classes (0-11) and the values are 0/1, determined by whether that pitch belongs to the mode.

Parameters

tonic_value (float) – an optional value to store in the tonic of the scale, i.e., the first tone. Otherwise, all pitches of the scale will be set to 1 (and the others set to 0).

Return type

dict

pc_vector(tonic_value=None)

Returns the molt.MOLT.pc_dict as a vector, ordered by the pitch class.

param float tonic_value

an optional value to store in the tonic of the scale, i.e., the first tone. Otherwise, all pitches of the scale will be set to 1 (and the others set to 0).

decitala.hm.molt.MOLT_query(collection)

Returns a list of the possible MOLT (objects) that contain the collection. Accepts either a list of midi tones, a list of strings, a list of pitch objecs, or a list of note objects.