Developers’ Reference — ms3 0.4.9 documentation

# Developers’ Reference

The library installs a couple of commands to your system. The documentation for these commands can be found below or by executing `ms3 -h`.

When using ms3 as a module, 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', ms=None)

  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.

  `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 momentarily matches nothing because ms3 tries interpreting Roman Numerals als DCML harmony annotations.

  `native_formats` = ('mscx', 'mscz')

    `tuple` Formats that MS3 reads without having to convert.

  `convertible_formats` = ('cap', 'capx', 'midi', 'mid', 'musicxml', 'mxl', 'xml')

    `tuple` Formats that have to be converted before parsing.

  `parseable_formats` = ('mscx', 'mscz', 'cap', 'capx', 'midi', 'mid', 'musicxml', 'mxl', 'xml')

    `tuple` Formats that ms3 can parse.

  `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()`.

  `ms`

    `str` Path or command of the local MuseScore 3 installation if specified by the user.

  `_mscx`

    `MSCX` The object representing the parsed MuseScore file.

  `_detached_annotations`

    `dict` `{(key, i): Annotations object}` dictionary for accessing all detached `Annotations` objects.

  `_types_to_infer`

    `list` Current order in which types are being recognized.

  `_label_types`

    `dict` Mapping label types to their descriptions. 0: “Simple string (does not begin with a note name, otherwise MS3 will turn it into type 3; prevent through leading dot)”, 1: “MuseScore’s Roman Numeral Annotation format”, 2: “MuseScore’s Nashville Number format”, 3: “Absolute chord encoded by MuseScore”, ‘dcml’: “Latest version of the DCML harmonic annotation standard.”,

  `_label_regex`

    `dict` Mapping label types to their corresponding regex. Managed via the property `infer_label_types()`. 1: self.RN_REGEX, 2: self.NASHVILLE_REGEX, 3: self.ABS_REGEX, ‘dcml’: utils.DCML_REGEX,

  `labels_cfg`

    `dict` Configuration dictionary to determine the output format of the `Annotations` objects contained in the current object, especially when calling `Score.mscx.labels`. The default options correspond to the default parameters of `Annotations.get_labels()`.

  `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, label_type=None, check_for_clashes=True, remove_detached=True)

    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.

      - label_type (`int`, optional) – By default, the labels are written into the staff’s layer for absolute (‘guitar’) chords, meaning that when opened next time, MuseScore will split and encode those beginning with a note name (internal label_type 3). In order to influence how MuseScore treats the labels pass one of these values: 1: Roman Numeral Analysis 2: Nashville Numbers

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

      - remove_detached (`bool`, optional) – By default, the detached `Annotations` object is removed after successfully attaching it. Pass False to have it remain in detached state.

    Returns

      - `int` – Number of newly attached labels.

      - `int` – Number of labels that were to be attached.

  `change_labels_cfg`(labels_cfg={}, staff=None, voice=None, label_type=None, positioning=None, decode=None, column_name=None, color_format=None)

    Update `Score.labels_cfg` and `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()`

  `check_labels`(keys='annotations', regex=None, label_type='dcml', **kwargs)

    Tries to match the labels `keys` against the given `regex` or the one of the registered `label_type`. Returns wrong labels.

    Parameters

      - keys (`str` or `Collection`, optional) – The key(s) of the Annotation objects you want to check. Defaults to ‘annotations’, the attached labels.

      - regex (`str`, optional) – Pass a regular expression against which to check the labels if you don’t want to use the one of an existing `label_type` or in order to register a new one on the fly by passing the new name as `label_type`.

      - label_type (`str`, optional) – To use the regular expression of a registered type, pass its name, defaults to ‘dcml’. Pass a new name and a `regex` to register a new label type on the fly.

      - kwargs – Parameters passed to `check_labels()`.

    Returns

      Labels not matching the regex.

    Return type

      `pandas.DataFrame`

  `compare_labels`(detached_key, new_color='ms3_darkgreen', old_color='ms3_darkred', detached_is_newer=False, add_to_rna=True)

    Compare detached labels `key` to the ones attached to the Score. By default, the attached labels are considered as the reviewed version and changes are colored in green; Changes with respect to the detached labels are attached to the Score in red.

    Parameters

      - detached_key (`str`) – Key of the detached labels you want to compare to the ones in the score.

      - new_color (`str` or `tuple`, optional) – The colors by which new and old labels are differentiated. Identical labels remain unchanged.

      - old_color (`str` or `tuple`, optional) – The colors by which new and old labels are differentiated. Identical labels remain unchanged.

      - detached_is_newer (`bool`, optional) – Pass True if the detached labels are to be added with `new_color` whereas the attached changed labels will turn `old_color`, as opposed to the default.

      - add_to_rna (`bool`, optional) – By default, new labels are attached to the Roman Numeral layer. Pass false to attach them to the chord layer instead.

  `detach_labels`(key, staff=None, voice=None, label_type=None, delete=True)

    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`()
    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)

    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)

    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='annotations', tsv_path=None, **kwargs)

    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)

    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.

  `_handle_path`(path, key=None, logger_name=None)

    Puts the path into `paths, files, fnames, fexts` dicts with the given key.

    Parameters

      - path (`str`) – Full file path.

      - key (`str`, optional) – The key chosen by the user. By default, the key is automatically assigend to be the file’s extension.

      - logger_name (`str`, optional) – By default, a logger name is generated for the file from its file name with extension, stripped of all dots. To designate a different logger to go with this file, pass its name.

  `_parse_mscx`(musescore_file, read_only=False, parser=None, labels_cfg={})

    This method is called by `__init__()` to parse the score. It checks the file extension and in the case of a compressed MuseScore file (.mscz), a temporary uncompressed file is generated which is removed after the parsing process. Essentially, parsing means to initiate a `MSCX` object and to make it available as `Score.mscx` and, if the score includes annotations, to initiate an `Annotations` object that can be accessed as `Score.annotations`. The method doesn’t systematically clean up data from a hypothetical previous parse.

    Parameters

      - musescore_file (`str`) – Path to the MuseScore file to be parsed.

      - read_only (`bool`, optional) – 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', optional) – The only XML parser currently implemented is BeautifulSoup 4.

      - labels_cfg (`dict`, optional) – Store a configuration dictionary to determine the output format of the `Annotations` object representing the currently attached annotations. See `MSCX.labels_cfg`.

### The MSCX class

This class defines the user interface for accessing score information via `Score.mscx`. It consists mainly of shortcuts for interacting with the parser in use, currently Beautifulsoup exclusively.

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

  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.

  `changed`

    `bool` Switches to True as soon as the original XML structure is changed. Does not automatically switch back to False.

  `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.

  `parent_score`

    `Score` The Score object to which this MSCX object is attached.

  `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 options correspond to the parameters of `Annotations.get_labels()`.

  `mscx_src`

    `str` Full path of the parsed MuseScore file.

  property `cadences`

    `pandas.DataFrame` DataFrame representing all cadence annotations in the score.

  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 `style`

    `Style` Can be used like a dictionary to change the information within the score’s <Style> tag.

  property `version`

    `str` MuseScore version that the file was created with.

  property `volta_structure`

    `dict` {first_mc -> {volta_number -> [mc1, mc2…]} } dictionary.

  `add_labels`(annotations_object)

    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

      annotations_object (`Annotations`) – Object of labels to be added.

    Returns

      Number of actually added labels.

    Return type

      `int`

  `change_label_color`(mc, mc_onset, staff, voice, label, color_name=None, color_html=None, color_r=None, color_g=None, color_b=None, color_a=None)

    Shortcut for :py:meth:`MSCX.parsed.change_label_color`

    Parameters

      - mc (`int`) – Measure count of the label

      - mc_onset (`fractions.Fraction`) – Onset position to which the label is attached.

      - staff (`int`) – Staff to which the label is attached.

      - voice (`int`) – Notational layer to which the label is attached.

      - label (`str`) – (Decoded) label.

      - color_name (`str`, optional) – Two ways of specifying the color.

      - color_html (`str`, optional) – Two ways of specifying the color.

      - color_r (`int` or `str`, optional) – To specify a RGB color instead, pass at least, the first three. `color_a` (alpha = opacity) defaults to 255.

      - color_g (`int` or `str`, optional) – To specify a RGB color instead, pass at least, the first three. `color_a` (alpha = opacity) defaults to 255.

      - color_b (`int` or `str`, optional) – To specify a RGB color instead, pass at least, the first three. `color_a` (alpha = opacity) defaults to 255.

      - color_a (`int` or `str`, optional) – To specify a RGB color instead, pass at least, the first three. `color_a` (alpha = opacity) defaults to 255.

  `change_labels_cfg`(labels_cfg={}, staff=None, voice=None, label_type=None, positioning=None, decode=None, column_name=None, color_format=None)

    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)

    Delete a set of labels from the current XML.

    Parameters

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

  `replace_labels`(annotations_object)
    Parameters

      annotations_object (`Annotations`) – Object of labels to be added.

  `delete_empty_labels`()

    Remove all empty labels from the attached annotations.

  `get_chords`(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 (`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`()

    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 (MuseScore’s Roman Numeral display), 2 (Nashville) 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)

    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

      - `int` – Measure count (MC), denoting particular <Measure> tags in the score.

      - `fractions.Fraction`

  `store_mscx`(filepath)

    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)

    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)

  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, color_format=None)

    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.

      - color_format ({'html', 'rgb', 'rgba', 'name', None}) – If label colors are encoded, determine how they are displayed.

  `expand_dcml`(drop_others=True, warn_about_others=True, drop_empty_cols=False, **kwargs)

    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.

      - drop_empty_cols (`bool`, optional) – Return without unused columns

      - 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`(directory=None, paths=None, key=None, index=['rel_paths', 'fnames'], file_re=None, folder_re='.*', exclude_re='^(\\.|_)', recursive=True, simulate=False, labels_cfg={}, logger_cfg={}, ms=None)

  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.

  `logger_names`

    `dict` `{(key, i): :obj:`str`}` dictionary of logger names.

  `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_mscx`

    `pandas.DataFrame` Returns an overview of the parsed scores.

  property `parsed_tsv`

    `pandas.DataFrame` Returns an overview of the parsed TSV files.

  `add_detached_annotations`(score_key=None, tsv_key=None, new_key=None, match_dict=None)

    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

      - score_key (`str`, optional) – A key under which parsed MuseScore files are stored. If one of `score_key` and `tsv_key` is None, no matching is performed and already matched files are used.

      - tsv_key (`str`, optional) – A key under which parsed TSV files are stored of which the type has been inferred as ‘labels’. If one of `score_key` and `tsv_key` is None, no matching is performed and already matched files are used.

      - 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`(directory, key=None, index=['rel_paths', 'fnames'], file_re=None, folder_re='.*', exclude_re='^(\\.|__)', recursive=True)

    This method 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

      - directory (`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’, ‘i’, `Collection`, ‘full_paths’, ‘rel_paths’, ‘scan_paths’, ‘paths’, ‘files’, ‘fnames’, ‘fexts’}) –

        Change this parameter if you want to create particular indices for output 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’, ‘i’, `Collection`, ‘full_paths’, ‘rel_paths’, ‘scan_paths’, ‘paths’, ‘files’, ‘fnames’, ‘fexts’} stands for an index level in the `MultiIndex`.
        If you pass a Collection that does not start with one of the defined keywords, 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 which is always unique.
        The keywords correspond to the dictionaries of Parse object that contain the constituents of the file paths.

      - directory – Directory to be scanned for files.

      - file_re (`str`, optional) – Regular expression for filtering certain file names. By default, all parseable score files and TSV files are detected. 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`.

  `add_files`(paths, key, index=None, exclude_re=None)
    Parameters

      - paths (`Collection`) – The paths of the files you want to add to the object.

      - key (`str`) –

        Pass a string to identify the loaded files.
        If None is passed, paths relative to `last_scanned_dir` are used as keys. If `add_dir()` hasn’t been used before, the longest common prefix of all paths is used.

      - index (element or `Collection` of {‘key’, ‘i’, `Collection`, ‘full_paths’, ‘rel_paths’, ‘scan_paths’, ‘paths’, ‘files’, ‘fnames’, ‘fexts’}) –

        Change this parameter if you want to create particular indices for output 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’, ‘i’, `Collection`, ‘full_paths’, ‘rel_paths’, ‘scan_paths’, ‘paths’, ‘files’, ‘fnames’, ‘fexts’} stands for an index level in the `MultiIndex`.
        If you pass a Collection that does not start with one of the defined keywords, 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 which is always unique.
        The keywords correspond to the dictionaries of Parse object that contain the constituents of the file paths.
    Returns

      The IDs of the added files.

    Return type

      `list`

  `add_rel_dir`(rel_dir, suffix='', score_extensions=None, keys=None, new_key=None, index=None)

    This method can be used for adding particular TSV files belonging to already loaded score files. This is useful, for example, to add annotation tables for comparison.

    Parameters

      - rel_dir (`str`) – Path where the files to be added can be found, relative to each loaded MSCX file. They are expected to have the same file name, maybe with an added `suffix`.

      - suffix (`str`. optional) – If the files to be loaded can be identified by adding a suffix to the filename, pass this suffix, e.g. ‘_labels’.

      - score_extensions (`Collection`, optional) – If you want to match only scores with particular extensions, pass a Collection of these extensions.

      - keys (`str` or `Collection`, optional) – Key(s) under which score files are stored. By default, all keys are selected.

      - new_key (`str`, optional) – Pass a string to identify the loaded files. By default, the keys of the score files are being used.

      - index (element or `Collection` of {‘key’, ‘i’, `Collection`, ‘full_paths’, ‘rel_paths’, ‘scan_paths’, ‘paths’, ‘files’, ‘fnames’, ‘fexts’}) –

        Change this parameter if you want to create particular indices for output 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’, ‘i’, `Collection`, ‘full_paths’, ‘rel_paths’, ‘scan_paths’, ‘paths’, ‘files’, ‘fnames’, ‘fexts’} stands for an index level in the `MultiIndex`.
        If you pass a Collection that does not start with one of the defined keywords, 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 which is always unique.
        The keywords correspond to the dictionaries of Parse object that contain the constituents of the file paths.
  `attach_labels`(keys=None, annotation_key=None, staff=None, voice=None, label_type=None, check_for_clashes=True)

    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 these warnings.

  `change_labels_cfg`(labels_cfg={}, staff=None, voice=None, label_type=None, positioning=None, decode=None, column_name=None, color_format=None)

    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()`

      - column_name – 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, cadences=False, only_new=True)

    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) –

      - cadences (`bool`, optional) –

      - only_new (`bool`, optional) – Set to False to also retrieve lists that had already been retrieved.

  `compare_labels`(detached_key, new_color='ms3_darkgreen', old_color='ms3_darkred', detached_is_newer=False, store_with_suffix=None)

    Compare detached labels `key` to the ones attached to the Score. By default, the attached labels are considered as the reviewed version and changes are colored in green; Changes with respect to the detached labels are attached to the Score in red.

    Parameters

      - detached_key (`str`) – Key under which the detached labels that you want to compare have been added to the scores.

      - new_color (`str` or `tuple`, optional) – The colors by which new and old labels are differentiated. Identical labels remain unchanged.

      - old_color (`str` or `tuple`, optional) – The colors by which new and old labels are differentiated. Identical labels remain unchanged.

      - detached_is_newer (`bool`, optional) – Pass True if the detached labels are to be added with `new_color` whereas the attached changed labels will turn `old_color`, as opposed to the default.

      - store_with_suffix (`str`, optional) – If you pass a suffix, the comparison MSCX files are stored with this suffix next to the originals.

  `count_annotation_layers`(keys=None, which='attached', per_key=False)

    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, ids=None, per_key=False)

    Count file extensions.

    Parameters

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

      - ids (`Collection`) – If you pass a collection of IDs, `keys` is ignored and only the selected extensions are counted.

      - 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)

    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)

    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)

    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)

    This function does not take into account self.labels_cfg

  `get_lists`(keys=None, ids=None, notes=False, rests=False, notes_and_rests=False, measures=False, events=False, labels=False, chords=False, expanded=False, cadences=False, simulate=False, flat=True, unfold=False, quarterbeats=False)

    Retrieve a dictionary with the selected feature matrices.

    Parameters

      - keys –

      - ids –

      - notes –

      - rests –

      - notes_and_rests –

      - measures –

      - events –

      - labels –

      - chords –

      - expanded –

      - cadences –

      - simulate –

      - flat (`bool`, optional) – By default, you get a dictionary {(id, list_type) -> list}. By passing False you get a nested dictionary {list_type -> {index -> list}}

      - unfold (`bool`, optional) – Pass True if lists should reflect repetitions and voltas to create a correct playthrough. Defaults to False, meaning that all measures including second endings are included, unless `quarterbeats` is set to True.

      - quarterbeats (`bool`, optional) – Pass True to add a quarterbeats column with a continuous offset from the piece’s beginning. If `unfold` is False, this option will remove second endings and the `volta` column.

  `get_continuous_offsets`(key, i, unfold)
    Using a corresponding measure list, return a dictionary mapping MCs to their absolute distance from MC 1,

      measured in quarter notes.

    Parameters

      - key – ID

      - i – ID

      - unfold (`bool`) – If True, return `{mc_playthrough -> offset}`, otherwise `{mc -> offset}`, keeping only second endings.

  `ids2idx`(ids=None, pandas_index=False)

    Receives a list of IDs and returns a list of index tuples or a pandas index created from it.

    Parameters

      - ids –

      - pandas_index –

    Returns

    Return type

      `pandas.Index` or `pandas.MultiIndex` or ( list(tuple()), tuple() )

  `idx2id`(full_path=None, rel_path=None, scan_path=None, path=None, file=None, fname=None, fext=None)

    Turn the respective value combinations of an index into an ID.

    Parameters

      - full_paths –

      - rel_paths –

      - scan_paths –

      - paths –

      - files –

      - fnames –

      - fexts –

    Returns

      the (key, i) pair corresponding to the index

    Return type

      `tuple`

  `match_files`(keys=None, ids=None, what=None, only_new=True)

    Match files based on their file names and return the matches for the requested keys or ids.

    Parameters

      - keys (`str` or `Collection`, optional) – Which key(s) to return after matching matching files.

      - what (`list` or ∈ {‘scores’, ‘notes’, ‘rests’, ‘notes_and_rests’, ‘measures’, ‘events’, ‘labels’, ‘chords’, ‘expanded’, ‘cadences’}) – If you pass only one element, the corresponding files will be matched to all other types. If you pass several elements the first type will be matched to the following types.

      - only_new (`bool`, optional) – Try matching only where matches are still missing.

    Returns

      Those files that were matched. This is a subsection of self._matches

    Return type

      `pandas.DataFrame`

  `parse`(keys=None, read_only=True, level=None, parallel=True, only_new=True, labels_cfg={}, fexts=None, cols={}, infer_types={'dcml': re.compile('\n ^(?P<first>\n (\\.?\n ((?P<globalkey>[a-gA-G](b*|\\#*))\\.)?\n, re.VERBOSE)}, simulate=None, **kwargs)

    Shorthand for executing parse_mscx and parse_tsv at a time.

  `parse_mscx`(keys=None, ids=None, read_only=True, level=None, parallel=True, only_new=True, labels_cfg={}, simulate=False)

    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.

      - ids (`Collection`) – To parse only particular files, pass their IDs. `keys` and `fexts` are ignored in this case.

      - 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, ids=None, fexts=None, cols={}, infer_types={'dcml': re.compile('\n ^(?P<first>\n (\\.?\n ((?P<globalkey>[a-gA-G](b*|\\#*))\\.)?\n, re.VERBOSE)}, level=None, **kwargs)

    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.

      - ids (`Collection`) – To parse only particular files, pass there IDs. `keys` and `fexts` are ignored in this case.

      - 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_lists`(keys=None, root_dir=None, notes_folder=None, notes_suffix='', rests_folder=None, rests_suffix='', notes_and_rests_folder=None, notes_and_rests_suffix='', measures_folder=None, measures_suffix='', events_folder=None, events_suffix='', labels_folder=None, labels_suffix='', chords_folder=None, chords_suffix='', expanded_folder=None, expanded_suffix='', cadences_folder=None, cadences_suffix='', metadata_path=None, markdown=True, simulate=None, unfold=False, quarterbeats=False)

    Store score information as TSV files.

    Parameters

      - keys (`str` or `Collection`, optional) – Key(s) under which score files are stored. By default, all keys are selected.

      - root_dir (`str`, optional) – Defaults to None, meaning that the original root directory is used that was added to the Parse object. Otherwise, pass a directory to rebuild the original directory structure. For `_folder` parameters describing absolute paths, `root_dir` is ignored.

      - notes_folder (str, optional) – Specify directory where to store the corresponding TSV files.

      - rests_folder (str, optional) – Specify directory where to store the corresponding TSV files.

      - notes_and_rests_folder (str, optional) – Specify directory where to store the corresponding TSV files.

      - measures_folder (str, optional) – Specify directory where to store the corresponding TSV files.

      - events_folder (str, optional) – Specify directory where to store the corresponding TSV files.

      - labels_folder (str, optional) – Specify directory where to store the corresponding TSV files.

      - chords_folder (str, optional) – Specify directory where to store the corresponding TSV files.

      - expanded_folder (str, optional) – Specify directory where to store the corresponding TSV files.

      - cadences_folder (str, optional) – Specify directory where to store the corresponding TSV files.

      - notes_suffix (str, optional) – Optionally specify suffixes appended to the TSVs’ file names.

      - rests_suffix (str, optional) – Optionally specify suffixes appended to the TSVs’ file names.

      - notes_and_rests_suffix (str, optional) – Optionally specify suffixes appended to the TSVs’ file names.

      - measures_suffix (str, optional) – Optionally specify suffixes appended to the TSVs’ file names.

      - events_suffix (str, optional) – Optionally specify suffixes appended to the TSVs’ file names.

      - labels_suffix (str, optional) – Optionally specify suffixes appended to the TSVs’ file names.

      - chords_suffix (str, optional) – Optionally specify suffixes appended to the TSVs’ file names.

      - expanded_suffix (str, optional) – Optionally specify suffixes appended to the TSVs’ file names.

      - cadences_suffix (str, optional) – Optionally specify suffixes appended to the TSVs’ file names.

      - metadata_path (str, optional) – Where to store an overview file with the MuseScore files’ metadata. If no file name is specified, the file will be named `metadata.tsv`.

      - markdown (bool, optional) – By default, when `metadata_path` is specified, a markdown file called `README.md` containing the columns [file_name, measures, labels, standard, annotators, reviewers] is created. If it exists already, this table will be appended or overwritten after the heading `# Overview`.

      - simulate (bool, optional) – Defaults to `None`. Pass a value to set the object attribute `simulate`.

      - unfold (bool, optional) – By default, repetitions are not unfolded. Pass True to duplicate values so that they correspond to a full playthrough, including correct positioning of first and second endings.

      - quarterbeats (bool, optional) – By default, no `quarterbeats` column is added with distances from the piece’s beginning measured in quarter notes. Pass True to add the columns `quarterbeats` and `durations_quarterbeats`. If a score has first and second endings, the behaviour depends on `unfold`: If False, repetitions are not unfolded and only last endings are included in the continuous count. If repetitions are being unfolded, all endings are taken into account.

  `store_mscx`(keys=None, ids=None, root_dir=None, folder='.', suffix='', overwrite=False, simulate=False)

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

  `update_metadata`()

    Uses all parsed metadata TSVs to update the information in the corresponding parsed MSCX files and returns the IDs of those that have been changed.

## The BeautifulSoup parser

class `ms3.bs4_parser.` `_MSCX_bs4`(mscx_src, read_only=False, logger_cfg={})

  This sister class implements `MSCX`’s methods for a score parsed with beautifulsoup4.

  `mscx_src`

    Path to the uncompressed MuseScore 3 file (MSCX) to be parsed.

    Type

      `str`

  `parse_mscx`()

    Load the XML structure from the score in self.mscx_src and store references to staves and measures.

  `parse_measures`()

    Converts the score into the three DataFrame self._measures, self._events, and self._notes

  `_make_measure_list`(sections=True, secure=True, reset_index=True)

    Regenerate the measure list from the parsed score with advanced options.

  property `chords`

    A list of <chord> tags (all <note> tags come within one) and attached score information such as lyrics, dynamics, articulations, slurs, etc.

  property `cl`

    Getting self._cl but without recomputing.

  property `measures`

    Retrieve a standard measure list from the parsed score.

  property `ml`

    Like property measures but without recomputing.

  property `notes`

    A list of all notes with their features.

  property `nl`

    Like property notes but without recomputing.

  property `notes_and_rests`

    Get a combination of properties notes and rests

  property `nrl`

    Like property notes_and_rests but without recomputing.

  property `rests`

    A list of all rests with their features.

  property `rl`

    Like property rests but without recomputing.

  `make_standard_chordlist`()

    This chord list has chords only as opposed to the one yielded by selr.get_chords()

  `get_chords`(staff=None, voice=None, mode='auto', lyrics=False, dynamics=False, articulation=False, staff_text=False, system_text=False, tempo=False, spanners=False, **kwargs)

    Shortcut for `MSCX.parsed.get_chords()`. Retrieve a customized chord lists, e.g. one including less of the processed features or additional, unprocessed ones.

    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) –

        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 (`bool`, optional) – Include lyrics.

      - 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.

      - staff_text (`bool`, optional) – Include expression text such as ‘dolce’ and free-hand staff text such as ‘div.’.

      - system_text (`bool`, optional) – Include system text such as movement titles.

      - tempo (`bool`, optional) – Include tempo markings.

      - **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`()

    Returns a list of <harmony> tags from the parsed score.

    Returns

    Return type

      `pandas.DataFrame`

  `infer_mc`(mn, mn_onset=0, volta=None)

    mn_onset and needs to be converted to mc_onset

  `delete_label`(mc, staff, voice, mc_onset, empty_only=False)

    Delete a label from a particular position (if there is one).

    Parameters

      - mc (`int`) – Measure count.

      - staff – Notational layer in which to delete the label.

      - voice – Notational layer in which to delete the label.

      - mc_onset (`fractions.Fraction`) – mc_onset

      - empty_only (`bool`, optional) – Set to True if you want to delete only empty harmonies. Since normally all labels at the defined position are deleted, this flag is needed to prevent non-empty <Harmony> tags.

    Returns

      Whether a label was deleted or not.

    Return type

      `bool`

  `add_label`(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.

    Parameters

      - label –

      - mc –

      - mc_onset –

      - staff –

      - voice –

      - kwargs –

  `change_label_color`(mc, mc_onset, staff, voice, label, color_name=None, color_html=None, color_r=None, color_g=None, color_b=None, color_a=None)

    Change the color of an existing label.

    Parameters

      - mc (`int`) – Measure count of the label

      - mc_onset (`fractions.Fraction`) – Onset position to which the label is attached.

      - staff (`int`) – Staff to which the label is attached.

      - voice (`int`) – Notational layer to which the label is attached.

      - label (`str`) – (Decoded) label.

      - color_name (`str`, optional) – Two ways of specifying the color.

      - color_html (`str`, optional) – Two ways of specifying the color.

      - color_r (`int` or `str`, optional) – To specify a RGB color instead, pass at least, the first three. `color_a` (alpha = opacity) defaults to 255.

      - color_g (`int` or `str`, optional) – To specify a RGB color instead, pass at least, the first three. `color_a` (alpha = opacity) defaults to 255.

      - color_b (`int` or `str`, optional) – To specify a RGB color instead, pass at least, the first three. `color_a` (alpha = opacity) defaults to 255.

      - color_a (`int` or `str`, optional) – To specify a RGB color instead, pass at least, the first three. `color_a` (alpha = opacity) defaults to 255.

class `ms3.bs4_parser.` `Metatags`(soup)

  Easy way to read and write any style information in a parsed MSCX score.

class `ms3.bs4_parser.` `Style`(soup)

  Easy way to read and write any style information in a parsed MSCX score.

`ms3.bs4_parser.` `get_duration_event`(elements)

  Receives a list of dicts representing the events for a given mc_onset and returns the index and name of the first event that has a duration, so either a Chord or a Rest.

`ms3.bs4_parser.` `get_part_info`(part_tag)

  Instrument names come in different forms in different places. This function extracts the information from a <Part> tag and returns it as a dictionary.

`ms3.bs4_parser.` `make_spanner_cols`(df, spanner_types=None)
  From a raw chord list as returned by `get_chords(spanners=True)`

    create a DataFrame with Spanner IDs for all chords for all spanner types they are associated with.

  Parameters

    spanner_types (`collection`) – If this parameter is passed, only the enlisted spanner types [‘Slur’, ‘HairPin’, ‘Pedal’, ‘Ottava’] are included.

`ms3.bs4_parser.` `safe_update`(old, new)

  Update dict without replacing values.

`ms3.bs4_parser.` `decode_harmony_tag`(tag)

  Decode a <Harmony> tag into a string.

`ms3.bs4_parser.` `make_oneliner`(node)

  Pass a tag of which the layout does not spread over several lines.

`ms3.bs4_parser.` `format_node`(node, indent)

  Recursively format Beautifulsoup tag as in an MSCX file.

`ms3.bs4_parser.` `bs4_to_mscx`(soup)

  Turn the BeautifulSoup into a string representing an MSCX file

## 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`

  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, volta_structure=None, relative_to_global=False, chord_tones=True, absolute=False, all_in_c=False)

  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()`, `roman_numeral2fifths()`, `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.

    - volta_structure (`dict`, optional) – {first_mc -> {volta_number -> [mc1, mc2…]} } dictionary as you can get it from `Score.mscx.volta_structure`. This allows for correct propagation into second and other voltas.

    - 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)

  Add n to all elements e recursively.

`ms3.expand_dcml.` `split_labels`(df, column, regex, cols={}, dropna=False, inplace=False, **kwargs)

  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)

  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={})
  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)

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

  Uses: `changes2list()`

