partitura.musicanalysis

This module contains tools for estimating key signature, time signature, pitch spelling, voice information, tonal tension, as well as methods for deriving note-level features and performance encodings.

partitura.musicanalysis.compute_note_array(part: List[Part | PartGroup] | Part | PartGroup | Score, include_pitch_spelling=False, include_key_signature=False, include_time_signature=False, include_metrical_position=False, include_grace_notes=False, feature_functions=None, force_fixed_size=False)

Create an extended note array from this part.

1) Without arguments this returns a structured array of onsets, offsets, pitch, and ID information: equivalent to part.note_array()

2) With any of the flag arguments set to true, a column with the specified information will be added to the array: equivalent t0 part.note_array(*flags)

3) With a list of strings or functions as feature_functions argument, a column (or multiple columns) with the specified information will be added to the array. See also: >>> make_note_features(part) For a list of features see: >>> list_note_feats_functions()

Parameters:

• include_pitch_spelling (bool (optional)) – If True, includes pitch spelling information for each note. Default is False

• include_key_signature (bool (optional)) – If True, includes key signature information, i.e., the key signature at the onset time of each note (all notes starting at the same time have the same key signature). Default is False

• include_time_signature (bool (optional)) – If True, includes time signature information, i.e., the time signature at the onset time of each note (all notes starting at the same time have the same time signature). Default is False

• include_metrical_position (bool (optional)) – If True, includes metrical position information, i.e., the position of the onset time of each note with respect to its measure (all notes starting at the same time have the same metrical position). Default is False

• include_grace_notes (bool (optional)) – If True, includes grace note information, i.e. if a note is a grace note and the grace type “” for non grace notes). Default is False

• feature_functions (list or str) – A list of feature functions. Elements of the list can be either the functions themselves or the names of a feature function as strings (or a mix). The feature functions specified by name are looked up in the featuremixer.featurefunctions module.

• force_fixed_size (bool (default: False)) – If True, the output array uses only features that have a fixed size with no new entries added.

Returns:

note_array : structured array

partitura.musicanalysis.decode_performance(score: List[Part | PartGroup] | Part | PartGroup | Score, performance_array: ndarray, snote_ids=None, part_id=None, part_name=None, return_alignment=False, beat_normalization: str = 'beat_period', *args, **kwargs) → PerformedPart

Given a Part (score) and a performance array return a PerformedPart.

Parameters:

• score (partitura.score.ScoreLike) – Score information, could be part, Score

• performance_array (structured array) – A performed array related to the part.

• snote_ids (list) –

• part_id (str) –

• part_name (str) –

• return_alignment (bool) – True returns alignment list of dicts.

Returns:

• ppart (partitura.performance.PerformedPart) – A partitura PerformedPart.

• alignment (list (optional)) – A list of dicts for the alignment.

partitura.musicanalysis.encode_performance(score: List[Part | PartGroup] | Part | PartGroup | Score, performance: List[PerformedPart] | PerformedPart | Performance, alignment: list, return_u_onset_idx=False, beat_normalization: str = 'beat_period', tempo_smooth: str | Callable = 'average')

Encode expressive parameters from a matched performance

Parameters:

• score (partitura.score.ScoreLike) – Score information, can be a part, score

• performance (partitura.performance.PerformanceLike) – Performance information, can be a ppart, performance

• alignment (list) – The score–performance alignment, a list of dictionaries

• return_u_onset_idx (bool) – Return the indices of the unique score onsets

• beat_normalization (str (Optional)) – Return extra columns for normalization parameters.

• tempo_smooth (str (Optional)) – How the tempo curve is computed. average or derivative. Can also input a callable function for user-defined tempo curve.

Returns:

• parameters (structured array) – A performance array with 4 fields: beat_period, velocity, timing, and articulation_log. If beat_normalization is defined as any method other than beat_period, return the normalization value as extra columns in parameters.

• snote_ids (dict) – A dict of snote_ids corresponding to performance notes.

• unique_onset_idxs (list (optional)) – List of unique onset ids. Returned only when return_u_onset_idx is set to True.

partitura.musicanalysis.estimate_key(note_info, method='krumhansl', *args, **kwargs)

Estimate key of a piece by comparing the pitch statistics of the note array to key profiles [2], [3].

Parameters:

• note_info (structured array, Part or PerformedPart) – Note information as a Part or PerformedPart instances or as a structured array. If it is a structured array, it has to contain the fields generated by the note_array properties of Part or PerformedPart objects. If the array contains onset and duration information of both score and performance, (e.g., containing both onset_beat and onset_sec), the score information will be preferred.

