Complexity
Full module path: melody_features.feature_definitions.complexity.
Also importable via import melody_features as mf (for example mf.pitch_range).
Complexity feature definitions.
- interval_entropy(pitches)[source]
The zeroth-order base-2 entropy of the interval distribution.
- Parameters:
- Returns:
Shannon entropy of signed melodic intervals (in semitones).
- Return type:
Note
Uses signed intervals rather than absolute interval sizes, consistent with FANTASTIC implementation.
- duration_entropy(starts, ends, tempo=120.0)[source]
The zeroth-order base-2 entropy of the duration distribution in quarter notes.
- duration_accent(starts, ends, tau=0.5, accent_index=2.0)[source]
Calculate duration accent for each note based on Parncutt (1994). Duration accent represents the perceptual salience of notes based on their duration.
- Parameters:
- Returns:
List of duration accent values for each note
- Return type:
Note
The MIDI toolbox implementation uses defaults of 0.5 for tau (saturation duration) and 2.0 for accent_index (minimum discriminable duration).
- mean_duration_accent(starts, ends, tau=0.5, accent_index=2.0)[source]
The mean duration accent across all notes. Duration accent represents the perceptual salience of notes based on their duration, as defined by Parncutt (1994).
- Parameters:
- Returns:
float – Mean duration accent value
Citation
——–
Parncutt (1994)
- Return type:
- duration_accent_std(starts, ends, tau=0.5, accent_index=2.0)[source]
The standard deviation of duration accents. Duration accent represents the perceptual salience of notes based on their duration, as defined by Parncutt (1994).
- Parameters:
- Returns:
float – Standard deviation of duration accent values
Citation
——–
Parncutt (1994)
- Return type:
- tonal_entropy(pitches)[source]
Zeroth-order base-2 entropy of the 24-key Krumhansl-Schmuckler key correlation distribution. Normalizes the correlation values to a probability mass over all 24 major/minor keys, then computes Shannon entropy.
- complebm_pitch(melody)[source]
Expectancy-based melodic complexity calculated using pitch patterns only, according to Eerola & North (2000). The complexity score is normalized against the Essen folksong collection, where a score of 5 represents average complexity.
Citation
Eerola & North (2000)
- complebm_rhythm(melody)[source]
Expectancy-based melodic complexity calculated using rhythmic features only, according to Eerola & North (2000). The complexity score is normalized against the Essen folksong collection, where a score of 5 represents average complexity.
Citation
Eerola & North (2000)
- complebm_optimal(melody)[source]
Expectancy-based melodic complexity calculated using an optimal combination of pitch patterns and rhythmic features, according to Eerola & North (2000). The complexity score is normalized against the Essen folksong collection, where a score of 5 represents average complexity.
Citation
Eerola & North (2000)
- bisect_unbalance(melody)[source]
The bisect unbalance of a melody’s temporal distribution of note onsets.
Measures equilibrium between the first and second halves of the stimulus. Computed as 1 - 4 * f1 * f2, where f1 and f2 are the proportions of note onsets falling before and after the temporal midpoint, respectively. Values near 1 indicate balanced onset placement; lower values indicate concentration of events in one half.
- center_mass_offset(melody)[source]
The center of mass offset of a melody’s note-onset distribution.
The absolute distance between the temporal center of mass (mean onset time, expressed as a proportion of total stimulus duration) and the geometric center (0.5). Values near 0 indicate a centrally concentrated onset distribution.
- event_heterogeneity(melody)[source]
The event heterogeneity of a melody’s temporal distribution of onsets.
First computes a local unbalance curve using sliding windows sized to contain two note events (stepped at half the window length), then returns the distance-weighted mean squared deviation of that curve from unity.
- av_abs_interval(melody)[source]
The mean log-transformed absolute melodic interval size.
Computed as the mean of log(abs(interval) + 1) over consecutive pitch pairs, where intervals are measured in semitones.
- mel_abruptness(melody)[source]
The melodic abruptness of pitch-direction changes in a melody.
For each interior note where the pitch contour changes direction, accumulates the natural logarithm of the mean absolute interval size at that turning point, then normalizes by total stimulus duration in seconds.
- dur_abruptness(melody)[source]
The durational abruptness of pitch-direction changes in a melody.
The proportion of total note duration (in seconds) accounted for by notes at which the pitch contour changes direction.
- rhythm_abruptness(melody)[source]
The rhythmic abruptness of consecutive note durations.
The mean ratio of consecutive beat durations after applying Parncutt (1994) duration accent, taking the larger-over-smaller ratio at each successive pair of notes.
- Parameters:
melody (Melody) – The melody to analyze
- Returns:
Rhythmic abruptness score
- Return type:
Note
Duration accent follows the MIDI Toolbox duraccent defaults (tau=0.5, accent_index=2.0).
References
Parncutt (1994)
- asym_total(melody)[source]
The total vertical mirror asymmetry of a melody.
Mirrors the MUST asymTotal implementation: build a sustained-pitch time series, compare each sample to its temporally reversed counterpart, and return the mean absolute pitch difference.
- Parameters:
melody (Melody) – The melody to analyze
- Returns:
Total asymmetry in semitones (time-averaged)
- Return type:
Note
In the MUST/MIDI Toolbox notematrix, onset (column 1) and duration (column 2) are in beats. The reference MATLAB code samples with for t = 0:0.0001:T using that same unit. There is no separate millisecond grid.
This implementation converts Melody timing to beats and uses the same 0.0001 beat step. The real-time length of one step depends on tempo (e.g. 0.1 ms only at 60 BPM, 0.05 ms at 120 BPM).
- asym_index(melody)[source]
The vertical mirror asymmetry index of a melody.
Mirrors the MUST asymIndex implementation: the proportion of sampled time points at which pitch differs from its temporally mirrored counterpart.
- Parameters:
melody (Melody) – The melody to analyze
- Returns:
Asymmetry index in the range [0, 1]
- Return type:
Note
In the MUST/MIDI Toolbox notematrix, onset (column 1) and duration (column 2) are in beats. The reference MATLAB code samples with for t = 0:0.0001:T using that same unit. There is no separate millisecond grid.
This implementation converts Melody timing to beats and uses the same 0.0001 beat step. The real-time length of one step depends on tempo (e.g. 0.1 ms only at 60 BPM, 0.05 ms at 120 BPM).
- event_density(melody)[source]
The event density of a melody.
The number of note events divided by total stimulus duration in seconds.
- av_local_p1_entropy(melody)[source]
The average local zeroth-order pitch entropy across a melody.
Computes Shannon entropy of the pitch distribution within sliding one-second windows advanced in 0.25-second steps, using an inclusive upper onset bound, then returns the mean entropy across windows.
- Parameters:
melody (Melody) – The melody to analyze
- Returns:
Average local pitch entropy
- Return type:
Note
Entropy is computed with the natural logarithm, consistent with the MUST Toolbox shentropy implementation.
- p1_entropy(melody)[source]
The zeroth-order pitch entropy of a melody.
Shannon entropy of the marginal pitch distribution.
Note
Entropy is computed with the natural logarithm, consistent with the MUST Toolbox shentropy implementation.
- p2_entropy(melody)[source]
The first-order (2-tuple) pitch entropy of a melody.
Shannon entropy of the distribution of consecutive pitch pairs.
- Parameters:
melody (Melody) – The melody to analyze
- Returns:
2-tuple pitch entropy
- Return type:
Note
Entropy is computed with the natural logarithm, consistent with the MUST Toolbox shentropy implementation.
- p3_entropy(melody)[source]
The second-order (3-tuple) pitch entropy of a melody.
Shannon entropy of the distribution of consecutive pitch triples.
- Parameters:
melody (Melody) – The melody to analyze
- Returns:
3-tuple pitch entropy
- Return type:
Note
Entropy is computed with the natural logarithm, consistent with the MUST Toolbox shentropy implementation.
- i1_entropy(melody)[source]
The zeroth-order interval entropy of a melody.
Shannon entropy of the distribution of consecutive melodic intervals, weighted by the underlying 2-tuple pitch distribution.
Note
Entropy is computed with the natural logarithm, consistent with the MUST Toolbox shentropy implementation.
- i2_entropy(melody)[source]
The first-order (2-tuple) interval entropy of a melody.
Shannon entropy of the distribution of consecutive interval pairs, weighted by the underlying 3-tuple pitch distribution.
- Parameters:
melody (Melody) – The melody to analyze
- Returns:
2-tuple interval entropy
- Return type:
Note
Entropy is computed with the natural logarithm, consistent with the MUST Toolbox shentropy implementation.
- d1_entropy(melody)[source]
The zeroth-order duration entropy of a melody.
Shannon entropy of the distribution of note durations in quarter-note beats. The final note duration is excluded, consistent with the MUST ddist1 convention.
Note
Entropy is computed with the natural logarithm, consistent with the MUST Toolbox shentropy implementation. Durations are rounded to two decimal places before binning.
- d2_entropy(melody)[source]
The first-order (2-tuple) duration entropy of a melody.
Shannon entropy of the distribution of consecutive duration pairs in quarter-note beats. The final note duration is excluded.
- Parameters:
melody (Melody) – The melody to analyze
- Returns:
2-tuple duration entropy
- Return type:
Note
Entropy is computed with the natural logarithm, consistent with the MUST Toolbox shentropy implementation. Durations are rounded to two decimal places before binning.
- d3_entropy(melody)[source]
The second-order (3-tuple) duration entropy of a melody.
Shannon entropy of the distribution of consecutive duration triples in quarter-note beats. The final note duration is excluded.
- Parameters:
melody (Melody) – The melody to analyze
- Returns:
3-tuple duration entropy
- Return type:
Note
Entropy is computed with the natural logarithm, consistent with the MUST Toolbox shentropy implementation. Durations are rounded to two decimal places before binning.
- wp_entropy(melody)[source]
The weighted permutation entropy of a melody’s pitch sequence.
Classifies each consecutive 3-note pitch window into one of 13 order signatures, weights each class by the standard deviation of the three pitches, and computes Shannon entropy over the resulting distribution.
- Parameters:
melody (Melody) – The melody to analyze
- Returns:
Weighted permutation entropy
- Return type:
Note
Entropy is computed with the natural logarithm, consistent with the MUST Toolbox shentropy implementation.
- pdist1(melody)[source]
Pitch distribution (MUST pdist1.m).
Returns normalized weights keyed by MIDI pitch.
- pdist2(melody)[source]
2-tuple pitch distribution (MUST pdist2.m).
Returns normalized weights keyed by consecutive pitch pairs.
- pdist3(melody)[source]
3-tuple pitch distribution (MUST pdist3.m).
Returns normalized weights keyed by consecutive pitch triples.
- ddist1(melody)[source]
Duration distribution in beats (MUST ddist1.m).
The final note duration is excluded, consistent with the MUST ddist* convention. Durations are rounded to two decimal places in beats.