`ms3.expand_dcml.` `propagate_keys`(df, volta_structure=None, globalkey='globalkey', localkey='localkey', add_bool=True)
  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().

    - volta_structure (`dict`, optional) – {first_mc -> {volta_number -> [mc1, mc2…]} } dictionary as you can get it from `Score.mscx.volta_structure`. This allows for correct propagation into second and other voltas.

    - 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.` `propagate_pedal`(df, relative=True, drop_pedalend=True, cols={})

  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.` `compute_chord_tones`(df, bass_only=False, expand=False, cols={})

  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)

  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()`, `name2fifths()`, `resolve_relative_keys()`, `roman_numeral2fifths()`, `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.` `transform_columns`(df, func, columns=None, param2col=None, inplace=False, **kwargs)

  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)

  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.` `chord2tpcs`(chord, regex=None, **kwargs)

  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`, optional) – Compiled regex with named groups for the five features. By default, the current version of the DCML harmony annotation standard is used.

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

## Utils

`ms3.utils.` `DCML_REGEX` = re.compile('\n^(\\.?\n ((?P<globalkey>[a-gA-G](b*|\\#*))\\.)?\n ((?P<localkey>((b*|\\#*)(VII|VI|V|IV|III|II|I|vii|vi|v|iv|iii|ii|i)/?)+)\\.)?\n ((?P<pedal>((b*|\\#*)(VII|VI|V|IV|III|II|I|vii|vi|v|iv|iii, re.VERBOSE)

  `str` Constant with a regular expression that recognizes labels conforming to the DCML harmony annotation standard excluding those consisting of two alternatives.

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

  `str` Constant with a regular expression that recognizes complete labels conforming to the DCML harmony annotation standard including those consisting of two alternatives, without having to split them. It is simply a doubled version of DCML_REGEX.

`ms3.utils.` `rgba`

  alias of `ms3.utils.RGBA`

class `ms3.utils.` `map_dict`

  Such a dictionary can be mapped to a Series to replace its values but leaving the values absent from the dict keys intact.

`ms3.utils.` `add_quarterbeats_col`(df, offset_dict, insert_after='mc')
  Insert a column measuring the distance of events from MC 1 in quarter notes. If no ‘mc_onset’ column is present,

    the column corresponds to the `insert_after` column’s measure counts.

  Parameters

    - df (`pandas.DataFrame`) – DataFrame with an `mc_playthrough` and an `mc_onset` column.

    - offset_dict (`pandas.Series` or `dict`) – If unfolded: {mc_playthrough -> offset} Otherwise: {mc -> offset} You can create the dict using the function `Parse.get_continuous_offsets()`

    - insert_after (`str`, optional) – Name of the column after which the new column will be inserted.

`ms3.utils.` `assert_all_lines_equal`(before, after, original, tmp_file)

  Compares two multiline strings to test equality.

`ms3.utils.` `assert_dfs_equal`(old, new, exclude=[])

  Compares the common columns of two DataFrames to test equality.

`ms3.utils.` `ambitus2oneliner`(ambitus)

  Turns a `metadata['parts'][staff_id]` dictionary into a string.

`ms3.utils.` `check_labels`(df, regex, column='label', split_regex=None, return_cols=['mc', 'mc_onset', 'staff', 'voice'])

  Checks the labels in `column` against `regex` and returns those that don’t match.

  Parameters

    - df (`pandas.DataFrame`) – DataFrame containing a column with labels.

    - regex (`str`) – Regular expression that incorrect labels don’t match.

    - column (`str`, optional) – Column name where the labels are. Defaults to ‘label’

    - split_regex (`str`, optional) – If you pass a regular expression (or simple string), it will be used to split the labels before checking the resulting column separately. Instead, pass True to use the default (a ‘-‘ that does not precede a scale degree).

    - return_cols (`list`, optional) – Pass a list of the DataFrame columns that you want to be displayed for the wrong labels.

  Returns

    df – DataFrame with wrong labels.

  Return type

    `pandas.DataFrame`

`ms3.utils.` `color2rgba`(c)

  Pass a RGB or RGBA tuple, HTML color or name to convert it to RGBA

`ms3.utils.` `color_name2format`(n, format='rgb')

  Converts a single CSS3 name into one of ‘HTML’, ‘rgb’, or ‘rgba’

`ms3.utils.` `color_name2html`(n)

  Converts a single CSS3 name into HTML

`ms3.utils.` `color_name2rgb`(n)

  Converts a single CSS3 name into RGB

`ms3.utils.` `color_name2rgba`(n)

  Converts a single CSS3 name into RGBA

`ms3.utils.` `commonprefix`(paths, sep='/')

  Returns common prefix of a list of paths. Uses: allnamesequal(), itertools.takewhile()

`ms3.utils.` `compute_mn`(df)

  Compute measure numbers from a measure list with columns [‘dont_count’, ‘numbering_offset’]

`ms3.utils.` `convert_folder`(directory, new_folder, extensions=[], target_extension='mscx', regex='.*', suffix=None, recursive=True, ms='mscore', overwrite=False, parallel=False)

  Convert all files in dir that have one of the extensions to .mscx format using the executable MS.

  Parameters

    - directory (str) – Directories

    - new_folder (str) – Directories

    - extensions (list, optional) – If you want to convert only certain formats, give those, e.g. [‘mscz’, ‘xml’]

    - recursive (bool, optional) – Subdirectories as well.

    - MS (str, optional) – Give the path to the MuseScore executable on your system. Need only if the command ‘mscore’ does not execute MuseScore on your system.

`ms3.utils.` `decode_harmonies`(df, label_col='label', keep_type=True, return_series=False, alt_cols='alt_label', alt_separator='-')

  MuseScore stores types 2 (Nashville) and 3 (absolute chords) in several columns. This function returns a copy of the DataFrame `Annotations.df` where the label column contains the strings corresponding to these columns.

  Parameters

    - df (`pandas.DataFrame`) – DataFrame with encoded harmony labels as stored in an `Annotations` object.

    - label_col (`str`, optional) – Column name where the main components (<name> tag) are stored, defaults to ‘label’

    - keep_type (`bool`, optional) – Defaults to True, retaining the ‘label_type’ column and setting types 2 and 3 to 0.

    - return_series (`bool`, optional) – If set to True, only the decoded labels column is returned as a Series rather than a copy of `df`.

    - alt_cols (`str` or `list`, optional) – Column(s) with alternative labels that are joined with the label columns using `alt_separator`. Defaults to ‘alt_label’. Suppress by passing None.

    - alt_separator (`str`, optional) – Separator for joining `alt_cols`.

  Returns

    Decoded harmony labels.

  Return type

    `pandas.DataFrame` or `pandas.Series`

`ms3.utils.` `df2md`(df, name='Overview')

  Turns a DataFrame into a MarkDown table. The returned writer can be converted into a string.

`ms3.utils.` `dict2oneliner`(d)

  Turns a dictionary into a single-line string without brackets.

`ms3.utils.` `fifths2acc`(fifths)

  Returns accidentals for a stack of fifths that can be combined with a basic representation of the seven steps.

`ms3.utils.` `fifths2iv`(fifths, smallest=False)

  Return interval name of a stack of fifths such that 0 = ‘P1’, -1 = ‘P4’, -2 = ‘m7’, 4 = ‘M3’ etc. If you pass `smallest=True`, intervals of a fifth or greater will be inverted (e.g. ‘m6’ => ‘-M3’ and ‘D5’ => ‘-A4’). Uses: map2elements()

`ms3.utils.` `fifths2name`(fifths, midi=None, ms=False)
  Return note name of a stack of fifths such that

    0 = C, -1 = F, -2 = Bb, 1 = G etc. Uses: map2elements(), fifths2str()

  Parameters

    - fifths (`int`) – Tonal pitch class to turn into a note name.

    - midi (`int`) – In order to include the octave into the note name, pass the corresponding MIDI pitch.

    - ms (`bool`, optional) – Pass True if `fifths` is a MuseScore TPC, i.e. C = 14

`ms3.utils.` `fifths2pc`(fifths)

  Turn a stack of fifths into a chromatic pitch class. Uses: map2elements()

`ms3.utils.` `fifths2rn`(fifths, minor=False, auto_key=False)
  Return Roman numeral of a stack of fifths such that

    0 = I, -1 = IV, 1 = V, -2 = bVII in major, VII in minor, etc. Uses: map2elements(), is_minor_mode()

  Parameters

    auto_key (`bool`, optional) – By default, the returned Roman numerals are uppercase. Pass True to pass upper- or lowercase according to the position in the scale.

`ms3.utils.` `fifths2sd`(fifths, minor=False)

  Return scale degree of a stack of fifths such that 0 = ‘1’, -1 = ‘4’, -2 = ‘b7’ in major, ‘7’ in minor etc. Uses: map2elements(), fifths2str()

`ms3.utils.` `fifths2str`(fifths, steps, inverted=False)

  Boiler plate used by fifths2-functions.

`ms3.utils.` `get_musescore`(MS)

  Tests whether a MuseScore executable can be found on the system. Uses: test_binary()

  Parameters

    MS (`str`) – A path to the executable, installed command, or one of the keywords {‘auto’, ‘win’, ‘mac’}

  Returns

    Path to the executable if found or None.

  Return type

    `str`

`ms3.utils.` `group_id_tuples`(l)

  Turns a list of (key, ix) into a {key: [ix]}

`ms3.utils.` `html2format`(df, format='name', html_col='color_html')

  Converts the HTML column of a DataFrame into ‘name’, ‘rgb , or ‘rgba’.

`ms3.utils.` `html_color2format`(h, format='name')

  Converts a single HTML color into ‘name’, ‘rgb’, or ‘rgba’.

`ms3.utils.` `html_color2name`(h)

  Converts a HTML color into its CSS3 name or itself if there is none.

`ms3.utils.` `html_color2rgb`(h)

  Converts a HTML color into RGB.

`ms3.utils.` `html_color2rgba`(h)

  Converts a HTML color into RGBA.

`ms3.utils.` `is_any_row_equal`(df1, df2)

  Returns True if any two rows of the two DataFrames contain the same value tuples.

`ms3.utils.` `is_minor_mode`(fifths, minor=False)

  Returns True if the scale degree fifths naturally has a minor third in the scale.

`ms3.utils.` `join_tsvs`(dfs, sort_cols=False)

  Performs outer join on the passed DataFrames based on ‘mc’ and ‘mc_onset’, if any. Uses: functools.reduce(), sort_cols(), sort_note_lists()

  Parameters

    - dfs (`Collection`) – Collection of DataFrames to join.

    - sort_cols (`bool`, optional) – If you pass True, the remaining columns (those that are not defined in the standard column order in the function sort_cols) will be sorted.

`ms3.utils.` `load_tsv`(path, index_col=None, sep='\t', converters={}, dtypes={}, stringtype=False, **kwargs)

  Loads the TSV file path while applying correct type conversion and parsing tuples.

  Parameters

    - path (`str`) – Path to a TSV file as output by format_data().

    - index_col (`list`, optional) – By default, the first two columns are loaded as MultiIndex. The first level distinguishes pieces and the second level the elements within.

    - converters (`dict`, optional) – Enhances or overwrites the mapping from column names to types included the constants.

    - dtypes (`dict`, optional) – Enhances or overwrites the mapping from column names to types included the constants.

    - stringtype (`bool`, optional) – If you’re using pandas >= 1.0.0 you might want to set this to True in order to be using the new string datatype that includes the new null type pd.NA.

`ms3.utils.` `make_continuous_offset`(act_durs, quarters=True, negative_anacrusis=None)

  In order to compute continuous offset, this function is required to compute each MC’s offset from the piece’s beginning.

  Parameters

    - act_durs (`pandas.Series`) – A series of actual measures durations as fractions of whole notes (might differ from time signature).

    - quarters (`bool`, optional) – By default, the continuous offsets are expressed in quarter notes. Pass false to leave them as fractions of a whole note.

    - negative_anacrusis (`fractions.Fraction`) – By default, the first value is 0. If you pass a fraction here, the first value will be its negative and the second value will be 0.

  Returns

    Cumulative sum of the values, shifted down by 1.

  Return type

    `pandas.Series`

`ms3.utils.` `make_id_tuples`(key, n)

  For a given key, this function return index tuples in the form [(key, 0), …, (key, n)]

  Returns

    indices in the form [(key, 0), …, (key, n)]

  Return type

    list

`ms3.utils.` `map2elements`(e, f, *args, **kwargs)

  If e is an iterable, f is applied to all elements.

`ms3.utils.` `merge_ties`(df, return_dropped=False, perform_checks=True)
  In a note list, merge tied notes to single events with accumulated durations.

    Input dataframe needs columns [‘duration’, ‘tied’, ‘midi’, ‘staff’]. This function does not handle correctly overlapping ties on the same pitch since it doesn’t take into account the notational layers (‘voice’).

  Parameters

    - df –

    - return_dropped –

`ms3.utils.` `metadata2series`(d)

  Turns a metadata dict into a pd.Series() (for storing in a DataFrame) Uses: ambitus2oneliner(), dict2oneliner(), parts_info()

  Returns

    A series allowing for storing metadata as a row of a DataFrame.

  Return type

    `pandas.Series`

`ms3.utils.` `midi2octave`(midi, fifths=None)
  For a given MIDI pitch, calculate the octave. Middle octave = 4

    Uses: fifths2pc(), map2elements()

  Parameters

    - midi (`int`) – MIDI pitch (positive integer)

    - tpc (`int`, optional) – To be precise, for some Tonal Pitch Classes, the octave deviates from the simple formula `MIDI // 12 - 1`, e.g. for B# or Cb.