• method ({'krumhansl'}) – Method for estimating the key. For now ‘krumhansl’ is the only supported method.

• args – Positional and Keyword arguments for the key estimation method

• kwargs – Positional and Keyword arguments for the key estimation method

Returns:

String representing the key name (i.e., Root(alteration)(m if minor)). See partitura.utils.key_name_to_fifths_mode and partitura.utils.fifths_mode_to_key_name.

Return type:

str

References

[2]

Krumhansl, Carol L. (1990) “Cognitive foundations of musical pitch”, Oxford University Press, New York.

[3]

Temperley, D. (1999) “What’s key for key? The Krumhansl-Schmuckler key-finding algorithm reconsidered”. Music Perception. 17(1), pp. 65–100.

partitura.musicanalysis.estimate_spelling(note_info, method='ps13s1', **kwargs)

Estimate pitch spelling using the ps13 algorithm [4], [5].

Parameters:

• note_info (structured array, Part or PerformedPart) – Note information as a Part or PerformedPart instances or as a structured array. If it is a structured array, it has to contain the fields generated by the note_array properties of Part or PerformedPart objects. If the array contains onset and duration information of both score and performance, (e.g., containing both onset_beat and onset_sec), the score information will be preferred.

• method ({'ps13s1'}) – Pitch spelling algorithm. More methods will be added.

• **kwargs – Keyword arguments for the algorithm specified in method.

Returns:

spelling – Array with pitch spellings. The fields are ‘step’, ‘alter’ and ‘octave’

Return type:

structured array

References

[4]

Meredith, D. (2006). “The ps13 Pitch Spelling Algorithm”. Journal of New Music Research, 35(2):121.

[5]

Meredith, D. (2019). “RecurSIA-RRT: Recursive translatable point-set pattern discovery with removal of redundant translators”. 12th International Workshop on Machine Learning and Music. Würzburg, Germany.

partitura.musicanalysis.estimate_time(note_info)

Estimate tempo, meter (currently only time signature numerator), and beats

Parameters:

note_info (structured array, Part or PerformedPart) – Note information as a Part or PerformedPart instances or as a structured array. If it is a structured array, it has to contain the fields generated by the note_array properties of Part or PerformedPart objects. If the array contains onset and duration information of both score and performance, (e.g., containing both onset_beat and onset_sec), the score information will be preferred.

Returns:

Tempo, meter, and beat information

Return type:

dict

partitura.musicanalysis.estimate_tonaltension(note_info, ws=1.0, ss='onset', scale_factor=0.09249316305671976, w=array([0.516, 0.315, 0.168]), alpha=0.75, beta=0.75)

Compute tonal tension ribbons defined in [1]

Parameters:

• note_info (structured array, Part or PerformedPart) – Note information as a Part or PerformedPart instances or as a structured array. If it is a structured array, it has to contain the fields generated by the note_array properties of Part or PerformedPart objects. If the array contains onset and duration information of both score and performance, (e.g., containing both onset_beat and onset_sec), the score information will be preferred. Furthermore, this method requires pitch spelling and key signature information. If a structured note array is provided as input, this information can be optionally provided in fields step, alter, ks_fifths and ks_mode. If these fields are not found in the input structured array, they will be estimated using the key and pitch spelling estimation methods from partitura.musicanalysis.estimate_key and and partitura.musicanalysis.estimate_spelling, respectively.

• ws ({int, float, np.array}, optional) – Window size for computing the tonal tension. If a number, it determines the size of the window centered at each specified score position (see ss below). If a numpy array, a 2D array of shape (len(ss), 2) specifying the left and right distance from each score position in ss. Default is 1 beat.

• ss ({float, int, np.array, 'onset'}, optional.) – Step size or score position for computing the tonal tension features. If a number, this parameter determines the size of the step (in beats) starting from the first score position. If an array, it specifies the score positions at which the tonal tension is estimated. If ‘onset’, it computes the tension at each unique score position (i.e., all notes in a chord have the same score position). Default is ‘onset’.

• scale_factor (float) – A multiplicative scaling factor.

• w (np.ndarray) – Weights for the chords

• alpha (float) – Alpha.

• beta (float) – Beta.

Returns:

tonal_tension – Array containing the tonal tension features. It contains the fields cloud_diameter, cloud_momentum, tensile_strain and onset.

Return type:

structured array

References

[1]

