symbolicUtils

pyampact.symbolicUtils.addMEINote(note, parent, syl=None)[source]

Add a note element to an MEI parent element from a music21 note object.

This function creates a new ‘note’ subelement under the given parent element, and sets its attributes based on the properties of the given note. It also handles grace notes, accidentals, lyrics, and dynamics if any of these are found on the note.

Parameters: note (music21.note.Note): The note to add. The note’s properties (octave,

step, id, duration, pitch, lyric, expressions) are used to set the attributes of the new MEI element.

parent (xml.etree.ElementTree.Element): The parent element to which the new: ‘note’ element will be added.
syl (str, optional): A syllable to add to the note as a ‘syl’ element. If: not provided, the note’s lyric property is used.

Returns: xml.etree.ElementTree.Element: The new ‘note’ element.

pyampact.symbolicUtils.addTieBreakers(partList)[source]

Add tie-breaker level to index. Changes parts in partList in place and returns None.

This is particularly useful to disambiguate the order of events that happen at the same offset, which is an issue most commonly encountered with grace notes since they have no duration. This is needed in several Score methods because you cannot append multiple pandas series (parts) if they have non-unique indices. So this method is needed internally to be able to use pd.concat to turn a list of series into a single dataframe if any of those series has a repeated value in its index.

Parameters:: partList – A list of pandas Series, each representing a part in the score.
Returns:: None

pyampact.symbolicUtils.combineRests(col)[source]

Helper function for the notes method.

Combine consecutive rests in a given voice. Non-first consecutive rests will be removed.

Parameters:: col – A pandas Series representing a voice.
Returns:: The same pandas Series with consecutive rests combined.

pyampact.symbolicUtils.combineUnisons(col)[source]

Helper function for the notes method.

Combine consecutive unisons in a given voice. Non-first consecutive unisons will be removed.

Parameters:: col – A pandas Series representing a voice.
Returns:: The same pandas Series with consecutive unisons combined.

pyampact.symbolicUtils.fromJSON(json_path)[source]

Load a JSON or dez file/url into a pandas DataFrame.

The outermost keys of the JSON object are interpreted as the index values of the DataFrame and should be in seconds with decimal places allowed. The second-level keys become the columns of the DataFrame.

Parameters:: json_path – Path to a JSON or dez file.
Returns:: A pandas DataFrame representing the JSON data.

See also

jsonCDATA(), nmats()

Example

piece = Score('./test_files/CloseToYou.mei.xml')
piece.fromJSON(json_path='./test_files/CloseToYou.json')

pyampact.symbolicUtils.githubURLtoRaw(string)[source]: Convert a GitHub URL to a raw URL and return it. Otherwise return the string.

pyampact.symbolicUtils.indentMEI(elem, indentation='\t', _level=0)[source]

Indent an MEI (Music Encoding Initiative) XML element and its children.

This function recursively indents an XML element and its children for pretty printing. The indentation level is increased for each level of depth in the XML tree.

Parameters: elem (xml.etree.ElementTree.Element): The XML element to indent. indentation (str, optional): The indentation string to use. Default is a

tab character. Use a ‘ ‘ (space) for maximally compact output.

_level (int, optional): The initial indentation level. This parameter is used: internally in recursive calls but should not be set by the user.

Returns: None. The function modifies the XML element in place.

pyampact.symbolicUtils.kernClefHelper(clef)[source]

Parse a music21 clef object into the corresponding humdrum syntax token.

Parameters:: clef – A music21 clef object.
Returns:: A string representing the humdrum syntax token for the clef.

pyampact.symbolicUtils.kernFooter(fileExtension)[source]

Return a string of the kern format footer global comments.

The footer includes the translation date and other relevant metadata.

Returns:: A string representing the kern format footer.

pyampact.symbolicUtils.kernHeader(metadata)[source]

Return a string of the kern format header global comments.

The header includes the composer and title metadata.

Returns:: A string representing the kern format header.

pyampact.symbolicUtils.kernNRCHelper(nrc)[source]

Convert a music21 note, rest, or chord object to its corresponding kern token.

This method uses the _kernNoteHelper and _kernChordHelper methods to convert note and chord objects, respectively. Rest objects are converted directly in this method.

Parameters:: nrc – A music21 note, rest, or chord object to be converted into a kern token.
Returns:: A string representing the kern token.

pyampact.symbolicUtils.noteRestHelper(nr)[source]

Helper function for the notes method.

If the note/rest object nr is a rest, return ‘r’. Otherwise, return the note’s name with octave.

Parameters:: nr – A note/rest object.
Returns:: ‘r’ if nr is a rest, otherwise the note’s name with octave.

pyampact.symbolicUtils.removeTied(noteOrRest)[source]

Helper function for the _m21ObjectsNoTies method.

Remove tied notes in a given note or rest. Only the first note in a tied group will be kept.

Parameters:: noteOrRest – A music21 note or rest object.
Returns:: np.nan if the note is tied and not the first in the group, otherwise the original note or rest.

pyampact.symbolicUtils.remove_namespaces(doc)[source]

Indent an MEI (Music Encoding Initiative) element for better readability.

This function recursively indents an MEI element and its children, improving the readability of the MEI XML structure. It modifies the input element in-place.

Parameters:

elem – An xml.etree.ElementTree.Element representing the MEI element.
level – An integer representing the current indentation level. Default is 0.

Returns:

None

pyampact.symbolicUtils.snapTo(data, snap_to=None, filler='forward', output='array')[source]

” Takes a harm, keys, functions, chords, or cdata as data and the snap_to and filler parameters as described in the former three’s doc strings.

The passed data is returned in the shape of the snap_to dataframe’s columns, and any filling operations are applied. The output will be in the form of a 1D numpy array unless output is changed, in which case a series will be returned for harm, keys, functions, and chords data, and a dataframe for cdata data.

Parameters:

data – Can be harm, keys, functions, chords, or cdata.
snap_to – Described in the docstrings of harm, keys, and functions.
filler – Described in the docstrings of harm, keys, and functions.
output – If changed, a series will be returned for harm, keys, functions, and chords data, and a dataframe for cdata data. Default is a 1D numpy array.

Returns:

The passed data in the shape of the snap_to dataframe’s columns with any filling operations applied.

pyampact.symbolicUtils.truncate_and_scale_onsOffsList(onsOffsList, target_length)[source]

Scale and truncate onsOffsList to match the target_length, adjusting values proportionally.

Parameters: onsOffsList (list of lists): List containing [ONSET_SEC, OFFSET_SEC] pairs. target_length (int): Desired length of the output list.

Returns: list of lists: Scaled and truncated onsOffsList.