`ms3.utils.` `mn2int`(mn_series)

  Turn a series of measure numbers parsed as strings into two integer columns ‘mn’ and ‘volta’.

`ms3.utils.` `name2format`(df, format='html', name_col='color_name')

  Converts a column with CSS3 names into ‘html’, ‘rgb’, or ‘rgba’.

`ms3.utils.` `name2fifths`(nn)

  Turn a note name such as Ab into a tonal pitch class, such that -1=F, 0=C, 1=G etc. Uses: split_note_name()

`ms3.utils.` `next2sequence`(nxt)

  Turns a ‘next’ column into the correct sequence of MCs corresponding to unfolded repetitions. Requires that the Series’ index be the MCs as in `measures.set_index('mc').next`.

`ms3.utils.` `no_collections_no_booleans`(df, coll_columns=None, bool_columns=None)

  Cleans the DataFrame columns [‘next’, ‘chord_tones’, ‘added_tones’] from tuples and the columns [‘globalkey_is_minor’, ‘localkey_is_minor’] from booleans, converting them all to integers

`ms3.utils.` `parts_info`(d)

  Turns a (nested) `metadata['parts']` dict into a flat dict based on staves.

  Example

      >>> d = s.mscx.metadata
      >>> parts_info(d['parts'])
      {'staff_1_instrument': 'Voice',
       'staff_1_ambitus': '66-76 (F#4-E5)',
       'staff_2_instrument': 'Voice',
       'staff_2_ambitus': '55-69 (G3-A4)',
       'staff_3_instrument': 'Voice',
       'staff_3_ambitus': '48-67 (C3-G4)',
       'staff_4_instrument': 'Voice',
       'staff_4_ambitus': '41-60 (F2-C4)'}