D. Herremans and E. Chew (2016) Tension ribbons: Quantifying and visualising tonal tension. Proceedings of the Second International Conference on Technologies for Music Notation and Representation (TENOR), Cambridge, UK.

partitura.musicanalysis.estimate_voices(note_info, monophonic_voices=True)

Voice estimation using the voice separation algorithm

proposed in [6].

Parameters:

• note_info (structured array, Part or PerformedPart) – Note information as a Part or PerformedPart instances or as a structured array. If it is a structured array, it has to contain the fields generated by the note_array properties of Part or PerformedPart objects. If the array contains onset and duration information of both score and performance, (e.g., containing both onset_beat and onset_sec), the score information will be preferred.

• monophonic_voices (bool) – If True voices are guaranteed to be monophonic. Otherwise notes with the same onset and duration are treated as a chord and assigned to the same voice. Defaults to False.

Returns:

voice – Voice for each note in the notearray. (The voices start with 1, as is the MusicXML convention).

Return type:

numpy array

References

[6]

Chew, E. and Wu, Xiaodan (2004) “Separating Voices in Polyphonic Music: A Contig Mapping Approach”. In Uffe Kock, editor, “Computer Music Modeling and Retrieval”. Springer Berlin Heidelberg.

partitura.musicanalysis.full_note_array(part)

Create a note array with all available information.

partitura.musicanalysis.list_note_feats_functions()

Return a list of all feature function names defined in this module.

The feature function names listed here can be specified by name in the make_note_features and make_rest_features functions. For example:

>>> feature, names = make_note_feats(part, ['metrical_feature', 'articulation_feature'])

Returns:

A list of strings

Return type:

list

partitura.musicanalysis.make_note_features(part: List[Part | PartGroup] | Part | PartGroup | Score, feature_functions: List | str, add_idx: bool = False, include_empty_features: bool = True, force_fixed_size: bool = False) → Tuple[ndarray, List]

Compute the specified feature functions for a part.

The function returns the computed feature functions as a N x M array, where N equals len(part.notes_tied) and M equals the total number of descriptors of all feature functions that occur in part.

Furthermore, the function returns the names of the feature functions. A list of strings of size M. The names have the name of the function prepended to the name of the descriptor. For example if a function named abc_feature returns descriptors a, b, and c, then the list of names returned by make_feature(part, [‘abc_feature’]) will be [‘abc_feature.a’, ‘abc_feature.b’, ‘abc_feature.c’].

Parameters:

• part (ScoreLike) – A partitura scoreLike object, can be Score, Part, or PartGroup.

• feature_functions (list or str) – A list of feature functions. Elements of the list can be either the functions themselves or the names of a feature function as strings (or a mix), or the keywork “all”. The feature functions specified by name are looked up in the featuremixer.featurefunctions module.

• add_idx (bool (default: False)) – If True, the index of the note in the part is added as a feature. This is useful for debugging.

• include_empty_features (bool (default: True)) – If True, features that are empty are included in the output. Otherwise, they are omitted.

• force_fixed_size (bool (default: False)) – If True, the output array uses only features that have a fixed size with no new entries added.

Returns:

• feature (ndarray) – The feature functions

• names (list) – The feature names

partitura.musicanalysis.make_performance_features(score: List[Part | PartGroup] | Part | PartGroup | Score, performance: List[PerformedPart] | PerformedPart | Performance, alignment: list, feature_functions: List | str, add_idx: bool = True)

Compute the performance features. This function is defined in the same style of note_features.make_note_features

Parameters:

• score (partitura.score.ScoreLike) – Score information, can be a part, score

• performance (partitura.performance.PerformanceLike) – Performance information, can be a ppart, performance

• alignment (list) – The score–performance alignment, a list of dictionaries

• feature_functions (list or str) – A list of performance feature functions. Elements of the list can be either the functions themselves or the names of a feature function as strings (or a mix). currently implemented: asynchrony_feature, articulation_feature, dynamics_feature, pedal_feature

• add_idx (bool) – add score note idx column to feature array

Returns:

performance_features

Return type:

structured array

partitura.musicanalysis.make_rest_features(part: Part | PartGroup | List, feature_functions: List | str, add_idx: bool = False) → Tuple[ndarray, List]

Compute the specified feature functions for a part.

The function returns the computed feature functions as a N x M array, where N equals len(part.rests) and M equals the total number of descriptors of all feature functions that occur in part.

Parameters:

• part (Part) – The score as a Part instance

