Developers’ Reference

When using ms3, we are dealing with four main object types:

  1. MSCX objects hold the information of a single parsed MuseScore file;

  2. Annotations objects hold a set of annotation labels which can be either attached to a score (i.e., contained in its XML structure), or detached.

  3. Both types of objects are contained within a Score object. For example, a set of Annotations read from a TSV file can be attached to the XML of an MSCX object, which can then be output as a MuseScore file.

  4. To manipulate many Score objects at once, for example those of an entire corpus, we use Parse objects.

Since MSCX and Annotations objects are always attached to a Score, the documentation starts with this central class.

The Score class

class ms3.score.Score(musescore_file=None, infer_label_types=['dcml'], read_only=False, labels_cfg={}, logger_cfg={}, parser='bs4')[source]

Object representing a score.

ABS_REGEX = '^\\(?[A-G|a-g](b*|#*).*?(/[A-G|a-g](b*|#*))?$'

str Class variable with a regular expression that recognizes absolute chord symbols in their decoded (string) form; they start with a note name.

DCML_REGEX = re.compile('\n ^(?P<first>\n (\\.?\n ((?P<globalkey>[a-gA-G](b*|\\#*))\\.)?\n , re.VERBOSE)

str Class variable with a regular expression that recognizes labels conforming to the DCML harmony annotation standard.

NASHVILLE_REGEX = '^(b*|#*)(\\d).*$'

str Class variable with a regular expression that recognizes labels representing a Nashville numeral, which MuseScore is able to encode.

RN_REGEX = '^$'

str Class variable with a regular expression for Roman numerals that romentarily matches nothing because ms3 tries interpreting Roman Numerals als DCML harmony annotations.

full_paths

dict {KEY: {i: full_path}} dictionary holding the full paths of all parsed MuseScore and TSV files, including file names. Handled internally by _handle_path().

paths

dict {KEY: {i: file path}} dictionary holding the paths of all parsed MuseScore and TSV files, excluding file names. Handled internally by _handle_path().

files

dict {KEY: {i: file name with extension}} dictionary holding the complete file name of each parsed file, including the extension. Handled internally by _handle_path().

fnames

dict {KEY: {i: file name without extension}} dictionary holding the file name of each parsed file, without its extension. Handled internally by _handle_path().

fexts

dict {KEY: {i: file extension}} dictionary holding the file extension of each parsed file. Handled internally by _handle_path().

parser

{‘bs4’} Currently only one XML parser has been implemented which uses BeautifulSoup 4.

property infer_label_types

list or dict, optional The order in which label types are to be inferred. Assigning a new value results in a call to infer_types(). Passing a {label type: regex} dictionary is a shortcut to update type regex’s or to add new ones. The inference will take place in the order in which they appear in the dictionary. To reuse an existing regex will updating others, you can refer to them as None, e.g. {'dcml': None, 'my_own': r'^(PAC|HC)$'}.

property has_detached_annotations

bool Is True as long as the score contains Annotations objects, that are not attached to the MSCX object.

property mscx

MSCX Standard way of accessing the parsed MuseScore file.

property types

dict Shows the mapping of label types to their descriptions.

attach_labels(key, staff=None, voice=None, check_for_clashes=True)[source]

Insert detached labels key into this score’s MSCX object.

Parameters
  • key (str) – Key of the detached labels you want to insert into the score.

  • staff (int, optional) – Pass one or both of these arguments to change the original annotation layer or if there was none.

  • voice (int, optional) – Pass one or both of these arguments to change the original annotation layer or if there was none.

  • check_for_clashes (bool, optional) – Defaults to True, meaning that the positions where the labels will be inserted will be checked for existing labels.

Returns

  • int – Number of newly attached labels.

  • int – Number of labels that were to be attached.

detach_labels(key, staff=None, voice=None, label_type=None, delete=True)[source]

Detach all annotations labels from this score’s MSCX object or just a selection of them. The extracted labels are stored as a new Annotations object that is accessible via Score.{key}. By default, delete is set to True, meaning that if you call store_mscx() afterwards, the created MuseScore file will not contain the detached labels.

Parameters
  • key (str) – Specify a new key for accessing the detached set of annotations. The string needs to be usable as an identifier, e.g. not start with a number, not contain special characters etc. In return you may use it as a property: For example, passing 'chords' lets you access the detached labels as Score.chords. The key ‘annotations’ is reserved for all annotations attached to the score.

  • staff (int, optional) – Pass a staff ID to select only labels from this staff. The upper staff has ID 1.

  • voice ({1, 2, 3, 4}, optional) – Can be used to select only labels from one of the four notational layers. Layer 1 is MuseScore’s main, ‘upper voice’ layer, coloured in blue.

  • label_type (int or str, optional) – Select one of the predefined or custom label types to select only labels of this type. Predefined types are {0, 1, 2, 3, ‘dcml’} (see _label_types).

  • delete (bool, optional) – By default, the labels are removed from the XML structure in MSCX. Pass False if you want them to remain. This could be useful if you only want to extract a subset of the annotations for storing them separately but without removing the labels from the score.

get_infer_regex()[source]
Returns

Mapping of label types to the corresponding regular expressions in the order in which they are currently set to be inferred.

Return type

dict

new_type(name, regex, description='', infer=True)[source]

Declare a custom label type. A type consists of a name, a regular expression and, falculatively, of a description.

Parameters
  • name (str or int) – Name of the custom label type.

  • regex (str) – Regular expression that matches all labels of the custom type.

  • description (str, optional) – Human readable description that appears when calling the property Score.types.

  • infer (bool, optional) – By default, the labels of all Annotations objects are matched against the new type. Pass False to not change any label’s type.

load_annotations(tsv_path=None, anno_obj=None, key='tsv', cols={}, infer=True)[source]

Attach an Annotations object to the score and make it available as Score.{key}. It can be an existing object or one newly created from the TSV file tsv_path.

Parameters
  • tsv_path (str) – If you want to create a new Annotations object from a TSV file, pass its path.

  • anno_obj (Annotations) – Instead, you can pass an existing object.

  • key (str, defaults to ‘tsv’) – Specify a new key for accessing the set of annotations. The string needs to be usable as an identifier, e.g. not start with a number, not contain special characters etc. In return you may use it as a property: For example, passing 'chords' lets you access the Annotations as Score.chords. The key ‘annotations’ is reserved for all annotations attached to the score.

  • cols (dict, optional) – If the columns in the specified TSV file diverge from the standard column names, pass a {standard name: custom name} dictionary.

  • infer (bool, optional) – By default, the label types are inferred in the currently configured order (see infer_label_types). Pass False to not add and not change any label types.

store_annotations(key=None, tsv_path=None, **kwargs)[source]

Save a set of annotations as TSV file. While store_list stores attached labels only, this method can also store detached labels by passing a key.

Parameters
  • key (str, optional) – Key of the Annotations object which you want to output as TSV file. By default, the annotations attached to the score (key=’annotations’) are stored.

  • tsv_path (str, optional) – Path of the newly created TSV file including the file name. By default, the TSV file is stored next to t

  • kwargs – Additional keyword arguments will be passed to the function pandas.DataFrame.to_csv() to customise the format of the created file (e.g. to change the separator to commas instead of tabs, you would pass sep=',').

store_mscx(filepath)[source]

Store the current MSCX object attached to this score as uncompressed MuseScore file. Just a shortcut for Score.mscx.store_mscx().

Parameters

filepath (str) – Path of the newly created MuseScore file, including the file name ending on ‘.mscx’. Uncompressed files (‘.mscz’) are not supported.

The MSCX class

class ms3.score.MSCX(mscx_src, read_only=False, parser='bs4', labels_cfg={}, logger_cfg={}, level=None)[source]

Object for interacting with the XML structure of a MuseScore 3 file. Is usually attached to a Score object and exposed as Score.mscx. An object is only created if a score was successfully parsed.

mscx_src

str Full path of the parsed MuseScore file.

read_only

bool, optional Shortcut for MSCX.parsed.read_only. Defaults to False, meaning that the parsing is slower and uses more memory in order to allow for manipulations of the score, such as adding and deleting labels. Set to True if you’re only extracting information.

parser

{‘bs4’} The currently used parser.

labels_cfg

dict Configuration dictionary to determine the output format of the Annotations object representing the labels that are attached to a score (stored as _annotations`). The default options correspond to the default parameters of Annotations.get_labels().

property changed

bool Shortcut for MSCX.parsed.changed. Switches to True as soon as the original XML structure is changed. Does not automatically switch back to False.

property chords

pandas.DataFrame DataFrame representing all <Chord> tags in the score. A chord in that sense is a grouping of all synchronous notes occurring in the same notational layer of the same staff. The DataFrame contains all kinds of score markup that is not attached to particular notes but to a <Chord>, such as slurs, lyrics, staff text, ottava lines etc.

property events

pandas.DataFrame DataFrame representating a raw skeleton of the score’s XML structure and contains all score events, i.e. <Chord>, <Rest>, <Harmony> and markup tags such as <Beam> together with, in the columns the values of their XML properties and children. It serves as master for computing chords, rests, and labels (and therefore expanded, too).

property expanded

pandas.DataFrame DataFrame of labels that have been split into various features using a regular expression.

property has_annotations

bool Shortcut for MSCX.parsed.has_annotations. Is True as long as at least one label is attached to the current XML.

property labels

pandas.DataFrame DataFrame representing all <Harmony> tags in the score as returned by calling get_labels() on the object at _annotations with the current _labels_cfg.

property measures

pandas.DataFrame DataFrame representing the measures of the MuseScore file (which can be incomplete measures). The potentially incomplete measure units are numbered starting from one, which corresponds to the “bar count” displayed in MuseScore 3’s status bar. This numbering is represented in the column mc. (measure count). The columns represent for every MC its actual duration, its time signature, how it is to be considered when computing measure numbers (mn), and which other MCs can “come next” according to the score’s repeat structure.

property metadata

dict Shortcut for MSCX.parsed.metadata. Metadata from and about the MuseScore file.

property notes

pandas.DataFrame DataFrame representing all <Note> tags within the score.

property notes_and_rests

pandas.DataFrame The union of notes and rests.

property parsed

{_MSCX_bs4} Standard way of accessing the object exposed by the current parser. MSCX uses this object’s interface for requesting manipulations of and information from the source XML.

property rests

pandas.DataFrame DataFrame representing all <Rest> tags.

property staff_ids

list of int The staff IDs contained in the score, usually just a list of increasing numbers starting at 1.

property version

str MuseScore version that the file was created with.

add_labels(df, label='label', mc='mc', mc_onset='mc_onset', staff='staff', voice='voice', **kwargs)[source]

Receives the labels from an Annotations object and adds them to the XML structure representing the MuseScore file that might be written to a file afterwards.

Parameters
  • df (pandas.DataFrame) – DataFrame with labels to be added.

  • label (str) – Names of the DataFrame columns for the five required parameters.

  • mc (str) – Names of the DataFrame columns for the five required parameters.

  • mc_onset (str) – Names of the DataFrame columns for the five required parameters.

  • staff (str) – Names of the DataFrame columns for the five required parameters.

  • voice (str) – Names of the DataFrame columns for the five required parameters.

  • kwargs

    label_type, root, base, leftParen, rightParen, offset_x, offset_y, nashville

    For these parameters, the standard column names are used automatically if the columns are present. If the column names have changed, pass them as kwargs, e.g. base='name_of_the_base_column'

Returns

Number of actually added labels.

Return type

int

change_labels_cfg(labels_cfg={}, staff=None, voice=None, label_type=None, positioning=None, decode=None)[source]

Update MSCX.labels_cfg.

Parameters
  • labels_cfg (dict) – Using an entire dictionary or, to change only particular options, choose from:

  • staff – Arguments as they will be passed to get_labels()

  • voice – Arguments as they will be passed to get_labels()

  • label_type – Arguments as they will be passed to get_labels()

  • positioning – Arguments as they will be passed to get_labels()

  • decode – Arguments as they will be passed to get_labels()

delete_labels(df)[source]

Delete a set of labels from the current XML.

Parameters

df (pandas.DataFrame) – A DataFrame with the columns [‘mc’, ‘mc_onset’, ‘staff’, ‘voice’]

get_chords(staff=None, voice=None, mode='auto', lyrics=False, staff_text=False, dynamics=False, articulation=False, spanners=False, **kwargs)[source]

Retrieve a customized chord list, e.g. one including less of the processed features or additional, unprocessed ones compared to the standard chord list.

Parameters
  • staff (int) – Get information from a particular staff only (1 = upper staff)

  • voice (int) – Get information from a particular voice only (1 = only the first layer of every staff)

  • mode ({'auto', 'all', 'strict'}, optional) –

    • ‘auto’ (default), meaning that those aspects are automatically included that occur in the score; the resulting DataFrame has no empty columns except for those parameters that are set to True.

    • ’all’: Columns for all aspects are created, even if they don’t occur in the score (e.g. lyrics).

    • ’strict’: Create columns for exactly those parameters that are set to True, regardless which aspects occur in the score.

  • lyrics (bool, optional) – Include lyrics.

  • staff_text (bool, optional) – Include staff text such as tempo markings.

  • dynamics (bool, optional) – Include dynamic markings such as f or p.

  • articulation (bool, optional) – Include articulation such as arpeggios.

  • spanners (bool, optional) – Include spanners such as slurs, 8va lines, pedal lines etc.

  • **kwargs (bool, optional) – Set a particular keyword to True in order to include all columns from the _events DataFrame whose names include that keyword. Column names include the tag names from the MSCX source code.

Returns

DataFrame representing all <Chord> tags in the score with the selected features.

Return type

pandas.DataFrame

get_raw_labels()[source]

Shortcut for MSCX.parsed.get_raw_labels(). Retrieve a “raw” list of labels, meaning that label types reflect only those defined within <Harmony> tags which can be 1 (Nashville), 2 (MuseScore’s Roman Numeral display) or undefined (in the case of ‘normal’ chord labels, defaulting to 0).

Returns

DataFrame with raw label features (i.e. as encoded in XML)

Return type

pandas.DataFrame

infer_mc(mn, mn_onset=0, volta=None)[source]

Shortcut for MSCX.parsed.infer_mc(). Tries to convert a (mn, mn_onset) into a (mc, mc_onset) tuple on the basis of this MuseScore file. In other words, a human readable score position such as “measure number 32b (i.e., a second ending), beat 3” needs to be converted to (32, 1/2, 2) if “beat” has length 1/4, or–if the meter is, say 9/8 and “beat” has a length of 3/8– to (32, 6/8, 2). The resulting (mc, mc_onset) tuples are required for attaching a label to a score. This is only necessary for labels that were not originally extracted by ms3.

Parameters
  • mn (int or str) – Measure number as in a reference print edition.

  • mn_onset (fractions.Fraction, optional) – Distance of the requested position from beat 1 of the complete measure (MN), expressed as fraction of a whole note. Defaults to 0, i.e. the position of beat 1.

  • volta (int, optional) – In the case of first and second endings, which bear the same measure number, a MN might have to be disambiguated by passing 1 for first ending, 2 for second, and so on. Alternatively, the MN can be disambiguated traditionally by passing it as string with a letter attached. In other words, infer_mc(mn=32, volta=1) is equivalent to infer_mc(mn='32a').

Returns

store_mscx(filepath)[source]

Shortcut for MSCX.parsed.store_mscx(). Store the current XML structure as uncompressed MuseScore file.

Parameters

filepath (str) – Path of the newly created MuseScore file, including the file name ending on ‘.mscx’. Uncompressed files (‘.mscz’) are not supported.

Returns

Whether the file was successfully created.

Return type

bool

store_list(what='all', folder=None, suffix=None, **kwargs)[source]

Store one or several several lists as TSV files(s).

Parameters
  • what (str or Collection, optional) – Defaults to ‘all’ but could instead be one or several strings out of {‘notes’, ‘rests’, ‘notes_and_rests’, ‘measures’, ‘events’, ‘labels’, ‘chords’, ‘expanded’}

  • folder (str, optional) – Where to store. Defaults to the directory of the parsed MSCX file.

  • suffix (str or Collection, optional) – Suffix appended to the file name of the parsed MSCX file to create a new file name. Defaults to None, meaning that standard suffixes based on what are attached. Number of suffixes needs to be equal to the number of what.

  • **kwargs – Keyword arguments for pandas.DataFrame.to_csv(). Defaults to {'sep': '\t', 'index': False}. If ‘sep’ is changed to a different separator, the file extension(s) will be changed to ‘.csv’ rather than ‘.tsv’.

Returns

Return type

None

The Annotations class

class ms3.annotations.Annotations(tsv_path=None, df=None, cols={}, index_col=None, sep='\t', mscx_obj=None, infer_types={}, read_only=False, logger_cfg={}, **kwargs)[source]

Class for storing, converting and manipulating annotation labels.

property label_types

Returns the counts of the label_types as dict.

get_labels(staff=None, voice=None, label_type=None, positioning=True, decode=False, drop=False, warnings=True, column_name=None)[source]

Returns a DataFrame of annotation labels.

Parameters
  • staff (int, optional) – Select harmonies from a given staff only. Pass staff=1 for the upper staff.

  • label_type ({0, 1, 2, 3, 'dcml', ..}, optional) –

    If MuseScore’s harmony feature has been used, you can filter harmony types by passing

    0 for unrecognized strings 1 for Roman Numeral Analysis 2 for Nashville Numbers 3 for encoded absolute chords ‘dcml’ for labels from the DCML harmonic annotation standard … self-defined types that have been added to self.regex_dict through the use of self.infer_types()

  • positioning (bool, optional) – Set to True if you want to include information about how labels have been manually positioned.

  • decode (bool, optional) – Set to True if you don’t want to keep labels in their original form as encoded by MuseScore (with root and bass as TPC (tonal pitch class) where C = 14).

  • drop (bool, optional) – Set to True to delete the returned labels from this object.

  • warnings (bool, optional) – Set to False to suppress warnings about non-existent label_types.

  • column_name (str, optional) – Can be used to rename the columns holding the labels.

expand_dcml(drop_others=True, warn_about_others=True, **kwargs)[source]

Expands all labels where the label_type has been inferred as ‘dcml’ and stores the DataFrame in self._expanded.

Parameters
  • drop_others (bool, optional) – Set to False if you want to keep labels in the expanded DataFrame which have not label_type ‘dcml’.

  • warn_about_others (bool, optional) – Set to False to suppress warnings about labels that have not label_type ‘dcml’. Is automatically set to False if drop_others is set to False.

  • kwargs – Additional arguments are passed to get_labels() to define the original representation.

Returns

Expanded DCML labels

Return type

pandas.DataFrame

The Parse class

class ms3.parse.Parse(dir=None, key=None, index=None, file_re='\\.(mscx|tsv)$', folder_re='.*', exclude_re='^(\\.|_)', recursive=True, simulate=False, labels_cfg={}, logger_cfg={})[source]

Class for storing and manipulating the information from multiple parses (i.e. Score objects).

full_paths

collections.defaultdict {key: [full_path]} dictionary of the full paths of all detected files.

rel_paths

collections.defaultdict {key: [rel_path]} dictionary of the relative (to scan_paths) paths of all detected files.

scan_paths

collections.defaultdict {key: [scan_path]} dictionary of the scan_paths from which each file was detected.

paths

collections.defaultdict {key: [path]} dictionary of the paths of all detected files (without file name).

files

collections.defaultdict {key: [file]} dictionary of file names with extensions of all detected files.

fnames

collections.defaultdict {key: [fname]} dictionary of file names without extensions of all detected files.

fexts

collections.defaultdict {key: [fext]} dictionary of file extensions of all detected files.

labels_cfg

dict Configuration dictionary to determine the output format of labels and expanded tables. The dictonary is passed to Score upon parsing.

last_scanned_dir

str The directory that was scanned for files last.

property parsed

dict Returns an overview of the parsed MuseScore files.

add_detached_annotations(mscx_key, tsv_key, new_key=None, match_dict=None)[source]

Add Annotations objects generated from TSV files to the Score objects to which they are being matched based on their filenames or on match_dict.

Parameters
  • mscx_key (str) – A key under which parsed MuseScore files are stored.

  • tsv_key (str) – A key under which parsed TSV files are stored of which the type has been inferred as ‘labels’.

  • new_key (str, optional) – The key under which the Annotations objects will be available after attaching them to the Score objects (Parsed.parsed_mscx[ID].key). By default, tsv_key is used.

  • match_dict (dict, optional) – Dictionary mapping IDs of parsed Score objects to IDs of parsed Annotations objects.

add_dir(dir, key=None, index=None, file_re='\\.mscx$', folder_re='.*', exclude_re='^(\\.|__)', recursive=True)[source]

This function scans the directory dir for files matching the criteria and adds them (i.e. paths and file names) to the Parse object without looking at them. It is recommended to add different types of files with different keys, e.g. ‘mscx’ for score, ‘harmonies’ for chord labels, and ‘form’ for form labels.

Parameters
  • dir (str) – Directory to scan for files.

  • key (str, optional) –

    Pass a string to identify the loaded files.
    By default, the relative sub-directories of dir are used as keys. For example, for files within dir itself, the key would be '.', for files in the subfolder scores it would be 'scores', etc.

  • index (element or Collection of {‘key’, ‘fname’, ‘i’, Collection}) –

    Change this parameter if you want to create particular indices for multi-piece DataFrames.
    The resulting index must be unique (for identification) and have as many elements as added files.
    Every single element or Collection of elements ∈ {‘key’, ‘fname’, ‘i’, Collection} stands for an index level.
    In other words, a single level will result in a single index and a collection of levels will result in a MultiIndex.
    If you pass a Collection that does not start with one of {‘key’, ‘fname’, ‘i’}, it is interpreted as an index level itself and needs to have at least as many elements as the number of added files.
    The default None is equivalent to passing (key, i), i.e. a MultiIndex of IDs.
    ’fname’ evokes an index level made from file names.

  • dir – Directory to be scanned for files.

  • file_re (str, optional) – Regular expression for filtering certain file names. The regEx is checked with search(), not match(), allowing for fuzzy search.

  • folder_re (str, optional) – Regular expression for filtering certain folder names. The regEx is checked with search(), not match(), allowing for fuzzy search.

  • recursive (bool, optional) – By default, sub-directories are recursively scanned. Pass False to scan only dir.

attach_labels(keys=None, annotation_key=None, staff=None, voice=None, check_for_clashes=True)[source]

Attach all Annotations objects that are reachable via Score.annotation_key to their respective Score, changing their current XML. Calling store_mscx() will output MuseScore files where the annotations show in the score.

Parameters
  • keys (str or Collection, optional) – Key(s) under which parsed MuseScore files are stored. By default, all keys are selected.

  • annotation_key (str or list or tuple, optional) – Key(s) under which the Annotations objects to be attached are stored in the Score objects. By default, all keys are selected.

  • staff (int, optional) – If you pass a staff ID, the labels will be attached to that staff where 1 is the upper stuff. By default, the staves indicated in the ‘staff’ column of ms3.annotations.Annotations.df will be used.

  • voice ({1, 2, 3, 4}, optional) – If you pass the ID of a notational layer (where 1 is the upper voice, blue in MuseScore), the labels will be attached to that one. By default, the notational layers indicated in the ‘voice’ column of ms3.annotations.Annotations.df will be used.

  • check_for_clashes (bool, optional) – By default, warnings are thrown when there already exists a label at a position (and in a notational layer) where a new one is attached. Pass False to deactivate this warnings.

change_labels_cfg(labels_cfg={}, staff=None, voice=None, label_type=None, positioning=None, decode=None)[source]

Update Parse.labels_cfg and retrieve new ‘labels’ tables accordingly.

Parameters
  • labels_cfg (dict) – Using an entire dictionary or, to change only particular options, choose from:

  • staff – Arguments as they will be passed to get_labels()

  • voice – Arguments as they will be passed to get_labels()

  • label_type – Arguments as they will be passed to get_labels()

  • positioning – Arguments as they will be passed to get_labels()

  • decode – Arguments as they will be passed to get_labels()

collect_lists(keys=None, ids=None, notes=False, rests=False, notes_and_rests=False, measures=False, events=False, labels=False, chords=False, expanded=False, only_new=True)[source]

Extracts DataFrames from the parsed scores in keys and stores them in dictionaries.

Parameters
  • keys (str or Collection, optional) – Key(s) under which parsed MuseScore files are stored. By default, all keys are selected.

  • ids (Collection) – If you pass a collection of IDs, keys is ignored and only_new is set to False.

  • notes (bool, optional) –

  • rests (bool, optional) –

  • notes_and_rests (bool, optional) –

  • measures (bool, optional) –

  • events (bool, optional) –

  • labels (bool, optional) –

  • chords (bool, optional) –

  • expanded (bool, optional) –

  • only_new (bool, optional) – Set to True to also retrieve lists that had already been retrieved.

count_annotation_layers(keys=None, which='attached', per_key=False)[source]

Counts the labels for each annotation layer defined as (staff, voice, label_type). By default, only labels attached to a score are counted.

Parameters
  • keys (str or Collection, optional) – Key(s) for which to count annotation layers. By default, all keys are selected.

  • which ({'attached', 'detached', 'tsv'}, optional) – ‘attached’: Counts layers from annotations attached to a score. ‘detached’: Counts layers from annotations that are in a Score object, but detached from the score. ‘tsv’: Counts layers from Annotation objects that have been loaded from or into annotation tables.

  • per_key (bool, optional) – If set to True, the results are returned as a dict {key: Counter}, otherwise the counts are summed up in one Counter. If which='detached', the keys are keys from Score objects, otherwise they are keys from this Parse object.

Returns

By default, the function returns a Counter of labels for every annotation layer (staff, voice, label_type) If per_key is set to True, a dictionary {key: Counter} is returned, separating the counts.

Return type

dict or collections.Counter

count_extensions(keys=None, per_key=False)[source]

Count file extensions.

Parameters
  • keys (str or Collection, optional) – Key(s) for which to count file extensions. By default, all keys are selected.

  • per_key (bool, optional) – If set to True, the results are returned as a dict {key: Counter}, otherwise the counts are summed up in one Counter.

Returns

By default, the function returns a Counter of file extensions. If per_key is set to True, a dictionary {key: Counter} is returned, separating the counts.

Return type

dict or collections.Counter

count_label_types(keys=None, per_key=False)[source]

Count label types.

Parameters
  • keys (str or Collection, optional) – Key(s) for which to count label types. By default, all keys are selected.

  • per_key (bool, optional) – If set to True, the results are returned as a dict {key: Counter}, otherwise the counts are summed up in one Counter.

Returns

By default, the function returns a Counter of label types. If per_key is set to True, a dictionary {key: Counter} is returned, separating the counts.

Return type

dict or collections.Counter

count_tsv_types(keys=None, per_key=False)[source]

Count inferred TSV types.

Parameters
  • keys (str or Collection, optional) – Key(s) for which to count inferred TSV types. By default, all keys are selected.

  • per_key (bool, optional) – If set to True, the results are returned as a dict {key: Counter}, otherwise the counts are summed up in one Counter.

Returns

By default, the function returns a Counter of inferred TSV types. If per_key is set to True, a dictionary {key: Counter} is returned, separating the counts.

Return type

dict or collections.Counter

detach_labels(keys=None, annotation_key='detached', staff=None, voice=None, label_type=None, delete=True)[source]

Calls Score.detach_labels<ms3.score.Score.detach_labels() on every parsed score with key key.

get_labels(keys=None, staff=None, voice=None, label_type=None, positioning=True, decode=False, column_name=None, concat=True)[source]

This function does not take into account self.labels_cfg

parse(keys=None, read_only=True, level=None, parallel=True, only_new=True, labels_cfg={}, fexts=None, cols={}, infer_types={}, simulate=None, **kwargs)[source]

Shorthand for executing parse_mscx and parse_tsv at a time.

parse_mscx(keys=None, read_only=True, level=None, parallel=True, only_new=True, labels_cfg={}, simulate=False)[source]

Parse uncompressed MuseScore 3 files (MSCX) and store the resulting read-only Score objects. If they need to be writeable, e.g. for removing or adding labels, pass parallel=False which takes longer but prevents having to re-parse at a later point.

Parameters
  • keys (str or Collection, optional) – For which key(s) to parse all MSCX files.

  • read_only (bool, optional) – If parallel=False, you can increase speed and lower memory requirements by passing read_only=True.

  • level ({'W', 'D', 'I', 'E', 'C', 'WARNING', 'DEBUG', 'INFO', 'ERROR', 'CRITICAL'}, optional) – Pass a level name for which (and above which) you want to see log records.

  • parallel (bool, optional) – Defaults to True, meaning that all CPU cores are used simultaneously to speed up the parsing. It implies that the resulting Score objects are in read-only mode and that you might not be able to use the computer during parsing. Set to False to parse one score after the other.

  • only_new (bool, optional) – By default, score which already have been parsed, are not parsed again. Pass False to parse them, too.

Returns

Return type

None

parse_tsv(keys=None, fexts=None, cols={}, infer_types={}, level=None, **kwargs)[source]

Parse TSV files (or other value-separated files such as CSV) to be able to do something with them.

Parameters
  • keys (: str or Collection, optional) – Key(s) for which to parse all non-MSCX files. By default, all keys are selected.

  • fexts (str or Collection, optional) – If you want to parse only files with one or several particular file extension(s), pass the extension(s)

  • annotations (str or Collection, optional) – By default, if a column called 'label' is found, the TSV is treated as an annotation table and turned into an Annotations object. Pass one or several column name(s) to treat them as label columns instead. If you pass None or no label column is found, the TSV is parsed as a “normal” table, i.e. a DataFrame.

  • infer_types (dict, optional) – To recognize one or several custom label type(s), pass {name: regEx}.

  • level ({'W', 'D', 'I', 'E', 'C', 'WARNING', 'DEBUG', 'INFO', 'ERROR', 'CRITICAL'}, optional) – Pass a level name for which (and above which) you want to see log records.

  • **kwargs – Arguments for pandas.DataFrame.to_csv(). Defaults to {'sep': '   ', 'index': False}. In particular, you might want to update the default dictionaries for dtypes and converters used in load_tsv().

Returns

Return type

None

store_mscx(keys=None, root_dir=None, folder='.', suffix='', simulate=False)[source]

Stores the parsed MuseScore files in their current state, e.g. after detaching or attaching annotations.

The expand_dcml module

This is the same code as in the corpora repo as copied on September 24, 2020 and then adapted.

class ms3.expand_dcml.SliceMaker[source]

This class serves for storing slice notation such as :3 as a variable or passing it as function argument.

Examples

SM = SliceMaker()
some_function( slice_this, SM[3:8] )

select_all = SM[:]
df.loc[select_all]
ms3.expand_dcml.expand_labels(df, column='label', regex=None, cols={}, dropna=False, propagate=True, relative_to_global=False, chord_tones=True, absolute=False, all_in_c=False)[source]

Split harmony labels complying with the DCML syntax into columns holding their various features and allows for additional computations and transformations.

Uses: compute_chord_tones(), features2type(), labels2global_tonic(), propagate_keys(), propagate_pedal(), replace_special(), rn2tpc(), split_alternatives(), split_labels(), transform(), transpose()

Parameters
  • df (pandas.DataFrame) – Dataframe where one column contains DCML chord labels.

  • column (str) – Name of the column that holds the harmony labels.

  • regex (re.Pattern) – Compiled regular expression used to split the labels. It needs to have named groups. The group names are used as column names unless replaced by cols.

  • cols (dict, optional) – Dictionary to map the regex’s group names to deviating column names of your choice.

  • dropna (bool, optional) – Pass True if you want to drop rows where column is NaN/<NA>

  • propagate (bool, optional) – By default, information about global and local keys and about pedal points is spread throughout the DataFrame. Pass False if you only want to split the labels into their features. This ignores all following parameters because their expansions depend on information about keys.

  • relative_to_global (bool, optional) – Pass True if you want all labels expressed with respect to the global key. This levels and eliminates the features localkey and relativeroot.

  • chord_tones (bool, optional) – Pass True if you want to add four columns that contain information about each label’s chord, added, root, and bass tones. The pitches are expressed as intervals relative to the respective chord’s local key or, if relative_to_global=True, to the globalkey. The intervals are represented as integers that represent stacks of fifths over the tonic, such that 0 = tonic, 1 = dominant, -1 = subdominant, 2 = supertonic etc.

  • absolute (bool, optional) – Pass True if you want to transpose the relative chord_tones to the global key, which makes them absolute so they can be expressed as actual note names. This implies prior conversion of the chord_tones (but not of the labels) to the global tonic.

  • all_in_c (bool, optional) – Pass True to transpose chord_tones to C major/minor. This performs the same transposition of chord tones as relative_to_global but without transposing the labels, too. This option clashes with absolute=True.

Returns

Original DataFrame plus additional columns with split features.

Return type

pandas.DataFrame

ms3.expand_dcml.transpose(e, n)[source]

Add n to all elements e recursively.

ms3.expand_dcml.split_alternatives(df, column='label', inplace=False)[source]

Splits labels that come with an alternative separated by ‘-‘ and adds a new column. Only one alternative is taken into account. df is mutated inplace.

Parameters
  • df (pandas.DataFrame) – Dataframe where one column contains DCML chord labels.

  • column (str, optional) – Name of the column that holds the harmony labels.

  • inplace (bool, optional) – Pass True if you want to mutate df.

Example

>>> import pandas as pd
>>> labels = pd.read_csv('labels.csv')
>>> split_alternatives(labels, inplace=True)
ms3.expand_dcml.split_labels(df, column, regex, cols={}, dropna=False, inplace=False, **kwargs)[source]

Split harmony labels complying with the DCML syntax into columns holding their various features.

Parameters
  • df (pandas.DataFrame) – Dataframe where one column contains DCML chord labels.

  • column (str) – Name of the column that holds the harmony labels.

  • regex (re.Pattern) – Compiled regular expression used to split the labels. It needs to have named groups. The group names are used as column names unless replaced by cols.

  • cols (dict) – Dictionary to map the regex’s group names to deviating column names.

  • dropna (bool, optional) – Pass True if you want to drop rows where column is NaN/<NA>

  • inplace (bool, optional) – Pass True if you want to mutate df.

ms3.expand_dcml.features2type(numeral, form=None, figbass=None)[source]

Turns a combination of the three chord features into a chord type.

Returns

  • ‘M’ (Major triad)

  • ’m’ (Minor triad)

  • ’o’ (Diminished triad)

  • ’+’ (Augmented triad)

  • ’mm7’ (Minor seventh chord)

  • ’Mm7’ (Dominant seventh chord)

  • ’MM7’ (Major seventh chord)

  • ’mM7’ (Minor major seventh chord)

  • ’o7’ (Diminished seventh chord)

  • ’%7’ (Half-diminished seventh chord)

  • ’+7’ (Augmented (minor) seventh chord)

  • ’+M7’ (Augmented major seventh chord)

ms3.expand_dcml.replace_special(df, regex, merge=False, inplace=False, cols={}, special_map={})[source]
Move special symbols in the numeral column to a separate column and replace them by the explicit chords they stand for.
In particular, this function replaces the symbols It, Ger, and Fr.

Uses: merge_changes()

Parameters
  • df (pandas.DataFrame) – Dataframe containing DCML chord labels that have been split by split_labels().

  • regex (re.Pattern) – Compiled regular expression used to split the labels replacing the special symbols.It needs to have named groups. The group names are used as column names unless replaced by cols.

  • merge (bool, optional) – False: By default, existing values, except figbass, are overwritten. True: Merge existing with new values (for changes and relativeroot).

  • cols (dict, optional) –

    The special symbols appear in the column numeral and are moved to the column special. In case the column names for ['numeral','form', 'figbass', 'changes', 'relativeroot', 'special'] deviate, pass a dict, such as

    {'numeral':         'numeral_col_name',
     'form':            'form_col_name
     'figbass':         'figbass_col_name',
     'changes':         'changes_col_name',
     'relativeroot':    'relativeroot_col_name',
     'special':         'special_col_name'}
    

  • special_map (dict, optional) – In case you want to add or alter special symbols to be replaced, pass a replacement map, e.g. {‘N’: ‘bII6’}. The column ‘figbass’ is only altered if it’s None to allow for inversions of special chords.

  • inplace (bool, optional) – Pass True if you want to mutate df.

ms3.expand_dcml.merge_changes(left, right, *args)[source]

Merge two changes into one, e.g. b3 and +#7 to +#7b3.

Uses: changes2list()

ms3.expand_dcml.changes2list(changes, sort=True)[source]

Splits a string of changes into a list of 4-tuples.

Example

>>> changes2list('+#7b5')
[('+#7', '+', '#', '7'),
 ('b5',  '',  'b', '5')]
ms3.expand_dcml.propagate_keys(df, globalkey='globalkey', localkey='localkey', add_bool=True)[source]
Propagate information about global keys and local keys throughout the dataframe.
Pass split harmonies for one piece at a time. For concatenated pieces, use apply().

Uses: series_is_minor()

Parameters
  • df (pandas.DataFrame) – Dataframe containing DCML chord labels that have been split by split_labels().

  • globalkey (str, optional) – In case you renamed the columns, pass column names.

  • localkey (str, optional) – In case you renamed the columns, pass column names.

  • add_bool (bool, optional) – Pass True if you want to add two boolean columns which are true if the respective key is a minor key.

ms3.expand_dcml.series_is_minor(S, is_name=True)[source]

Returns boolean Series where every value in S representing a minor key/chord is True.

ms3.expand_dcml.propagate_pedal(df, relative=True, drop_pedalend=True, cols={})[source]

Propagate the pedal note for all chords within square brackets. By default, the note is expressed in relation to each label’s localkey.

Uses: rel2abs_key(), abs2rel_key()

Parameters
  • df (pandas.DataFrame) – Dataframe containing DCML chord labels that have been split by split_labels() and where the keys have been propagated using propagate_keys().

  • relative (bool, optional) – Pass False if you want the pedal note to stay the same even if the localkey changes.

  • drop_pedalend (bool, optional) – Pass False if you don’t want the column with the ending brackets to be dropped.

  • cols (dict, optional) –

    In case the column names for ['pedal','pedalend', 'globalkey', 'localkey'] deviate, pass a dict, such as

    {'pedal':       'pedal_col_name',
     'pedalend':    'pedalend_col_name',
     'globalkey':   'globalkey_col_name',
     'localkey':    'localkey_col_name'}
    

ms3.expand_dcml.abs2rel_key(absolute, localkey, global_minor=False)[source]

Expresses a Roman numeral as scale degree relative to a given localkey. The result changes depending on whether Roman numeral and localkey are interpreted within a global major or minor key.

Uses: split_sd()

Parameters
  • absolute (str) – Relative key expressed as Roman scale degree of the local key.

  • localkey (str) – The local key in terms of which absolute will be expressed.

  • global_minor (bool, optional) – Has to be set to True if absolute and localkey are scale degrees of a global minor key.

Examples

In a minor context, the key of II would appear within the key of vii as #III.

>>> abs2rel_key('iv', 'VI', global_minor=False)
'bvi'       # F minor expressed with respect to A major
>>> abs2rel_key('iv', 'vi', global_minor=False)
'vi'        # F minor expressed with respect to A minor
>>> abs2rel_key('iv', 'VI', global_minor=True)
'vi'        # F minor expressed with respect to Ab major
>>> abs2rel_key('iv', 'vi', global_minor=True)
'#vi'       # F minor expressed with respect to Ab minor
>>> abs2rel_key('VI', 'IV', global_minor=False)
'III'       # A major expressed with respect to F major
>>> abs2rel_key('VI', 'iv', global_minor=False)
'#III'       # A major expressed with respect to F minor
>>> abs2rel_key('VI', 'IV', global_minor=True)
'bIII'       # Ab major expressed with respect to F major
>>> abs2rel_key('VI', 'iv', global_minor=False)
'III'       # Ab major expressed with respect to F minor
ms3.expand_dcml.compute_chord_tones(df, bass_only=False, expand=False, cols={})[source]

Compute the chord tones for DCML harmony labels. They are returned as lists of tonal pitch classes in close position, starting with the bass note. The tonal pitch classes represent intervals relative to the local tonic:

-2: Second below tonic -1: fifth below tonic 0: tonic 1: fifth above tonic 2: second above tonic, etc.

The labels need to have undergone split_labels() and propagate_keys(). Pedal points are not taken into account.

Uses: features2tpcs()

Parameters
  • df (pandas.DataFrame) – Dataframe containing DCML chord labels that have been split by split_labels() and where the keys have been propagated using propagate_keys(add_bool=True).

  • bass_only (bool, optional) – Pass True if you need only the bass note.

  • expand (bool, optional) – Pass True if you need chord tones and added tones in separate columns.

  • cols (dict, optional) –

    In case the column names for ['mc', 'numeral', 'form', 'figbass', 'changes', 'relativeroot', 'localkey', 'globalkey'] deviate, pass a dict, such as

    {'mc':              'mc',
     'numeral':         'numeral_col_name',
     'form':            'form_col_name',
     'figbass':         'figbass_col_name',
     'changes':         'changes_col_name',
     'relativeroot':    'relativeroot_col_name',
     'localkey':        'localkey_col_name',
     'globalkey':       'globalkey_col_name'}
    

    You may also deactivate columns by setting them to None, e.g. {‘changes’: None}

Returns

For every row of df one tuple with chord tones, expressed as tonal pitch classes. If expand is True, the function returns a DataFrame with four columns: Two with tuples for chord tones and added tones, one with the chord root, and one with the bass note.

Return type

pandas.Series or pandas.DataFrame

ms3.expand_dcml.features2tpcs(numeral, form=None, figbass=None, changes=None, relativeroot=None, key='C', minor=None, merge_tones=True, bass_only=False, mc=None, logger=None)[source]

Given the features of a chord label, this function returns the chord tones in the order of the inversion, starting from the bass note. The tones are expressed as tonal pitch classes, where -1=F, 0=C, 1=G etc.

Uses: changes2list(), name2tpc(), resolve_relative_keys(), rn2tpc(), sort_tpcs(), str_is_minor()

Parameters
  • numeral (str) – Roman numeral of the chord’s root

  • form ({None, 'M', 'o', '+' '%'}, optional) – Indicates the chord type if not a major or minor triad (for which `form`is None). ‘%’ and ‘M’ can only occur as tetrads, not as triads.

  • figbass ({None, '6', '64', '7', '65', '43', '2'}, optional) – Indicates chord’s inversion. Pass None for triad root position.

  • changes (str, optional) – Added steps such as ‘+6’ or suspensions such as ‘4’ or any combination such as (9+64). Numbers need to be in descending order.

  • relativeroot (str, optional) – Pass a Roman scale degree if numeral is to be applied to a different scale degree of the local key, as in ‘V65/V’

  • key (str or int, optional) – The local key expressed as the root’s note name or a tonal pitch class. If it is a name and minor is None, uppercase means major and lowercase minor. If it is a tonal pitch class, minor needs to be specified.

  • minor (bool, optional) – Pass True for minor and False for major. Can be omitted if key is a note name. This affects calculation of chords related to III, VI and VII.

  • merge_tones (bool, optional) – Pass False if you want the function to return two tuples, one with (potentially suspended) chord tones and one with added notes.

  • bass_only (bool, optional) – Return only the bass note instead of all chord tones.

  • mc (int or str) – Pass measure count to display it in warnings.

ms3.expand_dcml.str_is_minor(tone, is_name=True)[source]

Returns True if tone represents a minor key or chord.

ms3.expand_dcml.rn2tpc(rn, global_minor=False)[source]

Turn a Roman numeral into a TPC interval (e.g. for transposition purposes).

Uses: split_sd()

ms3.expand_dcml.split_sd(sd, count=False)[source]

Splits a scale degree such as ‘bbVI’ or ‘b6’ into accidentals and numeral.

Parameters
  • sd (str) – Scale degree.

  • count (bool, optional) – Pass True to get the accidentals as integer rather than as string.

ms3.expand_dcml.labels2global_tonic(df, cols={}, inplace=False)[source]

Transposes all numerals to their position in the global major or minor scale. This eliminates localkeys and relativeroots. The resulting chords are defined by [numeral, figbass, changes, globalkey_is_minor] (and pedal).

Uses: transform(), rel2abs_key^, :py:func:`resolve_relative_keys() -> str_is_minor() transpose_changes(), series_is_minor(),

Parameters
  • df (pandas.DataFrame) – Dataframe containing DCML chord labels that have been split by split_labels() and where the keys have been propagated using propagate_keys(add_bool=True).

  • cols (dict, optional) –

    In case the column names for ['numeral', 'form', 'figbass', 'changes', 'relativeroot', 'localkey', 'globalkey'] deviate, pass a dict, such as

    {'chord':           'chord_col_name'
     'pedal':           'pedal_col_name',
     'numeral':         'numeral_col_name',
     'form':            'form_col_name',
     'figbass':         'figbass_col_name',
     'changes':         'changes_col_name',
     'relativeroot':    'relativeroot_col_name',
     'localkey':        'localkey_col_name',
     'globalkey':       'globalkey_col_name'}}
    

  • inplace (bool, optional) – Pass True if you want to mutate the input.

Returns

If inplace=False, the relevant features of the transposed chords are returned. Otherwise, the original DataFrame is mutated.

Return type

pandas.DataFrame

ms3.expand_dcml.rel2abs_key(rel, localkey, global_minor=False)[source]

Expresses a Roman numeral that is expressed relative to a localkey as scale degree of the global key. For local keys {III, iii, VI, vi, VII, vii} the result changes depending on whether the global key is major or minor.

Uses: split_sd()

Parameters
  • rel (str) – Relative key or chord expressed as Roman scale degree of the local key.

  • localkey (str) – The local key to which rel is relative.

  • global_minor (bool, optional) – Has to be set to True if localkey is a scale degree of a global minor key.

Examples

If the label viio6/VI appears in the context of the local key VI or vi, viio6 the absolute key to which viio6 applies depends on the global key. The comments express the examples in relation to global C major or C minor.

>>> rel2abs_key('vi', 'VI', global_minor=False)
'#iv'       # vi of A major = F# minor
>>> rel2abs_key('vi', 'vi', global_minor=False)
'iv'        # vi of A minor = F minor
>>> rel2abs_key('vi', 'VI', global_minor=True)
'iv'        # vi of Ab major = F minor
>>> rel2abs_key('vi', 'vi', global_minor=True)
'biv'       # vi of Ab minor = Fb minor

The same examples hold if you’re expressing in terms of the global key the root of a VI-chord within the local keys VI or vi.

ms3.expand_dcml.resolve_relative_keys(relativeroot, minor=False)[source]

Resolve nested relative keys, e.g. ‘V/V/V’ => ‘VI’.

Uses: rel2abs_key(), str_is_minor()

relativerootstr

One or several relative keys, e.g. iv/v/VI (fourth scale degree of the fifth scale degree of the sixth scale degree)

minorbool, optional

Pass True if the last of the relative keys is to be interpreted within a minor context.

ms3.expand_dcml.transpose_changes(changes, old_num, new_num, old_minor=False, new_minor=False)[source]

Since the interval sizes expressed by the changes of the DCML harmony syntax depend on the numeral’s position in the scale, these may change if the numeral is transposed. This function expresses the same changes for the new position. Chord tone alterations (of 3 and 5) stay untouched.

Uses: changes2tpc()

Parameters
  • changes (str) – A string of changes following the DCML harmony standard.

  • old_num (str:) – Old numeral, new numeral.

  • new_num (str:) – Old numeral, new numeral.

  • old_minor (bool, optional) – For each numeral, pass True if it occurs in a minor context.

  • new_minor (bool, optional) – For each numeral, pass True if it occurs in a minor context.

ms3.expand_dcml.transform_columns(df, func, columns=None, param2col=None, inplace=False, **kwargs)[source]

Wrapper function to use transform() on df[columns], leaving the other columns untouched.

Parameters
  • df (pandas.DataFrame) – DataFrame where columns (or column combinations) work as function arguments.

  • func (callable) – Function you want to apply to all elements in columns.

  • columns (list) – Columns to which you want to apply func.

  • param2col (dict or list, optional) – Mapping from parameter names of func to column names. If you pass a list of column names, the columns’ values are passed as positional arguments. Pass None if you want to use all columns as positional arguments.

  • inplace (bool, optional) – Pass True if you want to mutate df rather than getting an altered copy.

  • **kwargs (keyword arguments for transform()) –

ms3.expand_dcml.transform_note_columns(df, to, note_cols=['chord_tones', 'added_tones', 'bass_note', 'root'], minor_col='localkey_is_minor', inplace=False, **kwargs)[source]

Turns columns with line-of-fifth tonal pitch classes into another representation.

Uses: transform_columns()

Parameters
  • df (pandas.DataFrame) – DataFrame where columns (or column combinations) work as function arguments.

  • to ({'name', 'iv', 'pc', 'sd', 'rn'}) –

    The tone representation that you want to get from the note_cols.

    • ’name’: Note names. Should only be used if the stacked fifths actually represent

      absolute tonal pitch classes rather than intervals over the local tonic. In other words, make sure to use ‘name’ only if 0 means C rather than I.

    • ’iv’: Intervals such that 0 = ‘P1’, 1 = ‘P5’, 4 = ‘M3’, -3 = ‘m3’, 6 = ‘A4’,

      -6 = ‘D5’ etc.

    • ’pc’: (Relative) chromatic pitch class, or distance from tonic in semitones.

    • ’sd’: Scale degrees such that 0 = ‘1’, -1 = ‘4’, -2 = ‘b7’ in major, ‘7’ in minor etc.

      This representation requires a boolean column minor_col which is True in those rows where the stacks of fifths occur in a local minor context and False for the others. Alternatively, if all pitches are in the same mode or you simply want to express them as degrees of particular mode, you can pass the boolean keyword argument minor.

    • ’rn’: Roman numerals such that 0 = ‘I’, -2 = ‘bVII’ in major, ‘VII’ in minor etc.

      Requires boolean ‘minor’ values, see ‘sd’.

  • note_cols (list, optional) – List of columns that hold integers or collections of integers that represent stacks of fifth (0 = tonal center, 1 = fifth above, -1 = fourth above, etc).

  • minor_col (str, optional) – If to is ‘sd’ or ‘rn’, specify a boolean column where the value is True in those rows where the stacks of fifths occur in a local minor context and False for the others.

ms3.expand_dcml.changes2tpc(changes, numeral, minor=False, root_alterations=False)[source]

Given a numeral and changes, computes the intervals that the changes represent. Changes do not express absolute intervals but instead depend on the numeral and the mode.

Uses: split_sd(), changes2list()

Parameters
  • changes (str) – A string of changes following the DCML harmony standard.

  • numeral (str) – Roman numeral. If it is preceded by accidentals, it depends on the parameter root_alterations whether these are taken into account.

  • minor (bool, optional) – Set to true if the numeral occurs in a minor context.

  • root_alterations (bool, optional) – Set to True if accidentals of the root should change the result.

ms3.expand_dcml.chord2tpcs(chord, regex, **kwargs)[source]

Split a chord label into its features and apply features2tpcs().

Uses: features2tpcs()

Parameters
  • chord (str) – Chord label that can be split into the features [‘numeral’, ‘form’, ‘figbass’, ‘changes’, ‘relativeroot’].

  • regex (re.Pattern) – Compiled regex with named groups for the five features.

  • **kwargs – arguments for features2tpcs (pass MC to show it in warnings!)

Developing a new parser

Every new parser needs to fulfil the following interface requirements.

Methods

def add_label(self, label, mc, mc_onset, staff=1, voice=1, **kwargs):
    """ Adds a single label to the current XML in form of a new
    <Harmony> (and maybe also <location>) tag.
    """

def delete_label(self, mc, staff, voice, mc_onset):
    """ Delete a label from a particular position (if there is one).

    Parameters
    ----------
    mc : :obj:`int`
        Measure count.
    staff, voice
        Notational layer in which to delete the label.
    mc_onset : :obj:`fractions.Fraction`
        mc_onset

    Returns
    -------
    :obj:`bool`
        Whether a label was deleted or not.
    """

def get_chords(self, staff=None, voice=None, mode='auto', lyrics=False, staff_text=False, dynamics=False, articulation=False, spanners=False, **kwargs):
    """ Retrieve a customized chord list, e.g. one including less of the processed features or additional,
    unprocessed ones compared to the standard chord list.

    Parameters
    ----------
    staff : :obj:`int`
        Get information from a particular staff only (1 = upper staff)
    voice : :obj:`int`
        Get information from a particular voice only (1 = only the first layer of every staff)
    mode : {'auto', 'all', 'strict'}, optional
        Defaults to 'auto', meaning that those aspects are automatically included that occur in the score; the resulting
            DataFrame has no empty columns except for those parameters that are set to True.
        'all': Columns for all aspects are created, even if they don't occur in the score (e.g. lyrics).
        'strict': Create columns for exactly those parameters that are set to True, regardless which aspects occur in the score.
    lyrics : :obj:`bool`, optional
        Include lyrics.
    staff_text : :obj:`bool`, optional
        Include staff text such as tempo markings.
    dynamics : :obj:`bool`, optional
        Include dynamic markings such as f or p.
    articulation : :obj:`bool`, optional
        Include articulation such as arpeggios.
    spanners : :obj:`bool`, optional
        Include spanners such as slurs, 8va lines, pedal lines etc.
    **kwargs : :obj:`bool`, optional
        Set a particular keyword to True in order to include all columns from the _events DataFrame
        whose names include that keyword. Column names include the tag names from the MSCX source code.

    Returns
    -------
    :obj:`pandas.DataFrame`
        DataFrame representing all <Chord> tags in the score with the selected features.
    """

def infer_mc(self, mn, mn_onset=0, volta=None):
    """ Shortcut for ``MSCX.parsed.infer_mc()``.
    Tries to convert a ``(mn, mn_onset)`` into a ``(mc, mc_onset)`` tuple on the basis of this MuseScore file.
    In other words, a human readable score position such as "measure number 32b (i.e., a second ending), beat
    3" needs to be converted to ``(32, 1/2, 2)`` if "beat" has length 1/4, or--if the meter is, say 9/8 and "beat"
    has a length of 3/8-- to ``(32, 6/8, 2)``. The resulting ``(mc, mc_onset)`` tuples are required for attaching
    a label to a score. This is only necessary for labels that were not originally extracted by ms3.

    Parameters
    ----------
    mn : :obj:`int` or :obj:`str`
        Measure number as in a reference print edition.
    mn_onset : :obj:`fractions.Fraction`, optional
        Distance of the requested position from beat 1 of the complete measure (MN), expressed as
        fraction of a whole note. Defaults to 0, i.e. the position of beat 1.
    volta : :obj:`int`, optional
        In the case of first and second endings, which bear the same measure number, a MN might have to be
        disambiguated by passing 1 for first ending, 2 for second, and so on. Alternatively, the MN
        can be disambiguated traditionally by passing it as string with a letter attached. In other words,
        ``infer_mc(mn=32, volta=1)`` is equivalent to ``infer_mc(mn='32a')``.

    Returns
    -------
    :obj:`int`
        Measure count (MC), denoting particular <Measure> tags in the score.
    :obj:`fractions.Fraction`

    """

def parse_measures()