`ms3.utils.` `pretty_dict`(d, heading=None)

  Turns a dictionary into a string where the keys are printed in a column, separated by ‘->’.

`ms3.utils.` `resolve_dir`(d)

  Resolves ‘~’ to HOME directory and turns `d` into an absolute path.

`ms3.utils.` `rgb2format`(df, format='html', r_col='color_r', g_col='color_g', b_col='color_b')

  Converts three RGB columns into a color_html or color_name column.

`ms3.utils.` `rgb_tuple2format`(t, format='html')

  Converts a single RGB tuple into ‘HTML’ or ‘name’.

`ms3.utils.` `rgb_tuple2html`(t)

  Converts a single RGB tuple into HTML.

`ms3.utils.` `rgb_tuple2name`(t)

  Converts a single RGB tuple into its CSS3 name or to HTML if there is none.

`ms3.utils.` `roman_numeral2fifths`(rn, global_minor=False)

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

`ms3.utils.` `roman_numeral2semitones`(rn, global_minor=False)

  Turn a Roman numeral into a semitone distance from the root (0-11). Uses: split_scale_degree()

`ms3.utils.` `scan_directory`(directory, file_re='.*', folder_re='.*', exclude_re='^(\\.|_)', recursive=True, subdirs=False, progress=False, exclude_files_only=False)

  Generator of file names in `directory`.

  Parameters

    - dir (`str`) – Directory to be scanned for files.

    - file_re (`str` or `re.Pattern`, optional) – Regular expressions for filtering certain file names or folder names. The regEx are checked with search(), not match(), allowing for fuzzy search.

    - folder_re (`str` or `re.Pattern`, optional) – Regular expressions for filtering certain file names or folder names. The regEx are 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`.

    - subdirs (`bool`, optional) – By default, full file paths are returned. Pass True to return (path, name) tuples instead.

    - progress (`bool`, optional) – By default, the scanning process is shown. Pass False to prevent.

    - exclude_files_only (`bool`, optional) – By default, `exclude_re` excludes files and folder. Pass True to exclude only files matching the regEx.

  Yields

    list – List of full paths meeting the criteria.

`ms3.utils.` `column_order`(df, first_cols=None, sort=True)

  Sort DataFrame columns so that they start with the order of `first_cols`, followed by those not included.

`ms3.utils.` `sort_note_list`(df, mc_col='mc', mc_onset_col='mc_onset', midi_col='midi', duration_col='duration')

  Sort every measure (MC) by [‘mc_onset’, ‘midi’, ‘duration’] while leaving gracenotes’ order (duration=0) intact.

  Parameters

    - df –

    - mc_col –

    - mc_onset_col –

    - midi_col –

    - duration_col –

`ms3.utils.` `sort_tpcs`(tpcs, ascending=True, start=None)
  Sort tonal pitch classes by order on the piano.

    Uses: fifths2pc()

  Parameters

    - tpcs (collection of `int`) – Tonal pitch classes to sort.

    - ascending (`bool`, optional) – Pass False to sort by descending order.

    - start (`int`, optional) – Start on or above this TPC.

`ms3.utils.` `split_alternatives`(df, column='label', regex='-(?!(\\d|b+\\d|\\#+\\d))', max=2, inplace=False, alternatives_only=False)

  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.

    - regex (`str`, optional) – The regular expression (or simple string) that detects the character combination used to separate alternative annotations. By default, alternatives are separated by a ‘-‘ that does not precede a scale degree such as ‘b6’ or ‘3’.

    - max (`int`, optional) – Maximum number of admitted alternatives, defaults to 2.

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

    - alternatives_only (`bool`, optional) – By default the alternatives are added to the original DataFrame (`inplace` or not). Pass True if you just need the split alternatives.

  Example

      >>> import pandas as pd
      >>> labels = pd.read_csv('labels.csv')
      >>> split_alternatives(labels, inplace=True)

`ms3.utils.` `split_note_name`(nn, count=False)

  Splits a note name such as ‘Ab’ into accidentals and name.

  nn`str`

    Note name.

  count`bool`, optional

    Pass True to get the accidentals as integer rather than as string.

`ms3.utils.` `split_scale_degree`(sd, count=False)

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

  sd`str`

    Scale degree.

  count`bool`, optional

    Pass True to get the accidentals as integer rather than as string.

`ms3.utils.` `chunkstring`(string, length=80)

  Generate chunks of a given length

`ms3.utils.` `string2lines`(string, length=80)

  Use chunkstring() and make chunks into lines.

`ms3.utils.` `transform`(df, func, param2col=None, column_wise=False, **kwargs)
  Compute a function for every row of a DataFrame, using several cols as arguments.

    The result is the same as using df.apply(lambda r: func(param1=r.col1, param2=r.col2…), axis=1) but it optimizes the procedure by precomputing func for all occurrent parameter combinations. Uses: inspect.getfullargspec()

  Parameters

    - df (`pandas.DataFrame` or `pandas.Series`) – Dataframe containing function parameters.

    - func (`callable`) – The result of this function for every row will be returned.

    - 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.

    - column_wise (`bool`, optional) – Pass True if you want to map `func` to the elements of every column separately. This is simply an optimized version of df.apply(func) but allows for naming columns to use as function arguments. If param2col is None, `func` is mapped to the elements of all columns, otherwise to all columns that are not named as parameters in `param2col`. In the case where `func` does not require a positional first element and you want to pass the elements of the various columns as keyword argument, give it as param2col={‘function_argument’: None}

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

    - **kwargs (Other parameters passed to `func`.) –

`ms3.utils.` `unfold_repeats`(df, mc_sequence)

  Use a succesion of MCs to bring a DataFrame in this succession. MCs may repeat.

  Parameters

    - df (`pandas.DataFrame`) – DataFrame needs to have the columns ‘mc’ and ‘mn’.

    - mc_sequence (`pandas.Series`) – A Series of the format `{mc_playthrough: mc}` where `mc_playthrough` corresponds to continuous MC

`ms3.utils.` `abs2rel_key`(absolute, localkey, global_minor=False)

  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_scale_degree()`

  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.utils.` `rel2abs_key`(rel, localkey, global_minor=False)

  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_scale_degree()`

  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.utils.` `labels2global_tonic`(df, cols={}, inplace=False)

  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.utils.` `series_is_minor`(S, is_name=True)

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