• feature_functions (list or str) – A list of feature functions. Elements of the list can be either the functions themselves or the names of a feature function as strings (or a mix), or the keywork “all”. The feature functions specified by name are looked up in the featuremixer.featurefunctions module.

Returns:

• feature (ndarray) – The feature functions

• names (list) – The feature names

partitura.musicanalysis.note_array_to_score(note_array: ndarray | list, name_id: str = '', divs: int | None = None, key_sigs: list | None = None, time_sigs: list | None = None, part_name: str = '', assign_note_ids: bool = True, estimate_key: bool = False, estimate_time: bool = False, sanitize: bool = True, return_part: bool = False) → List[Part | PartGroup] | Part | PartGroup | Score

A generic function to transform an enriched note_array to part or Score.

The function can be used for many different occasions, i.e. part_from_graph, part from note_array, part from midi score import, etc. This function requires a note array that contains time signatures and key signatures (optional - can also estimate it automatically). Note array should contain the following fields: - onset_div or onset_beat - duration_div or duration_beat - pitch

For time signature and key signature the arguments are processed in the following hierarchy:

Key sig: ([“key_fifths”, “key_mode”] fields) overrides (key_sigs list) overrides (estimate_key bool) Time sig: ([“ts_beats”, “ts_beat_type”] fields) overrides (time_sigs list) overrides (estimate_time bool)

If either times in divs or beats are missing, these cases are assumed:

Only divs: divs/ticks need to be specified, beats are computed as quarters (not relative to time signature). Only beats: divs/ticks as well as times in divs are computed assuming the beat times are given in quarters.

This function thus handles the following cases:

1. note_array fields [“onset_beat”, “duration_beat”, “pitch”]

   -> barebones part, divs estimated assuming uniform beats in quarters + estimate_time -> 4/4 time signature + estimate_key -> barebones + estimate key signature + time_sigs -> time signatures are added, times assumed in quarters (possible error against div/beat) + key_sigs -> key signatures are added, times assumed in quarters + [“ts_beats”, “ts_beat_type”] -> time signatures are added (possible error against div/beat) + [“key_fifths”, “key_mode”] -> key signatures are added

2. note_array fields [“onset_div”, “duration_div”, “pitch”]

   -> barebones part, uniform beats in quarters estimated from beats + estimate_time -> 4/4 time signature + estimate_key -> barebones + estimate key signature + time_sigs -> time signatures are added, times assumed in divs (possible error against div/beat) + key_sigs -> key signatures are added, times assumed in divs + [“ts_beats”, “ts_beat_type”] -> time signatures are added (possible error against div/beat) + [“key_fifths”, “key_mode”] -> key signatures are added

3. note_array fields [“onset_div”, “duration_div”, “onset_beat”, “duration_beat”, “pitch”]

   -> barebones part + estimate_time -> 4/4 time signature (possible error against div/beat) + estimate_key -> barebones + estimate key signature + time_sigs -> time signatures are added, times assumed in divs (possible error against div/beat) + key_sigs -> key signatures are added, times assumed in divs + [“ts_beats”, “ts_beat_type”] -> time signatures are added (possible error against div/beat) + [“key_fifths”, “key_mode”] -> key signatures are added

Parameters:

• note_array (structure array or list of structured arrays.) – A note array with the following fields: - onset_div or onset_beat - duration_div or duration_beat - pitch - ts_beats (optional) - ts_beat_type (optional) - key_mode(optional) - key_fifths(optional) - id (optional)

• divs (int (optional)) – Divs/ticks per quarter note. If not given, it is estimated assuming a beats in quarters.

• key_sigs (list (optional)) – A list of key signatures. Each key signature is a tuple of the form (onset, key_name, offset). Overridden by note_array fields “key_mode” and “key_fifths”. Overrides estimate_key.

• time_sigs (list (optional)) – A list of time signatures. Each time signature is a tuple of the form (onset, ts_num, ts_den, offset). Overridden by note_array fields “key_mode” and “key_fifths”. Overrides estimate_time.

• estimate_key (bool (optional)) – Estimate a single key signature.

• estimate_time (bool (optional)) – Add a default time signature.

• assign_note_ids (bool (optional)) – Assign note_ids.

• sanitize (bool (optional)) – sanitize the part by adding measures, tying notes, and finding tuplets.

• return_part (bool (optional)) – Return a Partitura part object instead of a score.

Returns:

part or score – a Part object or a Score object, depending on return_part.

Return type:

Part or Score