`ms3.utils.` `resolve_relative_keys`(relativeroot, minor=False)

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

  Uses: `rel2abs_key()`, `str_is_minor()`

  relativeroot`str`

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

  minor`bool`, optional

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

`ms3.utils.` `transpose_changes`(changes, old_num, new_num, old_minor=False, new_minor=False)

  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.utils.` `str_is_minor`(tone, is_name=True)

  Returns True if `tone` represents a minor key or chord.

`ms3.utils.` `changes2tpc`(changes, numeral, minor=False, root_alterations=False)

  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_scale_degree(), 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.utils.` `changes2list`(changes, sort=True)

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

  Example

      >>> changes2list('+#7b5')
      [('+#7', '+', '#', '7'),
       ('b5',  '',  'b', '5')]

## The commandline interface

Welcome to ms3 parsing |

The library offers you the following commands. Add the flag -h to one of them to learn about its parameters.

    usage: ms3 [-h] {extract,check,compare,convert,metadata,repair,update} ...

### Positional Arguments

`action`

  Possible choices: extract, check, compare, convert, metadata, repair, update

  The action that you want to perform.

### Sub-commands:

#### extract

Extract selected information from MuseScore files and store it in TSV files.

    ms3 extract [-h] [-d DIR [DIR ...]] [-n] [-f PATHs [PATHs ...]] [-o OUT_DIR] [-r REGEX] [-e regex] [-l {c, e, w, i, d}] [-M [folder]] [-N [folder]]
                [-R [folder]] [-L [folder]] [-X [folder]] [-E [folder]] [-C [folder]] [-D [path]] [-s [SUFFIX [SUFFIX ...]]] [-m MUSESCORE] [-t] [-p] [--raw]
                [-u] [-q] [--logfile file path or file name] [--logpath [LOGPATH]]

##### Named Arguments

`-d, --dir`

  Folder(s) that will be scanned for input files. Defaults to current working directory if no individual files are passed via -f.

`-n, --nonrecursive`

  Don’t scan folders recursively, i.e. parse only files in DIR.

  Default: True

`-f, --file`

  Add path(s) of individual file(s) to be checked.

`-o, --out`

  Output directory. Subfolder trees are retained.

`-r, --regex`

  Select only file names including this string or regular expression. Defaults to MSCX, MSCZ and TSV files only.

  Default: “(.mscx|.mscz|.tsv)$”

`-e, --exclude`

  Any files or folders (and their subfolders) including this regex will be disregarded.By default, files including ‘_reviewed’ or starting with . or _ are excluded.

  Default: “(^(.|_)|_reviewed)”

`-l, --level`

  Choose how many log messages you want to see: c (none), e, w, i, d (maximum)

  Default: “i”

`-M, --measures`

  Folder where to store TSV files with measure information needed for tasks such as unfolding repetitions.

`-N, --notes`

  Folder where to store TSV files with information on all notes.

`-R, --rests`

  Folder where to store TSV files with information on all rests.

`-L, --labels`

  Folder where to store TSV files with information on all annotation labels.

`-X, --expanded`

  Folder where to store TSV files with expanded DCML labels.

`-E, --events`

  Folder where to store TSV files with all events (notes, rests, articulation, etc.) without further processing.

`-C, --chords`

  Folder where to store TSV files with <chord> tags, i.e. groups of notes in the same voice with identical onset and duration. The tables include lyrics, slurs, and other markup.

`-D, --metadata`

  Directory or full path for storing one TSV file with metadata. If no filename is included in the path, it is called metadata.tsv

`-s, --suffix`

  Pass -s to use standard suffixes or -s SUFFIX to choose your own.

`-m, --musescore`

  Command or path of MuseScore executable. Defaults to ‘auto’ (attempt to use standard path for your system). Other standard options are -m win, -m mac, and -m mscore (for Linux).

  Default: “auto”

`-t, --test`

  No data is written to disk.

  Default: False

`-p, --positioning`

  When extracting labels, include manually shifted position coordinates in order to restore them when re-inserting.

  Default: False

`--raw`

  When extracting labels, leave chord symbols encoded instead of turning them into a single column of strings.

  Default: True

`-u, --unfold`

  Unfold the repeats for all stored DataFrames.

  Default: False

`-q, --quarterbeats`

  Add a column with continuous quarterbeat positions. If a score as first and second endings, the behaviour depends onthe parameter –unfold: If it is not set, repetitions are not unfolded and only last endings are included in the continuouscount. If repetitions are being unfolded, all endings are taken into account.

  Default: False

`--logfile`

  Either pass an absolute file path to store all logging data in that particular file or pass just a file name and the argument –logpath to create several log files of the same name in a replicated folder structure. In the former case, –logpath will be disregarded.

`--logpath`

  If you define a path for storing log files, the original folder structure of the parsed MuseScore files is recreated there. Additionally, you can pass a filename to –logfile to combine logging data for each subdirectory; otherwise, an individual log file is automatically created for each MuseScore file. Pass without value to use current working directory.

#### check

Parse MSCX files and look for errors. In particular, check DCML harmony labels for syntactic correctness.

    ms3 check [-h] [-d DIR [DIR ...]] [-n] [-f PATHs [PATHs ...]] [-o OUT_DIR] [-r REGEX] [-e regex] [-l {c, e, w, i, d}] [-s] [--assertion] [--log NAME]

##### Named Arguments

`-d, --dir`

  Folder(s) that will be scanned for input files. Defaults to current working directory if no individual files are passed via -f.

`-n, --nonrecursive`

  Don’t scan folders recursively, i.e. parse only files in DIR.

  Default: True

`-f, --file`

  Add path(s) of individual file(s) to be checked.

`-o, --out`

  Output directory. Subfolder trees are retained.

`-r, --regex`

  Select only file names including this string or regular expression. Defaults to MSCX, MSCZ and TSV files only.

  Default: “(.mscx|.mscz|.tsv)$”

`-e, --exclude`

  Any files or folders (and their subfolders) including this regex will be disregarded.By default, files including ‘_reviewed’ or starting with . or _ are excluded.

  Default: “(^(.|_)|_reviewed)”

`-l, --level`

  Choose how many log messages you want to see: c (none), e, w, i, d (maximum)

  Default: “i”

`-s, --scores_only`

  Don’t check DCML labels for syntactic correctness.

  Default: False

`--assertion`

  If you pass this argument, an error will be thrown if there are any mistakes.

  Default: False

`--log`

  Can be a an absolute file path or relative to the current directory.

#### compare

For MSCX files for which annotation tables exist, create another MSCX file with a coloured label comparison.

    ms3 compare [-h] [-d DIR [DIR ...]] [-n] [-f PATHs [PATHs ...]] [-o OUT_DIR] [-r REGEX] [-e regex] [-l {c, e, w, i, d}] [-a PATH] [-s SUFFIX]
                [-x EXT [EXT ...]]

##### Named Arguments

`-d, --dir`

  Folder(s) that will be scanned for input files. Defaults to current working directory if no individual files are passed via -f.

`-n, --nonrecursive`

  Don’t scan folders recursively, i.e. parse only files in DIR.

  Default: True

`-f, --file`

  Add path(s) of individual file(s) to be checked.

`-o, --out`

  Output directory. Subfolder trees are retained.

`-r, --regex`

  Select only file names including this string or regular expression. Defaults to MSCX, MSCZ and TSV files only.

  Default: “(.mscx|.mscz|.tsv)$”

`-e, --exclude`

  Any files or folders (and their subfolders) including this regex will be disregarded.By default, files including ‘_reviewed’ or starting with . or _ are excluded.

  Default: “(^(.|_)|_reviewed)”

`-l, --level`

  Choose how many log messages you want to see: c (none), e, w, i, d (maximum)

  Default: “i”

`-a, --annotations`

  Path relative to the score file(s) where to look for existing annotation tables. Defaults to ../harmonies

  Default: “../harmonies”

`-s, --suffix`

  If existing annotation tables have a particular suffix, pass this suffix.

  Default: “”

`-x, --extensions`

  If you only want to compare scores with particular extensions, pass these extensions.

#### convert

Use your local install of MuseScore to convert MuseScore files.

    ms3 convert [-h] [-d DIR [DIR ...]] [-n] [-f PATHs [PATHs ...]] [-o OUT_DIR] [-r REGEX] [-e regex] [-l {c, e, w, i, d}] [-t TARGET_FORMAT] [-m MUSESCORE]
                [-p] [-s SUFFIX] [--safe]

##### Named Arguments

`-d, --dir`

  Folder(s) that will be scanned for input files. Defaults to current working directory if no individual files are passed via -f.

`-n, --nonrecursive`

  Don’t scan folders recursively, i.e. parse only files in DIR.

  Default: True

`-f, --file`

  Add path(s) of individual file(s) to be checked.

`-o, --out`

  Output directory. Subfolder trees are retained.

`-r, --regex`

  Select only file names including this string or regular expression. Defaults to MSCX, MSCZ and TSV files only.

  Default: “(.mscx|.mscz|.tsv)$”

`-e, --exclude`

  Any files or folders (and their subfolders) including this regex will be disregarded.By default, files including ‘_reviewed’ or starting with . or _ are excluded.

  Default: “(^(.|_)|_reviewed)”

`-l, --level`

  Choose how many log messages you want to see: c (none), e, w, i, d (maximum)

  Default: “i”

`-t, --target_format`

  You may choose one out of {png, svg, pdf, mscz, mscx, wav, mp3, flac, ogg, xml, mxl, mid}

  Default: “mscx”

`-m, --musescore`
  Path to MuseScore executable. Defaults to the command ‘mscore’ (standard on *nix systems).

    To use standard paths on commercial systems, try -m win, or -m mac.

  Default: “mscore”

`-p, --nonparallel`

  Do not use all available CPU cores in parallel to speed up batch jobs.

  Default: True

`-s, --suffix`

  Add this suffix to the filename of every new file.

`--safe`

  Don’t overwrite existing files.

  Default: True

#### metadata

Update MSCX files with changes made in metadata.tsv (created via ms3 extract -D).

    ms3 metadata [-h] [-d DIR [DIR ...]] [-n] [-f PATHs [PATHs ...]] [-o OUT_DIR] [-r REGEX] [-e regex] [-l {c, e, w, i, d}]

##### Named Arguments

`-d, --dir`

  Folder(s) that will be scanned for input files. Defaults to current working directory if no individual files are passed via -f.

`-n, --nonrecursive`

  Don’t scan folders recursively, i.e. parse only files in DIR.

  Default: True

`-f, --file`

  Add path(s) of individual file(s) to be checked.

`-o, --out`

  Output directory. Subfolder trees are retained.

`-r, --regex`

  Select only file names including this string or regular expression. Defaults to MSCX, MSCZ and TSV files only.

  Default: “(.mscx|.mscz|.tsv)$”

`-e, --exclude`

  Any files or folders (and their subfolders) including this regex will be disregarded.By default, files including ‘_reviewed’ or starting with . or _ are excluded.

  Default: “(^(.|_)|_reviewed)”

`-l, --level`

  Choose how many log messages you want to see: c (none), e, w, i, d (maximum)

  Default: “i”

#### repair

Apply automatic repairs to your uncompressed MuseScore files.

    ms3 repair [-h] [-d DIR [DIR ...]] [-n] [-f PATHs [PATHs ...]] [-o OUT_DIR] [-r REGEX] [-e regex] [-l {c, e, w, i, d}]

##### Named Arguments

`-d, --dir`

  Folder(s) that will be scanned for input files. Defaults to current working directory if no individual files are passed via -f.

`-n, --nonrecursive`

  Don’t scan folders recursively, i.e. parse only files in DIR.

  Default: True

`-f, --file`

  Add path(s) of individual file(s) to be checked.

`-o, --out`

  Output directory. Subfolder trees are retained.

`-r, --regex`

  Select only file names including this string or regular expression. Defaults to MSCX, MSCZ and TSV files only.

  Default: “(.mscx|.mscz|.tsv)$”

`-e, --exclude`

  Any files or folders (and their subfolders) including this regex will be disregarded.By default, files including ‘_reviewed’ or starting with . or _ are excluded.

  Default: “(^(.|_)|_reviewed)”

`-l, --level`

  Choose how many log messages you want to see: c (none), e, w, i, d (maximum)

  Default: “i”

#### update

Convert MSCX files to the latest MuseScore version and move all chord annotations to the Roman Numeral Analysis layer. This command overwrites existing files!!!

    ms3 update [-h] [-d DIR [DIR ...]] [-n] [-f PATHs [PATHs ...]] [-o OUT_DIR] [-r REGEX] [-e regex] [-l {c, e, w, i, d}] [-s SUFFIX] [-m MUSESCORE] [--above]
               [--safe] [--staff STAFF] [--type TYPE]

##### Named Arguments

`-d, --dir`

  Folder(s) that will be scanned for input files. Defaults to current working directory if no individual files are passed via -f.

`-n, --nonrecursive`

  Don’t scan folders recursively, i.e. parse only files in DIR.

  Default: True

`-f, --file`

  Add path(s) of individual file(s) to be checked.

`-o, --out`

  Output directory. Subfolder trees are retained.

`-r, --regex`

  Select only file names including this string or regular expression. Defaults to MSCX, MSCZ and TSV files only.

  Default: “(.mscx|.mscz|.tsv)$”

`-e, --exclude`

  Any files or folders (and their subfolders) including this regex will be disregarded.By default, files including ‘_reviewed’ or starting with . or _ are excluded.

  Default: “(^(.|_)|_reviewed)”

`-l, --level`

  Choose how many log messages you want to see: c (none), e, w, i, d (maximum)

  Default: “i”

`-s, --suffix`

  Add this suffix to the filename of every new file.

`-m, --musescore`
  Path to MuseScore executable. Defaults to the command ‘mscore’ (standard on *nix systems).

    To try standard paths on commercial systems, try -m win, or -m mac.

  Default: “mscore”

`--above`

  Display Roman Numerals above the system.

  Default: False

`--safe`

  Only moves labels if their temporal positions stay intact.

  Default: False

`--staff`

  Which staff you want to move the annotations to. 1=upper staff; -1=lowest staff (default)

  Default: -1

`--type`

  defaults to 1, i.e. moves labels to Roman Numeral layer. Other types have not been tested!

  Default: 1

## 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()