Classes Representing Basic Score Elements¶

basics ¶

Basic Symbolic Music Representation Classes

from amads.core import *

Note: amads.core includes amads.core.basics, amads.core.distribution and amads.core.timemap.

Overview¶

The basic hierarchy of a score is described here.

Author: Roger B. Dannenberg

Constructor Details

The safe way to construct a score is to fully specify onsets for every Event. These onsets are absolute and will not be adjusted provided that the parent onset is also specified.

However, for convenience and to support simple constructs such as

Chord(Note(pitch=60), Note(pitch=64)),

onsets are optional and default to None. To make this simple example work:

Concurrences (Score, Part, and Chord) replace unspecified (None) onsets in their immediate content with the parent's onset (or 0 if it is None).
Sequences (Staff, Measure) replace unspecified (None) onsets in their immediate content starting with the parent's onset (or 0 if None) for the first event and the offset of the previous Event for subsequent events.
To handle the construction of nested Events, when an unspecified (None) onset of an EventGroup is replaced, the entire subtree of its content is shifted by the same amount. E.g. if a Chord is constructed with Notes with unspecified onsets, the Notes onsets will initially be replaced with zeros. Then, if the Chord onset is unspecified (None) and the Chord is passed in the content of a Measure and the Chord onset is replaced with 1.0, then the Notes are shifted to 1.0. If the Measure is then passed in the content of a Staff, the Measure and all its content might be shifted again.

Author: Roger Dannenberg

Event ¶

Event(
    parent: Optional[EventGroup],
    onset: Optional[float],
    duration: float,
)

A superclass for Note, Rest, EventGroup, and anything happening in time.

Parameters:

parent (Optional[EventGroup]) –

The containing object or None.
onset (float | None) –

The onset (start) time. This can be an “idealized” time for a symbolic score or an actual “real” time from a performance. Default is None.
duration (float) –

The duration of the event in quarters or seconds. This can be zero for objects such as key signatures or time signatures.

Attributes:

parent (Optional[Event]) –

The containing object or None.
_onset (float | None) –

The onset (start) time.
duration (float) –

The duration of the event in quarters or seconds.
info (Optional[Dict]) –

Additional attribute/value information.

Source code in amads/core/basics.py

def __init__(self, parent: Optional["EventGroup"],
             onset: Optional[float], duration: float):
    """
    Initialize an Event instance.

    """
    self.parent = None  # set below when inserted into parent
    self._onset = onset
    self.duration = duration
    self.info = None

    if parent:
        assert isinstance(parent, EventGroup)
        parent.insert(self)
    else:
        self.parent = None

Attributes¶

onset `property` `writable` ¶

onset: float

Retrieve the onset (start) time.

If the onset is None, raise an exception. (Events can have None onset times, but they must be set before retrieval. onsets that are None are automatically set when the Event is added to an EventGroup.)

Returns:

float | None –

The onset (start) time.

Raises:

ValueError –

If the onset time is not set (None).

units_are_seconds `property` ¶

units_are_seconds: bool

Check if the times are in seconds.

This event must be in a Score (where _units_are_seconds is stored).

Returns:

bool –

True iff the event's times are in seconds. If not in a score, False is returned.

units_are_quarters `property` ¶

units_are_quarters: bool

Check if the times are in quarters.

This event must be in a Score (where _units_are_seconds is stored).

Returns:

bool –

True iff the event's times are in quarters. If not in a score, False is returned.

offset `property` `writable` ¶

offset: float

Retrieve the global offset (stop) time.

Returns:

float –

The global offset (stop) time.

part `property` ¶

part: Optional[Part]

Retrieve the Part containing this event.

Returns:

Optional[Part] –

The Part containing this event or None if not found.

score `property` ¶

score: Optional[Score]

Retrieve the Score containing this event, or self if it is a score.

Returns:

Optional[Score] –

The Score containing this event or None if not found.

staff `property` ¶

staff: Optional[Staff]

Retrieve the Staff containing this event

Returns:

Optional[Staff] –

The Staff containing this event or None if not found.

measure `property` ¶

measure: Optional[Measure]

Retrieve the Measure containing this event

Returns:

Optional[Measure] –

The Measure containing this event or None if not found.

Functions¶

set ¶

set(property: str, value: Any) -> Event

Set a named property on this Event.

Every event can be extended with additional properties. Although Python objects are already extensible with new attributes, new attributes that are not set in __init__ confuse type checkers and other tools, so every Event has an info attribute as a dictionary where additional, application-specific information can be stored. The info attribute is None to save space until the first property is set, so you should use set and get methods and avoid writing event.info[property].

Parameters:

property (str) –

The name of the property to set.
value (Any) –

The value to assign to the property.

Returns:

Event –

returns this object (self)

Examples:

>>> note = Note()
>>> note.get("color", "no color")
'no color'
>>> _ = note.set("color", "red").set("harmonicity", 0.2)
>>> (note.has("color"), note.has("shape"))
(True, False)
>>> (note.get("color"), note.get("harmonicity"))
('red', 0.2)

Source code in amads/core/basics.py

def set(self, property : str, value : Any) -> "Event":
    """Set a named property on this Event.

    Every event can be extended with additional properties. Although
    Python objects are already extensible with new attributes, new
    attributes that are not set in `__init__` confuse type checkers
    and other tools, so every `Event` has an `info` attribute as a
    dictionary where additional, application-specific information can
    be stored. The `info` attribute is `None` to save space until the
    first property is set, so you should use `set` and `get` methods
    and avoid writing `event.info[property]`.

    Parameters
    ----------
    property : str
        The name of the property to set.
    value : Any
        The value to assign to the property.

    Returns
    -------
    Event
        returns this object (self)

    Examples
    --------
    >>> note = Note()
    >>> note.get("color", "no color")
    'no color'
    >>> _ = note.set("color", "red").set("harmonicity", 0.2)
    >>> (note.has("color"), note.has("shape"))
    (True, False)
    >>> (note.get("color"), note.get("harmonicity"))
    ('red', 0.2)
    """
    if self.info is None:
        self.info = {}
    self.info[property] = value
    return self

get ¶

get(property: str, default: Any = None) -> Any

Get the value of a property from this Event.

See set for more details.

Parameters:

property (str.) –

The name of the property to get.
default (Any, default: None ) –

The default value to return if the property is not found.

Returns:

Any –

The value of the specified property.

Source code in amads/core/basics.py

def get(self, property : str, default : Any = None) -> Any:
    """Get the value of a property from this Event.

    See [set][amads.core.basics.Event.set] for more details.

    Parameters
    ----------
    property : str.
        The name of the property to get.
    default : Any
        The default value to return if the property is not found.

    Returns
    -------
    Any
        The value of the specified property.
    """
    if self.info is None:
        return default
    return self.info.get(property, default)

has ¶

has(property) -> bool

Check if the Event has a specific property.

See set for more details.

Parameters:

property (str) –

The name of the property to check.

Returns:

bool –

True if the property exists, False otherwise.

Source code in amads/core/basics.py

def has(self, property) -> bool:
    """Check if the Event has a specific property.

    See [set][amads.core.basics.Event.set] for more details.

    Parameters
    ----------
    property : str
        The name of the property to check.

    Returns
    -------
    bool
        True if the property exists, False otherwise.
    """
    return (self.info is not None) and (property in self.info)

time_shift ¶

time_shift(increment: float, content_only=False) -> Event

Change the onset by an increment.

Parameters:

increment (float) –

The time increment (in quarters or seconds).
content_only (bool, default: False ) –

This parameter is ignored. (See EventGroup.time_shift)

Returns:

Event –

The object. This method modifies the Event.

Source code in amads/core/basics.py

def time_shift(self, increment: float, content_only=False) -> "Event":
    """
    Change the onset by an increment.

    Parameters
    ----------
    increment : float
        The time increment (in quarters or seconds).
    content_only : bool, optional
        This parameter is ignored. (See EventGroup.time_shift)
    Returns
    -------
    Event
        The object. This method modifies the `Event`.
    """
    self._onset += increment  # type: ignore
    return self

insert_copy_into ¶

insert_copy_into(parent: Optional[EventGroup] = None) -> Event

Make a (mostly) deep copy of the Event and add to a new parent.

Pitch objects are considered immutable and are shared rather than copied.

Parameters:

parent (Optional(EventGroup), default: None ) –

The copied Event will be a child of parent if not None. The parent is modified by this operation.

Returns:

Event –

A deep copy (except for parent and pitch) of the Event instance.

Source code in amads/core/basics.py

def insert_copy_into(self,
                     parent: Optional["EventGroup"] = None) -> "Event":
    """
    Make a (mostly) deep copy of the `Event` and add to a new `parent`.

    `Pitch` objects are considered immutable and are shared rather
    than copied.

    Parameters
    ----------
    parent : Optional(EventGroup)
        The copied `Event` will be a child of `parent` if not `None`.
        The parent is modified by this operation.

    Returns
    -------
    Event
        A deep copy (except for parent and pitch) of the Event instance.
    """
    # remove link to parent to break link going up the tree
    # preventing deep copy from copying the entire tree
    original_parent = self.parent
    self.parent = None
    c = copy.deepcopy(self)  # deep copy of this event down to leaf nodes
    self.parent = original_parent  # restore link to parent
    if parent:
        parent.insert(c)
    return c

Note ¶

Note(
    parent: Optional[EventGroup] = None,
    onset: Optional[float] = None,
    duration: float = 1.0,
    pitch: Union[Pitch, int, float, str, None] = 60,
    dynamic: Union[int, str, None] = None,
    lyric: Optional[str] = None,
)

Bases: Event

Note represents a musical note.

A Note is normally an element of a Measure in a full score, and an element of a Part in a flat score.

Parameters:

parent (Optional[EventGroup], default: None ) –

The containing object or None.
onset (float, default: None ) –

The onset (start) time. If None (default) is specified, a default onset will be calculated when the Note is inserted into an EventGroup.
duration (float, default: 1.0 ) –

The duration of the note in quarters or seconds.
pitch (Union[Pitch, int, float], default: 60 ) –

A Pitch object or an integer MIDI key number that will be converted to a Pitch object. The default (60) represents middle C.
dynamic (Optional[Union[int, str]], default: None ) –

Dynamic level (integer MIDI velocity or arbitrary string).
lyric (Optional[str], default: None ) –

Lyric text.

Attributes:

parent (Optional[EventGroup]) –

The containing object or None.
_onset (Optional[float]) –

The onset (start) time. None represents an unspecified onset.
duration (float) –

The duration of the note in quarters or seconds. See the property tied_duration for the duration of an entire group if the note is the first of a tied group of notes.
pitch (Pitch | None) –

The pitch of the note. Unpitched notes have a pitch of None.
dynamic (Optional[Union[int, str]]) –

Dynamic level (integer MIDI velocity or arbitrary string).
lyric (Optional[str]) –

Lyric text.
tie (Optional[Note]) –

The note that this note is tied to, if any.

Grace Notes

A grace note is indicated by the property "is_grace" which can be accessed using .get("is_grace", False). If true, then you can also query for "has_slash" using .get("has_slash", False). If true, this is an acciaccatura; if false, this is an appoggiatura. Note that Music21 incorrectly (at present) defaults to adding a slash when it reads a MusicXML grace tag with no slash attribute, and the acciaccatura/appoggiatura distinction is often ambiguous or incorrect to begin with.

Other Expressions

Other Note properties are set as follows: "has_trill" and "trill_pitch" are set for Music21 Trill ("trill_pitch" has an AMADS Pitch object as its value); "has_trill_extension" is set for TrillExtension. "has_turn" and "turn_pitches" are set for Turn expressions ("turn_pitches" consists of a list with the upper pitch and the lower pitch as AMADS Pitch objects); "has_inverted_turn" and "inverted_turn_pitches" are set for InvertedTurn expressions ("inverted_turn_pitches" consists of a list with the lower pitch and the upper pitch as AMADS Pitch objects); "has_mordent" and "mordent_pitch" are set for Mordent expressions ("mordent_pitch" consists of the upper pitch as an AMADS Pitch object); "has_inverted_mordent" and "inverted_mordent_pitch" are set for InvertedMordent expressions ("inverted_mordent_pitch" consists of the upper pitch as an AMADS Pitch object); "has_shake" is set for Shake expressions; and "has_schleifer" is set for Schleifer expressions.

Source code in amads/core/basics.py

def __init__(self,
             parent: Optional["EventGroup"] = None,
             onset: Optional[float] = None,
             duration: float = 1.0,
             pitch: Union["Pitch", int, float, str, None] = 60,
             dynamic: Union[int, str, None] = None,
             lyric: Optional[str] = None):
    super().__init__(parent, onset, float(duration))
    if isinstance(pitch, (int, float, str)):
        pitch = Pitch(pitch)
    self.pitch = pitch
    self.dynamic = dynamic
    self.lyric = lyric
    self.tie = None

Attributes¶

onset `property` `writable` ¶

onset: float

Retrieve the onset (start) time.

If the onset is None, raise an exception. (Events can have None onset times, but they must be set before retrieval. onsets that are None are automatically set when the Event is added to an EventGroup.)

Returns:

float | None –

The onset (start) time.

Raises:

ValueError –

If the onset time is not set (None).

units_are_seconds `property` ¶

units_are_seconds: bool

Check if the times are in seconds.

This event must be in a Score (where _units_are_seconds is stored).

Returns:

bool –

True iff the event's times are in seconds. If not in a score, False is returned.

units_are_quarters `property` ¶

units_are_quarters: bool

Check if the times are in quarters.

This event must be in a Score (where _units_are_seconds is stored).

Returns:

bool –

True iff the event's times are in quarters. If not in a score, False is returned.

offset `property` `writable` ¶

offset: float

Retrieve the global offset (stop) time.

Returns:

float –

The global offset (stop) time.

part `property` ¶

part: Optional[Part]

Retrieve the Part containing this event.

Returns:

Optional[Part] –

The Part containing this event or None if not found.

score `property` ¶

score: Optional[Score]

Retrieve the Score containing this event, or self if it is a score.

Returns:

Optional[Score] –

The Score containing this event or None if not found.

staff `property` ¶

staff: Optional[Staff]

Retrieve the Staff containing this event

Returns:

Optional[Staff] –

The Staff containing this event or None if not found.

measure `property` ¶

measure: Optional[Measure]

Retrieve the Measure containing this event

Returns:

Optional[Measure] –

The Measure containing this event or None if not found.

tied_duration `property` ¶

tied_duration: Union[float, int]

Retrieve the duration of the note in quarters or seconds.

If the note is the first note of a sequence of tied notes, return the duration of the entire sequence. However, if there are preceding notes tied to this note, they will not be considered part of the tied sequence. If you want to avoid processing notes that are tied to from earlier notes, you should either use merge_tied_notes() to eliminate them, or follow the tie links and add tied-to notes to a set as you traverse the score so you can ignore them when they are encountered. In some cases, notes can be tied across staves, in which case it might require two passes to (1) find all tied-to notes, and then (2) enumerate the rest of them. merge_tied_notes() handles this case properly.

Returns:

float –

The duration of the note and those it is tied to directly or indirectly, in quarters or seconds. The sum of durations is returned without checking whether notes are contiguous.

tied_offset `property` ¶

tied_offset: float

Retrieve the offset (stop) time of a note or tied group of notes.

If the note is the first note of a sequence of tied notes, return the offset of the entire sequence. However, if there are preceding notes tied to this note, they will not be considered part of the tied sequence.

Returns:

float –

The global offset (stop) time of the note and those it is tied to.

step `property` ¶

step: str

Retrieve the name of the pitch without accidental, e.g., "G".

If the note is unpitched (pitch is None), return the empty string.

name `property` ¶

name: str

Retrieve the name of the pitch with accidental, e.g., "Bb".

If the note is unpitched (pitch is None), return the empty string.

name_with_octave `property` ¶

name_with_octave: str

Retrieve the name of the pitch with octave, e.g., A4 or Bb3.

If the note is unpitched (pitch is None), return the empty string.

pitch_class `property` `writable` ¶

pitch_class: int

Retrieve the pitch class of the note, e.g., 0, 1, 2, ..., 11.

If the note is unpitched (pitch is None), raise ValueError.

octave `property` `writable` ¶

octave: int

Retrieve the octave number of the note.

The note name is based on key_num - alt, e.g., C4 has octave 4 while B#3 has octave 3. See also Pitch.register.

If the note is unpitched (pitch is None), raise ValueError.

Returns:

int –

The octave number of the note.

key_num `property` ¶

key_num: float | int

Retrieve the MIDI key number of the note, e.g., C4 = 60.

If the note is unpitched (pitch is None), raise ValueError.

Returns:

int –

The MIDI key number of the note.

Functions¶

set ¶

set(property: str, value: Any) -> Event

Set a named property on this Event.

Every event can be extended with additional properties. Although Python objects are already extensible with new attributes, new attributes that are not set in __init__ confuse type checkers and other tools, so every Event has an info attribute as a dictionary where additional, application-specific information can be stored. The info attribute is None to save space until the first property is set, so you should use set and get methods and avoid writing event.info[property].

Parameters:

property (str) –

The name of the property to set.
value (Any) –

The value to assign to the property.

Returns:

Event –

returns this object (self)

Examples:

>>> note = Note()
>>> note.get("color", "no color")
'no color'
>>> _ = note.set("color", "red").set("harmonicity", 0.2)
>>> (note.has("color"), note.has("shape"))
(True, False)
>>> (note.get("color"), note.get("harmonicity"))
('red', 0.2)

Source code in amads/core/basics.py

def set(self, property : str, value : Any) -> "Event":
    """Set a named property on this Event.

    Every event can be extended with additional properties. Although
    Python objects are already extensible with new attributes, new
    attributes that are not set in `__init__` confuse type checkers
    and other tools, so every `Event` has an `info` attribute as a
    dictionary where additional, application-specific information can
    be stored. The `info` attribute is `None` to save space until the
    first property is set, so you should use `set` and `get` methods
    and avoid writing `event.info[property]`.

    Parameters
    ----------
    property : str
        The name of the property to set.
    value : Any
        The value to assign to the property.

    Returns
    -------
    Event
        returns this object (self)

    Examples
    --------
    >>> note = Note()
    >>> note.get("color", "no color")
    'no color'
    >>> _ = note.set("color", "red").set("harmonicity", 0.2)
    >>> (note.has("color"), note.has("shape"))
    (True, False)
    >>> (note.get("color"), note.get("harmonicity"))
    ('red', 0.2)
    """
    if self.info is None:
        self.info = {}
    self.info[property] = value
    return self

get ¶

get(property: str, default: Any = None) -> Any

Get the value of a property from this Event.

See set for more details.

Parameters:

property (str.) –

The name of the property to get.
default (Any, default: None ) –

The default value to return if the property is not found.

Returns:

Any –

The value of the specified property.

Source code in amads/core/basics.py

def get(self, property : str, default : Any = None) -> Any:
    """Get the value of a property from this Event.

    See [set][amads.core.basics.Event.set] for more details.

    Parameters
    ----------
    property : str.
        The name of the property to get.
    default : Any
        The default value to return if the property is not found.

    Returns
    -------
    Any
        The value of the specified property.
    """
    if self.info is None:
        return default
    return self.info.get(property, default)

has ¶

has(property) -> bool

Check if the Event has a specific property.

See set for more details.

Parameters:

property (str) –

The name of the property to check.

Returns:

bool –

True if the property exists, False otherwise.

Source code in amads/core/basics.py

def has(self, property) -> bool:
    """Check if the Event has a specific property.

    See [set][amads.core.basics.Event.set] for more details.

    Parameters
    ----------
    property : str
        The name of the property to check.

    Returns
    -------
    bool
        True if the property exists, False otherwise.
    """
    return (self.info is not None) and (property in self.info)

time_shift ¶

time_shift(increment: float, content_only=False) -> Event

Change the onset by an increment.

Parameters:

increment (float) –

The time increment (in quarters or seconds).
content_only (bool, default: False ) –

This parameter is ignored. (See EventGroup.time_shift)

Returns:

Event –

The object. This method modifies the Event.

Source code in amads/core/basics.py

def time_shift(self, increment: float, content_only=False) -> "Event":
    """
    Change the onset by an increment.

    Parameters
    ----------
    increment : float
        The time increment (in quarters or seconds).
    content_only : bool, optional
        This parameter is ignored. (See EventGroup.time_shift)
    Returns
    -------
    Event
        The object. This method modifies the `Event`.
    """
    self._onset += increment  # type: ignore
    return self

insert_copy_into ¶

insert_copy_into(parent: Optional[EventGroup] = None) -> Event

Make a (mostly) deep copy of the Event and add to a new parent.

Pitch objects are considered immutable and are shared rather than copied.

Parameters:

parent (Optional(EventGroup), default: None ) –

The copied Event will be a child of parent if not None. The parent is modified by this operation.

Returns:

Event –

A deep copy (except for parent and pitch) of the Event instance.

Source code in amads/core/basics.py

def insert_copy_into(self,
                     parent: Optional["EventGroup"] = None) -> "Event":
    """
    Make a (mostly) deep copy of the `Event` and add to a new `parent`.

    `Pitch` objects are considered immutable and are shared rather
    than copied.

    Parameters
    ----------
    parent : Optional(EventGroup)
        The copied `Event` will be a child of `parent` if not `None`.
        The parent is modified by this operation.

    Returns
    -------
    Event
        A deep copy (except for parent and pitch) of the Event instance.
    """
    # remove link to parent to break link going up the tree
    # preventing deep copy from copying the entire tree
    original_parent = self.parent
    self.parent = None
    c = copy.deepcopy(self)  # deep copy of this event down to leaf nodes
    self.parent = original_parent  # restore link to parent
    if parent:
        parent.insert(c)
    return c

show ¶

show(
    indent: int = 0, file: Optional[TextIO] = None, tied: bool = False
) -> Note

Print note information.

Output includes pitch name, onset, duration, and optional tie, dynamic, and lyric information.

Parameters:

indent (int, default: 0 ) –

The indentation level for display.
tied (bool, default: False ) –

Include information about ties.

Returns:

Note –

The Note instance itself.

Source code in amads/core/basics.py

def show(self, indent: int = 0, file: Optional[TextIO] = None,
         tied: bool = False) -> "Note":
    """Print note information.

    Output includes pitch name, onset, duration, and optional
    tie, dynamic, and lyric information.

    Parameters
    ----------
    indent : int
        The indentation level for display.
    tied : bool
        Include information about ties.

    Returns
    -------
    Note
        The Note instance itself.
    """
    tie_info = ""
    if self.tie is not None:
        tie_info = " tied"
    tie_prefix = "  tied to " if tied else ""

    print(" " * indent, tie_prefix, self, tie_info, sep="", file=file)
    if self.tie:
        self.tie.show(indent + 2, tied=True, file=file)
    return self

enharmonic ¶

enharmonic() -> Pitch

Return a Pitch representing the enharmonic.

The enharmonic Pitch's alt will be zero or have the opposite sign such that alt is minimized. E.g., the enharmonic of C-double-flat is A-sharp (not B-flat). If alt is zero, return a Pitch with alt of +1 or -1 if possible. Otherwise, return a Pitch with alt of -2.

If the note is unpitched (pitch is None), raise ValueError.

Returns:

Pitch –

A Pitch object representing the enharmonic equivalent of the note.

Source code in amads/core/basics.py

def enharmonic(self) -> "Pitch":
    """Return a `Pitch` representing the enharmonic.

    The enharmonic `Pitch`'s `alt` will be zero or have the opposite
    sign such that `alt` is minimized. E.g., the enharmonic of
    C-double-flat is A-sharp (not B-flat). If `alt` is zero, return
    a Pitch with alt of +1 or -1 if possible. Otherwise, return a
    Pitch with alt of -2.

    If the note is unpitched (pitch is None), raise ValueError.

    If the note is unpitched (pitch is None), raise ValueError.

    Returns
    -------
    Pitch
        A Pitch object representing the enharmonic equivalent of the note.
    """
    if self.pitch is None:
        raise ValueError("Unpitched note has no enharmonic equivalent.")
    return self.pitch.enharmonic()

upper_enharmonic ¶

upper_enharmonic() -> Pitch

Return a valid enharmonic Pitch with alt decreased, e.g., C#->Db.

It follows that the alt is decreased by 1 or 2, e.g., C### (with alt = +3) becomes D# (with alt = +1).

If the note is unpitched (pitch is None), raise ValueError.

Returns:

Pitch –

A Pitch object representing the upper enharmonic equivalent of the note.

Source code in amads/core/basics.py

def upper_enharmonic(self) -> "Pitch":
    """Return a valid enharmonic Pitch with alt decreased, e.g., C#->Db.

    It follows that the alt is decreased by 1 or 2, e.g., C###
    (with `alt` = +3) becomes D# (with `alt` = +1).

    If the note is unpitched (pitch is None), raise ValueError.

    If the note is unpitched (pitch is None), raise ValueError.

    Returns
    -------
    Pitch
        A Pitch object representing the upper enharmonic
        equivalent of the note.
    """
    if self.pitch is None:
        raise ValueError(
                  "Unpitched note has no upper enharmonic equivalent.")
    return self.pitch.upper_enharmonic()

lower_enharmonic ¶

lower_enharmonic() -> Pitch

Return a valid enharmonic Pitch with alt increased, e.g., Db->C#.

It follows that the alt is increased by 1 or 2, e.g., D# (with alt = +1) becomes C### (with alt = +3).

If the note is unpitched (pitch is None), raise ValueError.

Returns:

Pitch –

A Pitch object representing the lower enharmonic equivalent of the note.

Source code in amads/core/basics.py

def lower_enharmonic(self) -> "Pitch":
    """Return a valid enharmonic Pitch with alt increased, e.g., Db->C#.

    It follows that the alt is increased by 1 or 2, e.g., D#
    (with `alt` = +1) becomes C### (with `alt` = +3).

    If the note is unpitched (pitch is None), raise ValueError.

    If the note is unpitched (pitch is None), raise ValueError.

    Returns
    -------
    Pitch
        A Pitch object representing the lower enharmonic
        equivalent of the note.
    """
    if self.pitch is None:
        raise ValueError(
                  "Unpitched note has no lower enharmonic equivalent.")
    return self.pitch.lower_enharmonic()

simplest_enharmonic ¶

simplest_enharmonic(sharp_or_flat: Optional[str] = 'default') -> Pitch

Return a valid Pitch with the simplest enharmonic representation.

(See [simplest_enharmonic] [amads.core.pitch.Pitch.simplest_enharmonic].)

Parameters:

sharp_or_flat (Optional[str], default: 'default' ) –

This is only relevant if the pitch needs an alteration, otherwise it is unused. The value can be "sharp" (use sharps), "flat" (use flats), and otherwise use the same enharmonic choice as the Pitch constructor.

Exceptions

If the note is unpitched (pitch is None), raise ValueError.

Returns:

Pitch –

A Pitch object representing the enharmonic equivalent.

Source code in amads/core/basics.py

def simplest_enharmonic(self, 
        sharp_or_flat: Optional[str] = "default") -> "Pitch":
    """Return a valid Pitch with the simplest enharmonic representation.

    (See [simplest_enharmonic]
     [amads.core.pitch.Pitch.simplest_enharmonic].)

    Parameters
    ----------
    sharp_or_flat: str
        This is only relevant if the pitch needs an alteration, otherwise
        it is unused. The value can be "sharp" (use sharps), "flat" (use
        flats), and otherwise use the same enharmonic choice as the Pitch
        constructor.

    Exceptions
    ----------
    If the note is unpitched (pitch is None), raise ValueError.

    Returns
    -------
    Pitch
        A Pitch object representing the enharmonic equivalent.
    """
    if self.pitch is None:
        raise ValueError(
                  "Unpitched note has no simplest enharmonic equivalent.")
    return self.pitch.simplest_enharmonic(sharp_or_flat)

Rest ¶

Rest(
    parent: Optional[EventGroup] = None,
    onset: Optional[float] = None,
    duration: float = 1,
)

Bases: Event

Rest represents a musical rest.

A Rest is normally an element of a Measure.

Parameters:

parent (Optional[EventGroup], default: None ) –

The containing object or None.
onset (float, default: None ) –

The onset (start) time. An initial value of None might be assigned when the Note is inserted into an EventGroup.
duration (float, default: 1 ) –

The duration of the rest in quarters or seconds.

Attributes:

parent (Optional[EventGroup]) –

The containing object or None.
_onset (float) –

The onset (start) time. None represents an unspecified onset.
duration (float) –

The duration of the rest in quarters or seconds.

Source code in amads/core/basics.py

def __init__(self, parent: Optional["EventGroup"] = None,
             onset: Optional[float] = None, duration: float = 1):
    super().__init__(parent, onset, duration)

Attributes¶

onset `property` `writable` ¶

onset: float

Retrieve the onset (start) time.

If the onset is None, raise an exception. (Events can have None onset times, but they must be set before retrieval. onsets that are None are automatically set when the Event is added to an EventGroup.)

Returns:

float | None –

The onset (start) time.

Raises:

ValueError –

If the onset time is not set (None).

units_are_seconds `property` ¶

units_are_seconds: bool

Check if the times are in seconds.

This event must be in a Score (where _units_are_seconds is stored).

Returns:

bool –

True iff the event's times are in seconds. If not in a score, False is returned.

units_are_quarters `property` ¶

units_are_quarters: bool

Check if the times are in quarters.

This event must be in a Score (where _units_are_seconds is stored).

Returns:

bool –

True iff the event's times are in quarters. If not in a score, False is returned.

offset `property` `writable` ¶

offset: float

Retrieve the global offset (stop) time.

Returns:

float –

The global offset (stop) time.

part `property` ¶

part: Optional[Part]

Retrieve the Part containing this event.

Returns:

Optional[Part] –

The Part containing this event or None if not found.

score `property` ¶

score: Optional[Score]

Retrieve the Score containing this event, or self if it is a score.

Returns:

Optional[Score] –

The Score containing this event or None if not found.

staff `property` ¶

staff: Optional[Staff]

Retrieve the Staff containing this event

Returns:

Optional[Staff] –

The Staff containing this event or None if not found.

measure `property` ¶

measure: Optional[Measure]

Retrieve the Measure containing this event

Returns:

Optional[Measure] –

The Measure containing this event or None if not found.

Functions¶

set ¶

set(property: str, value: Any) -> Event

Set a named property on this Event.

Every event can be extended with additional properties. Although Python objects are already extensible with new attributes, new attributes that are not set in __init__ confuse type checkers and other tools, so every Event has an info attribute as a dictionary where additional, application-specific information can be stored. The info attribute is None to save space until the first property is set, so you should use set and get methods and avoid writing event.info[property].

Parameters:

property (str) –

The name of the property to set.
value (Any) –

The value to assign to the property.

Returns:

Event –

returns this object (self)

Examples:

>>> note = Note()
>>> note.get("color", "no color")
'no color'
>>> _ = note.set("color", "red").set("harmonicity", 0.2)
>>> (note.has("color"), note.has("shape"))
(True, False)
>>> (note.get("color"), note.get("harmonicity"))
('red', 0.2)

Source code in amads/core/basics.py

def set(self, property : str, value : Any) -> "Event":
    """Set a named property on this Event.

    Every event can be extended with additional properties. Although
    Python objects are already extensible with new attributes, new
    attributes that are not set in `__init__` confuse type checkers
    and other tools, so every `Event` has an `info` attribute as a
    dictionary where additional, application-specific information can
    be stored. The `info` attribute is `None` to save space until the
    first property is set, so you should use `set` and `get` methods
    and avoid writing `event.info[property]`.

    Parameters
    ----------
    property : str
        The name of the property to set.
    value : Any
        The value to assign to the property.

    Returns
    -------
    Event
        returns this object (self)

    Examples
    --------
    >>> note = Note()
    >>> note.get("color", "no color")
    'no color'
    >>> _ = note.set("color", "red").set("harmonicity", 0.2)
    >>> (note.has("color"), note.has("shape"))
    (True, False)
    >>> (note.get("color"), note.get("harmonicity"))
    ('red', 0.2)
    """
    if self.info is None:
        self.info = {}
    self.info[property] = value
    return self

get ¶

get(property: str, default: Any = None) -> Any

Get the value of a property from this Event.

See set for more details.

Parameters:

property (str.) –

The name of the property to get.
default (Any, default: None ) –

The default value to return if the property is not found.

Returns:

Any –

The value of the specified property.

Source code in amads/core/basics.py

def get(self, property : str, default : Any = None) -> Any:
    """Get the value of a property from this Event.

    See [set][amads.core.basics.Event.set] for more details.

    Parameters
    ----------
    property : str.
        The name of the property to get.
    default : Any
        The default value to return if the property is not found.

    Returns
    -------
    Any
        The value of the specified property.
    """
    if self.info is None:
        return default
    return self.info.get(property, default)

has ¶

has(property) -> bool

Check if the Event has a specific property.

See set for more details.

Parameters:

property (str) –

The name of the property to check.

Returns:

bool –

True if the property exists, False otherwise.

Source code in amads/core/basics.py

def has(self, property) -> bool:
    """Check if the Event has a specific property.

    See [set][amads.core.basics.Event.set] for more details.

    Parameters
    ----------
    property : str
        The name of the property to check.

    Returns
    -------
    bool
        True if the property exists, False otherwise.
    """
    return (self.info is not None) and (property in self.info)

time_shift ¶

time_shift(increment: float, content_only=False) -> Event

Change the onset by an increment.

Parameters:

increment (float) –

The time increment (in quarters or seconds).
content_only (bool, default: False ) –

This parameter is ignored. (See EventGroup.time_shift)

Returns:

Event –

The object. This method modifies the Event.

Source code in amads/core/basics.py

def time_shift(self, increment: float, content_only=False) -> "Event":
    """
    Change the onset by an increment.

    Parameters
    ----------
    increment : float
        The time increment (in quarters or seconds).
    content_only : bool, optional
        This parameter is ignored. (See EventGroup.time_shift)
    Returns
    -------
    Event
        The object. This method modifies the `Event`.
    """
    self._onset += increment  # type: ignore
    return self

insert_copy_into ¶

insert_copy_into(parent: Optional[EventGroup] = None) -> Event

Make a (mostly) deep copy of the Event and add to a new parent.

Pitch objects are considered immutable and are shared rather than copied.

Parameters:

parent (Optional(EventGroup), default: None ) –

The copied Event will be a child of parent if not None. The parent is modified by this operation.

Returns:

Event –

A deep copy (except for parent and pitch) of the Event instance.

Source code in amads/core/basics.py

def insert_copy_into(self,
                     parent: Optional["EventGroup"] = None) -> "Event":
    """
    Make a (mostly) deep copy of the `Event` and add to a new `parent`.

    `Pitch` objects are considered immutable and are shared rather
    than copied.

    Parameters
    ----------
    parent : Optional(EventGroup)
        The copied `Event` will be a child of `parent` if not `None`.
        The parent is modified by this operation.

    Returns
    -------
    Event
        A deep copy (except for parent and pitch) of the Event instance.
    """
    # remove link to parent to break link going up the tree
    # preventing deep copy from copying the entire tree
    original_parent = self.parent
    self.parent = None
    c = copy.deepcopy(self)  # deep copy of this event down to leaf nodes
    self.parent = original_parent  # restore link to parent
    if parent:
        parent.insert(c)
    return c

show ¶

show(indent: int = 0, file: Optional[TextIO] = None) -> Rest

Display the Rest information.

Parameters:

indent (int, default: 0 ) –

The indentation level for display.

Returns:

Rest –

The Rest instance itself.

Source code in amads/core/basics.py

def show(self, indent: int = 0, file: Optional[TextIO] = None) -> "Rest":
    """Display the Rest information.

    Parameters
    ----------
    indent : int
        The indentation level for display.

    Returns
    -------
    Rest
        The Rest instance itself.
    """

    print(" " * indent, self, sep="", file=file)
    return self

Measure ¶

Measure(
    *args: Event,
    parent: Optional[EventGroup] = None,
    onset: Optional[float] = None,
    duration: float = 4,
    number: Optional[str] = None
)

Bases: Sequence

A Measure models a musical measure (bar).

A Measure can contain many object types including Note, Rest, Chord, and (in theory) custom Events. Measures are elements of a Staff.

The duration of a measure may differ from the prevailing time signature.

See Constructor Details.

Parameters:

*args (Event, default: () ) –

A variable number of Event objects to be added to the group.
parent (Optional[EventGroup], default: None ) –

The containing object or None. Must be passed as a keyword parameter due to *args.
onset (Optional[float], default: None ) –

The onset (start) time. None means unknown, to be set when Sequence is added to a parent. Must be passed as a keyword parameter due to *args.
duration (Optional[float], default: 4 ) –

The duration in quarters or seconds. Must be passed as a keyword parameter due to *args.
number (Optional[str], default: None ) –

A string representing the measure number. Must be passed as a keyword parameter due to *args.

Attributes:

parent (Optional[EventGroup]) –

The containing object or None.
_onset (Optional[float]) –

The onset (start) time. None represents "unknown" and to be determined when this object is added to a parent.
duration (float) –

The duration in quarters or seconds.
content (list[Event]) –

Elements contained within this Measure.
number (Optional[str]) –

A string representing the measure number if any.

Source code in amads/core/basics.py

def __init__(self, *args: Event, parent: Optional[EventGroup] = None,
             onset: Optional[float] = None, duration: float = 4,
             number: Optional[str] = None):
    super().__init__(parent, onset, duration, list(args))
    self.number = number

Attributes¶

onset `property` `writable` ¶

onset: float

Retrieve the onset (start) time.

If the onset is None, raise an exception. (Events can have None onset times, but they must be set before retrieval. onsets that are None are automatically set when the Event is added to an EventGroup.)

Returns:

float –

The onset (start) time.

Raises:

ValueError –

If the onset time is not set (None).

units_are_seconds `property` ¶

units_are_seconds: bool

Check if the times are in seconds.

This event must be in a Score (where _units_are_seconds is stored).

Returns:

bool –

True iff the event's times are in seconds. If not in a score, False is returned.

units_are_quarters `property` ¶

units_are_quarters: bool

Check if the times are in quarters.

This event must be in a Score (where _units_are_seconds is stored).

Returns:

bool –

True iff the event's times are in quarters. If not in a score, False is returned.

offset `property` `writable` ¶

offset: float

Retrieve the global offset (stop) time.

Returns:

float –

The global offset (stop) time.

part `property` ¶

part: Optional[Part]

Retrieve the Part containing this event.

Returns:

Optional[Part] –

The Part containing this event or None if not found.

score `property` ¶

score: Optional[Score]

Retrieve the Score containing this event, or self if it is a score.

Returns:

Optional[Score] –

The Score containing this event or None if not found.

staff `property` ¶

staff: Optional[Staff]

Retrieve the Staff containing this event

Returns:

Optional[Staff] –

The Staff containing this event or None if not found.

measure `property` ¶

measure: Optional[Measure]

Retrieve the Measure containing this event

Returns:

Optional[Measure] –

The Measure containing this event or None if not found.

Functions¶

set ¶

set(property: str, value: Any) -> Event

Set a named property on this Event.

Every event can be extended with additional properties. Although Python objects are already extensible with new attributes, new attributes that are not set in __init__ confuse type checkers and other tools, so every Event has an info attribute as a dictionary where additional, application-specific information can be stored. The info attribute is None to save space until the first property is set, so you should use set and get methods and avoid writing event.info[property].

Parameters:

property (str) –

The name of the property to set.
value (Any) –

The value to assign to the property.

Returns:

Event –

returns this object (self)

Examples:

>>> note = Note()
>>> note.get("color", "no color")
'no color'
>>> _ = note.set("color", "red").set("harmonicity", 0.2)
>>> (note.has("color"), note.has("shape"))
(True, False)
>>> (note.get("color"), note.get("harmonicity"))
('red', 0.2)

Source code in amads/core/basics.py

def set(self, property : str, value : Any) -> "Event":
    """Set a named property on this Event.

    Every event can be extended with additional properties. Although
    Python objects are already extensible with new attributes, new
    attributes that are not set in `__init__` confuse type checkers
    and other tools, so every `Event` has an `info` attribute as a
    dictionary where additional, application-specific information can
    be stored. The `info` attribute is `None` to save space until the
    first property is set, so you should use `set` and `get` methods
    and avoid writing `event.info[property]`.

    Parameters
    ----------
    property : str
        The name of the property to set.
    value : Any
        The value to assign to the property.

    Returns
    -------
    Event
        returns this object (self)

    Examples
    --------
    >>> note = Note()
    >>> note.get("color", "no color")
    'no color'
    >>> _ = note.set("color", "red").set("harmonicity", 0.2)
    >>> (note.has("color"), note.has("shape"))
    (True, False)
    >>> (note.get("color"), note.get("harmonicity"))
    ('red', 0.2)
    """
    if self.info is None:
        self.info = {}
    self.info[property] = value
    return self

get ¶

get(property: str, default: Any = None) -> Any

Get the value of a property from this Event.

See set for more details.

Parameters:

property (str.) –

The name of the property to get.
default (Any, default: None ) –

The default value to return if the property is not found.

Returns:

Any –

The value of the specified property.

Source code in amads/core/basics.py

def get(self, property : str, default : Any = None) -> Any:
    """Get the value of a property from this Event.

    See [set][amads.core.basics.Event.set] for more details.

    Parameters
    ----------
    property : str.
        The name of the property to get.
    default : Any
        The default value to return if the property is not found.

    Returns
    -------
    Any
        The value of the specified property.
    """
    if self.info is None:
        return default
    return self.info.get(property, default)

has ¶

has(property) -> bool

Check if the Event has a specific property.

See set for more details.

Parameters:

property (str) –

The name of the property to check.

Returns:

bool –

True if the property exists, False otherwise.

Source code in amads/core/basics.py

def has(self, property) -> bool:
    """Check if the Event has a specific property.

    See [set][amads.core.basics.Event.set] for more details.

    Parameters
    ----------
    property : str
        The name of the property to check.

    Returns
    -------
    bool
        True if the property exists, False otherwise.
    """
    return (self.info is not None) and (property in self.info)

time_shift ¶

time_shift(increment: float, content_only: bool = False) -> EventGroup

Change the onset by an increment, affecting all content.

If content_only is true, preserves EventGroup times (Score, Part, Staff, but not Chord or Measure) and shifts only the content (recursively). Otherwise, shifts this container and all content by the increment. Container onsets (recursively) are not allowed to become negative, so the onset time is set to zero if the increment would make it negative. However, even if the onset is is not shifted by increment, time_shift is still applied recursively to the content, and non-EventGroup events (e.g., Notes) are allowed to have negative onsets, even if this may not be well-defined for all AMADS operations.

Parameters:

increment (float) –

The time increment (in quarters or seconds).
content_only (bool, default: False ) –

If true, preserves this container's time and shifts only the content.

Returns:

Event –

The object. This method modifies the EventGroup.

Raises:

ValueError –

If the EventGroup has an unknown (None) onset and content_only is false.

Source code in amads/core/basics.py

def time_shift(self, increment: float,
               content_only: bool = False) -> "EventGroup":
    """
    Change the onset by an increment, affecting all content.

    If content_only is true, preserves EventGroup times (Score, Part,
    Staff, but *not* Chord or Measure) and shifts only the content
    (recursively). Otherwise, shifts this container and all content by the
    increment. Container onsets (recursively) are not allowed to become
    negative, so the onset time is set to zero if the increment would
    make it negative. However, even if the onset is is not shifted by
    increment, time_shift is still applied recursively to the content,
    and non-EventGroup events (e.g., Notes) are allowed to have negative
    onsets, even if this may not be well-defined for all AMADS operations.

    Parameters
    ----------
    increment : float
        The time increment (in quarters or seconds).
    content_only: bool
        If true, preserves this container's time and shifts only
        the content.

    Returns
    -------
    Event
        The object. This method modifies the `EventGroup`.

    Raises
    ------
    ValueError
        If the EventGroup has an unknown (None) onset and
        content_only is false.
    """
    # note that Chord and Measures are special cases
    if not content_only or isinstance(self, (Chord, Measure)):
        if self._onset is None:
            raise ValueError(
                    "Cannot shift time of EventGroup with unknown onset")
        self._onset = max(0.0, self._onset + increment)
    for elem in self.content:
        elem.time_shift(increment, content_only)
    return self

insert_copy_into ¶

insert_copy_into(parent: Optional[EventGroup] = None) -> Event

Make a (mostly) deep copy of the Event and add to a new parent.

Pitch objects are considered immutable and are shared rather than copied.

Parameters:

parent (Optional(EventGroup), default: None ) –

The copied Event will be a child of parent if not None. The parent is modified by this operation.

Returns:

Event –

A deep copy (except for parent and pitch) of the Event instance.

Source code in amads/core/basics.py

def insert_copy_into(self,
                     parent: Optional["EventGroup"] = None) -> "Event":
    """
    Make a (mostly) deep copy of the `Event` and add to a new `parent`.

    `Pitch` objects are considered immutable and are shared rather
    than copied.

    Parameters
    ----------
    parent : Optional(EventGroup)
        The copied `Event` will be a child of `parent` if not `None`.
        The parent is modified by this operation.

    Returns
    -------
    Event
        A deep copy (except for parent and pitch) of the Event instance.
    """
    # remove link to parent to break link going up the tree
    # preventing deep copy from copying the entire tree
    original_parent = self.parent
    self.parent = None
    c = copy.deepcopy(self)  # deep copy of this event down to leaf nodes
    self.parent = original_parent  # restore link to parent
    if parent:
        parent.insert(c)
    return c

ismonophonic ¶

ismonophonic() -> bool

Determine if content is monophonic (non-overlapping notes).

A monophonic list of notes has no overlapping notes (e.g., chords). Serves as a helper function for ismonophonic and parts_are_monophonic.

Returns:

bool –

True if the list of notes is monophonic, False otherwise.

Source code in amads/core/basics.py

def ismonophonic(self) -> bool:
    """
    Determine if content is monophonic (non-overlapping notes).

    A monophonic list of notes has no overlapping notes (e.g., chords).
    Serves as a helper function for `ismonophonic` and
    `parts_are_monophonic`.

    Returns
    -------
    bool
        True if the list of notes is monophonic, False otherwise.
    """
    prev = None
    notes = self.list_all(Note)
    # Sort the notes by start time
    notes.sort(key=lambda note: note.onset)
    # Check for overlaps
    for note in notes:
        if prev:
            # 0.01 is to prevent precision errors when comparing floats
            if note.onset - prev.offset < -0.01:
                return False
        prev = note
    return True

insert_emptycopy_into ¶

insert_emptycopy_into(
    parent: Optional[EventGroup] = None,
) -> EventGroup

Create a deep copy of the EventGroup except for content.

A new parent is provided as an argument and the copy is inserted into this parent. This method is useful for copying an EventGroup without copying its content. See also insert_copy_into to copy an EventGroup with its content into a new parent.

Parameters:

parent (Optional[EventGroup], default: None ) –

The new parent to insert the copied Event into.

Returns:

EventGroup –

A deep copy of the EventGroup instance with the new parent (if any) and no content.

Source code in amads/core/basics.py

def insert_emptycopy_into(self, 
            parent: Optional["EventGroup"] = None) -> "EventGroup":
    """Create a deep copy of the EventGroup except for content.

    A new parent is provided as an argument and the copy is inserted
    into this parent. This method is  useful for copying an
    EventGroup without copying its content.  See also
    [insert_copy_into][amads.core.basics.Event.insert_copy_into] to
    copy an EventGroup *with* its content into a new parent.

    Parameters
    ----------
    parent : Optional[EventGroup]
        The new parent to insert the copied Event into.

    Returns
    -------
    EventGroup
        A deep copy of the EventGroup instance with the new parent
        (if any) and no content.
    """
    # rather than customize __deepcopy__, we "hide" the content to avoid
    # copying it. Then we restore it after copying and fix parent.
    original_content = self.content
    self.content = []
    c = self.insert_copy_into(parent)
    self.content = original_content
    return c  #type: ignore (c will always be an EventGroup)

expand_chords ¶

expand_chords(parent: Optional[EventGroup] = None) -> EventGroup

Replace chords with the multiple notes they contain.

Returns a deep copy with no parent unless parent is provided. Normally, you will call score.expand_chords() which returns a deep copy of Score with notes moved from each chord to the copy of the chord's parent (a Measure or a Part). The parent parameter is primarily for internal use when expand_chords is called recursively on score content.

Parameters:

parent (EventGroup, default: None ) –

The new parent to insert the copied EventGroup into.

Returns:

EventGroup –

A deep copy of the EventGroup instance with all Chord instances expanded.

Source code in amads/core/basics.py

def expand_chords(self,
                  parent: Optional["EventGroup"] = None) -> "EventGroup":
    """Replace chords with the multiple notes they contain.

    Returns a deep copy with no parent unless parent is provided.
    Normally, you will call `score.expand_chords()` which returns a deep
    copy of Score with notes moved from each chord to the copy of the
    chord's parent (a Measure or a Part). The parent parameter is 
    primarily for internal use when `expand_chords` is called recursively
    on score content.

    Parameters
    ----------
    parent : EventGroup
        The new parent to insert the copied EventGroup into.

    Returns
    -------
    EventGroup
        A deep copy of the EventGroup instance with all
        Chord instances expanded.
    """
    group = self.insert_emptycopy_into(parent)
    for item in self.content:
        if isinstance(item, Chord):
            for note in item.content:  # expand chord
                note.insert_copy_into(group)
        if isinstance(item, EventGroup):
            item.expand_chords(group)  # recursion for deep copy/expand
        else:
            item.insert_copy_into(group)  # deep copy non-EventGroup
    return group

find_all ¶

find_all(elem_type: Type[Event]) -> Generator[Event, None, None]

Find all instances of a specific type within the EventGroup.

Assumes that objects of type elem_type are not nested within other objects of the same type. (The first elem_type encountered in a depth-first enumeration is returned without looking at any children in its content).

Parameters:

elem_type (Type[Event]) –

The type of event to search for.

Yields:

Event –

Instances of the specified type found within the EventGroup.

Source code in amads/core/basics.py

def find_all(self, elem_type: Type[Event]) -> Generator[Event, None, None]:
    """Find all instances of a specific type within the EventGroup.

    Assumes that objects of type `elem_type` are not nested within
    other objects of the same type. (The first `elem_type` encountered
    in a depth-first enumeration is returned without looking at any
    children in its `content`).

    Parameters
    ----------
    elem_type : Type[Event]
        The type of event to search for.

    Yields
    -------
    Event
        Instances of the specified type found within the EventGroup.
    """
    # Algorithm: depth-first enumeration of EventGroup content.
    # If elem_types are nested, only the top-level elem_type is
    # returned since it is found first, and the content is not
    # searched. This makes it efficient, e.g., to search for
    # Parts in a Score without enumerating all Notes within.
    for elem in self.content:
        if isinstance(elem, elem_type):
            yield elem
        elif isinstance(elem, EventGroup):
            yield from elem.find_all(elem_type)

get_sorted_notes ¶

get_sorted_notes(has_ties: bool = True) -> List[Note]

Return a list of sorted notes with merged ties.

This should generally be called on Parts and Scores since in all other EventGroups, Events are in time order and Notes retrieved with find_all() or list_all() are in time order. However, get_sorted_notes also sorts notes into increasing pitch (keynum) where note onsets are equal.

Parameters:

has_ties (bool, default: True ) –

If True (default), copy the score, merge the ties, and return a list of these merged copies. If False, assume there are no ties and return a list of original notes.

Raises:

ValueError –

If has_ties is False, but a tie is encountered.

Returns:

list(Note) –

a list of sorted notes with merged ties

Source code in amads/core/basics.py

def get_sorted_notes(self, has_ties: bool = True) -> List[Note]:
    """Return a list of sorted notes with merged ties.

    This should generally be called on Parts and Scores since
    in all other EventGroups, Events are in time order and
    Notes retrieved with `find_all()` or `list_all()` are in
    time order. However, `get_sorted_notes` *also* sorts notes
    into increasing pitch (`keynum`) where note onsets are equal.

    Parameters
    ----------
    has_ties: bool
        If True (default), copy the score, merge the ties, and
        return a list of these merged copies. If False, assume
        there are no ties and return a list of original notes.

    Raises
    ------
    ValueError
        If has_ties is False, but a tie is encountered.

    Returns
    -------
    list(Note)
        a list of sorted notes with merged ties
    """
    if has_ties:
        # after flatten, score will have one Part with all Notes:
        return self.flatten(collapse=True).content[0].content  # type: ignore
    else:
        notes : List[Note] = cast(List[Note], self.list_all(Note))
        for note in notes:
            if note.tie is not None:
                raise ValueError(
                        "tie found by get_sorted_notes with has_ties=False")
        notes.sort(key=lambda x: (x.onset, x.pitch))
        return notes

has_instanceof ¶

has_instanceof(the_class: Type[Event]) -> bool

Test if EventGroup contains any instances of the_class.

Parameters:

the_class (Type[Event]) –

The class type to check for.

Returns:

bool –

True iff the EventGroup contains an instance of the_class.

Source code in amads/core/basics.py

def has_instanceof(self, the_class: Type[Event]) -> bool:
    """Test if EventGroup contains any instances of `the_class`.

    Parameters
    ----------
    the_class : Type[Event]
        The class type to check for.

    Returns
    -------
    bool
        True iff the EventGroup contains an instance of the_class.
    """
    instances = self.find_all(the_class)
    # if there are no instances (of the_class), next will return "empty":
    return next(instances, "empty") != "empty"

has_rests ¶

has_rests() -> bool

Test if EventGroup (e.g., Score, Part, ...) has any Rest objects.

Returns:

bool –

True iff the EventGroup contains any Rest objects.

Source code in amads/core/basics.py

def has_rests(self) -> bool:
    """Test if EventGroup (e.g., Score, Part, ...) has any `Rest` objects.

    Returns
    -------
    bool
        True iff the EventGroup contains any Rest objects.
    """
    return self.has_instanceof(Rest)

has_chords ¶

has_chords() -> bool

Test if EventGroup (e.g., Score, Part, ...) has any Chord objects.

Returns:

bool –

True iff the EventGroup contains any Chord objects.

Source code in amads/core/basics.py

def has_chords(self) -> bool:
    """Test if EventGroup (e.g., Score, Part, ...) has any Chord objects.

    Returns
    -------
    bool
        True iff the EventGroup contains any Chord objects.
    """
    return self.has_instanceof(Chord)

has_ties ¶

has_ties() -> bool

Test if EventGroup (e.g., Score, Part, ...) has any tied notes.

Returns:

bool –

True iff the EventGroup contains any tied notes.

Source code in amads/core/basics.py

def has_ties(self) -> bool:
    """Test if EventGroup (e.g., Score, Part, ...) has any tied notes.

    Returns
    -------
    bool
        True iff the EventGroup contains any tied notes.
    """
    notes = self.find_all(Note)
    for note in notes:
        if note.tie:
            return True
    return False

has_measures ¶

has_measures() -> bool

Test if EventGroup (e.g., Score, Part, ...) has any Measures.

Returns:

bool –

True iff the EventGroup contains any Measure objects.

Source code in amads/core/basics.py

def has_measures(self) -> bool:
    """Test if EventGroup (e.g., Score, Part, ...) has any Measures.

    Returns
    -------
    bool
        True iff the EventGroup contains any Measure objects.
    """
    return self.has_instanceof(Measure)

inherit_duration ¶

inherit_duration() -> EventGroup

Set the duration of this EventGroup according to maximum offset.

The duration is set to the maximum offset (end) time of the children. If the EventGroup is empty, the duration is set to 0. This method modifies this EventGroup instance.

Returns:

EventGroup –

The EventGroup instance (self) with updated duration.

Source code in amads/core/basics.py

def inherit_duration(self) -> "EventGroup":
    """Set the duration of this EventGroup according to maximum offset.

    The `duration` is set to the maximum offset (end) time of the
    children. If the EventGroup is empty, the duration is set to 0.
    This method modifies this `EventGroup` instance.

    Returns
    -------
    EventGroup
        The EventGroup instance (self) with updated duration.
    """
    onset = 0 if self._onset == None else self._onset
    max_offset = onset
    for elem in self.content:
        max_offset = max(max_offset, elem.offset)
    self.duration = max_offset - onset

    return self

insert ¶

insert(event: Event) -> EventGroup

Insert an event.

Sets the parent of event to this EventGroup and makes event be a member of this EventGroup.content. No changes are made to event.onset or self.duration. Insert event in content just before the first element with a greater onset. The method modifies this object (self).

Parameters:

event (Event) –

The event to be inserted.

Returns:

EventGroup –

The EventGroup instance (self) with the event inserted.

Raises:

ValueError –

If event._onset is None (it must be a number)

Caution Regarding Zero-Duration Event Order

If you have note N with non-zero duration and, at the same time, a grace note G with zero duration, the notes will be ordered according to when they are inserted. So if you insert N and then G, then N will be placed before G. See io.pt_import.py, where this case is dealt with.

Source code in amads/core/basics.py

def insert(self, event: Event) -> "EventGroup":
    """Insert an event.

    Sets the `parent` of `event` to this `EventGroup` and makes `event`
    be a member of this `EventGroup.content`. No changes are made to
    `event.onset` or `self.duration`. Insert `event` in `content` just
    before the first element with a greater onset. The method modifies
    this object (self).

    Parameters
    ----------
    event : Event
        The event to be inserted.

    Returns
    -------
    EventGroup
        The EventGroup instance (self) with the event inserted.

    Raises
    ------
    ValueError
        If event._onset is None (it must be a number)

    Caution Regarding Zero-Duration Event Order
    -------------------------------------------
    If you have note N with non-zero duration and, at the same
    time, a grace note G with zero duration, the notes will be
    ordered according to when they are inserted. So if you insert
    N and then G, then N will be placed *before* G. See
    io.pt_import.py, where this case is dealt with.
    """

    assert not event.parent
    if event._onset is None:  # must be a number
        raise ValueError(f"event's _onset attribute must be a number")
    atend = self.last()
    if atend and event.onset < atend.onset:
        # search in reverse from end
        i = len(self.content) - 2
        while i >= 0 and self.content[i].onset > event.onset:
            i -= 1
        # now i is either -1 or content[i] <= event.onset, so
        # insert event at content[i+1]
        self.content.insert(i + 1, event)
    else:  # simply append at the end of content:
        self.content.append(event)
    event.parent = self
    return self

last ¶

last() -> Optional[Event]

Retrieve the last event in the content list.

Because the content list is sorted by onset, the returned Event is simply the last element of content, but not necessarily the event with the greatest offset.

Returns:

Optional[Event] –

The last event in the content list or None if the list is empty.

Source code in amads/core/basics.py

def last(self) -> Optional[Event]:
    """Retrieve the last event in the content list.

    Because the `content` list is sorted by `onset`, the returned
    `Event` is simply the last element of `content`, but not
    necessarily the event with the greatest *`offset`*.

    Returns
    -------
    Optional[Event]
        The last event in the content list or None if the list is empty.
    """
    return self.content[-1] if len(self.content) > 0 else None

list_all ¶

list_all(elem_type: Type[Event]) -> list[Event]

Find all instances of a specific type within the EventGroup.

Assumes that objects of type elem_type are not nested within other objects of the same type. See also find_all, which returns a generator instead of a list.

Parameters:

elem_type (Type[Event]) –

The type of event to search for.

Returns:

list[Event] –

A list of all instances of the specified type found within the EventGroup.

Source code in amads/core/basics.py

def list_all(self, elem_type: Type[Event]) -> list[Event]:
    """Find all instances of a specific type within the EventGroup.

    Assumes that objects of type `elem_type` are not nested within
    other objects of the same type.  See also
    [find_all][amads.core.basics.EventGroup.find_all], which returns
    a generator instead of a list.

    Parameters
    ----------
    elem_type : Type[Event]
        The type of event to search for.

    Returns
    -------
    list[Event]
        A list of all instances of the specified type found
        within the EventGroup.
    """
    return list(self.find_all(elem_type))

merge_tied_notes ¶

merge_tied_notes(
    parent: Optional[EventGroup] = None, ignore: list[Note] = []
) -> EventGroup

Create a new EventGroup with tied notes replaced by single notes.

If ties cross staffs, the replacement is placed in the staff of the first note in the tied sequence. Insert the new EventGroup into parent.

Ordinarily, this method is called on a Score with no parameters. The parameters are used when Score.merge_tied_notes() calls this method recursively on EventGroups within the Score such as Parts and Staffs.

Parameters:

parent (Optional[EventGroup], default: None ) –

Where to insert the result.
ignore (list[Note], default: [] ) –

This parameter is used internally. Caller should not use this parameter.

Returns:

EventGroup –

A copy with tied notes replaced by equivalent single notes.

Source code in amads/core/basics.py

def merge_tied_notes(self, parent: Optional["EventGroup"] = None,
                     ignore: list[Note] = []) -> "EventGroup":
    """Create a new `EventGroup` with tied notes replaced by single notes.

    If ties cross staffs, the replacement is placed in the staff of the
    first note in the tied sequence. Insert the new `EventGroup` into
    `parent`.

    Ordinarily, this method is called on a Score with no parameters. The
    parameters are used when `Score.merge_tied_notes()` calls this method
    recursively on `EventGroup`s within the Score such as `Part`s and
    `Staff`s.

    Parameters
    ----------
    parent: Optional(EventGroup)
        Where to insert the result.

    ignore: Optional(list[Note])
        This parameter is used internally. Caller should not use
        this parameter.

    Returns
    -------
    EventGroup
        A copy with tied notes replaced by equivalent single notes.
    """
    # Algorithm: Find all notes, removing tied notes and updating
    # duration when ties are found. These tied notes are added to
    # ignore so they can be skipped when they are encountered.

    group = self.insert_emptycopy_into(parent)
    for event in self.content:
        if isinstance(event, Note):
            if event in ignore:  # do not copy tied notes into group;
                if event.tie:
                    ignore.append(event.tie)  # add tied note to ignore
                # We will not see this note again, so
                # we can also remove it from ignore. Removal is expensive
                # but it could be worse for ignore to grow large when there
                # are many ties since we have to search it entirely once
                # per note. An alternate representation might be a set to
                # make searching fast.
                ignore.remove(event)
            else:
                if event.tie:
                    tied_note = event.tie  # save the tied-to note
                    event.tie = None  # block the copy
                    ignore.append(tied_note)
                    # copy note into group:
                    event_copy = event.insert_copy_into(group)
                    event.tie = tied_note  # restore original event
                    # this is subtle: event.tied_duration (a property) will
                    # sum up durations of all the tied notes. Since
                    # event_copy is not tied, the sum of durations is
                    # stored on that one event_copy:
                    event_copy.duration = event.tied_duration
                else:  # put the untied note into group
                    event.insert_copy_into(group)
        elif isinstance(event, EventGroup):
            event.merge_tied_notes(group, ignore)
        else:
            event.insert_copy_into(group)  # simply copy to new parent
    return group

pack ¶

pack(onset: float = 0.0, sequential: bool = True) -> float

Adjust the content to be sequential.

The resulting content will begin with the parameter onset (defaults to 0), and each other object will get an onset equal to the offset of the previous element. The duration of self is set to the offset of the last element. This method essentially arranges the content to eliminate gaps. pack() works recursively on elements that are EventGroups.

Be careful not to pack Measures (directly or through recursion) if the Measure's content durations do not add up to the intended quarters per measure.

To override the sequential behavior, set the sequential parameter to False. In that case, pack behaves like the Concurrence.pack() method.

The pack method alters self and its content in place.

Parameters:

onset (float, default: 0.0 ) –

The onset (start) time for this object.

Returns:

float –

duration of self

Source code in amads/core/basics.py

def pack(self, onset: float = 0.0, sequential: bool = True) -> float:
    """Adjust the content to be sequential.

    The resulting content will begin with the parameter `onset`
    (defaults to 0), and each other object will get an onset equal
    to the offset of the previous element. The duration of self is
    set to the offset of the last element.  This method essentially
    arranges the content to eliminate gaps. pack() works recursively
    on elements that are `EventGroups`.

    Be careful not to pack `Measures` (directly or through
    recursion) if the Measure's content durations do not add up to
    the intended quarters per measure.

    To override the sequential behavior, set the `sequential` 
    parameter to False.  In that case, pack behaves like the
    `Concurrence.pack()` method.

    The pack method alters self and its content in place.

    Parameters
    ----------
    onset : float
        The onset (start) time for this object.

    Returns
    -------
    float
        duration of self
    """
    return super().pack(onset, sequential)

quantize ¶

quantize(divisions: int) -> EventGroup

Align onsets and durations to a rhythmic grid.

Assumes time units are quarters. (See Score.convert_to_quarters.)

Modify all times and durations to a multiple of divisions per quarter note, e.g., 4 for sixteenth notes. Onsets and offsets are moved to the nearest quantized time. Any resulting duration change is less than one quantum, but not necessarily less than 0.5 quantum, since the onset and offset can round in opposite directions by up to 0.5 quantum each. Any non-zero duration that would quantize to zero duration gets a duration of one quantum since zero duration is almost certainly going to cause notation and visualization problems.

Special cases for zero duration:

If the original duration is zero as in metadata or possibly grace notes, we preserve that.
If a tied note duration quantizes to zero, we remove the tied note entirely provided some other note in the tied sequence has non-zero duration. If all tied notes quantize to zero, we keep the first one and set its duration to one quantum.

This method modifies this EventGroup and all its content in place.

Note that there is no way to specify "sixteenths or eighth triplets" because 6 would not allow sixteenths and 12 would admit sixteenth triplets. Using tuples as in Music21, e.g., (4, 3) for this problem creates another problem: if quantization is to time points 1/4, 1/3, then the difference is 1/12 or a thirty-second triplet. If the quantization is applied to durations, then you could have 1/4 + 1/3 = 7/12, and the remaining duration in a single beat would be 5/12, which is not expressible as sixteenths, eighth triplets or any tied combination.

Parameters:

divisions (int) –

The number of divisions per quarter note, e.g., 4 for sixteenths, to control quantization.

Returns:

EventGroup –

The EventGroup instance (self) with (modified in place) quantized times.

Source code in amads/core/basics.py

def quantize(self, divisions: int) -> "EventGroup":
    """Align onsets and durations to a rhythmic grid.

    Assumes time units are quarters. (See [Score.convert_to_quarters](
            basics.md#amads.core.basics.Score.convert_to_quarters).)

    Modify all times and durations to a multiple of divisions
    per quarter note, e.g., 4 for sixteenth notes. Onsets and offsets
    are moved to the nearest quantized time. Any resulting duration
    change is less than one quantum, but not necessarily less than
    0.5 quantum, since the onset and offset can round in opposite
    directions by up to 0.5 quantum each. Any non-zero duration that would
    quantize to zero duration gets a duration of one quantum since
    zero duration is almost certainly going to cause notation and
    visualization problems.

    Special cases for zero duration:

    1. If the original duration is zero as in metadata or possibly
           grace notes, we preserve that.
    2. If a tied note duration quantizes to zero, we remove the
           tied note entirely provided some other note in the tied
           sequence has non-zero duration. If all tied notes quantize
           to zero, we keep the first one and set its duration to
           one quantum.

    This method modifies this EventGroup and all its content in place.

    Note that there is no way to specify "sixteenths or eighth triplets"
    because 6 would not allow sixteenths and 12 would admit sixteenth
    triplets. Using tuples as in Music21, e.g., (4, 3) for this problem
    creates another problem: if quantization is to time points 1/4, 1/3,
    then the difference is 1/12 or a thirty-second triplet. If the
    quantization is applied to durations, then you could have 1/4 + 1/3
    = 7/12, and the remaining duration in a single beat would be 5/12,
    which is not expressible as sixteenths, eighth triplets or any tied
    combination.

    Parameters
    ----------
    divisions : int
        The number of divisions per quarter note, e.g., 4 for
        sixteenths, to control quantization.

    Returns
    -------
    EventGroup
        The EventGroup instance (self) with (modified in place) 
        quantized times.
    """

    super()._quantize(divisions)
    # iterating through content is tricky because we may delete a
    # Note, shifting the content:
    i = 0
    while i < len(self.content):
        event = self.content[i]
        event._quantize(divisions)
        if event == self.content[i]:
            i += 1
        # otherwise, we deleted event so the next event to
        # quantize is at index i; don't incremenet i
    return self

remove ¶

remove(element: Event) -> EventGroup

Remove an element from the content list.

The method modifies this object (self).

Parameters:

element (Event) –

The event to be removed.

Returns:

EventGroup –

The EventGroup instance (self) with the element removed. The returned value is not a copy.

Source code in amads/core/basics.py

def remove(self, element: Event) -> "EventGroup":
    """Remove an element from the content list. 

    The method modifies this object (self).

    Parameters
    ----------
    element : Event
        The event to be removed.

    Returns
    -------
    EventGroup
        The EventGroup instance (self) with the element removed.
        The returned value is not a copy.
    """
    self.content.remove(element)
    element.parent = None
    return self

remove_rests ¶

remove_rests(parent: Union[EventGroup, None] = None) -> EventGroup

Remove all Rest objects from content.

Returns a deep copy with no parent unless parent is provided.

Parameters:

parent (EventGroup, default: None ) –

The new parent to insert the copied Event into.

Returns:

EventGroup –

A deep copy of the EventGroup instance with all Rest objects removed.

Source code in amads/core/basics.py

def remove_rests(self, parent: Union["EventGroup", 
                                     None] = None) -> "EventGroup":
    """Remove all Rest objects from content.

    Returns a deep copy with no parent unless parent is provided.

    Parameters
    ----------
    parent : EventGroup
        The new parent to insert the copied Event into.

    Returns
    -------
    EventGroup
        A deep copy of the EventGroup instance with all Rest
        objects removed.
    """
    # implementation detail: when called without argument, remove_rests
    # makes a deep copy of the subtree and returns the copy without a
    # parent. remove_rests calls itself recursively *with* a parameter
    # indicating that the subtree copy should be inserted into a
    # parent which is the new copy at the next level up. Of course,
    # we check for and ignore Rests so they are never copied.
    group = self.insert_emptycopy_into(parent)
    for item in self.content:
        if isinstance(item, Rest):
            continue  # skip the Rests while making deep copy
        if isinstance(item, EventGroup):
            item.remove_rests(group)  # recursion for deep copy
        else:
            item.insert_copy_into(group)  # deep copy non-EventGroup
    return group

show ¶

show(indent: int = 0, file: Optional[TextIO] = None) -> EventGroup

Print the EventGroup information.

Parameters:

indent (int, default: 0 ) –

The indentation level for display.

Returns:

EventGroup –

The EventGroup instance itself.

Source code in amads/core/basics.py

def show(self, indent: int = 0,
        file: Optional[TextIO] = None) -> "EventGroup":
    """Print the EventGroup information.

    Parameters
    ----------
    indent : int
        The indentation level for display.

    Returns
    -------
    EventGroup
        The EventGroup instance itself.
    """
    print(" " * indent, self, sep="", file=file)
    for elem in self.content:
        elem.show(indent + 4, file=file)  # type: ignore (show exists)
    return self

measure_times ¶

measure_times(n: int) -> tuple[float, float]

Return the start and end times of measure n.

Parameters:

n (int) –

The 0-based measure number.

Returns:

tuple(float, float) –

A tuple containing the start and end times of measure n. Measure 0 is the first measure. Units are the same as the score's time units.

Raises:

ValueError –

If there is no measure with number n.

Source code in amads/core/basics.py

def measure_times(self, n: int) -> tuple[float, float]:
    """Return the start and end times of measure n.

    Parameters
    ----------
    n : int
        The 0-based measure number.

    Returns
    -------
    tuple(float, float)
        A tuple containing the start and end times of measure n.
        Measure 0 is the first measure.  Units are the same as the
        score's time units.

    Raises
    ------
    ValueError
        If there is no measure with number n.
    """
    # Algorithm: For each Staff, linear search for nth Measure, returning
    # the onset and offset of the first one found.
    for staff in self.find_all(Staff):
        staff = cast(Staff, staff)
        for i, measure in enumerate(staff.find_all(Measure)):
            if i == n:
                return (measure.onset, measure.offset)
    raise ValueError(f"measure {n} not found")

slice ¶

slice(
    start: float,
    end: float,
    units: str = "quarters",
    mode: str = "onsets",
    truncate: str = "keep",
    shift: bool = False,
    min_duration: float = 0.05,
) -> EventGroup

Create a new Score containing the content between start and end.

Typically, this method is called on a Score to create a new Score, but it works on any Sequence as long as the sequence is part of a Score.

If self has Measures, units must be "measures" or "bars", the start and end parameters are interpreted as 0-based measure numbers, and the result will therefore contain whole measures. It is assumed that notes are tied across measure boundaries. The result will contain only the parts of tied notes that are within the specified measures, excluding measure numbered by end.

For any units besides "measures" or "bars", the score must be flat. Notes that extend beyond the start or end time are included in the result unless the truncate parameter specifies otherwise.

In principle, there is no reason to require a flat score for slicing by time, but there are many difficult edge cases to consider such as ties from within one chord to a note in another measure. Therefore, to slice by time or quarter, you must have a flattened score. Conversely, to slice a full score, you must slice by measure so that the result gives you whole measures, which are encoded into the full Score structure.

The entire result can be shifted to start at time 0 by setting the shift parameter to True. Unless truncate is "truncate" or "beginning", the result can include events that start before the start time, in which case shifting will only shift the earliest onset to 0, which means the shift amount depends upon the content. (Negative onsets are currently not allowed.)

The resulting Score, Part, and other content will have onset and offset times matching start and end, even if some content starts earlier or ends later.

Parameters:

start (float) –

The start time of the slice, inclusive. If units is "measures" or "bars", start is a 0-based measure number of the first measure.
end (float) –

The end time of the slice, exclusive. For measures, end is the 0-based measure number of the last measure plus one, so the last measure is end - 1.
units (str, default: 'quarters' ) –

The time units for start and end. Valid values are "quarters", "s", "sec", "seconds", "measures", or "bars".
shift (bool, default: False ) –

If true, shift the content in the result so that the result starts time 0.0. If false (default), the content in the result retains the same time values as in the original Score.
mode (Optional[str], default: 'onsets' ) –
The slicing mode, ignored if units is "measures" or "bars". Valid values are:
- "onsets" - include events that start within bounds (default)
- "overlaps" - include events that overlap (either onset or offset) is within the bounds. An event ending is considered to overlap if its offset is greater than start.
- "offsets" - include events that end within the bounds
- "strict" - include only events that start at or after start and end at or before end. (End times that are exactly equal to end are considered to be within bounds, so this is inclusive of end time.)
truncate (str, default: 'keep' ) –
How to handle events that partially overlap the bounds, ignored if units is "measures" or "bars". Valid values are:
- "truncate" - truncate (clip) events that partially overlap the bounds. If the event onset is before start, the onset is increased to start (adjusting duration to maintain the offset time). Also, if the event offset is after end, the duration is decreased so that the offset time is end.
- "keep" - no modification/truncation (default). Note that with the default mode="onsets", no event onsets will be earlier than start, but offsets may extend beyond end.
- "end" or "ending" or "dur" or "duration" - truncate (clip) events that extend beyond end so that all offsets <= end.
- "beginning" - events with onsets before start are moved to make their onsets equal to start, and their duration is adjusted to maintain the original offset.
min_duration (float, default: 0.05 ) –

Events with duration less than min_duration (after any truncation is applied) are removed. Ignored if units is "measures" or "bars". If None or 0.0, no events are removed. The default is 0.05, independent of time units. Be careful with gracenotes that, when read from MusicXML, have zero duration.

Returns:

Score –

A new Score instance containing the content between start and end.

Raises:

ValueError –

If the Sequence is not part of a Score, or if invalid values are provided for the parameters.

Source code in amads/core/basics.py

def slice(self, start: float, end: float, units: str = "quarters",
          mode: str = "onsets", truncate: str = "keep", shift: bool = False,
          min_duration: float = 0.05) -> "EventGroup":
    """
    Create a new Score containing the content between start and end.

    Typically, this method is called on a Score to create a new Score,
    but it works on any Sequence as long as the sequence is part of a Score.

    If self has Measures, units must be "measures" or "bars", the start and
    end parameters are interpreted as 0-based measure numbers, and the
    result will therefore contain whole measures. It is assumed that notes
    are tied across measure boundaries. The result will contain only the
    parts of tied notes that are within the specified measures, excluding
    measure numbered by `end`.

    For any units besides "measures" or "bars", the score must be flat.
    Notes that extend beyond the start or end time are included in the
    result unless the `truncate` parameter specifies otherwise.

    In principle, there is no reason to require a flat score for slicing by
    time, but there are many difficult edge cases to consider such as ties
    from within one chord to a note in another measure. Therefore, to slice
    by time or quarter, you must have a flattened score. Conversely, to
    slice a full score, you must slice by measure so that the result gives
    you whole measures, which are encoded into the full Score structure.

    The entire result can be shifted to start at time 0 by setting the
    `shift` parameter to True.  Unless `truncate` is "truncate" or
    "beginning", the result can include events that start before the start
    time, in which case shifting will only shift the earliest onset to 0,
    which means the shift amount depends upon the content. (Negative onsets
    are currently not allowed.)

    The resulting Score, Part, and other content will have onset and offset
    times matching start and end, even if some content starts earlier or
    ends later.

    Parameters
    ----------
    start : float
        The start time of the slice, inclusive. If units is "measures" or
        "bars", start is a 0-based measure number of the first measure.
    end : float
        The end time of the slice, exclusive. For measures, end is the
        0-based measure number of the last measure plus one, so the last
        measure is end - 1.
    units : str
        The time units for start and end. Valid values are "quarters", "s",
        "sec", "seconds", "measures", or "bars".
    shift: bool
        If true, shift the content in the result so that the result starts
        time 0.0. If false (default), the content in the result retains
        the same time values as in the original Score.
    mode : Optional[str]
        The slicing mode, ignored if units is "measures" or "bars".
        Valid values are:

        - `"onsets"` - include events that start within bounds (default)
        - `"overlaps"` - include events that overlap (either onset or
            offset) is within the bounds. An event ending is considered
            to overlap if its offset is greater than start.
        - `"offsets"` - include events that end within the bounds
        - `"strict"` - include only events that start at or after start
            and end at or before end. (End times that are exactly equal
            to end are considered to be within bounds, so this is
            inclusive of end time.)

    truncate: Optional[str]
        How to handle events that partially overlap the bounds,
        ignored if units is "measures" or "bars". Valid values are:

        - `"truncate"` - truncate (clip) events that partially overlap
            the bounds. If the event onset is before start, the onset
            is increased to start (adjusting duration to maintain the
            offset time). Also, if the event offset is after end, the
            duration is decreased so that the offset time is end.
        - `"keep"` - no modification/truncation (default). Note that
            with the default mode="onsets", no event onsets will be
            earlier than start, but offsets may extend beyond end.
        - `"end"` or "ending" or "dur" or "duration" - truncate (clip)
            events that extend beyond end so that all offsets <= end.
        - `"beginning"` - events with onsets before start are moved to
            make their onsets equal to start, and their duration is
            adjusted to maintain the original offset.

    min_duration: Optional[float]
        Events with duration less than min_duration (after any truncation
        is applied) are removed.  Ignored if units is "measures" or "bars".
        If None or 0.0, no events are removed. The default is 0.05,
        independent of time units. Be careful with gracenotes that, when
        read from MusicXML, have zero duration.

    Returns
    -------
    Score
        A new Score instance containing the content between start and end.

    Raises
    ------
    ValueError
        If the Sequence is not part of a Score, or if invalid values are
        provided for the parameters.
    """
    score = self.score
    if score is None:
        raise ValueError("slice can only be called on a Sequence that is "
                         "part of a Score")
    if score.is_flat():
        if units in ("measures", "bars"):
            raise ValueError(f"units cannot be {units} for slicing a "
                             "flat score")
    else:
        if units not in ("measures", "bars"):
            raise ValueError(f"units must be measures or bars for slicing "
                "a score with Measures (or flatten the score before "
                "slicing)")

    if units in ("quarters", "measures", "bars"):
        score.convert_to_quarters()
    elif units in ("s", "sec", "seconds"):
        score.convert_to_seconds()
    else:
        raise ValueError('units must be "quarters", "measures, "'
                         '"bars", "s", "sec", or "seconds"')

    # Find start time and end time for slice. It may not be (start, end)
    # if units is measures or bars.
    if units in ("measures", "bars"):
        (start_time, end_time) = self.measure_times(int(start))
        if end != start:
            (_, end_time) = self.measure_times(int(end) - 1)
    else:
        start_time = start
        end_time = end

    # construct the parts of the tree above self and make an empty copy
    # of self to add the slice content.
    result = (score.emptycopy() if isinstance(self, Score)
              else self._copy_parents(start_time, end_time))
    result.onset = start_time  # result is an empty copy of self. Set the
    result.offset = end_time   # onset and offset to the slice bounds.
    if units in ("measures", "bars"):
        c_min, c_max = result._add_measure_children(self, start, end,
                                                    start_time, end_time)
        if c_min < start_time or c_max > end_time:
            raise ValueError("unexpectedly found content outside the "
                             "measure slice bounds")
        min_time = c_min
        max_time = c_max
    else:   
        min_time, max_time = result._add_slice_children(self, start_time,
                                  end_time, mode, truncate, min_duration)
    result._trim_map_and_signatures(min_time, max_time)
    if shift and min_time != float("inf") and min_time > 0:
        result.time_shift(-min_time)
    return result

time_signature ¶

time_signature() -> Optional[TimeSignature]

Retrieve the time signature that applies to this measure.

Returns:

Optional[TimeSignature] –

The time signature from the score corresponding to the time of this measure, or None if not found.

Raises:

ValueError –

If there is no Score or no onset time.

Source code in amads/core/basics.py

def time_signature(self) -> Optional[TimeSignature]:
    """Retrieve the time signature that applies to this measure.

    Returns
    -------
    Optional[TimeSignature]
        The time signature from the score corresponding to the
        time of this measure, or None if not found.

    Raises
    ------
    ValueError
        If there is no Score or no onset time.
    """
    score = self.score
    if score is None:
        raise ValueError("Measure has no Score")
    else:  # find time sig at onset + a little to avoid rounding error:
        q = self.onset
        if self.score.units_are_seconds:
            q = self.score.time_map.seconds_to_quarters(self.onset)
        # use a small offset in case there is a time signature change
        # near the measure boundary, but a little bit late due to rounding:
        return score._find_time_signature(q + 0.002)

Staff ¶

Staff(
    *args: Event,
    parent: Optional[EventGroup] = None,
    onset: Optional[float] = 0,
    duration: Optional[float] = None,
    number: Optional[int] = None
)

Bases: Sequence

A Staff models a musical staff.

This can also model one channel of a standard MIDI file track. A Staff normally contains Measure objects and is an element of a Part.

See Constructor Details.

Parameters:

*args (Optional[Event], default: () ) –

A variable number of Event objects to be added to the group.
parent (Optional[EventGroup], default: None ) –

The containing object or None.
onset (Optional[float], default: 0 ) –

The onset (start) time. If unknown (None), it will be set when this Staff is added to a parent. Must be passed as a keyword parameter due to *args.
duration (Optional[float], default: None ) –

The duration in quarters or seconds. (If duration is omitted or None, the duration is set so that self.offset ends at the max offset of args, or 0 if there is no content.) Must be passed as a keyword parameter due to *args.
number (Optional[int], default: None ) –

The staff number. Normally, a Staff is given an integer number where 1 is the top staff of the part, 2 is the 2nd, etc. Must be passed as a keyword parameter due to *args.

Attributes:

parent (Optional[EventGroup]) –

The containing object or None.
_onset (float) –

The onset (start) time.
duration (float) –

The duration in quarters or seconds.
content (list[Event]) –

Elements contained within this collection.
number (Optional[int]) –

The staff number. Normally a Staff is given an integer number where 1 is the top staff of the part, 2 is the 2nd, etc.

Source code in amads/core/basics.py

def __init__(self, *args: Event,
             parent: Optional[EventGroup] = None,
             onset: Optional[float] = 0,
             duration: Optional[float] = None,
             number: Optional[int] = None):
    super().__init__(parent, onset, duration, list(args))
    self.number = number

Attributes¶

onset `property` `writable` ¶

onset: float

Retrieve the onset (start) time.

If the onset is None, raise an exception. (Events can have None onset times, but they must be set before retrieval. onsets that are None are automatically set when the Event is added to an EventGroup.)

Returns:

float –

The onset (start) time.

Raises:

ValueError –

If the onset time is not set (None).

units_are_seconds `property` ¶

units_are_seconds: bool

Check if the times are in seconds.

This event must be in a Score (where _units_are_seconds is stored).

Returns:

bool –

True iff the event's times are in seconds. If not in a score, False is returned.

units_are_quarters `property` ¶

units_are_quarters: bool

Check if the times are in quarters.

This event must be in a Score (where _units_are_seconds is stored).

Returns:

bool –

True iff the event's times are in quarters. If not in a score, False is returned.

offset `property` `writable` ¶

offset: float

Retrieve the global offset (stop) time.

Returns:

float –

The global offset (stop) time.

part `property` ¶

part: Optional[Part]

Retrieve the Part containing this event.

Returns:

Optional[Part] –

The Part containing this event or None if not found.

score `property` ¶

score: Optional[Score]

Retrieve the Score containing this event, or self if it is a score.

Returns:

Optional[Score] –

The Score containing this event or None if not found.

staff `property` ¶

staff: Optional[Staff]

Retrieve the Staff containing this event

Returns:

Optional[Staff] –

The Staff containing this event or None if not found.

measure `property` ¶

measure: Optional[Measure]

Retrieve the Measure containing this event

Returns:

Optional[Measure] –

The Measure containing this event or None if not found.

Functions¶

set ¶

set(property: str, value: Any) -> Event

Set a named property on this Event.

Every event can be extended with additional properties. Although Python objects are already extensible with new attributes, new attributes that are not set in __init__ confuse type checkers and other tools, so every Event has an info attribute as a dictionary where additional, application-specific information can be stored. The info attribute is None to save space until the first property is set, so you should use set and get methods and avoid writing event.info[property].

Parameters:

property (str) –

The name of the property to set.
value (Any) –

The value to assign to the property.

Returns:

Event –

returns this object (self)

Examples:

>>> note = Note()
>>> note.get("color", "no color")
'no color'
>>> _ = note.set("color", "red").set("harmonicity", 0.2)
>>> (note.has("color"), note.has("shape"))
(True, False)
>>> (note.get("color"), note.get("harmonicity"))
('red', 0.2)

Source code in amads/core/basics.py

def set(self, property : str, value : Any) -> "Event":
    """Set a named property on this Event.

    Every event can be extended with additional properties. Although
    Python objects are already extensible with new attributes, new
    attributes that are not set in `__init__` confuse type checkers
    and other tools, so every `Event` has an `info` attribute as a
    dictionary where additional, application-specific information can
    be stored. The `info` attribute is `None` to save space until the
    first property is set, so you should use `set` and `get` methods
    and avoid writing `event.info[property]`.

    Parameters
    ----------
    property : str
        The name of the property to set.
    value : Any
        The value to assign to the property.

    Returns
    -------
    Event
        returns this object (self)

    Examples
    --------
    >>> note = Note()
    >>> note.get("color", "no color")
    'no color'
    >>> _ = note.set("color", "red").set("harmonicity", 0.2)
    >>> (note.has("color"), note.has("shape"))
    (True, False)
    >>> (note.get("color"), note.get("harmonicity"))
    ('red', 0.2)
    """
    if self.info is None:
        self.info = {}
    self.info[property] = value
    return self

get ¶

get(property: str, default: Any = None) -> Any

Get the value of a property from this Event.

See set for more details.

Parameters:

property (str.) –

The name of the property to get.
default (Any, default: None ) –

The default value to return if the property is not found.

Returns:

Any –

The value of the specified property.

Source code in amads/core/basics.py

def get(self, property : str, default : Any = None) -> Any:
    """Get the value of a property from this Event.

    See [set][amads.core.basics.Event.set] for more details.

    Parameters
    ----------
    property : str.
        The name of the property to get.
    default : Any
        The default value to return if the property is not found.

    Returns
    -------
    Any
        The value of the specified property.
    """
    if self.info is None:
        return default
    return self.info.get(property, default)

has ¶

has(property) -> bool

Check if the Event has a specific property.

See set for more details.

Parameters:

property (str) –

The name of the property to check.

Returns:

bool –

True if the property exists, False otherwise.

Source code in amads/core/basics.py

def has(self, property) -> bool:
    """Check if the Event has a specific property.

    See [set][amads.core.basics.Event.set] for more details.

    Parameters
    ----------
    property : str
        The name of the property to check.

    Returns
    -------
    bool
        True if the property exists, False otherwise.
    """
    return (self.info is not None) and (property in self.info)

time_shift ¶

time_shift(increment: float, content_only: bool = False) -> EventGroup

Change the onset by an increment, affecting all content.

If content_only is true, preserves EventGroup times (Score, Part, Staff, but not Chord or Measure) and shifts only the content (recursively). Otherwise, shifts this container and all content by the increment. Container onsets (recursively) are not allowed to become negative, so the onset time is set to zero if the increment would make it negative. However, even if the onset is is not shifted by increment, time_shift is still applied recursively to the content, and non-EventGroup events (e.g., Notes) are allowed to have negative onsets, even if this may not be well-defined for all AMADS operations.

Parameters:

increment (float) –

The time increment (in quarters or seconds).
content_only (bool, default: False ) –

If true, preserves this container's time and shifts only the content.

Returns:

Event –

The object. This method modifies the EventGroup.

Raises:

ValueError –

If the EventGroup has an unknown (None) onset and content_only is false.

Source code in amads/core/basics.py

def time_shift(self, increment: float,
               content_only: bool = False) -> "EventGroup":
    """
    Change the onset by an increment, affecting all content.

    If content_only is true, preserves EventGroup times (Score, Part,
    Staff, but *not* Chord or Measure) and shifts only the content
    (recursively). Otherwise, shifts this container and all content by the
    increment. Container onsets (recursively) are not allowed to become
    negative, so the onset time is set to zero if the increment would
    make it negative. However, even if the onset is is not shifted by
    increment, time_shift is still applied recursively to the content,
    and non-EventGroup events (e.g., Notes) are allowed to have negative
    onsets, even if this may not be well-defined for all AMADS operations.

    Parameters
    ----------
    increment : float
        The time increment (in quarters or seconds).
    content_only: bool
        If true, preserves this container's time and shifts only
        the content.

    Returns
    -------
    Event
        The object. This method modifies the `EventGroup`.

    Raises
    ------
    ValueError
        If the EventGroup has an unknown (None) onset and
        content_only is false.
    """
    # note that Chord and Measures are special cases
    if not content_only or isinstance(self, (Chord, Measure)):
        if self._onset is None:
            raise ValueError(
                    "Cannot shift time of EventGroup with unknown onset")
        self._onset = max(0.0, self._onset + increment)
    for elem in self.content:
        elem.time_shift(increment, content_only)
    return self

insert_copy_into ¶

insert_copy_into(parent: Optional[EventGroup] = None) -> Event

Make a (mostly) deep copy of the Event and add to a new parent.

Pitch objects are considered immutable and are shared rather than copied.

Parameters:

parent (Optional(EventGroup), default: None ) –

The copied Event will be a child of parent if not None. The parent is modified by this operation.

Returns:

Event –

A deep copy (except for parent and pitch) of the Event instance.

Source code in amads/core/basics.py

def insert_copy_into(self,
                     parent: Optional["EventGroup"] = None) -> "Event":
    """
    Make a (mostly) deep copy of the `Event` and add to a new `parent`.

    `Pitch` objects are considered immutable and are shared rather
    than copied.

    Parameters
    ----------
    parent : Optional(EventGroup)
        The copied `Event` will be a child of `parent` if not `None`.
        The parent is modified by this operation.

    Returns
    -------
    Event
        A deep copy (except for parent and pitch) of the Event instance.
    """
    # remove link to parent to break link going up the tree
    # preventing deep copy from copying the entire tree
    original_parent = self.parent
    self.parent = None
    c = copy.deepcopy(self)  # deep copy of this event down to leaf nodes
    self.parent = original_parent  # restore link to parent
    if parent:
        parent.insert(c)
    return c

ismonophonic ¶

ismonophonic() -> bool

Determine if content is monophonic (non-overlapping notes).

A monophonic list of notes has no overlapping notes (e.g., chords). Serves as a helper function for ismonophonic and parts_are_monophonic.

Returns:

bool –

True if the list of notes is monophonic, False otherwise.

Source code in amads/core/basics.py

def ismonophonic(self) -> bool:
    """
    Determine if content is monophonic (non-overlapping notes).

    A monophonic list of notes has no overlapping notes (e.g., chords).
    Serves as a helper function for `ismonophonic` and
    `parts_are_monophonic`.

    Returns
    -------
    bool
        True if the list of notes is monophonic, False otherwise.
    """
    prev = None
    notes = self.list_all(Note)
    # Sort the notes by start time
    notes.sort(key=lambda note: note.onset)
    # Check for overlaps
    for note in notes:
        if prev:
            # 0.01 is to prevent precision errors when comparing floats
            if note.onset - prev.offset < -0.01:
                return False
        prev = note
    return True

insert_emptycopy_into ¶

insert_emptycopy_into(
    parent: Optional[EventGroup] = None,
) -> EventGroup

Create a deep copy of the EventGroup except for content.

A new parent is provided as an argument and the copy is inserted into this parent. This method is useful for copying an EventGroup without copying its content. See also insert_copy_into to copy an EventGroup with its content into a new parent.

Parameters:

parent (Optional[EventGroup], default: None ) –

The new parent to insert the copied Event into.

Returns:

EventGroup –

A deep copy of the EventGroup instance with the new parent (if any) and no content.

Source code in amads/core/basics.py

def insert_emptycopy_into(self, 
            parent: Optional["EventGroup"] = None) -> "EventGroup":
    """Create a deep copy of the EventGroup except for content.

    A new parent is provided as an argument and the copy is inserted
    into this parent. This method is  useful for copying an
    EventGroup without copying its content.  See also
    [insert_copy_into][amads.core.basics.Event.insert_copy_into] to
    copy an EventGroup *with* its content into a new parent.

    Parameters
    ----------
    parent : Optional[EventGroup]
        The new parent to insert the copied Event into.

    Returns
    -------
    EventGroup
        A deep copy of the EventGroup instance with the new parent
        (if any) and no content.
    """
    # rather than customize __deepcopy__, we "hide" the content to avoid
    # copying it. Then we restore it after copying and fix parent.
    original_content = self.content
    self.content = []
    c = self.insert_copy_into(parent)
    self.content = original_content
    return c  #type: ignore (c will always be an EventGroup)

expand_chords ¶

expand_chords(parent: Optional[EventGroup] = None) -> EventGroup

Replace chords with the multiple notes they contain.

Returns a deep copy with no parent unless parent is provided. Normally, you will call score.expand_chords() which returns a deep copy of Score with notes moved from each chord to the copy of the chord's parent (a Measure or a Part). The parent parameter is primarily for internal use when expand_chords is called recursively on score content.

Parameters:

parent (EventGroup, default: None ) –

The new parent to insert the copied EventGroup into.

Returns:

EventGroup –

A deep copy of the EventGroup instance with all Chord instances expanded.

Source code in amads/core/basics.py

def expand_chords(self,
                  parent: Optional["EventGroup"] = None) -> "EventGroup":
    """Replace chords with the multiple notes they contain.

    Returns a deep copy with no parent unless parent is provided.
    Normally, you will call `score.expand_chords()` which returns a deep
    copy of Score with notes moved from each chord to the copy of the
    chord's parent (a Measure or a Part). The parent parameter is 
    primarily for internal use when `expand_chords` is called recursively
    on score content.

    Parameters
    ----------
    parent : EventGroup
        The new parent to insert the copied EventGroup into.

    Returns
    -------
    EventGroup
        A deep copy of the EventGroup instance with all
        Chord instances expanded.
    """
    group = self.insert_emptycopy_into(parent)
    for item in self.content:
        if isinstance(item, Chord):
            for note in item.content:  # expand chord
                note.insert_copy_into(group)
        if isinstance(item, EventGroup):
            item.expand_chords(group)  # recursion for deep copy/expand
        else:
            item.insert_copy_into(group)  # deep copy non-EventGroup
    return group

find_all ¶

find_all(elem_type: Type[Event]) -> Generator[Event, None, None]

Find all instances of a specific type within the EventGroup.

Assumes that objects of type elem_type are not nested within other objects of the same type. (The first elem_type encountered in a depth-first enumeration is returned without looking at any children in its content).

Parameters:

elem_type (Type[Event]) –

The type of event to search for.

Yields:

Event –

Instances of the specified type found within the EventGroup.

Source code in amads/core/basics.py

def find_all(self, elem_type: Type[Event]) -> Generator[Event, None, None]:
    """Find all instances of a specific type within the EventGroup.

    Assumes that objects of type `elem_type` are not nested within
    other objects of the same type. (The first `elem_type` encountered
    in a depth-first enumeration is returned without looking at any
    children in its `content`).

    Parameters
    ----------
    elem_type : Type[Event]
        The type of event to search for.

    Yields
    -------
    Event
        Instances of the specified type found within the EventGroup.
    """
    # Algorithm: depth-first enumeration of EventGroup content.
    # If elem_types are nested, only the top-level elem_type is
    # returned since it is found first, and the content is not
    # searched. This makes it efficient, e.g., to search for
    # Parts in a Score without enumerating all Notes within.
    for elem in self.content:
        if isinstance(elem, elem_type):
            yield elem
        elif isinstance(elem, EventGroup):
            yield from elem.find_all(elem_type)

get_sorted_notes ¶

get_sorted_notes(has_ties: bool = True) -> List[Note]

Return a list of sorted notes with merged ties.

This should generally be called on Parts and Scores since in all other EventGroups, Events are in time order and Notes retrieved with find_all() or list_all() are in time order. However, get_sorted_notes also sorts notes into increasing pitch (keynum) where note onsets are equal.

Parameters:

has_ties (bool, default: True ) –

If True (default), copy the score, merge the ties, and return a list of these merged copies. If False, assume there are no ties and return a list of original notes.

Raises:

ValueError –

If has_ties is False, but a tie is encountered.

Returns:

list(Note) –

a list of sorted notes with merged ties

Source code in amads/core/basics.py

def get_sorted_notes(self, has_ties: bool = True) -> List[Note]:
    """Return a list of sorted notes with merged ties.

    This should generally be called on Parts and Scores since
    in all other EventGroups, Events are in time order and
    Notes retrieved with `find_all()` or `list_all()` are in
    time order. However, `get_sorted_notes` *also* sorts notes
    into increasing pitch (`keynum`) where note onsets are equal.

    Parameters
    ----------
    has_ties: bool
        If True (default), copy the score, merge the ties, and
        return a list of these merged copies. If False, assume
        there are no ties and return a list of original notes.

    Raises
    ------
    ValueError
        If has_ties is False, but a tie is encountered.

    Returns
    -------
    list(Note)
        a list of sorted notes with merged ties
    """
    if has_ties:
        # after flatten, score will have one Part with all Notes:
        return self.flatten(collapse=True).content[0].content  # type: ignore
    else:
        notes : List[Note] = cast(List[Note], self.list_all(Note))
        for note in notes:
            if note.tie is not None:
                raise ValueError(
                        "tie found by get_sorted_notes with has_ties=False")
        notes.sort(key=lambda x: (x.onset, x.pitch))
        return notes

has_instanceof ¶

has_instanceof(the_class: Type[Event]) -> bool

Test if EventGroup contains any instances of the_class.

Parameters:

the_class (Type[Event]) –

The class type to check for.

Returns:

bool –

True iff the EventGroup contains an instance of the_class.

Source code in amads/core/basics.py

def has_instanceof(self, the_class: Type[Event]) -> bool:
    """Test if EventGroup contains any instances of `the_class`.

    Parameters
    ----------
    the_class : Type[Event]
        The class type to check for.

    Returns
    -------
    bool
        True iff the EventGroup contains an instance of the_class.
    """
    instances = self.find_all(the_class)
    # if there are no instances (of the_class), next will return "empty":
    return next(instances, "empty") != "empty"

has_rests ¶

has_rests() -> bool

Test if EventGroup (e.g., Score, Part, ...) has any Rest objects.

Returns:

bool –

True iff the EventGroup contains any Rest objects.

Source code in amads/core/basics.py

def has_rests(self) -> bool:
    """Test if EventGroup (e.g., Score, Part, ...) has any `Rest` objects.

    Returns
    -------
    bool
        True iff the EventGroup contains any Rest objects.
    """
    return self.has_instanceof(Rest)

has_chords ¶

has_chords() -> bool

Test if EventGroup (e.g., Score, Part, ...) has any Chord objects.

Returns:

bool –

True iff the EventGroup contains any Chord objects.

Source code in amads/core/basics.py

def has_chords(self) -> bool:
    """Test if EventGroup (e.g., Score, Part, ...) has any Chord objects.

    Returns
    -------
    bool
        True iff the EventGroup contains any Chord objects.
    """
    return self.has_instanceof(Chord)

has_ties ¶

has_ties() -> bool

Test if EventGroup (e.g., Score, Part, ...) has any tied notes.

Returns:

bool –

True iff the EventGroup contains any tied notes.

Source code in amads/core/basics.py

def has_ties(self) -> bool:
    """Test if EventGroup (e.g., Score, Part, ...) has any tied notes.

    Returns
    -------
    bool
        True iff the EventGroup contains any tied notes.
    """
    notes = self.find_all(Note)
    for note in notes:
        if note.tie:
            return True
    return False

has_measures ¶

has_measures() -> bool

Test if EventGroup (e.g., Score, Part, ...) has any Measures.

Returns:

bool –

True iff the EventGroup contains any Measure objects.

Source code in amads/core/basics.py

def has_measures(self) -> bool:
    """Test if EventGroup (e.g., Score, Part, ...) has any Measures.

    Returns
    -------
    bool
        True iff the EventGroup contains any Measure objects.
    """
    return self.has_instanceof(Measure)

inherit_duration ¶

inherit_duration() -> EventGroup

Set the duration of this EventGroup according to maximum offset.

The duration is set to the maximum offset (end) time of the children. If the EventGroup is empty, the duration is set to 0. This method modifies this EventGroup instance.

Returns:

EventGroup –

The EventGroup instance (self) with updated duration.

Source code in amads/core/basics.py

def inherit_duration(self) -> "EventGroup":
    """Set the duration of this EventGroup according to maximum offset.

    The `duration` is set to the maximum offset (end) time of the
    children. If the EventGroup is empty, the duration is set to 0.
    This method modifies this `EventGroup` instance.

    Returns
    -------
    EventGroup
        The EventGroup instance (self) with updated duration.
    """
    onset = 0 if self._onset == None else self._onset
    max_offset = onset
    for elem in self.content:
        max_offset = max(max_offset, elem.offset)
    self.duration = max_offset - onset

    return self

insert ¶

insert(event: Event) -> EventGroup

Insert an event.

Sets the parent of event to this EventGroup and makes event be a member of this EventGroup.content. No changes are made to event.onset or self.duration. Insert event in content just before the first element with a greater onset. The method modifies this object (self).

Parameters:

event (Event) –

The event to be inserted.

Returns:

EventGroup –

The EventGroup instance (self) with the event inserted.

Raises:

ValueError –

If event._onset is None (it must be a number)

Caution Regarding Zero-Duration Event Order

If you have note N with non-zero duration and, at the same time, a grace note G with zero duration, the notes will be ordered according to when they are inserted. So if you insert N and then G, then N will be placed before G. See io.pt_import.py, where this case is dealt with.

Source code in amads/core/basics.py

def insert(self, event: Event) -> "EventGroup":
    """Insert an event.

    Sets the `parent` of `event` to this `EventGroup` and makes `event`
    be a member of this `EventGroup.content`. No changes are made to
    `event.onset` or `self.duration`. Insert `event` in `content` just
    before the first element with a greater onset. The method modifies
    this object (self).

    Parameters
    ----------
    event : Event
        The event to be inserted.

    Returns
    -------
    EventGroup
        The EventGroup instance (self) with the event inserted.

    Raises
    ------
    ValueError
        If event._onset is None (it must be a number)

    Caution Regarding Zero-Duration Event Order
    -------------------------------------------
    If you have note N with non-zero duration and, at the same
    time, a grace note G with zero duration, the notes will be
    ordered according to when they are inserted. So if you insert
    N and then G, then N will be placed *before* G. See
    io.pt_import.py, where this case is dealt with.
    """

    assert not event.parent
    if event._onset is None:  # must be a number
        raise ValueError(f"event's _onset attribute must be a number")
    atend = self.last()
    if atend and event.onset < atend.onset:
        # search in reverse from end
        i = len(self.content) - 2
        while i >= 0 and self.content[i].onset > event.onset:
            i -= 1
        # now i is either -1 or content[i] <= event.onset, so
        # insert event at content[i+1]
        self.content.insert(i + 1, event)
    else:  # simply append at the end of content:
        self.content.append(event)
    event.parent = self
    return self

last ¶

last() -> Optional[Event]

Retrieve the last event in the content list.

Because the content list is sorted by onset, the returned Event is simply the last element of content, but not necessarily the event with the greatest offset.

Returns:

Optional[Event] –

The last event in the content list or None if the list is empty.

Source code in amads/core/basics.py

def last(self) -> Optional[Event]:
    """Retrieve the last event in the content list.

    Because the `content` list is sorted by `onset`, the returned
    `Event` is simply the last element of `content`, but not
    necessarily the event with the greatest *`offset`*.

    Returns
    -------
    Optional[Event]
        The last event in the content list or None if the list is empty.
    """
    return self.content[-1] if len(self.content) > 0 else None

list_all ¶

list_all(elem_type: Type[Event]) -> list[Event]

Find all instances of a specific type within the EventGroup.

Assumes that objects of type elem_type are not nested within other objects of the same type. See also find_all, which returns a generator instead of a list.

Parameters:

elem_type (Type[Event]) –

The type of event to search for.

Returns:

list[Event] –

A list of all instances of the specified type found within the EventGroup.

Source code in amads/core/basics.py

def list_all(self, elem_type: Type[Event]) -> list[Event]:
    """Find all instances of a specific type within the EventGroup.

    Assumes that objects of type `elem_type` are not nested within
    other objects of the same type.  See also
    [find_all][amads.core.basics.EventGroup.find_all], which returns
    a generator instead of a list.

    Parameters
    ----------
    elem_type : Type[Event]
        The type of event to search for.

    Returns
    -------
    list[Event]
        A list of all instances of the specified type found
        within the EventGroup.
    """
    return list(self.find_all(elem_type))

merge_tied_notes ¶

merge_tied_notes(
    parent: Optional[EventGroup] = None, ignore: list[Note] = []
) -> EventGroup

Create a new EventGroup with tied notes replaced by single notes.

If ties cross staffs, the replacement is placed in the staff of the first note in the tied sequence. Insert the new EventGroup into parent.

Ordinarily, this method is called on a Score with no parameters. The parameters are used when Score.merge_tied_notes() calls this method recursively on EventGroups within the Score such as Parts and Staffs.

Parameters:

parent (Optional[EventGroup], default: None ) –

Where to insert the result.
ignore (list[Note], default: [] ) –

This parameter is used internally. Caller should not use this parameter.

Returns:

EventGroup –

A copy with tied notes replaced by equivalent single notes.

Source code in amads/core/basics.py

def merge_tied_notes(self, parent: Optional["EventGroup"] = None,
                     ignore: list[Note] = []) -> "EventGroup":
    """Create a new `EventGroup` with tied notes replaced by single notes.

    If ties cross staffs, the replacement is placed in the staff of the
    first note in the tied sequence. Insert the new `EventGroup` into
    `parent`.

    Ordinarily, this method is called on a Score with no parameters. The
    parameters are used when `Score.merge_tied_notes()` calls this method
    recursively on `EventGroup`s within the Score such as `Part`s and
    `Staff`s.

    Parameters
    ----------
    parent: Optional(EventGroup)
        Where to insert the result.

    ignore: Optional(list[Note])
        This parameter is used internally. Caller should not use
        this parameter.

    Returns
    -------
    EventGroup
        A copy with tied notes replaced by equivalent single notes.
    """
    # Algorithm: Find all notes, removing tied notes and updating
    # duration when ties are found. These tied notes are added to
    # ignore so they can be skipped when they are encountered.

    group = self.insert_emptycopy_into(parent)
    for event in self.content:
        if isinstance(event, Note):
            if event in ignore:  # do not copy tied notes into group;
                if event.tie:
                    ignore.append(event.tie)  # add tied note to ignore
                # We will not see this note again, so
                # we can also remove it from ignore. Removal is expensive
                # but it could be worse for ignore to grow large when there
                # are many ties since we have to search it entirely once
                # per note. An alternate representation might be a set to
                # make searching fast.
                ignore.remove(event)
            else:
                if event.tie:
                    tied_note = event.tie  # save the tied-to note
                    event.tie = None  # block the copy
                    ignore.append(tied_note)
                    # copy note into group:
                    event_copy = event.insert_copy_into(group)
                    event.tie = tied_note  # restore original event
                    # this is subtle: event.tied_duration (a property) will
                    # sum up durations of all the tied notes. Since
                    # event_copy is not tied, the sum of durations is
                    # stored on that one event_copy:
                    event_copy.duration = event.tied_duration
                else:  # put the untied note into group
                    event.insert_copy_into(group)
        elif isinstance(event, EventGroup):
            event.merge_tied_notes(group, ignore)
        else:
            event.insert_copy_into(group)  # simply copy to new parent
    return group

pack ¶

pack(onset: float = 0.0, sequential: bool = True) -> float

Adjust the content to be sequential.

The resulting content will begin with the parameter onset (defaults to 0), and each other object will get an onset equal to the offset of the previous element. The duration of self is set to the offset of the last element. This method essentially arranges the content to eliminate gaps. pack() works recursively on elements that are EventGroups.

Be careful not to pack Measures (directly or through recursion) if the Measure's content durations do not add up to the intended quarters per measure.

To override the sequential behavior, set the sequential parameter to False. In that case, pack behaves like the Concurrence.pack() method.

The pack method alters self and its content in place.

Parameters:

onset (float, default: 0.0 ) –

The onset (start) time for this object.

Returns:

float –

duration of self

Source code in amads/core/basics.py

def pack(self, onset: float = 0.0, sequential: bool = True) -> float:
    """Adjust the content to be sequential.

    The resulting content will begin with the parameter `onset`
    (defaults to 0), and each other object will get an onset equal
    to the offset of the previous element. The duration of self is
    set to the offset of the last element.  This method essentially
    arranges the content to eliminate gaps. pack() works recursively
    on elements that are `EventGroups`.

    Be careful not to pack `Measures` (directly or through
    recursion) if the Measure's content durations do not add up to
    the intended quarters per measure.

    To override the sequential behavior, set the `sequential` 
    parameter to False.  In that case, pack behaves like the
    `Concurrence.pack()` method.

    The pack method alters self and its content in place.

    Parameters
    ----------
    onset : float
        The onset (start) time for this object.

    Returns
    -------
    float
        duration of self
    """
    return super().pack(onset, sequential)

quantize ¶

quantize(divisions: int) -> EventGroup

Align onsets and durations to a rhythmic grid.

Assumes time units are quarters. (See Score.convert_to_quarters.)

Modify all times and durations to a multiple of divisions per quarter note, e.g., 4 for sixteenth notes. Onsets and offsets are moved to the nearest quantized time. Any resulting duration change is less than one quantum, but not necessarily less than 0.5 quantum, since the onset and offset can round in opposite directions by up to 0.5 quantum each. Any non-zero duration that would quantize to zero duration gets a duration of one quantum since zero duration is almost certainly going to cause notation and visualization problems.

Special cases for zero duration:

If the original duration is zero as in metadata or possibly grace notes, we preserve that.
If a tied note duration quantizes to zero, we remove the tied note entirely provided some other note in the tied sequence has non-zero duration. If all tied notes quantize to zero, we keep the first one and set its duration to one quantum.

This method modifies this EventGroup and all its content in place.

Note that there is no way to specify "sixteenths or eighth triplets" because 6 would not allow sixteenths and 12 would admit sixteenth triplets. Using tuples as in Music21, e.g., (4, 3) for this problem creates another problem: if quantization is to time points 1/4, 1/3, then the difference is 1/12 or a thirty-second triplet. If the quantization is applied to durations, then you could have 1/4 + 1/3 = 7/12, and the remaining duration in a single beat would be 5/12, which is not expressible as sixteenths, eighth triplets or any tied combination.

Parameters:

divisions (int) –

The number of divisions per quarter note, e.g., 4 for sixteenths, to control quantization.

Returns:

EventGroup –

The EventGroup instance (self) with (modified in place) quantized times.

Source code in amads/core/basics.py

def quantize(self, divisions: int) -> "EventGroup":
    """Align onsets and durations to a rhythmic grid.

    Assumes time units are quarters. (See [Score.convert_to_quarters](
            basics.md#amads.core.basics.Score.convert_to_quarters).)

    Modify all times and durations to a multiple of divisions
    per quarter note, e.g., 4 for sixteenth notes. Onsets and offsets
    are moved to the nearest quantized time. Any resulting duration
    change is less than one quantum, but not necessarily less than
    0.5 quantum, since the onset and offset can round in opposite
    directions by up to 0.5 quantum each. Any non-zero duration that would
    quantize to zero duration gets a duration of one quantum since
    zero duration is almost certainly going to cause notation and
    visualization problems.

    Special cases for zero duration:

    1. If the original duration is zero as in metadata or possibly
           grace notes, we preserve that.
    2. If a tied note duration quantizes to zero, we remove the
           tied note entirely provided some other note in the tied
           sequence has non-zero duration. If all tied notes quantize
           to zero, we keep the first one and set its duration to
           one quantum.

    This method modifies this EventGroup and all its content in place.

    Note that there is no way to specify "sixteenths or eighth triplets"
    because 6 would not allow sixteenths and 12 would admit sixteenth
    triplets. Using tuples as in Music21, e.g., (4, 3) for this problem
    creates another problem: if quantization is to time points 1/4, 1/3,
    then the difference is 1/12 or a thirty-second triplet. If the
    quantization is applied to durations, then you could have 1/4 + 1/3
    = 7/12, and the remaining duration in a single beat would be 5/12,
    which is not expressible as sixteenths, eighth triplets or any tied
    combination.

    Parameters
    ----------
    divisions : int
        The number of divisions per quarter note, e.g., 4 for
        sixteenths, to control quantization.

    Returns
    -------
    EventGroup
        The EventGroup instance (self) with (modified in place) 
        quantized times.
    """

    super()._quantize(divisions)
    # iterating through content is tricky because we may delete a
    # Note, shifting the content:
    i = 0
    while i < len(self.content):
        event = self.content[i]
        event._quantize(divisions)
        if event == self.content[i]:
            i += 1
        # otherwise, we deleted event so the next event to
        # quantize is at index i; don't incremenet i
    return self

remove ¶

remove(element: Event) -> EventGroup

Remove an element from the content list.

The method modifies this object (self).

Parameters:

element (Event) –

The event to be removed.

Returns:

EventGroup –

The EventGroup instance (self) with the element removed. The returned value is not a copy.

Source code in amads/core/basics.py

def remove(self, element: Event) -> "EventGroup":
    """Remove an element from the content list. 

    The method modifies this object (self).

    Parameters
    ----------
    element : Event
        The event to be removed.

    Returns
    -------
    EventGroup
        The EventGroup instance (self) with the element removed.
        The returned value is not a copy.
    """
    self.content.remove(element)
    element.parent = None
    return self

remove_rests ¶

remove_rests(parent: Union[EventGroup, None] = None) -> EventGroup

Remove all Rest objects from content.

Returns a deep copy with no parent unless parent is provided.

Parameters:

parent (EventGroup, default: None ) –

The new parent to insert the copied Event into.

Returns:

EventGroup –

A deep copy of the EventGroup instance with all Rest objects removed.

Source code in amads/core/basics.py

def remove_rests(self, parent: Union["EventGroup", 
                                     None] = None) -> "EventGroup":
    """Remove all Rest objects from content.

    Returns a deep copy with no parent unless parent is provided.

    Parameters
    ----------
    parent : EventGroup
        The new parent to insert the copied Event into.

    Returns
    -------
    EventGroup
        A deep copy of the EventGroup instance with all Rest
        objects removed.
    """
    # implementation detail: when called without argument, remove_rests
    # makes a deep copy of the subtree and returns the copy without a
    # parent. remove_rests calls itself recursively *with* a parameter
    # indicating that the subtree copy should be inserted into a
    # parent which is the new copy at the next level up. Of course,
    # we check for and ignore Rests so they are never copied.
    group = self.insert_emptycopy_into(parent)
    for item in self.content:
        if isinstance(item, Rest):
            continue  # skip the Rests while making deep copy
        if isinstance(item, EventGroup):
            item.remove_rests(group)  # recursion for deep copy
        else:
            item.insert_copy_into(group)  # deep copy non-EventGroup
    return group

show ¶

show(indent: int = 0, file: Optional[TextIO] = None) -> EventGroup

Print the EventGroup information.

Parameters:

indent (int, default: 0 ) –

The indentation level for display.

Returns:

EventGroup –

The EventGroup instance itself.

Source code in amads/core/basics.py

def show(self, indent: int = 0,
        file: Optional[TextIO] = None) -> "EventGroup":
    """Print the EventGroup information.

    Parameters
    ----------
    indent : int
        The indentation level for display.

    Returns
    -------
    EventGroup
        The EventGroup instance itself.
    """
    print(" " * indent, self, sep="", file=file)
    for elem in self.content:
        elem.show(indent + 4, file=file)  # type: ignore (show exists)
    return self

measure_times ¶

measure_times(n: int) -> tuple[float, float]

Return the start and end times of measure n.

Parameters:

n (int) –

The 0-based measure number.

Returns:

tuple(float, float) –

A tuple containing the start and end times of measure n. Measure 0 is the first measure. Units are the same as the score's time units.

Raises:

ValueError –

If there is no measure with number n.

Source code in amads/core/basics.py

def measure_times(self, n: int) -> tuple[float, float]:
    """Return the start and end times of measure n.

    Parameters
    ----------
    n : int
        The 0-based measure number.

    Returns
    -------
    tuple(float, float)
        A tuple containing the start and end times of measure n.
        Measure 0 is the first measure.  Units are the same as the
        score's time units.

    Raises
    ------
    ValueError
        If there is no measure with number n.
    """
    # Algorithm: For each Staff, linear search for nth Measure, returning
    # the onset and offset of the first one found.
    for staff in self.find_all(Staff):
        staff = cast(Staff, staff)
        for i, measure in enumerate(staff.find_all(Measure)):
            if i == n:
                return (measure.onset, measure.offset)
    raise ValueError(f"measure {n} not found")

slice ¶

slice(
    start: float,
    end: float,
    units: str = "quarters",
    mode: str = "onsets",
    truncate: str = "keep",
    shift: bool = False,
    min_duration: float = 0.05,
) -> EventGroup

Create a new Score containing the content between start and end.

Typically, this method is called on a Score to create a new Score, but it works on any Sequence as long as the sequence is part of a Score.

If self has Measures, units must be "measures" or "bars", the start and end parameters are interpreted as 0-based measure numbers, and the result will therefore contain whole measures. It is assumed that notes are tied across measure boundaries. The result will contain only the parts of tied notes that are within the specified measures, excluding measure numbered by end.

For any units besides "measures" or "bars", the score must be flat. Notes that extend beyond the start or end time are included in the result unless the truncate parameter specifies otherwise.

In principle, there is no reason to require a flat score for slicing by time, but there are many difficult edge cases to consider such as ties from within one chord to a note in another measure. Therefore, to slice by time or quarter, you must have a flattened score. Conversely, to slice a full score, you must slice by measure so that the result gives you whole measures, which are encoded into the full Score structure.

The entire result can be shifted to start at time 0 by setting the shift parameter to True. Unless truncate is "truncate" or "beginning", the result can include events that start before the start time, in which case shifting will only shift the earliest onset to 0, which means the shift amount depends upon the content. (Negative onsets are currently not allowed.)

The resulting Score, Part, and other content will have onset and offset times matching start and end, even if some content starts earlier or ends later.

Parameters:

start (float) –

The start time of the slice, inclusive. If units is "measures" or "bars", start is a 0-based measure number of the first measure.
end (float) –

The end time of the slice, exclusive. For measures, end is the 0-based measure number of the last measure plus one, so the last measure is end - 1.
units (str, default: 'quarters' ) –

The time units for start and end. Valid values are "quarters", "s", "sec", "seconds", "measures", or "bars".
shift (bool, default: False ) –

If true, shift the content in the result so that the result starts time 0.0. If false (default), the content in the result retains the same time values as in the original Score.
mode (Optional[str], default: 'onsets' ) –
The slicing mode, ignored if units is "measures" or "bars". Valid values are:
- "onsets" - include events that start within bounds (default)
- "overlaps" - include events that overlap (either onset or offset) is within the bounds. An event ending is considered to overlap if its offset is greater than start.
- "offsets" - include events that end within the bounds
- "strict" - include only events that start at or after start and end at or before end. (End times that are exactly equal to end are considered to be within bounds, so this is inclusive of end time.)
truncate (str, default: 'keep' ) –
How to handle events that partially overlap the bounds, ignored if units is "measures" or "bars". Valid values are:
- "truncate" - truncate (clip) events that partially overlap the bounds. If the event onset is before start, the onset is increased to start (adjusting duration to maintain the offset time). Also, if the event offset is after end, the duration is decreased so that the offset time is end.
- "keep" - no modification/truncation (default). Note that with the default mode="onsets", no event onsets will be earlier than start, but offsets may extend beyond end.
- "end" or "ending" or "dur" or "duration" - truncate (clip) events that extend beyond end so that all offsets <= end.
- "beginning" - events with onsets before start are moved to make their onsets equal to start, and their duration is adjusted to maintain the original offset.
min_duration (float, default: 0.05 ) –

Events with duration less than min_duration (after any truncation is applied) are removed. Ignored if units is "measures" or "bars". If None or 0.0, no events are removed. The default is 0.05, independent of time units. Be careful with gracenotes that, when read from MusicXML, have zero duration.

Returns:

Score –

A new Score instance containing the content between start and end.

Raises:

ValueError –

If the Sequence is not part of a Score, or if invalid values are provided for the parameters.

Source code in amads/core/basics.py

def slice(self, start: float, end: float, units: str = "quarters",
          mode: str = "onsets", truncate: str = "keep", shift: bool = False,
          min_duration: float = 0.05) -> "EventGroup":
    """
    Create a new Score containing the content between start and end.

    Typically, this method is called on a Score to create a new Score,
    but it works on any Sequence as long as the sequence is part of a Score.

    If self has Measures, units must be "measures" or "bars", the start and
    end parameters are interpreted as 0-based measure numbers, and the
    result will therefore contain whole measures. It is assumed that notes
    are tied across measure boundaries. The result will contain only the
    parts of tied notes that are within the specified measures, excluding
    measure numbered by `end`.

    For any units besides "measures" or "bars", the score must be flat.
    Notes that extend beyond the start or end time are included in the
    result unless the `truncate` parameter specifies otherwise.

    In principle, there is no reason to require a flat score for slicing by
    time, but there are many difficult edge cases to consider such as ties
    from within one chord to a note in another measure. Therefore, to slice
    by time or quarter, you must have a flattened score. Conversely, to
    slice a full score, you must slice by measure so that the result gives
    you whole measures, which are encoded into the full Score structure.

    The entire result can be shifted to start at time 0 by setting the
    `shift` parameter to True.  Unless `truncate` is "truncate" or
    "beginning", the result can include events that start before the start
    time, in which case shifting will only shift the earliest onset to 0,
    which means the shift amount depends upon the content. (Negative onsets
    are currently not allowed.)

    The resulting Score, Part, and other content will have onset and offset
    times matching start and end, even if some content starts earlier or
    ends later.

    Parameters
    ----------
    start : float
        The start time of the slice, inclusive. If units is "measures" or
        "bars", start is a 0-based measure number of the first measure.
    end : float
        The end time of the slice, exclusive. For measures, end is the
        0-based measure number of the last measure plus one, so the last
        measure is end - 1.
    units : str
        The time units for start and end. Valid values are "quarters", "s",
        "sec", "seconds", "measures", or "bars".
    shift: bool
        If true, shift the content in the result so that the result starts
        time 0.0. If false (default), the content in the result retains
        the same time values as in the original Score.
    mode : Optional[str]
        The slicing mode, ignored if units is "measures" or "bars".
        Valid values are:

        - `"onsets"` - include events that start within bounds (default)
        - `"overlaps"` - include events that overlap (either onset or
            offset) is within the bounds. An event ending is considered
            to overlap if its offset is greater than start.
        - `"offsets"` - include events that end within the bounds
        - `"strict"` - include only events that start at or after start
            and end at or before end. (End times that are exactly equal
            to end are considered to be within bounds, so this is
            inclusive of end time.)

    truncate: Optional[str]
        How to handle events that partially overlap the bounds,
        ignored if units is "measures" or "bars". Valid values are:

        - `"truncate"` - truncate (clip) events that partially overlap
            the bounds. If the event onset is before start, the onset
            is increased to start (adjusting duration to maintain the
            offset time). Also, if the event offset is after end, the
            duration is decreased so that the offset time is end.
        - `"keep"` - no modification/truncation (default). Note that
            with the default mode="onsets", no event onsets will be
            earlier than start, but offsets may extend beyond end.
        - `"end"` or "ending" or "dur" or "duration" - truncate (clip)
            events that extend beyond end so that all offsets <= end.
        - `"beginning"` - events with onsets before start are moved to
            make their onsets equal to start, and their duration is
            adjusted to maintain the original offset.

    min_duration: Optional[float]
        Events with duration less than min_duration (after any truncation
        is applied) are removed.  Ignored if units is "measures" or "bars".
        If None or 0.0, no events are removed. The default is 0.05,
        independent of time units. Be careful with gracenotes that, when
        read from MusicXML, have zero duration.

    Returns
    -------
    Score
        A new Score instance containing the content between start and end.

    Raises
    ------
    ValueError
        If the Sequence is not part of a Score, or if invalid values are
        provided for the parameters.
    """
    score = self.score
    if score is None:
        raise ValueError("slice can only be called on a Sequence that is "
                         "part of a Score")
    if score.is_flat():
        if units in ("measures", "bars"):
            raise ValueError(f"units cannot be {units} for slicing a "
                             "flat score")
    else:
        if units not in ("measures", "bars"):
            raise ValueError(f"units must be measures or bars for slicing "
                "a score with Measures (or flatten the score before "
                "slicing)")

    if units in ("quarters", "measures", "bars"):
        score.convert_to_quarters()
    elif units in ("s", "sec", "seconds"):
        score.convert_to_seconds()
    else:
        raise ValueError('units must be "quarters", "measures, "'
                         '"bars", "s", "sec", or "seconds"')

    # Find start time and end time for slice. It may not be (start, end)
    # if units is measures or bars.
    if units in ("measures", "bars"):
        (start_time, end_time) = self.measure_times(int(start))
        if end != start:
            (_, end_time) = self.measure_times(int(end) - 1)
    else:
        start_time = start
        end_time = end

    # construct the parts of the tree above self and make an empty copy
    # of self to add the slice content.
    result = (score.emptycopy() if isinstance(self, Score)
              else self._copy_parents(start_time, end_time))
    result.onset = start_time  # result is an empty copy of self. Set the
    result.offset = end_time   # onset and offset to the slice bounds.
    if units in ("measures", "bars"):
        c_min, c_max = result._add_measure_children(self, start, end,
                                                    start_time, end_time)
        if c_min < start_time or c_max > end_time:
            raise ValueError("unexpectedly found content outside the "
                             "measure slice bounds")
        min_time = c_min
        max_time = c_max
    else:   
        min_time, max_time = result._add_slice_children(self, start_time,
                                  end_time, mode, truncate, min_duration)
    result._trim_map_and_signatures(min_time, max_time)
    if shift and min_time != float("inf") and min_time > 0:
        result.time_shift(-min_time)
    return result

remove_measures ¶

remove_measures() -> Staff

Modify Staff by removing all Measures.

Notes are “lifted” from Measures to become direct content of this Staff. There is no special handling for notes tied to or from another Staff, so normally this method should be used only on a Staff where ties have been merged (see merge_tied_notes()). This method is normally called from remove_measures() in Part, which insures that this Staff is not shared, so it is safe to modify it. If called directly, the caller, to avoid unintended side effects, must ensure that this Staff is not shared data. Only Note and KeySignature objects are copied from Measures to the Staff. All other objects are removed.

Returns:

Staff –

A Staff with all Measures removed.

Source code in amads/core/basics.py

def remove_measures(self) -> "Staff":
    """Modify Staff by removing all Measures.

    Notes are “lifted” from Measures to become direct content of this
    Staff. There is no special handling for notes tied to or from another
    Staff, so normally this method should be used only on a Staff where
    ties have been merged (see `merge_tied_notes()`).
    This method is normally called from `remove_measures()` in Part,
    which insures that this Staff is not shared, so it is safe to
    modify it. If called directly, the caller, to avoid unintended
    side effects, must ensure that this Staff is not shared data.
    Only Note and KeySignature objects are copied from Measures
    to the Staff. All other objects are removed.

    Returns
    -------
    Staff
        A Staff with all Measures removed.
    """
    new_content = []
    for measure in self.content:
        if isinstance(measure, Measure):
            for event in measure.content:
                if isinstance(event, (Note, KeySignature)):
                    new_content.append(event)
                # else ignore the event
        else:  # non-Measure objects are simply copied
            new_content.append(measure)
    self.content = new_content
    return self

Part ¶

Part(
    *args: Event,
    parent: Optional[Score] = None,
    onset: float = 0.0,
    duration: Optional[float] = None,
    number: Optional[str] = None,
    instrument: Optional[str] = None,
    flat: bool = False
)

Bases: EventGroup

A Part models a staff or staff group such as a grand staff.

For that reason, a Part contains one or more Staff objects. It should not contain any other object types. Parts are normally elements of a Score. Note that in a flat score, a Part is a collection of Notes, not Staffs, and it should be organized more sequentially than concurrently, so the default assignment of onset times may not be appropriate.

See Constructor Details.

Part is an EventGroup rather than a Sequence or Concurrence because in flat scores, it acts like a Sequence of notes, but in full scores, it is like a Concurrence of Staff objects.

Parameters:

*args (Optional[Event], default: () ) –

A variable number of Event objects to be added to the group. parent : Optional[EventGroup] The containing object or None. Must be passed as a keyword parameter due to *args.
onset (Optional[float], default: 0.0 ) –

The onset (start) time. If unknown (None), it will be set when this Part is added to a parent. Must be passed as a keyword parameter due to *args.
duration (Optional[float], default: None ) –

The duration in quarters or seconds. (If duration is omitted or None, the duration is set so that self.offset ends at the max offset of args, or 0 if there is no content.) Must be passed as a keyword parameter due to *args.
number (Optional[str], default: None ) –

A string representing the part number.
instrument (Optional[str], default: None ) –

A string representing the instrument name.
flat (bool, default: False ) –

If true, content in *args with onset None are modified to start at the offset of the previous note (or at onset if this is the first Event in *args, or at 0.0 if onset is unspecified). Otherwise, this is assumed to be a Part in a full score, *args is assumed to contain Staffs, and their default onset times are given onset by onset (or 0.0 if onset is unspecified). This must be passed as a keyword argument due to *args.

Attributes:

parent (Optional[EventGroup]) –

The containing object or None.
_onset (float) –

The onset (start) time.
duration (float) –

The duration in quarters or seconds.
content (list[Event]) –

Elements contained within this collection.
number (Union[str, None]) –

A string representing the part number (if any). E.g., "22a".
instrument (Union[str, None]) –

A string representing the instrument name (if any).

Notes

Standard MIDI File tracks often have text instrument names in
type 4 meta events. These are stored in the `instrument` attribute.
Tracks often contain events for a single MIDI channel and a single
“program” that is another representation of “instrument.” In fact,
the `pretty_midi` library considers MIDI program to be a property
of the track rather than a timed event within the track (many
sequencers use this model as well). Therefore, if there is a
single MIDI program in a track (or an AMADS Part), the program
number (int) is stored in `info` using the key `"midi_program"`.

Source code in amads/core/basics.py

def __init__(self, *args: Event,
             parent: Optional[Score] = None,
             onset: float = 0.0,
             duration: Optional[float] = None,
             number: Optional[str] = None,
             instrument: Optional[str] = None,
             flat: bool = False):
    content = list(args)
    if flat:  # adjust onsets to form a sequence (must be done before
        prev_onset : float = 0.0  # onset of previous note
        prev_offset : float = 0.0  # offset of previous note
        if not onset is None:
            prev_onset = onset
            prev_offset = onset
        for elem in content:
            if elem.parent and elem.parent != self:
                raise ValueError("Event already has a parent")
            elem.parent = self  # type: ignore
            if elem.onset is None:
                elem.onset = prev_offset
            elif elem.onset < prev_onset:
                raise ValueError("Event onsets are not in time order")
            prev_onset = elem.onset
            prev_offset = elem.offset
        packed_args = []
    super().__init__(parent, onset, duration, content)
    self.number = number
    self.instrument = instrument

Attributes¶

onset `property` `writable` ¶

onset: float

Retrieve the onset (start) time.

If the onset is None, raise an exception. (Events can have None onset times, but they must be set before retrieval. onsets that are None are automatically set when the Event is added to an EventGroup.)

Returns:

float –

The onset (start) time.

Raises:

ValueError –

If the onset time is not set (None).

units_are_seconds `property` ¶

units_are_seconds: bool

Check if the times are in seconds.

This event must be in a Score (where _units_are_seconds is stored).

Returns:

bool –

True iff the event's times are in seconds. If not in a score, False is returned.

units_are_quarters `property` ¶

units_are_quarters: bool

Check if the times are in quarters.

This event must be in a Score (where _units_are_seconds is stored).

Returns:

bool –

True iff the event's times are in quarters. If not in a score, False is returned.

offset `property` `writable` ¶

offset: float

Retrieve the global offset (stop) time.

Returns:

float –

The global offset (stop) time.

part `property` ¶

part: Optional[Part]

Retrieve the Part containing this event.

Returns:

Optional[Part] –

The Part containing this event or None if not found.

score `property` ¶

score: Optional[Score]

Retrieve the Score containing this event, or self if it is a score.

Returns:

Optional[Score] –

The Score containing this event or None if not found.

staff `property` ¶

staff: Optional[Staff]

Retrieve the Staff containing this event

Returns:

Optional[Staff] –

The Staff containing this event or None if not found.

measure `property` ¶

measure: Optional[Measure]

Retrieve the Measure containing this event

Returns:

Optional[Measure] –

The Measure containing this event or None if not found.

Functions¶

set ¶

set(property: str, value: Any) -> Event

Set a named property on this Event.

Every event can be extended with additional properties. Although Python objects are already extensible with new attributes, new attributes that are not set in __init__ confuse type checkers and other tools, so every Event has an info attribute as a dictionary where additional, application-specific information can be stored. The info attribute is None to save space until the first property is set, so you should use set and get methods and avoid writing event.info[property].

Parameters:

property (str) –

The name of the property to set.
value (Any) –

The value to assign to the property.

Returns:

Event –

returns this object (self)

Examples:

>>> note = Note()
>>> note.get("color", "no color")
'no color'
>>> _ = note.set("color", "red").set("harmonicity", 0.2)
>>> (note.has("color"), note.has("shape"))
(True, False)
>>> (note.get("color"), note.get("harmonicity"))
('red', 0.2)

Source code in amads/core/basics.py

def set(self, property : str, value : Any) -> "Event":
    """Set a named property on this Event.

    Every event can be extended with additional properties. Although
    Python objects are already extensible with new attributes, new
    attributes that are not set in `__init__` confuse type checkers
    and other tools, so every `Event` has an `info` attribute as a
    dictionary where additional, application-specific information can
    be stored. The `info` attribute is `None` to save space until the
    first property is set, so you should use `set` and `get` methods
    and avoid writing `event.info[property]`.

    Parameters
    ----------
    property : str
        The name of the property to set.
    value : Any
        The value to assign to the property.

    Returns
    -------
    Event
        returns this object (self)

    Examples
    --------
    >>> note = Note()
    >>> note.get("color", "no color")
    'no color'
    >>> _ = note.set("color", "red").set("harmonicity", 0.2)
    >>> (note.has("color"), note.has("shape"))
    (True, False)
    >>> (note.get("color"), note.get("harmonicity"))
    ('red', 0.2)
    """
    if self.info is None:
        self.info = {}
    self.info[property] = value
    return self

get ¶

get(property: str, default: Any = None) -> Any

Get the value of a property from this Event.

See set for more details.

Parameters:

property (str.) –

The name of the property to get.
default (Any, default: None ) –

The default value to return if the property is not found.

Returns:

Any –

The value of the specified property.

Source code in amads/core/basics.py

def get(self, property : str, default : Any = None) -> Any:
    """Get the value of a property from this Event.

    See [set][amads.core.basics.Event.set] for more details.

    Parameters
    ----------
    property : str.
        The name of the property to get.
    default : Any
        The default value to return if the property is not found.

    Returns
    -------
    Any
        The value of the specified property.
    """
    if self.info is None:
        return default
    return self.info.get(property, default)

has ¶

has(property) -> bool

Check if the Event has a specific property.

See set for more details.

Parameters:

property (str) –

The name of the property to check.

Returns:

bool –

True if the property exists, False otherwise.

Source code in amads/core/basics.py

def has(self, property) -> bool:
    """Check if the Event has a specific property.

    See [set][amads.core.basics.Event.set] for more details.

    Parameters
    ----------
    property : str
        The name of the property to check.

    Returns
    -------
    bool
        True if the property exists, False otherwise.
    """
    return (self.info is not None) and (property in self.info)

time_shift ¶

time_shift(increment: float, content_only: bool = False) -> EventGroup

Change the onset by an increment, affecting all content.

If content_only is true, preserves EventGroup times (Score, Part, Staff, but not Chord or Measure) and shifts only the content (recursively). Otherwise, shifts this container and all content by the increment. Container onsets (recursively) are not allowed to become negative, so the onset time is set to zero if the increment would make it negative. However, even if the onset is is not shifted by increment, time_shift is still applied recursively to the content, and non-EventGroup events (e.g., Notes) are allowed to have negative onsets, even if this may not be well-defined for all AMADS operations.

Parameters:

increment (float) –

The time increment (in quarters or seconds).
content_only (bool, default: False ) –

If true, preserves this container's time and shifts only the content.

Returns:

Event –

The object. This method modifies the EventGroup.

Raises:

ValueError –

If the EventGroup has an unknown (None) onset and content_only is false.

Source code in amads/core/basics.py

def time_shift(self, increment: float,
               content_only: bool = False) -> "EventGroup":
    """
    Change the onset by an increment, affecting all content.

    If content_only is true, preserves EventGroup times (Score, Part,
    Staff, but *not* Chord or Measure) and shifts only the content
    (recursively). Otherwise, shifts this container and all content by the
    increment. Container onsets (recursively) are not allowed to become
    negative, so the onset time is set to zero if the increment would
    make it negative. However, even if the onset is is not shifted by
    increment, time_shift is still applied recursively to the content,
    and non-EventGroup events (e.g., Notes) are allowed to have negative
    onsets, even if this may not be well-defined for all AMADS operations.

    Parameters
    ----------
    increment : float
        The time increment (in quarters or seconds).
    content_only: bool
        If true, preserves this container's time and shifts only
        the content.

    Returns
    -------
    Event
        The object. This method modifies the `EventGroup`.

    Raises
    ------
    ValueError
        If the EventGroup has an unknown (None) onset and
        content_only is false.
    """
    # note that Chord and Measures are special cases
    if not content_only or isinstance(self, (Chord, Measure)):
        if self._onset is None:
            raise ValueError(
                    "Cannot shift time of EventGroup with unknown onset")
        self._onset = max(0.0, self._onset + increment)
    for elem in self.content:
        elem.time_shift(increment, content_only)
    return self

insert_copy_into ¶

insert_copy_into(parent: Optional[EventGroup] = None) -> Event

Make a (mostly) deep copy of the Event and add to a new parent.

Pitch objects are considered immutable and are shared rather than copied.

Parameters:

parent (Optional(EventGroup), default: None ) –

The copied Event will be a child of parent if not None. The parent is modified by this operation.

Returns:

Event –

A deep copy (except for parent and pitch) of the Event instance.

Source code in amads/core/basics.py

def insert_copy_into(self,
                     parent: Optional["EventGroup"] = None) -> "Event":
    """
    Make a (mostly) deep copy of the `Event` and add to a new `parent`.

    `Pitch` objects are considered immutable and are shared rather
    than copied.

    Parameters
    ----------
    parent : Optional(EventGroup)
        The copied `Event` will be a child of `parent` if not `None`.
        The parent is modified by this operation.

    Returns
    -------
    Event
        A deep copy (except for parent and pitch) of the Event instance.
    """
    # remove link to parent to break link going up the tree
    # preventing deep copy from copying the entire tree
    original_parent = self.parent
    self.parent = None
    c = copy.deepcopy(self)  # deep copy of this event down to leaf nodes
    self.parent = original_parent  # restore link to parent
    if parent:
        parent.insert(c)
    return c

ismonophonic ¶

ismonophonic() -> bool

Determine if content is monophonic (non-overlapping notes).

A monophonic list of notes has no overlapping notes (e.g., chords). Serves as a helper function for ismonophonic and parts_are_monophonic.

Returns:

bool –

True if the list of notes is monophonic, False otherwise.

Source code in amads/core/basics.py

def ismonophonic(self) -> bool:
    """
    Determine if content is monophonic (non-overlapping notes).

    A monophonic list of notes has no overlapping notes (e.g., chords).
    Serves as a helper function for `ismonophonic` and
    `parts_are_monophonic`.

    Returns
    -------
    bool
        True if the list of notes is monophonic, False otherwise.
    """
    prev = None
    notes = self.list_all(Note)
    # Sort the notes by start time
    notes.sort(key=lambda note: note.onset)
    # Check for overlaps
    for note in notes:
        if prev:
            # 0.01 is to prevent precision errors when comparing floats
            if note.onset - prev.offset < -0.01:
                return False
        prev = note
    return True

insert_emptycopy_into ¶

insert_emptycopy_into(
    parent: Optional[EventGroup] = None,
) -> EventGroup

Create a deep copy of the EventGroup except for content.

A new parent is provided as an argument and the copy is inserted into this parent. This method is useful for copying an EventGroup without copying its content. See also insert_copy_into to copy an EventGroup with its content into a new parent.

Parameters:

parent (Optional[EventGroup], default: None ) –

The new parent to insert the copied Event into.

Returns:

EventGroup –

A deep copy of the EventGroup instance with the new parent (if any) and no content.

Source code in amads/core/basics.py

def insert_emptycopy_into(self, 
            parent: Optional["EventGroup"] = None) -> "EventGroup":
    """Create a deep copy of the EventGroup except for content.

    A new parent is provided as an argument and the copy is inserted
    into this parent. This method is  useful for copying an
    EventGroup without copying its content.  See also
    [insert_copy_into][amads.core.basics.Event.insert_copy_into] to
    copy an EventGroup *with* its content into a new parent.

    Parameters
    ----------
    parent : Optional[EventGroup]
        The new parent to insert the copied Event into.

    Returns
    -------
    EventGroup
        A deep copy of the EventGroup instance with the new parent
        (if any) and no content.
    """
    # rather than customize __deepcopy__, we "hide" the content to avoid
    # copying it. Then we restore it after copying and fix parent.
    original_content = self.content
    self.content = []
    c = self.insert_copy_into(parent)
    self.content = original_content
    return c  #type: ignore (c will always be an EventGroup)

expand_chords ¶

expand_chords(parent: Optional[EventGroup] = None) -> EventGroup

Replace chords with the multiple notes they contain.

Returns a deep copy with no parent unless parent is provided. Normally, you will call score.expand_chords() which returns a deep copy of Score with notes moved from each chord to the copy of the chord's parent (a Measure or a Part). The parent parameter is primarily for internal use when expand_chords is called recursively on score content.

Parameters:

parent (EventGroup, default: None ) –

The new parent to insert the copied EventGroup into.

Returns:

EventGroup –

A deep copy of the EventGroup instance with all Chord instances expanded.

Source code in amads/core/basics.py

def expand_chords(self,
                  parent: Optional["EventGroup"] = None) -> "EventGroup":
    """Replace chords with the multiple notes they contain.

    Returns a deep copy with no parent unless parent is provided.
    Normally, you will call `score.expand_chords()` which returns a deep
    copy of Score with notes moved from each chord to the copy of the
    chord's parent (a Measure or a Part). The parent parameter is 
    primarily for internal use when `expand_chords` is called recursively
    on score content.

    Parameters
    ----------
    parent : EventGroup
        The new parent to insert the copied EventGroup into.

    Returns
    -------
    EventGroup
        A deep copy of the EventGroup instance with all
        Chord instances expanded.
    """
    group = self.insert_emptycopy_into(parent)
    for item in self.content:
        if isinstance(item, Chord):
            for note in item.content:  # expand chord
                note.insert_copy_into(group)
        if isinstance(item, EventGroup):
            item.expand_chords(group)  # recursion for deep copy/expand
        else:
            item.insert_copy_into(group)  # deep copy non-EventGroup
    return group

find_all ¶

find_all(elem_type: Type[Event]) -> Generator[Event, None, None]

Find all instances of a specific type within the EventGroup.

Assumes that objects of type elem_type are not nested within other objects of the same type. (The first elem_type encountered in a depth-first enumeration is returned without looking at any children in its content).

Parameters:

elem_type (Type[Event]) –

The type of event to search for.

Yields:

Event –

Instances of the specified type found within the EventGroup.

Source code in amads/core/basics.py

def find_all(self, elem_type: Type[Event]) -> Generator[Event, None, None]:
    """Find all instances of a specific type within the EventGroup.

    Assumes that objects of type `elem_type` are not nested within
    other objects of the same type. (The first `elem_type` encountered
    in a depth-first enumeration is returned without looking at any
    children in its `content`).

    Parameters
    ----------
    elem_type : Type[Event]
        The type of event to search for.

    Yields
    -------
    Event
        Instances of the specified type found within the EventGroup.
    """
    # Algorithm: depth-first enumeration of EventGroup content.
    # If elem_types are nested, only the top-level elem_type is
    # returned since it is found first, and the content is not
    # searched. This makes it efficient, e.g., to search for
    # Parts in a Score without enumerating all Notes within.
    for elem in self.content:
        if isinstance(elem, elem_type):
            yield elem
        elif isinstance(elem, EventGroup):
            yield from elem.find_all(elem_type)

get_sorted_notes ¶

get_sorted_notes(has_ties: bool = True) -> List[Note]

Return a list of sorted notes with merged ties.

This should generally be called on Parts and Scores since in all other EventGroups, Events are in time order and Notes retrieved with find_all() or list_all() are in time order. However, get_sorted_notes also sorts notes into increasing pitch (keynum) where note onsets are equal.

Parameters:

has_ties (bool, default: True ) –

If True (default), copy the score, merge the ties, and return a list of these merged copies. If False, assume there are no ties and return a list of original notes.

Raises:

ValueError –

If has_ties is False, but a tie is encountered.

Returns:

list(Note) –

a list of sorted notes with merged ties

Source code in amads/core/basics.py

def get_sorted_notes(self, has_ties: bool = True) -> List[Note]:
    """Return a list of sorted notes with merged ties.

    This should generally be called on Parts and Scores since
    in all other EventGroups, Events are in time order and
    Notes retrieved with `find_all()` or `list_all()` are in
    time order. However, `get_sorted_notes` *also* sorts notes
    into increasing pitch (`keynum`) where note onsets are equal.

    Parameters
    ----------
    has_ties: bool
        If True (default), copy the score, merge the ties, and
        return a list of these merged copies. If False, assume
        there are no ties and return a list of original notes.

    Raises
    ------
    ValueError
        If has_ties is False, but a tie is encountered.

    Returns
    -------
    list(Note)
        a list of sorted notes with merged ties
    """
    if has_ties:
        # after flatten, score will have one Part with all Notes:
        return self.flatten(collapse=True).content[0].content  # type: ignore
    else:
        notes : List[Note] = cast(List[Note], self.list_all(Note))
        for note in notes:
            if note.tie is not None:
                raise ValueError(
                        "tie found by get_sorted_notes with has_ties=False")
        notes.sort(key=lambda x: (x.onset, x.pitch))
        return notes

has_instanceof ¶

has_instanceof(the_class: Type[Event]) -> bool

Test if EventGroup contains any instances of the_class.

Parameters:

the_class (Type[Event]) –

The class type to check for.

Returns:

bool –

True iff the EventGroup contains an instance of the_class.

Source code in amads/core/basics.py

def has_instanceof(self, the_class: Type[Event]) -> bool:
    """Test if EventGroup contains any instances of `the_class`.

    Parameters
    ----------
    the_class : Type[Event]
        The class type to check for.

    Returns
    -------
    bool
        True iff the EventGroup contains an instance of the_class.
    """
    instances = self.find_all(the_class)
    # if there are no instances (of the_class), next will return "empty":
    return next(instances, "empty") != "empty"

has_rests ¶

has_rests() -> bool

Test if EventGroup (e.g., Score, Part, ...) has any Rest objects.

Returns:

bool –

True iff the EventGroup contains any Rest objects.

Source code in amads/core/basics.py

def has_rests(self) -> bool:
    """Test if EventGroup (e.g., Score, Part, ...) has any `Rest` objects.

    Returns
    -------
    bool
        True iff the EventGroup contains any Rest objects.
    """
    return self.has_instanceof(Rest)

has_chords ¶

has_chords() -> bool

Test if EventGroup (e.g., Score, Part, ...) has any Chord objects.

Returns:

bool –

True iff the EventGroup contains any Chord objects.

Source code in amads/core/basics.py

def has_chords(self) -> bool:
    """Test if EventGroup (e.g., Score, Part, ...) has any Chord objects.

    Returns
    -------
    bool
        True iff the EventGroup contains any Chord objects.
    """
    return self.has_instanceof(Chord)

has_ties ¶

has_ties() -> bool

Test if EventGroup (e.g., Score, Part, ...) has any tied notes.

Returns:

bool –

True iff the EventGroup contains any tied notes.

Source code in amads/core/basics.py

def has_ties(self) -> bool:
    """Test if EventGroup (e.g., Score, Part, ...) has any tied notes.

    Returns
    -------
    bool
        True iff the EventGroup contains any tied notes.
    """
    notes = self.find_all(Note)
    for note in notes:
        if note.tie:
            return True
    return False

has_measures ¶

has_measures() -> bool

Test if EventGroup (e.g., Score, Part, ...) has any Measures.

Returns:

bool –

True iff the EventGroup contains any Measure objects.

Source code in amads/core/basics.py

def has_measures(self) -> bool:
    """Test if EventGroup (e.g., Score, Part, ...) has any Measures.

    Returns
    -------
    bool
        True iff the EventGroup contains any Measure objects.
    """
    return self.has_instanceof(Measure)

inherit_duration ¶

inherit_duration() -> EventGroup

Set the duration of this EventGroup according to maximum offset.

The duration is set to the maximum offset (end) time of the children. If the EventGroup is empty, the duration is set to 0. This method modifies this EventGroup instance.

Returns:

EventGroup –

The EventGroup instance (self) with updated duration.

Source code in amads/core/basics.py

def inherit_duration(self) -> "EventGroup":
    """Set the duration of this EventGroup according to maximum offset.

    The `duration` is set to the maximum offset (end) time of the
    children. If the EventGroup is empty, the duration is set to 0.
    This method modifies this `EventGroup` instance.

    Returns
    -------
    EventGroup
        The EventGroup instance (self) with updated duration.
    """
    onset = 0 if self._onset == None else self._onset
    max_offset = onset
    for elem in self.content:
        max_offset = max(max_offset, elem.offset)
    self.duration = max_offset - onset

    return self

insert ¶

insert(event: Event) -> EventGroup

Insert an event.

Sets the parent of event to this EventGroup and makes event be a member of this EventGroup.content. No changes are made to event.onset or self.duration. Insert event in content just before the first element with a greater onset. The method modifies this object (self).

Parameters:

event (Event) –

The event to be inserted.

Returns:

EventGroup –

The EventGroup instance (self) with the event inserted.

Raises:

ValueError –

If event._onset is None (it must be a number)

Caution Regarding Zero-Duration Event Order

If you have note N with non-zero duration and, at the same time, a grace note G with zero duration, the notes will be ordered according to when they are inserted. So if you insert N and then G, then N will be placed before G. See io.pt_import.py, where this case is dealt with.

Source code in amads/core/basics.py

def insert(self, event: Event) -> "EventGroup":
    """Insert an event.

    Sets the `parent` of `event` to this `EventGroup` and makes `event`
    be a member of this `EventGroup.content`. No changes are made to
    `event.onset` or `self.duration`. Insert `event` in `content` just
    before the first element with a greater onset. The method modifies
    this object (self).

    Parameters
    ----------
    event : Event
        The event to be inserted.

    Returns
    -------
    EventGroup
        The EventGroup instance (self) with the event inserted.

    Raises
    ------
    ValueError
        If event._onset is None (it must be a number)

    Caution Regarding Zero-Duration Event Order
    -------------------------------------------
    If you have note N with non-zero duration and, at the same
    time, a grace note G with zero duration, the notes will be
    ordered according to when they are inserted. So if you insert
    N and then G, then N will be placed *before* G. See
    io.pt_import.py, where this case is dealt with.
    """

    assert not event.parent
    if event._onset is None:  # must be a number
        raise ValueError(f"event's _onset attribute must be a number")
    atend = self.last()
    if atend and event.onset < atend.onset:
        # search in reverse from end
        i = len(self.content) - 2
        while i >= 0 and self.content[i].onset > event.onset:
            i -= 1
        # now i is either -1 or content[i] <= event.onset, so
        # insert event at content[i+1]
        self.content.insert(i + 1, event)
    else:  # simply append at the end of content:
        self.content.append(event)
    event.parent = self
    return self

last ¶

last() -> Optional[Event]

Retrieve the last event in the content list.

Because the content list is sorted by onset, the returned Event is simply the last element of content, but not necessarily the event with the greatest offset.

Returns:

Optional[Event] –

The last event in the content list or None if the list is empty.

Source code in amads/core/basics.py

def last(self) -> Optional[Event]:
    """Retrieve the last event in the content list.

    Because the `content` list is sorted by `onset`, the returned
    `Event` is simply the last element of `content`, but not
    necessarily the event with the greatest *`offset`*.

    Returns
    -------
    Optional[Event]
        The last event in the content list or None if the list is empty.
    """
    return self.content[-1] if len(self.content) > 0 else None

list_all ¶

list_all(elem_type: Type[Event]) -> list[Event]

Find all instances of a specific type within the EventGroup.

Assumes that objects of type elem_type are not nested within other objects of the same type. See also find_all, which returns a generator instead of a list.

Parameters:

elem_type (Type[Event]) –

The type of event to search for.

Returns:

list[Event] –

A list of all instances of the specified type found within the EventGroup.

Source code in amads/core/basics.py

def list_all(self, elem_type: Type[Event]) -> list[Event]:
    """Find all instances of a specific type within the EventGroup.

    Assumes that objects of type `elem_type` are not nested within
    other objects of the same type.  See also
    [find_all][amads.core.basics.EventGroup.find_all], which returns
    a generator instead of a list.

    Parameters
    ----------
    elem_type : Type[Event]
        The type of event to search for.

    Returns
    -------
    list[Event]
        A list of all instances of the specified type found
        within the EventGroup.
    """
    return list(self.find_all(elem_type))

merge_tied_notes ¶

merge_tied_notes(
    parent: Optional[EventGroup] = None, ignore: list[Note] = []
) -> EventGroup

Create a new EventGroup with tied notes replaced by single notes.

If ties cross staffs, the replacement is placed in the staff of the first note in the tied sequence. Insert the new EventGroup into parent.

Ordinarily, this method is called on a Score with no parameters. The parameters are used when Score.merge_tied_notes() calls this method recursively on EventGroups within the Score such as Parts and Staffs.

Parameters:

parent (Optional[EventGroup], default: None ) –

Where to insert the result.
ignore (list[Note], default: [] ) –

This parameter is used internally. Caller should not use this parameter.

Returns:

EventGroup –

A copy with tied notes replaced by equivalent single notes.

Source code in amads/core/basics.py

def merge_tied_notes(self, parent: Optional["EventGroup"] = None,
                     ignore: list[Note] = []) -> "EventGroup":
    """Create a new `EventGroup` with tied notes replaced by single notes.

    If ties cross staffs, the replacement is placed in the staff of the
    first note in the tied sequence. Insert the new `EventGroup` into
    `parent`.

    Ordinarily, this method is called on a Score with no parameters. The
    parameters are used when `Score.merge_tied_notes()` calls this method
    recursively on `EventGroup`s within the Score such as `Part`s and
    `Staff`s.

    Parameters
    ----------
    parent: Optional(EventGroup)
        Where to insert the result.

    ignore: Optional(list[Note])
        This parameter is used internally. Caller should not use
        this parameter.

    Returns
    -------
    EventGroup
        A copy with tied notes replaced by equivalent single notes.
    """
    # Algorithm: Find all notes, removing tied notes and updating
    # duration when ties are found. These tied notes are added to
    # ignore so they can be skipped when they are encountered.

    group = self.insert_emptycopy_into(parent)
    for event in self.content:
        if isinstance(event, Note):
            if event in ignore:  # do not copy tied notes into group;
                if event.tie:
                    ignore.append(event.tie)  # add tied note to ignore
                # We will not see this note again, so
                # we can also remove it from ignore. Removal is expensive
                # but it could be worse for ignore to grow large when there
                # are many ties since we have to search it entirely once
                # per note. An alternate representation might be a set to
                # make searching fast.
                ignore.remove(event)
            else:
                if event.tie:
                    tied_note = event.tie  # save the tied-to note
                    event.tie = None  # block the copy
                    ignore.append(tied_note)
                    # copy note into group:
                    event_copy = event.insert_copy_into(group)
                    event.tie = tied_note  # restore original event
                    # this is subtle: event.tied_duration (a property) will
                    # sum up durations of all the tied notes. Since
                    # event_copy is not tied, the sum of durations is
                    # stored on that one event_copy:
                    event_copy.duration = event.tied_duration
                else:  # put the untied note into group
                    event.insert_copy_into(group)
        elif isinstance(event, EventGroup):
            event.merge_tied_notes(group, ignore)
        else:
            event.insert_copy_into(group)  # simply copy to new parent
    return group

pack ¶

pack(onset: float = 0.0, sequential: bool = False) -> float

Adjust the content to onsets starting with the onset parameter.

By default onsets are set to onset and the duration of self is set to the maximum duration of the content. pack() works recursively on elements that are EventGroups. Setting sequential to True implements sequential packing, where events are placed one after another.

Parameters:

onset (float, default: 0.0 ) –

The onset (start) time for this object.

Returns:

float –

duration of self

Source code in amads/core/basics.py

def pack(self, onset: float = 0.0, sequential : bool = False) -> float:
    """Adjust the content to onsets starting with the onset parameter.

    By default onsets are set to `onset` and the duration of self is set to
    the maximum duration of the content. pack() works recursively on
    elements that are EventGroups. Setting sequential to True implements
    sequential packing, where events are placed one after another.

    Parameters
    ----------
    onset : float
        The onset (start) time for this object.

    Returns
    -------
    float
        duration of self
    """
    self.onset = onset
    self.duration = 0
    for elem in self.content:
        elem.onset = onset
        if isinstance(elem, EventGroup):   # either Sequence or Concurrence
            elem.duration = elem.pack(onset)  #type: ignore
        if sequential:
            onset += elem.duration
        else:
            self.duration = max(self.duration, elem.duration)
    if sequential:
        self.duration = onset - self.onset
    return self.duration

quantize ¶

quantize(divisions: int) -> EventGroup

Align onsets and durations to a rhythmic grid.

Assumes time units are quarters. (See Score.convert_to_quarters.)

Modify all times and durations to a multiple of divisions per quarter note, e.g., 4 for sixteenth notes. Onsets and offsets are moved to the nearest quantized time. Any resulting duration change is less than one quantum, but not necessarily less than 0.5 quantum, since the onset and offset can round in opposite directions by up to 0.5 quantum each. Any non-zero duration that would quantize to zero duration gets a duration of one quantum since zero duration is almost certainly going to cause notation and visualization problems.

Special cases for zero duration:

If the original duration is zero as in metadata or possibly grace notes, we preserve that.
If a tied note duration quantizes to zero, we remove the tied note entirely provided some other note in the tied sequence has non-zero duration. If all tied notes quantize to zero, we keep the first one and set its duration to one quantum.

This method modifies this EventGroup and all its content in place.

Note that there is no way to specify "sixteenths or eighth triplets" because 6 would not allow sixteenths and 12 would admit sixteenth triplets. Using tuples as in Music21, e.g., (4, 3) for this problem creates another problem: if quantization is to time points 1/4, 1/3, then the difference is 1/12 or a thirty-second triplet. If the quantization is applied to durations, then you could have 1/4 + 1/3 = 7/12, and the remaining duration in a single beat would be 5/12, which is not expressible as sixteenths, eighth triplets or any tied combination.

Parameters:

divisions (int) –

The number of divisions per quarter note, e.g., 4 for sixteenths, to control quantization.

Returns:

EventGroup –

The EventGroup instance (self) with (modified in place) quantized times.

Source code in amads/core/basics.py

def quantize(self, divisions: int) -> "EventGroup":
    """Align onsets and durations to a rhythmic grid.

    Assumes time units are quarters. (See [Score.convert_to_quarters](
            basics.md#amads.core.basics.Score.convert_to_quarters).)

    Modify all times and durations to a multiple of divisions
    per quarter note, e.g., 4 for sixteenth notes. Onsets and offsets
    are moved to the nearest quantized time. Any resulting duration
    change is less than one quantum, but not necessarily less than
    0.5 quantum, since the onset and offset can round in opposite
    directions by up to 0.5 quantum each. Any non-zero duration that would
    quantize to zero duration gets a duration of one quantum since
    zero duration is almost certainly going to cause notation and
    visualization problems.

    Special cases for zero duration:

    1. If the original duration is zero as in metadata or possibly
           grace notes, we preserve that.
    2. If a tied note duration quantizes to zero, we remove the
           tied note entirely provided some other note in the tied
           sequence has non-zero duration. If all tied notes quantize
           to zero, we keep the first one and set its duration to
           one quantum.

    This method modifies this EventGroup and all its content in place.

    Note that there is no way to specify "sixteenths or eighth triplets"
    because 6 would not allow sixteenths and 12 would admit sixteenth
    triplets. Using tuples as in Music21, e.g., (4, 3) for this problem
    creates another problem: if quantization is to time points 1/4, 1/3,
    then the difference is 1/12 or a thirty-second triplet. If the
    quantization is applied to durations, then you could have 1/4 + 1/3
    = 7/12, and the remaining duration in a single beat would be 5/12,
    which is not expressible as sixteenths, eighth triplets or any tied
    combination.

    Parameters
    ----------
    divisions : int
        The number of divisions per quarter note, e.g., 4 for
        sixteenths, to control quantization.

    Returns
    -------
    EventGroup
        The EventGroup instance (self) with (modified in place) 
        quantized times.
    """

    super()._quantize(divisions)
    # iterating through content is tricky because we may delete a
    # Note, shifting the content:
    i = 0
    while i < len(self.content):
        event = self.content[i]
        event._quantize(divisions)
        if event == self.content[i]:
            i += 1
        # otherwise, we deleted event so the next event to
        # quantize is at index i; don't incremenet i
    return self

remove ¶

remove(element: Event) -> EventGroup

Remove an element from the content list.

The method modifies this object (self).

Parameters:

element (Event) –

The event to be removed.

Returns:

EventGroup –

The EventGroup instance (self) with the element removed. The returned value is not a copy.

Source code in amads/core/basics.py

def remove(self, element: Event) -> "EventGroup":
    """Remove an element from the content list. 

    The method modifies this object (self).

    Parameters
    ----------
    element : Event
        The event to be removed.

    Returns
    -------
    EventGroup
        The EventGroup instance (self) with the element removed.
        The returned value is not a copy.
    """
    self.content.remove(element)
    element.parent = None
    return self

remove_rests ¶

remove_rests(parent: Union[EventGroup, None] = None) -> EventGroup

Remove all Rest objects from content.

Returns a deep copy with no parent unless parent is provided.

Parameters:

parent (EventGroup, default: None ) –

The new parent to insert the copied Event into.

Returns:

EventGroup –

A deep copy of the EventGroup instance with all Rest objects removed.

Source code in amads/core/basics.py

def remove_rests(self, parent: Union["EventGroup", 
                                     None] = None) -> "EventGroup":
    """Remove all Rest objects from content.

    Returns a deep copy with no parent unless parent is provided.

    Parameters
    ----------
    parent : EventGroup
        The new parent to insert the copied Event into.

    Returns
    -------
    EventGroup
        A deep copy of the EventGroup instance with all Rest
        objects removed.
    """
    # implementation detail: when called without argument, remove_rests
    # makes a deep copy of the subtree and returns the copy without a
    # parent. remove_rests calls itself recursively *with* a parameter
    # indicating that the subtree copy should be inserted into a
    # parent which is the new copy at the next level up. Of course,
    # we check for and ignore Rests so they are never copied.
    group = self.insert_emptycopy_into(parent)
    for item in self.content:
        if isinstance(item, Rest):
            continue  # skip the Rests while making deep copy
        if isinstance(item, EventGroup):
            item.remove_rests(group)  # recursion for deep copy
        else:
            item.insert_copy_into(group)  # deep copy non-EventGroup
    return group

show ¶

show(indent: int = 0, file: Optional[TextIO] = None) -> EventGroup

Print the EventGroup information.

Parameters:

indent (int, default: 0 ) –

The indentation level for display.

Returns:

EventGroup –

The EventGroup instance itself.

Source code in amads/core/basics.py

def show(self, indent: int = 0,
        file: Optional[TextIO] = None) -> "EventGroup":
    """Print the EventGroup information.

    Parameters
    ----------
    indent : int
        The indentation level for display.

    Returns
    -------
    EventGroup
        The EventGroup instance itself.
    """
    print(" " * indent, self, sep="", file=file)
    for elem in self.content:
        elem.show(indent + 4, file=file)  # type: ignore (show exists)
    return self

measure_times ¶

measure_times(n: int) -> tuple[float, float]

Return the start and end times of measure n.

Parameters:

n (int) –

The 0-based measure number.

Returns:

tuple(float, float) –

A tuple containing the start and end times of measure n. Measure 0 is the first measure. Units are the same as the score's time units.

Raises:

ValueError –

If there is no measure with number n.

Source code in amads/core/basics.py

def measure_times(self, n: int) -> tuple[float, float]:
    """Return the start and end times of measure n.

    Parameters
    ----------
    n : int
        The 0-based measure number.

    Returns
    -------
    tuple(float, float)
        A tuple containing the start and end times of measure n.
        Measure 0 is the first measure.  Units are the same as the
        score's time units.

    Raises
    ------
    ValueError
        If there is no measure with number n.
    """
    # Algorithm: For each Staff, linear search for nth Measure, returning
    # the onset and offset of the first one found.
    for staff in self.find_all(Staff):
        staff = cast(Staff, staff)
        for i, measure in enumerate(staff.find_all(Measure)):
            if i == n:
                return (measure.onset, measure.offset)
    raise ValueError(f"measure {n} not found")

slice ¶

slice(
    start: float,
    end: float,
    units: str = "quarters",
    mode: str = "onsets",
    truncate: str = "keep",
    shift: bool = False,
    min_duration: float = 0.05,
) -> EventGroup

Create a new Score containing the content between start and end.

Typically, this method is called on a Score to create a new Score, but it works on any Sequence as long as the sequence is part of a Score.

If self has Measures, units must be "measures" or "bars", the start and end parameters are interpreted as 0-based measure numbers, and the result will therefore contain whole measures. It is assumed that notes are tied across measure boundaries. The result will contain only the parts of tied notes that are within the specified measures, excluding measure numbered by end.

For any units besides "measures" or "bars", the score must be flat. Notes that extend beyond the start or end time are included in the result unless the truncate parameter specifies otherwise.

In principle, there is no reason to require a flat score for slicing by time, but there are many difficult edge cases to consider such as ties from within one chord to a note in another measure. Therefore, to slice by time or quarter, you must have a flattened score. Conversely, to slice a full score, you must slice by measure so that the result gives you whole measures, which are encoded into the full Score structure.

The entire result can be shifted to start at time 0 by setting the shift parameter to True. Unless truncate is "truncate" or "beginning", the result can include events that start before the start time, in which case shifting will only shift the earliest onset to 0, which means the shift amount depends upon the content. (Negative onsets are currently not allowed.)

The resulting Score, Part, and other content will have onset and offset times matching start and end, even if some content starts earlier or ends later.

Parameters:

start (float) –

The start time of the slice, inclusive. If units is "measures" or "bars", start is a 0-based measure number of the first measure.
end (float) –

The end time of the slice, exclusive. For measures, end is the 0-based measure number of the last measure plus one, so the last measure is end - 1.
units (str, default: 'quarters' ) –

The time units for start and end. Valid values are "quarters", "s", "sec", "seconds", "measures", or "bars".
shift (bool, default: False ) –

If true, shift the content in the result so that the result starts time 0.0. If false (default), the content in the result retains the same time values as in the original Score.
mode (Optional[str], default: 'onsets' ) –
The slicing mode, ignored if units is "measures" or "bars". Valid values are:
- "onsets" - include events that start within bounds (default)
- "overlaps" - include events that overlap (either onset or offset) is within the bounds. An event ending is considered to overlap if its offset is greater than start.
- "offsets" - include events that end within the bounds
- "strict" - include only events that start at or after start and end at or before end. (End times that are exactly equal to end are considered to be within bounds, so this is inclusive of end time.)
truncate (str, default: 'keep' ) –
How to handle events that partially overlap the bounds, ignored if units is "measures" or "bars". Valid values are:
- "truncate" - truncate (clip) events that partially overlap the bounds. If the event onset is before start, the onset is increased to start (adjusting duration to maintain the offset time). Also, if the event offset is after end, the duration is decreased so that the offset time is end.
- "keep" - no modification/truncation (default). Note that with the default mode="onsets", no event onsets will be earlier than start, but offsets may extend beyond end.
- "end" or "ending" or "dur" or "duration" - truncate (clip) events that extend beyond end so that all offsets <= end.
- "beginning" - events with onsets before start are moved to make their onsets equal to start, and their duration is adjusted to maintain the original offset.
min_duration (float, default: 0.05 ) –

Events with duration less than min_duration (after any truncation is applied) are removed. Ignored if units is "measures" or "bars". If None or 0.0, no events are removed. The default is 0.05, independent of time units. Be careful with gracenotes that, when read from MusicXML, have zero duration.

Returns:

Score –

A new Score instance containing the content between start and end.

Raises:

ValueError –

If the Sequence is not part of a Score, or if invalid values are provided for the parameters.

Source code in amads/core/basics.py

def slice(self, start: float, end: float, units: str = "quarters",
          mode: str = "onsets", truncate: str = "keep", shift: bool = False,
          min_duration: float = 0.05) -> "EventGroup":
    """
    Create a new Score containing the content between start and end.

    Typically, this method is called on a Score to create a new Score,
    but it works on any Sequence as long as the sequence is part of a Score.

    If self has Measures, units must be "measures" or "bars", the start and
    end parameters are interpreted as 0-based measure numbers, and the
    result will therefore contain whole measures. It is assumed that notes
    are tied across measure boundaries. The result will contain only the
    parts of tied notes that are within the specified measures, excluding
    measure numbered by `end`.

    For any units besides "measures" or "bars", the score must be flat.
    Notes that extend beyond the start or end time are included in the
    result unless the `truncate` parameter specifies otherwise.

    In principle, there is no reason to require a flat score for slicing by
    time, but there are many difficult edge cases to consider such as ties
    from within one chord to a note in another measure. Therefore, to slice
    by time or quarter, you must have a flattened score. Conversely, to
    slice a full score, you must slice by measure so that the result gives
    you whole measures, which are encoded into the full Score structure.

    The entire result can be shifted to start at time 0 by setting the
    `shift` parameter to True.  Unless `truncate` is "truncate" or
    "beginning", the result can include events that start before the start
    time, in which case shifting will only shift the earliest onset to 0,
    which means the shift amount depends upon the content. (Negative onsets
    are currently not allowed.)

    The resulting Score, Part, and other content will have onset and offset
    times matching start and end, even if some content starts earlier or
    ends later.

    Parameters
    ----------
    start : float
        The start time of the slice, inclusive. If units is "measures" or
        "bars", start is a 0-based measure number of the first measure.
    end : float
        The end time of the slice, exclusive. For measures, end is the
        0-based measure number of the last measure plus one, so the last
        measure is end - 1.
    units : str
        The time units for start and end. Valid values are "quarters", "s",
        "sec", "seconds", "measures", or "bars".
    shift: bool
        If true, shift the content in the result so that the result starts
        time 0.0. If false (default), the content in the result retains
        the same time values as in the original Score.
    mode : Optional[str]
        The slicing mode, ignored if units is "measures" or "bars".
        Valid values are:

        - `"onsets"` - include events that start within bounds (default)
        - `"overlaps"` - include events that overlap (either onset or
            offset) is within the bounds. An event ending is considered
            to overlap if its offset is greater than start.
        - `"offsets"` - include events that end within the bounds
        - `"strict"` - include only events that start at or after start
            and end at or before end. (End times that are exactly equal
            to end are considered to be within bounds, so this is
            inclusive of end time.)

    truncate: Optional[str]
        How to handle events that partially overlap the bounds,
        ignored if units is "measures" or "bars". Valid values are:

        - `"truncate"` - truncate (clip) events that partially overlap
            the bounds. If the event onset is before start, the onset
            is increased to start (adjusting duration to maintain the
            offset time). Also, if the event offset is after end, the
            duration is decreased so that the offset time is end.
        - `"keep"` - no modification/truncation (default). Note that
            with the default mode="onsets", no event onsets will be
            earlier than start, but offsets may extend beyond end.
        - `"end"` or "ending" or "dur" or "duration" - truncate (clip)
            events that extend beyond end so that all offsets <= end.
        - `"beginning"` - events with onsets before start are moved to
            make their onsets equal to start, and their duration is
            adjusted to maintain the original offset.

    min_duration: Optional[float]
        Events with duration less than min_duration (after any truncation
        is applied) are removed.  Ignored if units is "measures" or "bars".
        If None or 0.0, no events are removed. The default is 0.05,
        independent of time units. Be careful with gracenotes that, when
        read from MusicXML, have zero duration.

    Returns
    -------
    Score
        A new Score instance containing the content between start and end.

    Raises
    ------
    ValueError
        If the Sequence is not part of a Score, or if invalid values are
        provided for the parameters.
    """
    score = self.score
    if score is None:
        raise ValueError("slice can only be called on a Sequence that is "
                         "part of a Score")
    if score.is_flat():
        if units in ("measures", "bars"):
            raise ValueError(f"units cannot be {units} for slicing a "
                             "flat score")
    else:
        if units not in ("measures", "bars"):
            raise ValueError(f"units must be measures or bars for slicing "
                "a score with Measures (or flatten the score before "
                "slicing)")

    if units in ("quarters", "measures", "bars"):
        score.convert_to_quarters()
    elif units in ("s", "sec", "seconds"):
        score.convert_to_seconds()
    else:
        raise ValueError('units must be "quarters", "measures, "'
                         '"bars", "s", "sec", or "seconds"')

    # Find start time and end time for slice. It may not be (start, end)
    # if units is measures or bars.
    if units in ("measures", "bars"):
        (start_time, end_time) = self.measure_times(int(start))
        if end != start:
            (_, end_time) = self.measure_times(int(end) - 1)
    else:
        start_time = start
        end_time = end

    # construct the parts of the tree above self and make an empty copy
    # of self to add the slice content.
    result = (score.emptycopy() if isinstance(self, Score)
              else self._copy_parents(start_time, end_time))
    result.onset = start_time  # result is an empty copy of self. Set the
    result.offset = end_time   # onset and offset to the slice bounds.
    if units in ("measures", "bars"):
        c_min, c_max = result._add_measure_children(self, start, end,
                                                    start_time, end_time)
        if c_min < start_time or c_max > end_time:
            raise ValueError("unexpectedly found content outside the "
                             "measure slice bounds")
        min_time = c_min
        max_time = c_max
    else:   
        min_time, max_time = result._add_slice_children(self, start_time,
                                  end_time, mode, truncate, min_duration)
    result._trim_map_and_signatures(min_time, max_time)
    if shift and min_time != float("inf") and min_time > 0:
        result.time_shift(-min_time)
    return result

is_well_formed_full_part ¶

is_well_formed_full_part()

Test if Part is measured and well-formed.

Part must conform to a strict hierarchy of: Part-Staff-Measure-(Note or Rest or Chord) and Chord-Note.

Source code in amads/core/basics.py

def is_well_formed_full_part(self):
    """Test if Part is measured and well-formed.

    Part must conform to a strict hierarchy of:
    Part-Staff-Measure-(Note or Rest or Chord) and Chord-Note.
    """
    for staff in self.content:  # type: ignore (Part contains Staffs)
        staff : Staff
        # only Staffs are expected, but things outside of the hierarchy
        # are allowed, so we only rule out violations of the hierarchy:
        if isinstance(staff, (Score, Part, Measure, Note, Rest, Chord)):
            return False
        if isinstance(staff, Staff) and not staff._is_well_formed():
            return False
    return True

flatten ¶

flatten(in_place=False)

Build a flat Part where content will consist of notes only.

Parameters:

in_place (bool, default: False ) –

If in_place=True, assume Part already has no ties and can be modified. Otherwise, return a new Part where deep copies of tied notes are merged.

Returns:

Part –

a new part that has been flattened

Source code in amads/core/basics.py

def flatten(self, in_place=False):
    """Build a flat Part where content will consist of notes only.

    Parameters
    ----------
    in_place : bool
        If in_place=True, assume Part already has no ties and can be
        modified. Otherwise, return a new Part where deep copies of
        tied notes are merged.

    Returns
    -------
    Part
        a new part that has been flattened
    """
    part = self if in_place else self.merge_tied_notes()
    notes : List[Note] \
          = part.list_all(Note)  # type: ignore (Notes < Events)
    for note in notes:
        note.parent = part
    notes.sort(key=lambda x: (x.onset, x.pitch))
    part.content = notes  # type: ignore (List[Note] < List[Event])
    return part

is_flat ¶

is_flat()

Test if Part is flat (contains only notes without ties).

Returns:

bool –

True iff the Part is flat

Source code in amads/core/basics.py

def is_flat(self):
    """Test if Part is flat (contains only notes without ties).

    Returns
    -------
    bool
        True iff the Part is flat
    """
    for note in self.content:
        # only Notes without ties are expected, but things outside of
        # the hierarchy are allowed, so we only rule out violations of
        # the hierarchy:
        if isinstance(note, (Score, Part, Staff, Measure, Rest, Chord)):
            return False
        if isinstance(note, Note) and note.tie is not None:
            return False
    return True

remove_measures ¶

remove_measures(score: Optional[Score], has_ties: bool = True) -> Part

Return a Part with all Measures removed.

Preserves Staffs in the hierarchy. Notes are “lifted” from Measures to become direct content of their Staff. Uses merge_tied_notes() to copy this Part unless has_ties is False, in which case there must be no tied notes and this Part is modified. (Note: it is harmless for has_ties to be True even if there are no ties. This will simply copy the Part before removing measures.)

Parameters:

score (Union[Score, None]) –

The Score instance (if any) to which the new Part will be added.
has_ties (bool, default: True ) –

If False, assume this is a copy we are free to modify, there are tied notes, and this Part is already contained by score. If True, this Part will be copied into score.

Returns:

Part –

A Part with all Measures removed.

Source code in amads/core/basics.py

def remove_measures(self, score: Optional["Score"],
                    has_ties: bool = True) -> "Part":
    """Return a Part with all Measures removed.

    Preserves Staffs in the hierarchy. Notes are “lifted” from Measures
    to become direct content of their Staff. Uses `merge_tied_notes()`
    to copy this Part unless `has_ties` is False, in which case
    there must be no tied notes and this Part is modified. (Note: it is
    harmless for `has_ties` to be True even if there are no ties. This
    will simply copy the Part before removing measures.)

    Parameters
    ----------
    score : Union[Score, None]
        The Score instance (if any) to which the new Part will be added.
    has_ties : bool
        If False, assume this is a copy we are free to modify,
        there are tied notes, and this Part is already contained
        by `score`. If True, this Part will be copied into `score`.

    Returns
    -------
    Part
        A Part with all Measures removed.
    """
    part : Part = (self.merge_tied_notes(score) 
                   if has_ties else self)  # type: ignore
    for staff in part.content:
        if isinstance(staff, Staff):
            staff.remove_measures()
    return part

calc_differences ¶

calc_differences(what: List[str]) -> List[Note]

Calculate inter-onset intervals (IOIs), IOI-ratios and intervals.

This method modifies the Part in place, calculating several differences between notes. Onset differences (IOIs) are the time differences between a Note's onset and the onset of the previous Note in the same Part (regardless of Staff). The IOI of the first Note in the Part is set to None. The IOI values are computed when what contains "ioi" or "ioi_ratio" and stored as "ioi" in the Note's info dictionary.

The IOI-ratio of a Note is the ratio of its IOI to the IOI of the previous Note. The IOI-ratios of the first two Notes are set to None. The IOI-ratio values are computed when what contains "ioi_ratio" and stored as "ioi_ratio" in the Note's info dictionary.

The pitch interval of a Note is the difference in semitones between its pitch and the pitch of the previous Note in the same Part. The interval of the first Note in the Part is set to None. The interval values are computed when what contains "interval" and stored as "interval" in the Note's info dictionary.

Note that this method assumes that the Part has no concurrent Notes (IOI == 0) and no ties. In either case, a ValueError is raised.

Parameters:

what (list of str) –

A list of strings indicating what differences to compute. Valid strings are: 'ioi' (for inter-onset intervals), 'ioi_ratio' (for ratio of successive IOIs), and 'interval' (for pitch intervals in semitones).

Raises:

ValueError –

If there are tied notes or concurrent notes in the Part or if what does not contain any of "ioi", "ioi_ratio" or "interval".

Returns:

List[Note] –

The sorted list of Notes with calculated IOIs and IOI-ratios.

Source code in amads/core/basics.py

def calc_differences(self, what: List[str]) -> List[Note]:
    """Calculate inter-onset intervals (IOIs), IOI-ratios and intervals.

    This method modifies the Part in place, calculating several
    differences between notes. Onset differences (IOIs) are the
    time differences between a Note's onset and the onset of the
    previous Note in the same Part (regardless of Staff). The IOI
    of the first Note in the Part is set to None. The IOI values
    are computed when `what` contains "ioi" or "ioi_ratio" and
    stored as `"ioi"` in the Note's `info` dictionary.

    The IOI-ratio of a Note is the ratio of its IOI to the IOI of
    the previous Note. The IOI-ratios of the first two Notes are set
    to None. The IOI-ratio values are computed when `what` contains
    "ioi_ratio" and stored as `"ioi_ratio"` in the Note's `info`
    dictionary.

    The pitch interval of a Note is the difference in semitones between
    its pitch and the pitch of the previous Note in the same Part. The
    interval of the first Note in the Part is set to None. The interval
    values are computed when `what` contains "interval" and stored
    as `"interval"` in the Note's `info` dictionary.

    Note that this method assumes that the Part has no concurrent
    Notes (IOI == 0) and no ties. In either case, a ValueError is raised.

    Parameters
    ----------
    what : list of str
        A list of strings indicating what differences to compute.
        Valid strings are: 'ioi' (for inter-onset intervals),
        'ioi_ratio' (for ratio of successive IOIs), and
        'interval' (for pitch intervals in semitones).

    Raises
    ------
    ValueError
        If there are tied notes or concurrent notes in the Part or if
        `what` does not contain any of "ioi", "ioi_ratio" or "interval".

    Returns
    -------
    List[Note]
        The sorted list of Notes with calculated IOIs and IOI-ratios.
    """
    # this will raise an exception if there are ties:
    notes : List[Note] = self.get_sorted_notes(has_ties=False)
    do_ioi = "ioi" in what or "ioi_ratio" in what
    do_interval = "interval" in what
    do_ioi_ratio = "ioi_ratio" in what
    if not (do_ioi or do_interval or do_ioi_ratio):
        raise ValueError(
                "what must contain 'ioi', 'ioi_ratio' or 'interval'")
    if len(notes) == 0:
        return []  # nothing to do
    else:
        if do_ioi:
            notes[0].set("ioi", None)
        if do_ioi_ratio:
            notes[0].set("ioi_ratio", None)
        if do_interval:
            notes[0].set("interval", None)

    prev_ioi : Optional[float] = None
    prev_note : Note = notes[0]
    for note in notes[1 : ]:
        if do_ioi:
            ioi = note.onset - prev_note.onset
            if ioi <= 0:
                raise ValueError(
                        "Part is not monophonic; cannot compute IOIs")
            note.set("ioi", ioi)
        if do_ioi_ratio:
            if prev_ioi is None:
                note.set("ioi_ratio", None)
            else:  # ignore typing because ioi is bound earlier:
                note.set("ioi_ratio", ioi / prev_ioi)  # type: ignore
            prev_ioi = ioi  # type: ignore (ioi is bound if do_ioi) 
        if do_interval:
            note.set("interval", note.key_num - prev_note.key_num)
        prev_note = note
    return notes

Score ¶

Score(
    *args: Event,
    onset: Optional[float] = 0,
    duration: Optional[float] = None,
    time_map: Optional[TimeMap] = None,
    time_signatures: Optional[List[TimeSignature]] = None
)

Bases: Concurrence

A Score (abstract class) represents a musical work.

Normally, a Score contains Part objects, all with onsets zero, and has no parent.

See Constructor Details.

Additional properties may be assigned, e.g., 'title', 'source_file', 'composer', etc. (See set.)

Parameters:

*args (Event, default: () ) –

A variable number of Event objects to be added to the group.
onset (Optional[float], default: 0 ) –

The onset (start) time. If unknown (None), onset will be set when the score is added to a parent, but normally, Scores do not have parents, so the default onset is 0. You can override this using keyword parameter (due to *args).
duration (Optional[float], default: None ) –

The duration in quarters or seconds. (If duration is omitted or None, the duration is set so that self.offset ends at the max offset of args, or 0 if there is no content.) Must be passed as a keyword parameter due to *args.
time_map (TimeMap, default: None ) –

A map from quarters to seconds (or seconds to quarters). Must be passed as a keyword parameter due to *args.

Attributes:

parent (Optional[EventGroup]) –

The containing object or None.
_onset (float) –

The onset (start) time.
duration (float) –

The duration in quarters or seconds.
content (list[Event]) –

Elements contained within this collection.
time_map (TimeMap) –

A map from quarters to seconds (or seconds to quarters).
time_signatures (list[TimeSignature]) –

A list of all time signature changes
_units_are_seconds (bool) –

True if the units are seconds, False if the units are quarters.

Source code in amads/core/basics.py

def __init__(self, *args: Event,
             onset: Optional[float] = 0,
             duration: Optional[float] = None,
             time_map: Optional["TimeMap"] = None,
             time_signatures: Optional[List[TimeSignature]] = None):
    super().__init__(None, onset, duration, list(args))  # parent is None
    self.time_map = time_map if time_map else TimeMap()
    self.time_signatures = (
            time_signatures if time_signatures else [TimeSignature(0)])
    self._units_are_seconds = False

Attributes¶

onset `property` `writable` ¶

onset: float

Retrieve the onset (start) time.

If the onset is None, raise an exception. (Events can have None onset times, but they must be set before retrieval. onsets that are None are automatically set when the Event is added to an EventGroup.)

Returns:

float –

The onset (start) time.

Raises:

ValueError –

If the onset time is not set (None).

offset `property` `writable` ¶

offset: float

Retrieve the global offset (stop) time.

Returns:

float –

The global offset (stop) time.

measure `property` ¶

measure: Optional[Measure]

Retrieve the Measure containing this event

Returns:

Optional[Measure] –

The Measure containing this event or None if not found.

units_are_quarters `property` ¶

units_are_quarters: bool

True if the units are in quarters, False if in seconds.

units_are_seconds `property` ¶

units_are_seconds: bool

True if the units are in seconds, False if in quarters.

Functions¶

set ¶

set(property: str, value: Any) -> Event

Set a named property on this Event.

Every event can be extended with additional properties. Although Python objects are already extensible with new attributes, new attributes that are not set in __init__ confuse type checkers and other tools, so every Event has an info attribute as a dictionary where additional, application-specific information can be stored. The info attribute is None to save space until the first property is set, so you should use set and get methods and avoid writing event.info[property].

Parameters:

property (str) –

The name of the property to set.
value (Any) –

The value to assign to the property.

Returns:

Event –

returns this object (self)

Examples:

>>> note = Note()
>>> note.get("color", "no color")
'no color'
>>> _ = note.set("color", "red").set("harmonicity", 0.2)
>>> (note.has("color"), note.has("shape"))
(True, False)
>>> (note.get("color"), note.get("harmonicity"))
('red', 0.2)

Source code in amads/core/basics.py

def set(self, property : str, value : Any) -> "Event":
    """Set a named property on this Event.

    Every event can be extended with additional properties. Although
    Python objects are already extensible with new attributes, new
    attributes that are not set in `__init__` confuse type checkers
    and other tools, so every `Event` has an `info` attribute as a
    dictionary where additional, application-specific information can
    be stored. The `info` attribute is `None` to save space until the
    first property is set, so you should use `set` and `get` methods
    and avoid writing `event.info[property]`.

    Parameters
    ----------
    property : str
        The name of the property to set.
    value : Any
        The value to assign to the property.

    Returns
    -------
    Event
        returns this object (self)

    Examples
    --------
    >>> note = Note()
    >>> note.get("color", "no color")
    'no color'
    >>> _ = note.set("color", "red").set("harmonicity", 0.2)
    >>> (note.has("color"), note.has("shape"))
    (True, False)
    >>> (note.get("color"), note.get("harmonicity"))
    ('red', 0.2)
    """
    if self.info is None:
        self.info = {}
    self.info[property] = value
    return self

get ¶

get(property: str, default: Any = None) -> Any

Get the value of a property from this Event.

See set for more details.

Parameters:

property (str.) –

The name of the property to get.
default (Any, default: None ) –

The default value to return if the property is not found.

Returns:

Any –

The value of the specified property.

Source code in amads/core/basics.py

def get(self, property : str, default : Any = None) -> Any:
    """Get the value of a property from this Event.

    See [set][amads.core.basics.Event.set] for more details.

    Parameters
    ----------
    property : str.
        The name of the property to get.
    default : Any
        The default value to return if the property is not found.

    Returns
    -------
    Any
        The value of the specified property.
    """
    if self.info is None:
        return default
    return self.info.get(property, default)

has ¶

has(property) -> bool

Check if the Event has a specific property.

See set for more details.

Parameters:

property (str) –

The name of the property to check.

Returns:

bool –

True if the property exists, False otherwise.

Source code in amads/core/basics.py

def has(self, property) -> bool:
    """Check if the Event has a specific property.

    See [set][amads.core.basics.Event.set] for more details.

    Parameters
    ----------
    property : str
        The name of the property to check.

    Returns
    -------
    bool
        True if the property exists, False otherwise.
    """
    return (self.info is not None) and (property in self.info)

insert_copy_into ¶

insert_copy_into(parent: Optional[EventGroup] = None) -> Event

Make a (mostly) deep copy of the Event and add to a new parent.

Pitch objects are considered immutable and are shared rather than copied.

Parameters:

parent (Optional(EventGroup), default: None ) –

The copied Event will be a child of parent if not None. The parent is modified by this operation.

Returns:

Event –

A deep copy (except for parent and pitch) of the Event instance.

Source code in amads/core/basics.py

def insert_copy_into(self,
                     parent: Optional["EventGroup"] = None) -> "Event":
    """
    Make a (mostly) deep copy of the `Event` and add to a new `parent`.

    `Pitch` objects are considered immutable and are shared rather
    than copied.

    Parameters
    ----------
    parent : Optional(EventGroup)
        The copied `Event` will be a child of `parent` if not `None`.
        The parent is modified by this operation.

    Returns
    -------
    Event
        A deep copy (except for parent and pitch) of the Event instance.
    """
    # remove link to parent to break link going up the tree
    # preventing deep copy from copying the entire tree
    original_parent = self.parent
    self.parent = None
    c = copy.deepcopy(self)  # deep copy of this event down to leaf nodes
    self.parent = original_parent  # restore link to parent
    if parent:
        parent.insert(c)
    return c

ismonophonic ¶

ismonophonic() -> bool

Determine if content is monophonic (non-overlapping notes).

A monophonic list of notes has no overlapping notes (e.g., chords). Serves as a helper function for ismonophonic and parts_are_monophonic.

Returns:

bool –

True if the list of notes is monophonic, False otherwise.

Source code in amads/core/basics.py

def ismonophonic(self) -> bool:
    """
    Determine if content is monophonic (non-overlapping notes).

    A monophonic list of notes has no overlapping notes (e.g., chords).
    Serves as a helper function for `ismonophonic` and
    `parts_are_monophonic`.

    Returns
    -------
    bool
        True if the list of notes is monophonic, False otherwise.
    """
    prev = None
    notes = self.list_all(Note)
    # Sort the notes by start time
    notes.sort(key=lambda note: note.onset)
    # Check for overlaps
    for note in notes:
        if prev:
            # 0.01 is to prevent precision errors when comparing floats
            if note.onset - prev.offset < -0.01:
                return False
        prev = note
    return True

insert_emptycopy_into ¶

insert_emptycopy_into(
    parent: Optional[EventGroup] = None,
) -> EventGroup

Create a deep copy of the EventGroup except for content.

A new parent is provided as an argument and the copy is inserted into this parent. This method is useful for copying an EventGroup without copying its content. See also insert_copy_into to copy an EventGroup with its content into a new parent.

Parameters:

parent (Optional[EventGroup], default: None ) –

The new parent to insert the copied Event into.

Returns:

EventGroup –

A deep copy of the EventGroup instance with the new parent (if any) and no content.

Source code in amads/core/basics.py

def insert_emptycopy_into(self, 
            parent: Optional["EventGroup"] = None) -> "EventGroup":
    """Create a deep copy of the EventGroup except for content.

    A new parent is provided as an argument and the copy is inserted
    into this parent. This method is  useful for copying an
    EventGroup without copying its content.  See also
    [insert_copy_into][amads.core.basics.Event.insert_copy_into] to
    copy an EventGroup *with* its content into a new parent.

    Parameters
    ----------
    parent : Optional[EventGroup]
        The new parent to insert the copied Event into.

    Returns
    -------
    EventGroup
        A deep copy of the EventGroup instance with the new parent
        (if any) and no content.
    """
    # rather than customize __deepcopy__, we "hide" the content to avoid
    # copying it. Then we restore it after copying and fix parent.
    original_content = self.content
    self.content = []
    c = self.insert_copy_into(parent)
    self.content = original_content
    return c  #type: ignore (c will always be an EventGroup)

expand_chords ¶

expand_chords(parent: Optional[EventGroup] = None) -> EventGroup

Replace chords with the multiple notes they contain.

Returns a deep copy with no parent unless parent is provided. Normally, you will call score.expand_chords() which returns a deep copy of Score with notes moved from each chord to the copy of the chord's parent (a Measure or a Part). The parent parameter is primarily for internal use when expand_chords is called recursively on score content.

Parameters:

parent (EventGroup, default: None ) –

The new parent to insert the copied EventGroup into.

Returns:

EventGroup –

A deep copy of the EventGroup instance with all Chord instances expanded.

Source code in amads/core/basics.py

def expand_chords(self,
                  parent: Optional["EventGroup"] = None) -> "EventGroup":
    """Replace chords with the multiple notes they contain.

    Returns a deep copy with no parent unless parent is provided.
    Normally, you will call `score.expand_chords()` which returns a deep
    copy of Score with notes moved from each chord to the copy of the
    chord's parent (a Measure or a Part). The parent parameter is 
    primarily for internal use when `expand_chords` is called recursively
    on score content.

    Parameters
    ----------
    parent : EventGroup
        The new parent to insert the copied EventGroup into.

    Returns
    -------
    EventGroup
        A deep copy of the EventGroup instance with all
        Chord instances expanded.
    """
    group = self.insert_emptycopy_into(parent)
    for item in self.content:
        if isinstance(item, Chord):
            for note in item.content:  # expand chord
                note.insert_copy_into(group)
        if isinstance(item, EventGroup):
            item.expand_chords(group)  # recursion for deep copy/expand
        else:
            item.insert_copy_into(group)  # deep copy non-EventGroup
    return group

find_all ¶

find_all(elem_type: Type[Event]) -> Generator[Event, None, None]

Find all instances of a specific type within the EventGroup.

Assumes that objects of type elem_type are not nested within other objects of the same type. (The first elem_type encountered in a depth-first enumeration is returned without looking at any children in its content).

Parameters:

elem_type (Type[Event]) –

The type of event to search for.

Yields:

Event –

Instances of the specified type found within the EventGroup.

Source code in amads/core/basics.py

def find_all(self, elem_type: Type[Event]) -> Generator[Event, None, None]:
    """Find all instances of a specific type within the EventGroup.

    Assumes that objects of type `elem_type` are not nested within
    other objects of the same type. (The first `elem_type` encountered
    in a depth-first enumeration is returned without looking at any
    children in its `content`).

    Parameters
    ----------
    elem_type : Type[Event]
        The type of event to search for.

    Yields
    -------
    Event
        Instances of the specified type found within the EventGroup.
    """
    # Algorithm: depth-first enumeration of EventGroup content.
    # If elem_types are nested, only the top-level elem_type is
    # returned since it is found first, and the content is not
    # searched. This makes it efficient, e.g., to search for
    # Parts in a Score without enumerating all Notes within.
    for elem in self.content:
        if isinstance(elem, elem_type):
            yield elem
        elif isinstance(elem, EventGroup):
            yield from elem.find_all(elem_type)

get_sorted_notes ¶

get_sorted_notes(has_ties: bool = True) -> List[Note]

Return a list of sorted notes with merged ties.

This should generally be called on Parts and Scores since in all other EventGroups, Events are in time order and Notes retrieved with find_all() or list_all() are in time order. However, get_sorted_notes also sorts notes into increasing pitch (keynum) where note onsets are equal.

Parameters:

has_ties (bool, default: True ) –

If True (default), copy the score, merge the ties, and return a list of these merged copies. If False, assume there are no ties and return a list of original notes.

Raises:

ValueError –

If has_ties is False, but a tie is encountered.

Returns:

list(Note) –

a list of sorted notes with merged ties

Source code in amads/core/basics.py

def get_sorted_notes(self, has_ties: bool = True) -> List[Note]:
    """Return a list of sorted notes with merged ties.

    This should generally be called on Parts and Scores since
    in all other EventGroups, Events are in time order and
    Notes retrieved with `find_all()` or `list_all()` are in
    time order. However, `get_sorted_notes` *also* sorts notes
    into increasing pitch (`keynum`) where note onsets are equal.

    Parameters
    ----------
    has_ties: bool
        If True (default), copy the score, merge the ties, and
        return a list of these merged copies. If False, assume
        there are no ties and return a list of original notes.

    Raises
    ------
    ValueError
        If has_ties is False, but a tie is encountered.

    Returns
    -------
    list(Note)
        a list of sorted notes with merged ties
    """
    if has_ties:
        # after flatten, score will have one Part with all Notes:
        return self.flatten(collapse=True).content[0].content  # type: ignore
    else:
        notes : List[Note] = cast(List[Note], self.list_all(Note))
        for note in notes:
            if note.tie is not None:
                raise ValueError(
                        "tie found by get_sorted_notes with has_ties=False")
        notes.sort(key=lambda x: (x.onset, x.pitch))
        return notes

has_instanceof ¶

has_instanceof(the_class: Type[Event]) -> bool

Test if EventGroup contains any instances of the_class.

Parameters:

the_class (Type[Event]) –

The class type to check for.

Returns:

bool –

True iff the EventGroup contains an instance of the_class.

Source code in amads/core/basics.py

def has_instanceof(self, the_class: Type[Event]) -> bool:
    """Test if EventGroup contains any instances of `the_class`.

    Parameters
    ----------
    the_class : Type[Event]
        The class type to check for.

    Returns
    -------
    bool
        True iff the EventGroup contains an instance of the_class.
    """
    instances = self.find_all(the_class)
    # if there are no instances (of the_class), next will return "empty":
    return next(instances, "empty") != "empty"

has_rests ¶

has_rests() -> bool

Test if EventGroup (e.g., Score, Part, ...) has any Rest objects.

Returns:

bool –

True iff the EventGroup contains any Rest objects.

Source code in amads/core/basics.py

def has_rests(self) -> bool:
    """Test if EventGroup (e.g., Score, Part, ...) has any `Rest` objects.

    Returns
    -------
    bool
        True iff the EventGroup contains any Rest objects.
    """
    return self.has_instanceof(Rest)

has_chords ¶

has_chords() -> bool

Test if EventGroup (e.g., Score, Part, ...) has any Chord objects.

Returns:

bool –

True iff the EventGroup contains any Chord objects.

Source code in amads/core/basics.py

def has_chords(self) -> bool:
    """Test if EventGroup (e.g., Score, Part, ...) has any Chord objects.

    Returns
    -------
    bool
        True iff the EventGroup contains any Chord objects.
    """
    return self.has_instanceof(Chord)

has_ties ¶

has_ties() -> bool

Test if EventGroup (e.g., Score, Part, ...) has any tied notes.

Returns:

bool –

True iff the EventGroup contains any tied notes.

Source code in amads/core/basics.py

def has_ties(self) -> bool:
    """Test if EventGroup (e.g., Score, Part, ...) has any tied notes.

    Returns
    -------
    bool
        True iff the EventGroup contains any tied notes.
    """
    notes = self.find_all(Note)
    for note in notes:
        if note.tie:
            return True
    return False

has_measures ¶

has_measures() -> bool

Test if EventGroup (e.g., Score, Part, ...) has any Measures.

Returns:

bool –

True iff the EventGroup contains any Measure objects.

Source code in amads/core/basics.py

def has_measures(self) -> bool:
    """Test if EventGroup (e.g., Score, Part, ...) has any Measures.

    Returns
    -------
    bool
        True iff the EventGroup contains any Measure objects.
    """
    return self.has_instanceof(Measure)

inherit_duration ¶

inherit_duration() -> EventGroup

Set the duration of this EventGroup according to maximum offset.

The duration is set to the maximum offset (end) time of the children. If the EventGroup is empty, the duration is set to 0. This method modifies this EventGroup instance.

Returns:

EventGroup –

The EventGroup instance (self) with updated duration.

Source code in amads/core/basics.py

def inherit_duration(self) -> "EventGroup":
    """Set the duration of this EventGroup according to maximum offset.

    The `duration` is set to the maximum offset (end) time of the
    children. If the EventGroup is empty, the duration is set to 0.
    This method modifies this `EventGroup` instance.

    Returns
    -------
    EventGroup
        The EventGroup instance (self) with updated duration.
    """
    onset = 0 if self._onset == None else self._onset
    max_offset = onset
    for elem in self.content:
        max_offset = max(max_offset, elem.offset)
    self.duration = max_offset - onset

    return self

insert ¶

insert(event: Event) -> EventGroup

Insert an event.

Sets the parent of event to this EventGroup and makes event be a member of this EventGroup.content. No changes are made to event.onset or self.duration. Insert event in content just before the first element with a greater onset. The method modifies this object (self).

Parameters:

event (Event) –

The event to be inserted.

Returns:

EventGroup –

The EventGroup instance (self) with the event inserted.

Raises:

ValueError –

If event._onset is None (it must be a number)

Caution Regarding Zero-Duration Event Order

If you have note N with non-zero duration and, at the same time, a grace note G with zero duration, the notes will be ordered according to when they are inserted. So if you insert N and then G, then N will be placed before G. See io.pt_import.py, where this case is dealt with.

Source code in amads/core/basics.py

def insert(self, event: Event) -> "EventGroup":
    """Insert an event.

    Sets the `parent` of `event` to this `EventGroup` and makes `event`
    be a member of this `EventGroup.content`. No changes are made to
    `event.onset` or `self.duration`. Insert `event` in `content` just
    before the first element with a greater onset. The method modifies
    this object (self).

    Parameters
    ----------
    event : Event
        The event to be inserted.

    Returns
    -------
    EventGroup
        The EventGroup instance (self) with the event inserted.

    Raises
    ------
    ValueError
        If event._onset is None (it must be a number)

    Caution Regarding Zero-Duration Event Order
    -------------------------------------------
    If you have note N with non-zero duration and, at the same
    time, a grace note G with zero duration, the notes will be
    ordered according to when they are inserted. So if you insert
    N and then G, then N will be placed *before* G. See
    io.pt_import.py, where this case is dealt with.
    """

    assert not event.parent
    if event._onset is None:  # must be a number
        raise ValueError(f"event's _onset attribute must be a number")
    atend = self.last()
    if atend and event.onset < atend.onset:
        # search in reverse from end
        i = len(self.content) - 2
        while i >= 0 and self.content[i].onset > event.onset:
            i -= 1
        # now i is either -1 or content[i] <= event.onset, so
        # insert event at content[i+1]
        self.content.insert(i + 1, event)
    else:  # simply append at the end of content:
        self.content.append(event)
    event.parent = self
    return self

last ¶

last() -> Optional[Event]

Retrieve the last event in the content list.

Because the content list is sorted by onset, the returned Event is simply the last element of content, but not necessarily the event with the greatest offset.

Returns:

Optional[Event] –

The last event in the content list or None if the list is empty.

Source code in amads/core/basics.py

def last(self) -> Optional[Event]:
    """Retrieve the last event in the content list.

    Because the `content` list is sorted by `onset`, the returned
    `Event` is simply the last element of `content`, but not
    necessarily the event with the greatest *`offset`*.

    Returns
    -------
    Optional[Event]
        The last event in the content list or None if the list is empty.
    """
    return self.content[-1] if len(self.content) > 0 else None

list_all ¶

list_all(elem_type: Type[Event]) -> list[Event]

Find all instances of a specific type within the EventGroup.

Assumes that objects of type elem_type are not nested within other objects of the same type. See also find_all, which returns a generator instead of a list.

Parameters:

elem_type (Type[Event]) –

The type of event to search for.

Returns:

list[Event] –

A list of all instances of the specified type found within the EventGroup.

Source code in amads/core/basics.py

def list_all(self, elem_type: Type[Event]) -> list[Event]:
    """Find all instances of a specific type within the EventGroup.

    Assumes that objects of type `elem_type` are not nested within
    other objects of the same type.  See also
    [find_all][amads.core.basics.EventGroup.find_all], which returns
    a generator instead of a list.

    Parameters
    ----------
    elem_type : Type[Event]
        The type of event to search for.

    Returns
    -------
    list[Event]
        A list of all instances of the specified type found
        within the EventGroup.
    """
    return list(self.find_all(elem_type))

merge_tied_notes ¶

merge_tied_notes(
    parent: Optional[EventGroup] = None, ignore: list[Note] = []
) -> EventGroup

Create a new EventGroup with tied notes replaced by single notes.

If ties cross staffs, the replacement is placed in the staff of the first note in the tied sequence. Insert the new EventGroup into parent.

Ordinarily, this method is called on a Score with no parameters. The parameters are used when Score.merge_tied_notes() calls this method recursively on EventGroups within the Score such as Parts and Staffs.

Parameters:

parent (Optional[EventGroup], default: None ) –

Where to insert the result.
ignore (list[Note], default: [] ) –

This parameter is used internally. Caller should not use this parameter.

Returns:

EventGroup –

A copy with tied notes replaced by equivalent single notes.

Source code in amads/core/basics.py

def merge_tied_notes(self, parent: Optional["EventGroup"] = None,
                     ignore: list[Note] = []) -> "EventGroup":
    """Create a new `EventGroup` with tied notes replaced by single notes.

    If ties cross staffs, the replacement is placed in the staff of the
    first note in the tied sequence. Insert the new `EventGroup` into
    `parent`.

    Ordinarily, this method is called on a Score with no parameters. The
    parameters are used when `Score.merge_tied_notes()` calls this method
    recursively on `EventGroup`s within the Score such as `Part`s and
    `Staff`s.

    Parameters
    ----------
    parent: Optional(EventGroup)
        Where to insert the result.

    ignore: Optional(list[Note])
        This parameter is used internally. Caller should not use
        this parameter.

    Returns
    -------
    EventGroup
        A copy with tied notes replaced by equivalent single notes.
    """
    # Algorithm: Find all notes, removing tied notes and updating
    # duration when ties are found. These tied notes are added to
    # ignore so they can be skipped when they are encountered.

    group = self.insert_emptycopy_into(parent)
    for event in self.content:
        if isinstance(event, Note):
            if event in ignore:  # do not copy tied notes into group;
                if event.tie:
                    ignore.append(event.tie)  # add tied note to ignore
                # We will not see this note again, so
                # we can also remove it from ignore. Removal is expensive
                # but it could be worse for ignore to grow large when there
                # are many ties since we have to search it entirely once
                # per note. An alternate representation might be a set to
                # make searching fast.
                ignore.remove(event)
            else:
                if event.tie:
                    tied_note = event.tie  # save the tied-to note
                    event.tie = None  # block the copy
                    ignore.append(tied_note)
                    # copy note into group:
                    event_copy = event.insert_copy_into(group)
                    event.tie = tied_note  # restore original event
                    # this is subtle: event.tied_duration (a property) will
                    # sum up durations of all the tied notes. Since
                    # event_copy is not tied, the sum of durations is
                    # stored on that one event_copy:
                    event_copy.duration = event.tied_duration
                else:  # put the untied note into group
                    event.insert_copy_into(group)
        elif isinstance(event, EventGroup):
            event.merge_tied_notes(group, ignore)
        else:
            event.insert_copy_into(group)  # simply copy to new parent
    return group

quantize ¶

quantize(divisions: int) -> EventGroup

Align onsets and durations to a rhythmic grid.

Assumes time units are quarters. (See Score.convert_to_quarters.)

Modify all times and durations to a multiple of divisions per quarter note, e.g., 4 for sixteenth notes. Onsets and offsets are moved to the nearest quantized time. Any resulting duration change is less than one quantum, but not necessarily less than 0.5 quantum, since the onset and offset can round in opposite directions by up to 0.5 quantum each. Any non-zero duration that would quantize to zero duration gets a duration of one quantum since zero duration is almost certainly going to cause notation and visualization problems.

Special cases for zero duration:

If the original duration is zero as in metadata or possibly grace notes, we preserve that.
If a tied note duration quantizes to zero, we remove the tied note entirely provided some other note in the tied sequence has non-zero duration. If all tied notes quantize to zero, we keep the first one and set its duration to one quantum.

This method modifies this EventGroup and all its content in place.

Note that there is no way to specify "sixteenths or eighth triplets" because 6 would not allow sixteenths and 12 would admit sixteenth triplets. Using tuples as in Music21, e.g., (4, 3) for this problem creates another problem: if quantization is to time points 1/4, 1/3, then the difference is 1/12 or a thirty-second triplet. If the quantization is applied to durations, then you could have 1/4 + 1/3 = 7/12, and the remaining duration in a single beat would be 5/12, which is not expressible as sixteenths, eighth triplets or any tied combination.

Parameters:

divisions (int) –

The number of divisions per quarter note, e.g., 4 for sixteenths, to control quantization.

Returns:

EventGroup –

The EventGroup instance (self) with (modified in place) quantized times.

Source code in amads/core/basics.py

def quantize(self, divisions: int) -> "EventGroup":
    """Align onsets and durations to a rhythmic grid.

    Assumes time units are quarters. (See [Score.convert_to_quarters](
            basics.md#amads.core.basics.Score.convert_to_quarters).)

    Modify all times and durations to a multiple of divisions
    per quarter note, e.g., 4 for sixteenth notes. Onsets and offsets
    are moved to the nearest quantized time. Any resulting duration
    change is less than one quantum, but not necessarily less than
    0.5 quantum, since the onset and offset can round in opposite
    directions by up to 0.5 quantum each. Any non-zero duration that would
    quantize to zero duration gets a duration of one quantum since
    zero duration is almost certainly going to cause notation and
    visualization problems.

    Special cases for zero duration:

    1. If the original duration is zero as in metadata or possibly
           grace notes, we preserve that.
    2. If a tied note duration quantizes to zero, we remove the
           tied note entirely provided some other note in the tied
           sequence has non-zero duration. If all tied notes quantize
           to zero, we keep the first one and set its duration to
           one quantum.

    This method modifies this EventGroup and all its content in place.

    Note that there is no way to specify "sixteenths or eighth triplets"
    because 6 would not allow sixteenths and 12 would admit sixteenth
    triplets. Using tuples as in Music21, e.g., (4, 3) for this problem
    creates another problem: if quantization is to time points 1/4, 1/3,
    then the difference is 1/12 or a thirty-second triplet. If the
    quantization is applied to durations, then you could have 1/4 + 1/3
    = 7/12, and the remaining duration in a single beat would be 5/12,
    which is not expressible as sixteenths, eighth triplets or any tied
    combination.

    Parameters
    ----------
    divisions : int
        The number of divisions per quarter note, e.g., 4 for
        sixteenths, to control quantization.

    Returns
    -------
    EventGroup
        The EventGroup instance (self) with (modified in place) 
        quantized times.
    """

    super()._quantize(divisions)
    # iterating through content is tricky because we may delete a
    # Note, shifting the content:
    i = 0
    while i < len(self.content):
        event = self.content[i]
        event._quantize(divisions)
        if event == self.content[i]:
            i += 1
        # otherwise, we deleted event so the next event to
        # quantize is at index i; don't incremenet i
    return self

remove ¶

remove(element: Event) -> EventGroup

Remove an element from the content list.

The method modifies this object (self).

Parameters:

element (Event) –

The event to be removed.

Returns:

EventGroup –

The EventGroup instance (self) with the element removed. The returned value is not a copy.

Source code in amads/core/basics.py

def remove(self, element: Event) -> "EventGroup":
    """Remove an element from the content list. 

    The method modifies this object (self).

    Parameters
    ----------
    element : Event
        The event to be removed.

    Returns
    -------
    EventGroup
        The EventGroup instance (self) with the element removed.
        The returned value is not a copy.
    """
    self.content.remove(element)
    element.parent = None
    return self

remove_rests ¶

remove_rests(parent: Union[EventGroup, None] = None) -> EventGroup

Remove all Rest objects from content.

Returns a deep copy with no parent unless parent is provided.

Parameters:

parent (EventGroup, default: None ) –

The new parent to insert the copied Event into.

Returns:

EventGroup –

A deep copy of the EventGroup instance with all Rest objects removed.

Source code in amads/core/basics.py

def remove_rests(self, parent: Union["EventGroup", 
                                     None] = None) -> "EventGroup":
    """Remove all Rest objects from content.

    Returns a deep copy with no parent unless parent is provided.

    Parameters
    ----------
    parent : EventGroup
        The new parent to insert the copied Event into.

    Returns
    -------
    EventGroup
        A deep copy of the EventGroup instance with all Rest
        objects removed.
    """
    # implementation detail: when called without argument, remove_rests
    # makes a deep copy of the subtree and returns the copy without a
    # parent. remove_rests calls itself recursively *with* a parameter
    # indicating that the subtree copy should be inserted into a
    # parent which is the new copy at the next level up. Of course,
    # we check for and ignore Rests so they are never copied.
    group = self.insert_emptycopy_into(parent)
    for item in self.content:
        if isinstance(item, Rest):
            continue  # skip the Rests while making deep copy
        if isinstance(item, EventGroup):
            item.remove_rests(group)  # recursion for deep copy
        else:
            item.insert_copy_into(group)  # deep copy non-EventGroup
    return group

measure_times ¶

measure_times(n: int) -> tuple[float, float]

Return the start and end times of measure n.

Parameters:

n (int) –

The 0-based measure number.

Returns:

tuple(float, float) –

A tuple containing the start and end times of measure n. Measure 0 is the first measure. Units are the same as the score's time units.

Raises:

ValueError –

If there is no measure with number n.

Source code in amads/core/basics.py

def measure_times(self, n: int) -> tuple[float, float]:
    """Return the start and end times of measure n.

    Parameters
    ----------
    n : int
        The 0-based measure number.

    Returns
    -------
    tuple(float, float)
        A tuple containing the start and end times of measure n.
        Measure 0 is the first measure.  Units are the same as the
        score's time units.

    Raises
    ------
    ValueError
        If there is no measure with number n.
    """
    # Algorithm: For each Staff, linear search for nth Measure, returning
    # the onset and offset of the first one found.
    for staff in self.find_all(Staff):
        staff = cast(Staff, staff)
        for i, measure in enumerate(staff.find_all(Measure)):
            if i == n:
                return (measure.onset, measure.offset)
    raise ValueError(f"measure {n} not found")

slice ¶

slice(
    start: float,
    end: float,
    units: str = "quarters",
    mode: str = "onsets",
    truncate: str = "keep",
    shift: bool = False,
    min_duration: float = 0.05,
) -> EventGroup

Create a new Score containing the content between start and end.

Typically, this method is called on a Score to create a new Score, but it works on any Sequence as long as the sequence is part of a Score.

If self has Measures, units must be "measures" or "bars", the start and end parameters are interpreted as 0-based measure numbers, and the result will therefore contain whole measures. It is assumed that notes are tied across measure boundaries. The result will contain only the parts of tied notes that are within the specified measures, excluding measure numbered by end.

For any units besides "measures" or "bars", the score must be flat. Notes that extend beyond the start or end time are included in the result unless the truncate parameter specifies otherwise.

In principle, there is no reason to require a flat score for slicing by time, but there are many difficult edge cases to consider such as ties from within one chord to a note in another measure. Therefore, to slice by time or quarter, you must have a flattened score. Conversely, to slice a full score, you must slice by measure so that the result gives you whole measures, which are encoded into the full Score structure.

The entire result can be shifted to start at time 0 by setting the shift parameter to True. Unless truncate is "truncate" or "beginning", the result can include events that start before the start time, in which case shifting will only shift the earliest onset to 0, which means the shift amount depends upon the content. (Negative onsets are currently not allowed.)

The resulting Score, Part, and other content will have onset and offset times matching start and end, even if some content starts earlier or ends later.

Parameters:

start (float) –

The start time of the slice, inclusive. If units is "measures" or "bars", start is a 0-based measure number of the first measure.
end (float) –

The end time of the slice, exclusive. For measures, end is the 0-based measure number of the last measure plus one, so the last measure is end - 1.
units (str, default: 'quarters' ) –

The time units for start and end. Valid values are "quarters", "s", "sec", "seconds", "measures", or "bars".
shift (bool, default: False ) –

If true, shift the content in the result so that the result starts time 0.0. If false (default), the content in the result retains the same time values as in the original Score.
mode (Optional[str], default: 'onsets' ) –
The slicing mode, ignored if units is "measures" or "bars". Valid values are:
- "onsets" - include events that start within bounds (default)
- "overlaps" - include events that overlap (either onset or offset) is within the bounds. An event ending is considered to overlap if its offset is greater than start.
- "offsets" - include events that end within the bounds
- "strict" - include only events that start at or after start and end at or before end. (End times that are exactly equal to end are considered to be within bounds, so this is inclusive of end time.)
truncate (str, default: 'keep' ) –
How to handle events that partially overlap the bounds, ignored if units is "measures" or "bars". Valid values are:
- "truncate" - truncate (clip) events that partially overlap the bounds. If the event onset is before start, the onset is increased to start (adjusting duration to maintain the offset time). Also, if the event offset is after end, the duration is decreased so that the offset time is end.
- "keep" - no modification/truncation (default). Note that with the default mode="onsets", no event onsets will be earlier than start, but offsets may extend beyond end.
- "end" or "ending" or "dur" or "duration" - truncate (clip) events that extend beyond end so that all offsets <= end.
- "beginning" - events with onsets before start are moved to make their onsets equal to start, and their duration is adjusted to maintain the original offset.
min_duration (float, default: 0.05 ) –

Events with duration less than min_duration (after any truncation is applied) are removed. Ignored if units is "measures" or "bars". If None or 0.0, no events are removed. The default is 0.05, independent of time units. Be careful with gracenotes that, when read from MusicXML, have zero duration.

Returns:

Score –

A new Score instance containing the content between start and end.

Raises:

ValueError –

If the Sequence is not part of a Score, or if invalid values are provided for the parameters.

Source code in amads/core/basics.py

def slice(self, start: float, end: float, units: str = "quarters",
          mode: str = "onsets", truncate: str = "keep", shift: bool = False,
          min_duration: float = 0.05) -> "EventGroup":
    """
    Create a new Score containing the content between start and end.

    Typically, this method is called on a Score to create a new Score,
    but it works on any Sequence as long as the sequence is part of a Score.

    If self has Measures, units must be "measures" or "bars", the start and
    end parameters are interpreted as 0-based measure numbers, and the
    result will therefore contain whole measures. It is assumed that notes
    are tied across measure boundaries. The result will contain only the
    parts of tied notes that are within the specified measures, excluding
    measure numbered by `end`.

    For any units besides "measures" or "bars", the score must be flat.
    Notes that extend beyond the start or end time are included in the
    result unless the `truncate` parameter specifies otherwise.

    In principle, there is no reason to require a flat score for slicing by
    time, but there are many difficult edge cases to consider such as ties
    from within one chord to a note in another measure. Therefore, to slice
    by time or quarter, you must have a flattened score. Conversely, to
    slice a full score, you must slice by measure so that the result gives
    you whole measures, which are encoded into the full Score structure.

    The entire result can be shifted to start at time 0 by setting the
    `shift` parameter to True.  Unless `truncate` is "truncate" or
    "beginning", the result can include events that start before the start
    time, in which case shifting will only shift the earliest onset to 0,
    which means the shift amount depends upon the content. (Negative onsets
    are currently not allowed.)

    The resulting Score, Part, and other content will have onset and offset
    times matching start and end, even if some content starts earlier or
    ends later.

    Parameters
    ----------
    start : float
        The start time of the slice, inclusive. If units is "measures" or
        "bars", start is a 0-based measure number of the first measure.
    end : float
        The end time of the slice, exclusive. For measures, end is the
        0-based measure number of the last measure plus one, so the last
        measure is end - 1.
    units : str
        The time units for start and end. Valid values are "quarters", "s",
        "sec", "seconds", "measures", or "bars".
    shift: bool
        If true, shift the content in the result so that the result starts
        time 0.0. If false (default), the content in the result retains
        the same time values as in the original Score.
    mode : Optional[str]
        The slicing mode, ignored if units is "measures" or "bars".
        Valid values are:

        - `"onsets"` - include events that start within bounds (default)
        - `"overlaps"` - include events that overlap (either onset or
            offset) is within the bounds. An event ending is considered
            to overlap if its offset is greater than start.
        - `"offsets"` - include events that end within the bounds
        - `"strict"` - include only events that start at or after start
            and end at or before end. (End times that are exactly equal
            to end are considered to be within bounds, so this is
            inclusive of end time.)

    truncate: Optional[str]
        How to handle events that partially overlap the bounds,
        ignored if units is "measures" or "bars". Valid values are:

        - `"truncate"` - truncate (clip) events that partially overlap
            the bounds. If the event onset is before start, the onset
            is increased to start (adjusting duration to maintain the
            offset time). Also, if the event offset is after end, the
            duration is decreased so that the offset time is end.
        - `"keep"` - no modification/truncation (default). Note that
            with the default mode="onsets", no event onsets will be
            earlier than start, but offsets may extend beyond end.
        - `"end"` or "ending" or "dur" or "duration" - truncate (clip)
            events that extend beyond end so that all offsets <= end.
        - `"beginning"` - events with onsets before start are moved to
            make their onsets equal to start, and their duration is
            adjusted to maintain the original offset.

    min_duration: Optional[float]
        Events with duration less than min_duration (after any truncation
        is applied) are removed.  Ignored if units is "measures" or "bars".
        If None or 0.0, no events are removed. The default is 0.05,
        independent of time units. Be careful with gracenotes that, when
        read from MusicXML, have zero duration.

    Returns
    -------
    Score
        A new Score instance containing the content between start and end.

    Raises
    ------
    ValueError
        If the Sequence is not part of a Score, or if invalid values are
        provided for the parameters.
    """
    score = self.score
    if score is None:
        raise ValueError("slice can only be called on a Sequence that is "
                         "part of a Score")
    if score.is_flat():
        if units in ("measures", "bars"):
            raise ValueError(f"units cannot be {units} for slicing a "
                             "flat score")
    else:
        if units not in ("measures", "bars"):
            raise ValueError(f"units must be measures or bars for slicing "
                "a score with Measures (or flatten the score before "
                "slicing)")

    if units in ("quarters", "measures", "bars"):
        score.convert_to_quarters()
    elif units in ("s", "sec", "seconds"):
        score.convert_to_seconds()
    else:
        raise ValueError('units must be "quarters", "measures, "'
                         '"bars", "s", "sec", or "seconds"')

    # Find start time and end time for slice. It may not be (start, end)
    # if units is measures or bars.
    if units in ("measures", "bars"):
        (start_time, end_time) = self.measure_times(int(start))
        if end != start:
            (_, end_time) = self.measure_times(int(end) - 1)
    else:
        start_time = start
        end_time = end

    # construct the parts of the tree above self and make an empty copy
    # of self to add the slice content.
    result = (score.emptycopy() if isinstance(self, Score)
              else self._copy_parents(start_time, end_time))
    result.onset = start_time  # result is an empty copy of self. Set the
    result.offset = end_time   # onset and offset to the slice bounds.
    if units in ("measures", "bars"):
        c_min, c_max = result._add_measure_children(self, start, end,
                                                    start_time, end_time)
        if c_min < start_time or c_max > end_time:
            raise ValueError("unexpectedly found content outside the "
                             "measure slice bounds")
        min_time = c_min
        max_time = c_max
    else:   
        min_time, max_time = result._add_slice_children(self, start_time,
                                  end_time, mode, truncate, min_duration)
    result._trim_map_and_signatures(min_time, max_time)
    if shift and min_time != float("inf") and min_time > 0:
        result.time_shift(-min_time)
    return result

from_melody `classmethod` ¶

from_melody(
    pitches: list[Union[Pitch, int, float, str]],
    durations: Union[float, list[float]] = 1.0,
    iois: Optional[Union[float, list[float]]] = None,
    onsets: Optional[list[float]] = None,
    ties: Optional[list[bool]] = None,
) -> Score

Create a Score from a melody specified by pitches and timing.

Parameters:

pitches (list of int or list of Pitch) –

MIDI note numbers or Pitch objects for each note.
durations (float or list of float, default: 1.0 ) –

Durations in quarters for each note. If a scalar value, it will be repeated for all notes.
iois (float or list of float or None Inter-onset, default: None ) –

intervals between successive notes. If a scalar value, it will be repeated for all notes. If not provided and onsets is None, takes values from the durations argument, assuming that notes are placed sequentially without overlap.
onsets (list of float or None, default: None ) –

Start times. Cannot be used together with iois. If both are None, defaults to using durations as IOIs.
ties (list of bool or None, default: None ) –

If provided, a list of booleans indicating whether each note is tied to the next note. The last note's tie value is ignored. If None, no ties are created.

Returns:

Score –

A new (flat) Score object containing the melody. If pitches is empty, returns a score with an empty part.

Examples:

Create a simple C major scale with default timing (sequential quarter notes):

>>> score = Score.from_melody([60, 62, 64, 65, 67, 69, 71, 72])
>>> notes = score.content[0].content
>>> len(notes)  # number of notes in first part
8
>>> notes[0].key_num
60
>>> score.duration  # last note ends at t=8
8.0

Create three notes with varying durations:

>>> score = Score.from_melody(
...     pitches=[60, 62, 64],  # C4, D4, E4
...     durations=[0.5, 1.0, 2.0],
... )
>>> score.duration  # last note ends at t=3.5
3.5

Create three notes with custom IOIs:

>>> score = Score.from_melody(
...     pitches=[60, 62, 64],  # C4, D4, E4
...     durations=1.0,  # quarter notes
...     iois=2.0,  # 2 beats between each note onset
... )
>>> score.duration  # last note ends at t=5
5.0

Create three notes with explicit onsets:

>>> score = Score.from_melody(
...     pitches=[60, 62, 64],  # C4, D4, E4
...     durations=1.0,  # quarter notes
...     onsets=[0.0, 2.0, 4.0],  # onset times 2 beats apart
... )
>>> score.duration  # last note ends at t=5
5.0

Source code in amads/core/basics.py

@classmethod
def from_melody(cls,
                pitches: list[Union[Pitch, int, float, str]],
                durations: Union[float, list[float]] = 1.0,
                iois: Optional[Union[float, list[float]]] = None,
                onsets: Optional[list[float]] = None,
                ties: Optional[list[bool]] = None) -> "Score":
    """Create a Score from a melody specified by pitches and timing.

    Parameters
    ----------
    pitches : list of int or list of Pitch
        MIDI note numbers or Pitch objects for each note.
    durations : float or list of float
        Durations in quarters for each note. If a scalar value,
        it will be repeated for all notes.
    iois : float or list of float or None Inter-onset
        intervals between successive notes. If a scalar value,
        it will be repeated for all notes. If not provided and
        onsets is None, takes values from the durations argument,
        assuming that notes are placed sequentially without overlap.
    onsets : list of float or None
        Start times. Cannot be used together with iois.
        If both are None, defaults to using durations as IOIs.
    ties : list of bool or None
        If provided, a list of booleans indicating whether each
        note is tied to the next note. The last note's tie value
        is ignored. If None, no ties are created.

    Returns
    -------
    Score
        A new (flat) Score object containing the melody. If pitches
        is empty, returns a score with an empty part.

    Examples
    --------
    Create a simple C major scale with default timing (sequential quarter notes):

    >>> score = Score.from_melody([60, 62, 64, 65, 67, 69, 71, 72])
    >>> notes = score.content[0].content
    >>> len(notes)  # number of notes in first part
    8
    >>> notes[0].key_num
    60
    >>> score.duration  # last note ends at t=8
    8.0

    Create three notes with varying durations:

    >>> score = Score.from_melody(
    ...     pitches=[60, 62, 64],  # C4, D4, E4
    ...     durations=[0.5, 1.0, 2.0],
    ... )
    >>> score.duration  # last note ends at t=3.5
    3.5

    Create three notes with custom IOIs:

    >>> score = Score.from_melody(
    ...     pitches=[60, 62, 64],  # C4, D4, E4
    ...     durations=1.0,  # quarter notes
    ...     iois=2.0,  # 2 beats between each note onset
    ... )
    >>> score.duration  # last note ends at t=5
    5.0

    Create three notes with explicit onsets:

    >>> score = Score.from_melody(
    ...     pitches=[60, 62, 64],  # C4, D4, E4
    ...     durations=1.0,  # quarter notes
    ...     onsets=[0.0, 2.0, 4.0],  # onset times 2 beats apart
    ... )
    >>> score.duration  # last note ends at t=5
    5.0
    """
    if len(pitches) == 0:
        return cls._from_melody(pitches=[], onsets=[], durations=[], ties=None)

    if iois is not None and onsets is not None:
        raise ValueError("Cannot specify both iois and onsets")

    # Convert scalar durations to list
    if isinstance(durations, (int, float)):
        durations = [float(durations)] * len(pitches)

    # If onsets are provided, use them directly
    if onsets is not None:
        if len(onsets) != len(pitches):
            raise ValueError("onsets list must have same length as pitches")
        onsets = [float(d) for d in onsets]

    # Otherwise convert IOIs to onsets
    else:  # onsets is Nonex
        onsets = [0.0]
        # If no IOIs provided, use durations as default IOIs
        if iois is None:
            iois = durations[:-1]  # last duration not needed for IOIs
        # Convert scalar IOIs to list
        elif isinstance(iois, (int, float)):
            iois = [float(iois)] * (len(pitches) - 1)

        # Validate IOIs length
        if len(iois) != len(pitches) - 1:
            raise ValueError("iois list must have length len(pitches) - 1")

        # Convert IOIs to onsets
        onsets = [0.0]  # first note onsets at 0
        current_time = 0.0
        for ioi in iois:
            current_time += float(ioi)
            onsets.append(current_time)

    if not (len(pitches) == len(onsets) == len(durations)):
        raise ValueError("All input lists must have the same length")

    return cls._from_melody(pitches, onsets, durations, ties)

copy ¶

copy()

Make a deep copy.

This is equivalent to EventGroup.insert_copy_into, and provided because scores do not normally have a parent and there is nothing to "copy into."

Returns:

Score –

a copy of the score.

Source code in amads/core/basics.py

def copy(self):
    """Make a deep copy.

    This is equivalent to [EventGroup.insert_copy_into](
        basics_more.md#amads.core.basics.EventGroup.insert_emptycopy_into),
    and provided
    because scores do not normally have a parent and there is nothing
    to "copy into."

    Returns
    -------
    Score
        a copy of the score.
    """
    return self.insert_copy_into(None)

emptycopy ¶

emptycopy()

Copy score without content.

See insert_emptycopy_into.

Since a Score does not normally have a parent, it is normal for the parent to be None, so emptycopy() is provided to make code more readable.

Returns:

Score –

a copy of the score with no content

Source code in amads/core/basics.py

def emptycopy(self):
    """Copy score without content.

    See [insert_emptycopy_into](
         basics_more.md#amads.core.basics.EventGroup.insert_emptycopy_into).

    Since a Score does not normally have a parent, it is normal for the
    parent to be None, so `emptycopy()` is provided to make code more
    readable.

    Returns
    -------
    Score
        a copy of the score with no content
    """
    return self.insert_emptycopy_into(None)

append_time_signature ¶

append_time_signature(time_signature: TimeSignature) -> None

Append a time signature change to the score.

If there is already a time signature at the given time, it is replaced.

Parameters:

time_signature (TimeSignature) –

The time signature to append.

Source code in amads/core/basics.py

def append_time_signature(self, time_signature: TimeSignature) -> None:
    """Append a time signature change to the score.

    If there is already a time signature at the given time, it is
    replaced.

    Parameters
    ----------
    time_signature : TimeSignature
        The time signature to append.
    """
    # Remove any existing time signature at the same time
    if isclose(self.time_signatures[-1].quarters, time_signature.quarters,
               abs_tol=0.003):
        self.time_signatures.pop()
    self.time_signatures.append(time_signature)

calc_differences ¶

calc_differences(what: List[str]) -> List[List[Note]]

Calculate inter-onset intervals (IOIs), IOI-ratios and intervals.

This method is a convenience function that calls Part.calc_differences() on each Part of the Score. Since this method requires that Notes have no ties and are not concurrent (IOI == 0), the Score will normally be flat, which means only one Part.

Parameters:

what (list of str) –

A list of strings indicating what differences to compute. Valid strings are: 'ioi' (for inter-onset intervals), 'ioi_ratio' (for ratio of successive IOIs), and 'interval' (for pitch intervals in semitones).

Returns:

list of List[Note] –

A list of Notes from each Part with the requested difference properties set.

Source code in amads/core/basics.py

def calc_differences(self, what: List[str]) -> List[List[Note]]:
    """Calculate inter-onset intervals (IOIs), IOI-ratios and intervals.

    This method is a convenience function that calls Part.calc_differences()
    on each Part of the Score. Since this method requires that Notes have
    no ties and are not concurrent (IOI == 0), the Score will normally be
    flat, which means only one Part.

    Parameters
    ----------
    what : list of str
        A list of strings indicating what differences to compute.
        Valid strings are: 'ioi' (for inter-onset intervals),
        'ioi_ratio' (for ratio of successive IOIs), and
        'interval' (for pitch intervals in semitones).

    Returns
    -------
    list of List[Note]
        A list of Notes from each Part with the requested difference
        properties set.
    """
    notes: List[List[Note]] = []
    parts: Generator = self.find_all(Part)
    for part in parts:
        part_notes = part.calc_differences(what)
        notes.append(part_notes)
    return notes

convert_to_seconds ¶

convert_to_seconds() -> None

Convert the score to represent time in seconds.

This function modifies Score without making a copy.

Source code in amads/core/basics.py

def convert_to_seconds(self) -> None:
    """Convert the score to represent time in seconds.

    This function modifies Score without making a copy.
    """
    if self.units_are_seconds:
        return
    # time_signatures are always in units of quarters
    # for ts in self.time_signatures:
    #     ts.quarters = self.time_map.quarter_to_time(ts.quarters)
    super()._convert_to_seconds(self.time_map)
    self._units_are_seconds = True   # set the flag

convert_to_quarters ¶

convert_to_quarters() -> None

Convert the score to represent time in quarters.

This function modifies Score without making a copy.

Source code in amads/core/basics.py

def convert_to_quarters(self) -> None:
    """Convert the score to represent time in quarters.

    This function modifies Score without making a copy.
    """
    if not self.units_are_seconds:
        return
    # time_signatures are always in units of quarters
    # for ts in self.time_signatures:
    #     ts.quarters = self.time_map.time_to_quarter(ts.quarters)
    super()._convert_to_quarters(self.time_map)
    self._units_are_seconds = False   # clear the flag

collapse_parts ¶

collapse_parts(part=None, staff=None, has_ties=True)

Merge the notes of selected Parts and Staffs.

This function is used to extract only selected parts or staffs from a Score and return the data as a flat Score (only one part containing only Notes, with ties merged).

The flatten() method is similar and generally preferred. Use this collapse_parts() only if you want to select an individual Staff (e.g., only the left hand when left and right appear as two staffs) or when you only want to process one Part and avoid the cost of flattening all Parts with flatten().

If you are calling this method to extract notes separately for each Staff, it may do extra work. It might save some computation by performing a one-time

score = score.merge_tied_notes()

and calling this method with the parameter has_ties=False. If has_ties is False, it is assumed without checking that each part.has_ties() is False, allowing this method to skip calls to part.merge_tied_notes() for each selected part.

Parameters:

part (Union[int, str, list[int], None], default: None ) –
If part is not None, only notes from the selected part are included:
1. part may be an integer to match a part number (number is an attribute of Part), or
2. part may be a string to match a part instrument, or
3. part may be a list with an index, e.g., [3] will select the 4th part (because indexing is zero-based).
staff (Union[int, List[int], None], default: None ) –
If staff is given, only the notes from selected staves are included. Note that staff selection requires part selection. Thus, if staff is given without part, an Exception is raised. Also, if staff is given and this is a flat score (no staves), an Exception is raised. Staff selection works as follows:
1. staff may be an integer to match a staff number, or
2. staff may be a list with an index, e.g., [1] will select the 2nd staff.
has_ties (bool, default: True ) –

Indicates the possibility of tied notes, which must be merged as part of flattening. If the parts are flat already, setting has_ties=False will save some computation.

Raises:

ValueError –
A ValueError is raised if:
- staff is given without a part specification
- staff is given and this is a flat score (no staves)

Note

The use of lists like [1] for part and staff index notation is not ideal, but parts can be assigned a designated number that is not the same as the index, so we need a way to select by designated number, e.g., 1, and by index, e.g., [1]. Initially, I used tuples, but they are error prone. E.g., part=(0) means part=0, so you would have to write collapse_parts(part=((0))). With [n] notation, you write collapse_parts(part=[0]) to indicate an index. This is prettier and less prone to error.

Source code in amads/core/basics.py

def collapse_parts(self, part=None, staff=None, has_ties=True):
    """Merge the notes of selected Parts and Staffs.

    This function is used to extract only selected parts or staffs
    from a Score and return the data as a flat Score (only
    one part containing only Notes, with ties merged).

    The `flatten()` method is similar and generally preferred. Use
    this `collapse_parts()` only if you want to select an individual
    Staff (e.g., only the left hand when left and right appear as
    two staffs) or when you only want to process one Part and avoid
    the cost of flattening *all* Parts with `flatten()`.

    If you are calling this method to extract notes separately for each
    Staff, it may do extra work. It might save some computation by
    performing a one-time

        score = score.merge_tied_notes()

    and calling this method with the parameter has_ties=False. 
    If has_ties is False, it is assumed without checking that
    each part.has_ties() is False, allowing this method to skip
    calls to part.merge_tied_notes() for each selected part.

    Parameters
    ----------
    part : Union[int, str, list[int], None]
        If part is not None, only notes from the selected part are
        included:

        1. part may be an integer to match a part number (`number` is an
              attribute of `Part`), or
        2. part may be a string to match a part instrument, or
        3. part may be a list with an index, e.g., [3] will select the 4th
              part (because indexing is zero-based).
    staff : Union[int, List[int], None]
        If staff is given, only the notes from selected staves are
        included. Note that staff selection requires part selection.
        Thus, if staff is given without part, an Exception is raised.
        Also, if staff is given and this is a flat score (no staves),
        an Exception is raised.
        Staff selection works as follows:

        1. staff may be an integer to match a staff number, or
        2. staff may be a list with an index, e.g., [1] will select
             the 2nd staff.
    has_ties : bool
        Indicates the possibility of tied notes, which must be merged
        as part of flattening. If the parts are flat already,
        setting has_ties=False will save some computation.

    Raises
    ------
    ValueError
        A ValueError is raised if:

        - staff is given without a part specification
        - staff is given and this is a flat score (no staves)

    Note
    ----
    The use of lists like [1] for part and staff index notation
    is not ideal, but parts can be assigned a designated number that
    is not the same as the index, so we need a way to select by
    designated number, e.g., 1, and by index, e.g., [1]. Initially, I
    used tuples, but they are error prone. E.g., part=(0) means part=0,
    so you would have to write collapse_parts(part=((0))). With [n]
    notation, you write collapse_parts(part=[0]) to indicate an index.
    This is prettier and less prone to error.
    """

    # Algorithm: Since we might be selecting individual Staffs and
    # Parts, we want to do selection first, then copy to avoid
    # modifying the source Score (self).
    content = []  # collect selected Parts/Staffs here
    score : Score = self.emptycopy()  # type: ignore
    parts : Generator = self.find_all(Part)
    for i, p in enumerate(parts):
        if (part is None
            or (isinstance(part, int) and part == p.number)
            or (isinstance(part, str) and part == p.instrument)
            or (isinstance(part, list) and part[0] == i)):
            # merging tied notes takes place at the Part level because
            # notes can be tied across Staffs.
            if has_ties:
                # put parts into score copy to allow onset computation
                # later, we will merge notes and remove these parts
                p = p.merge_tied_notes(score)

            if staff is None:  # no staff selection, use whole Part
                content.append(p)
            else:  # must find Notes in selected Staffs
                staffs = p.find_all(Staff)
                for i, s in enumerate(staffs):
                    if (staff is None
                        or (isinstance(staff, int) and staff == s.number)
                        or (isinstance(staff, list) and staff[0] == i)):
                        content.append(s)
    # now content is a list of Parts or Staffs to merge
    notes = []
    for part_or_staff in content:  # works with both Part and Score:
        notes += part_or_staff.list_all(Note)
    new_part = Part(parent=score)
    if not has_ties:
        # because we avoided merging ties in parts, notes still belong
        # to the original score (self), so we need to copy them:
        copies = []  # copy all notes to here
        for note in notes:
            # rather than a possibly expensive insert into new_part, we
            # use sort (below) to construct the content of new_part.
            copies.append(note.insert_copy_into(new_part))
        notes = copies
    # notes can be modified, so reuse them in the new_part:
    for note in notes:
        note.parent = new_part
    notes.sort(key=lambda x: (x.onset, x.pitch))
    new_part.content = notes
    # remove all the parts that we merged, leaving only new_part
    score.content = [new_part]
    return score

flatten ¶

flatten(collapse=False)

Deep copy notes in a score to a flat score.

A flat score consists of only Parts containing Notes (ties are merged).

See collapse_parts to select specific Parts or Staffs and flatten them.

Parameters:

collapse (bool, default: False ) –

If collapse is True, multiple parts are collapsed into a single part, and notes are ordered according to onset times. The resulting score contains one or more Parts, each containing only Notes.

Source code in amads/core/basics.py

def flatten(self, collapse=False):
    """Deep copy notes in a score to a flat score.

    A flat score consists of only Parts containing Notes
    (ties are merged).

    See [collapse_parts][amads.core.basics.Score.collapse_parts]
    to select specific Parts or Staffs and flatten them.

    Parameters
    ----------
    collapse : bool
        If collapse is True, multiple parts are collapsed into a single
        part, and notes are ordered according to onset times. The resulting
        score contains one or more Parts, each containing only Notes.
    """
    # make a deep copy of the score, merging tied notes in the process.
    score : Score = self.merge_tied_notes()  # type: ignore
    # it is now safe to modify score because it has been copied
    if collapse:  # similar to Part.flatten() but we have to sort and
        # do some other extra work to put all notes into score
        # first, see if all parts have the same instrument. If so, we
        # will set instrument in the collapsed part. Otherwise, the
        # collapsed part will not have an instrument name.
        instrument = None
        instr_state = None
        for part in score.content:
            if isinstance(part, Part):
                if instr_state is None:  # capture first instrument name
                    instrument = part.instrument
                    instr_state = "set"
                elif instrument != part.instrument:
                    instr_state = "multiple"
                    instrument = None  # multiple instrument names found
                else:  # this part.instrument is consistent
                    pass

        new_part = Part(parent=score, onset=score.onset,
                        instrument=instrument)
        notes : list[Note] = score.list_all(Note)  # type: ignore
        score.content = [new_part]  # remove all other parts and events
        for note in notes:
            note.parent = new_part
        # notes with equal onset times are sorted in pitch from high to low
        notes.sort(key=lambda x: (x.onset, x.pitch))

        new_part.content = notes  # type: ignore (List[Note] < List[Event])

        # set the Part duration so it ends at the max offset of all Parts:
        offset = max((part.offset for part in self.find_all(Part)),
                     default=0)
        new_part.duration = offset - score.onset

    else:  # flatten each part separately
        for part in score.find_all(Part):
            part.flatten(in_place=True)  # type: ignore (part is a Part)
    return score

is_flat ¶

is_flat()

Test if Score is flat.

a flat Score conforms to strict hierarchy of: Score-Part-Note with no tied notes.

Returns:

bool –

True iff the score is flat.

Source code in amads/core/basics.py

def is_flat(self):
    """Test if Score is flat.

    a flat Score conforms to strict hierarchy of:
    Score-Part-Note with no tied notes.

    Returns
    -------
    bool
        True iff the score is flat.
    """
    for part in self.content:
        # only Parts are expected, but things outside of the hierarchy
        # are allowed, so we only rule out violations of the hierarchy:
        if isinstance(part, (Score, Staff, Measure, Note, Rest, Chord)):
            return False
        if isinstance(part, Part) and not part.is_flat():
            return False
    return True

is_flat_and_collapsed ¶

is_flat_and_collapsed()

Determine if score has been flattened into one part

Returns:

bool –

True iff the score is flat and has one part.

Source code in amads/core/basics.py

def is_flat_and_collapsed(self):
    """Determine if score has been flattened into one part

    Returns
    -------
    bool
        True iff the score is flat and has one part.
    """
    return self.part_count() == 1 and self.is_flat()

is_well_formed_full_score ¶

is_well_formed_full_score() -> bool

Test if Score is a well-formed full score.

A well-formed full score is measured and conforms to a strict hierarchy of: Score-Part-Staff-Measure-(Note or Rest or Chord) and Chord-Note.

Returns:

bool –

True iff the Score is a well-formed full Score.

Source code in amads/core/basics.py

def is_well_formed_full_score(self) -> bool:
    """Test if Score is a well-formed full score.

    A well-formed full score is measured and conforms to a strict
    hierarchy of: Score-Part-Staff-Measure-(Note or Rest or Chord)
    and Chord-Note.

    Returns
    -------
    bool
        True iff the Score is a well-formed full Score.
    """
    for part in self.content:
        # only Parts are expected, but things outside of the hierarchy
        # are allowed, so we only rule out violations of the hierarchy:
        if isinstance(part, (Score, Staff, Measure, Note, Rest, Chord)):
            return False
        if isinstance(part, Part) and not part.is_well_formed_full_part():
            return False
    return True

note_containers ¶

note_containers()

Returns a list of non-empty note containers.

For full (measured) Scores, these are the Staff objects. For flat Scores, these are the Part objects. This is mainly useful for extracting note sequences where each part or staff represents a separate sequence. This method will retrieve either parts or staffs, whichever applies. This implementation also handles a mix of Parts with and without Staffs, returning a list of whichever is the direct parent of a list of Notes.

Returns:

list(EventGroup) –

list of (recursively) contained EventGroups that contain Notes

Source code in amads/core/basics.py

def note_containers(self):
    """Returns a list of non-empty note containers.

    For full (measured) Scores, these are the Staff objects.
    For flat Scores, these are the Part objects. This is mainly
    useful for extracting note sequences where each part or staff
    represents a separate sequence. This method will retrieve
    either parts or staffs, whichever applies. This implementation
    also handles a mix of Parts with and without Staffs, returning
    a list of whichever is the direct parent of a list of Notes.

    Returns
    -------
    list(EventGroup)
        list of (recursively) contained EventGroups that contain Notes
    """
    containers = []
    # start with parts, which are common to both measured scores and
    # flat scores. If the Part has a Staff, the Staffs are the
    # containers we want. If the Part has a Note, the Part itself is
    # the container. Other event classes can exist and are ignored.
    for part in self.find_all(Part):  # type: ignore (Part is an Event)
        part : Part
        for event in part.content:
            if isinstance(event, Staff):
                containers += part.list_all(Staff)
                break
            elif isinstance(event, Note):
                containers.append(part)
                break
        # if part was empty, it is not added to containers
    return containers

pack ¶

pack(onset: float = 0.0, sequential: bool = False) -> float

Adjust onsets to pack events in the entire Score.

This method modifies the Score in place, adjusting onsets so that events occur sequentially without gaps. By default, self is assumed to be a full score containing Parts with Staffs and Measures, so all contained Parts are concurrent, starting at onset, and Parts are also packed, making all Staffs start concurrently.

If the Score is flat (Parts contain only Notes), set sequential to True, which overrides the packing of Parts, making their content sequential (Notes) instead of concurrent (Staffs).

Note that the direct content of this Score starts concurrently at onset in either case. Pack is recursive, but it makes content concurrent in Concurrences like Chords and sequential is Sequences like Staffs and Measures.

Parameters:

onset (float, default: 0.0 ) –

The onset time for the Score after packing.
sequential (bool, default: False ) –

If true, Parts are conconcurrently started at onset, but each Part is packed sequentially, so that the first event in each Part starts at onset, and subsequent events start at the offset of the previous event. Use False for full scores (with Parts and Staffs) and True for flat scores (with Parts containing only Notes).

Returns:

Score –

The modified Score instance itself.

Source code in amads/core/basics.py

def pack(self, onset: float = 0.0, sequential: bool = False) -> float:
    """Adjust onsets to pack events in the entire Score.

    This method modifies the Score in place, adjusting onsets
    so that events occur sequentially without gaps. By default,
    self is assumed to be a full score containing Parts with Staffs
    and Measures, so all contained Parts are concurrent, starting
    at `onset`, and Parts are also packed, making all Staffs start
    concurrently.

    If the Score is flat (Parts contain only Notes), set `sequential`
    to True, which overrides the packing of Parts, making their
    content sequential (Notes) instead of concurrent (Staffs).

    Note that the direct content of this Score starts concurrently
    at `onset` in either case. Pack is recursive, but it makes
    content concurrent in Concurrences like Chords and sequential
    is Sequences like Staffs and Measures.

    Parameters
    ----------
    onset : float
        The onset time for the Score after packing.
    sequential : bool
        If true, Parts are conconcurrently started at `onset`, but
        each Part is packed sequentially, so that the first event
        in each Part starts at `onset`, and subsequent events
        start at the offset of the previous event. Use False for
        full scores (with Parts and Staffs) and True for flat scores
        (with Parts containing only Notes).
    Returns
    -------
    Score
        The modified Score instance itself.
    """
    dur = 0.0
    for part in self.content:  # type: ignore (score contains Parts)
        part.onset = onset
        if isinstance(part, Part):
            dur = max(dur, part.pack(onset, sequential))
        # anything but Part follows default packing behavior:
        elif isinstance(part, EventGroup):
            dur = max(dur, part.pack(onset))
        else:
            dur = max(dur, part.duration)
    self.duration = dur
    return dur

part_count ¶

part_count()

How many parts are in this score?

Returns:

int –

The number of parts in this score.

Source code in amads/core/basics.py

def part_count(self):
    """How many parts are in this score?

    Returns
    -------
    int
        The number of parts in this score.
    """
    return len(self.list_all(Part))

parts_are_monophonic ¶

parts_are_monophonic() -> bool

Determine if each part of a musical score is monophonic.

A monophonic part has no overlapping notes (e.g., chords).

Returns:

bool –

True if each part is monophonic, False otherwise.

Source code in amads/core/basics.py

def parts_are_monophonic(self) -> bool:
    """
    Determine if each part of a musical score is monophonic.

    A monophonic part has no overlapping notes (e.g., chords).

    Returns
    -------
    bool
        True if each part is monophonic, False otherwise.
    """
    for part in self.find_all(Part):
        part = cast(Part, part)
        if not part.ismonophonic():
            return False
    return True

remove_measures ¶

remove_measures() -> Score

Create a new Score with all Measures removed.

Preserves Staffs in the hierarchy. Notes are "lifted" from Measures to become direct content of their Staff. The result satisfies neither is_flat() nor is_well_formed_full_score(), but it could be useful in preserving a separation between staves. See also collapse_parts, which can be used to extract individual staves from a score. The result will have ties merged. (If you want to preserve ties and access the notes in a Staff, consider using find_all(Staff), and then for each staff, find_all(Note), but note that ties can cross between staves.)

Returns:

Score –

A new Score instance with all Measures removed.

Source code in amads/core/basics.py

def remove_measures(self) -> "Score":
    """Create a new Score with all Measures removed.

    Preserves Staffs in the hierarchy. Notes are "lifted" from Measures
    to become direct content of their Staff. The result satisfies neither
    `is_flat()` nor `is_well_formed_full_score()`, but it could be useful
    in preserving a separation between staves. See also `collapse_parts`,
    which can be used to extract individual staves from a score. The result
    will have ties merged. (If you want to preserve ties and access the
    notes in a Staff, consider using find_all(Staff), and then for each staff,
    find_all(Note), but note that ties can cross between staves.)

    Returns
    -------
    Score
        A new Score instance with all Measures removed.
    """
    score : Score = self.emptycopy()  # type: ignore
    for part in self.content:  # type: ignore (score contains Parts)
        if isinstance(part, Part):
            # puts a copy of Part with merged_notes into score and
            # then removes measures from each staff:
            part.remove_measures(score)
        else:  # non-Part objects are simply copied
            part.insert_copy_into(score)
    return score

show ¶

show(indent: int = 0, file: Optional[TextIO] = None) -> Score

Print the Score information.

Parameters:

indent (int, default: 0 ) –

The indentation level for display.

Returns:

Score –

The Score instance itself.

Source code in amads/core/basics.py

def show(self, indent: int = 0,
         file: Optional[TextIO] = None) -> "Score":
    """Print the Score information.

    Parameters
    ----------
    indent : int
        The indentation level for display.

    Returns
    -------
    Score
        The Score instance itself.
    """

    print(" " * indent, self, sep="", file=file)
    self.time_map.show(indent + 4, file=file)

    print(" " * indent, "    time_signatures [", sep="", end="") 
    need_blank = ""
    col = indent + 21
    for ts in self.time_signatures:
        tss = str(ts)
        if len(tss) + col > 79:
            print("\n", " " * (indent + 20), end="")
            col = indent + 21
        print(need_blank, tss, sep="", end="")
        col += len(tss)
        need_blank = " "
    print("]")  # newline after time signatures

    for elem in self.content:
        elem.show(indent + 4, file=file)  # type: ignore
        # type ignore because (all Events have show())
    return self

time_shift ¶

time_shift(increment: float, content_only: bool = False) -> Score

Change the onset by an increment, affecting all content.

This is tricky for scores because they have a time_map (tempo specification). If units_are_quarters, time_shift means insert initial quarters at the initial tempo, and shift all tempo changes by increment quarters. If increment is negative, it is assumed that all Events are at or after -increment, so they will shifted to positive times. Quarters are simply removed from the beginning, shifting all time signatures and tempo changes by increment quarters.

If units_are_seconds, we insert increment seconds at the initial tempo (positive increment), or we remove the first -increment seconds (negative increment) but converting increment to quarters and converting this Score to units_are_quarters.

If content_only is true, the time_map and time_signatures are left in place along with the placement of EventGroups including this Score, Parts, Staffs, Measures, and even Chords, but their Event content (Notes, Rests, KeySignatures, Clefs) are shifted. This probably only makes sense for flattened scores without Measures and Chords since Events could be shifted outside of their container boundaries.

Parameters:

increment (float) –

The time increment (in quarters or seconds).
content_only (bool, default: False ) –

If true, preserves this container's time and shifts only the content.

Returns:

Score –

The object. This method modifies the Score.

Source code in amads/core/basics.py

def time_shift(self, increment: float,
               content_only: bool = False) -> "Score":
    """
    Change the onset by an increment, affecting all content.

    This is tricky for scores because they have a time_map (tempo
    specification). If units_are_quarters, time_shift means insert
    initial quarters at the initial tempo, and shift all tempo
    changes by increment quarters. If increment is negative, it is
    assumed that all Events are at or after -increment, so they will
    shifted to positive times. Quarters are simply removed from the
    beginning, shifting all time signatures and tempo changes by
    increment quarters.

    If units_are_seconds, we insert increment seconds at the initial
    tempo (positive increment), or we remove the first -increment
    seconds (negative increment) but converting increment to quarters
    and converting this Score to units_are_quarters.

    If content_only is true, the time_map and time_signatures are
    left in place along with the placement of EventGroups including
    this Score, Parts, Staffs, Measures, and even Chords, but their
    Event content (Notes, Rests, KeySignatures, Clefs) are shifted.
    This probably only makes sense for flattened scores without
    Measures and Chords since Events could be shifted outside of
    their container boundaries.

    Parameters
    ----------
    increment : float
        The time increment (in quarters or seconds).
    content_only: bool
        If true, preserves this container's time and shifts only
        the content.

    Returns
    -------
    Score
        The object. This method modifies the `Score`.
    """
    original_units_are_seconds = self.units_are_seconds
    if original_units_are_seconds:
        if increment >= 0:
            increment = self.time_map.time_to_quarter(increment)
        else:
            increment = -self.time_map.time_to_quarter(-increment)
        self.convert_to_quarters()
    self._timesignatures_shift(increment)
    self.time_map._time_shift(increment)
    super().time_shift(increment, content_only)
    if original_units_are_seconds:
        self.convert_to_seconds()
    return self

time_stretch ¶

time_stretch(factor: float) -> Score

Scale all timing by a factor, affecting all content.

Stretching works by changing tempos, so the times in quarters are not changed.

Parameters:

factor (float) –

The scaling factor for timing.

Returns:

Score –

The object. This method modifies the Score. The units are not changed.

Source code in amads/core/basics.py

def time_stretch(self, factor: float) -> "Score":
    """
    Scale all timing by a factor, affecting all content.

    Stretching works by changing tempos, so the times in
    quarters are not changed.

    Parameters
    ----------
    factor : float
        The scaling factor for timing.

    Returns
    -------
    Score
        The object. This method modifies the `Score`. The units are
        not changed.
    """
    original_units_are_seconds = self.units_are_seconds
    if original_units_are_seconds:
        self.convert_to_quarters()
    self.time_map.time_stretch(factor)
    if original_units_are_seconds:
        self.convert_to_seconds()
    return self

Classes Representing Basic Score Elements¶

basics ¶

Overview¶

Event ¶

Attributes¶

onset property writable ¶

units_are_seconds property ¶

units_are_quarters property ¶

offset property writable ¶

part property ¶

score property ¶

staff property ¶

measure property ¶

Functions¶

set ¶

get ¶

has ¶

time_shift ¶

insert_copy_into ¶

Note ¶

Attributes¶

onset property writable ¶

units_are_seconds property ¶

units_are_quarters property ¶

offset property writable ¶

part property ¶

score property ¶

staff property ¶

measure property ¶

tied_duration property ¶

tied_offset property ¶

step property ¶

name property ¶

name_with_octave property ¶

pitch_class property writable ¶

octave property writable ¶

key_num property ¶

Functions¶

set ¶

get ¶

has ¶

time_shift ¶

insert_copy_into ¶

show ¶

enharmonic ¶

upper_enharmonic ¶

lower_enharmonic ¶

simplest_enharmonic ¶

Rest ¶

Attributes¶

onset property writable ¶

units_are_seconds property ¶

units_are_quarters property ¶

offset property writable ¶

part property ¶

score property ¶

staff property ¶

measure property ¶

Functions¶

set ¶

get ¶

has ¶

time_shift ¶

insert_copy_into ¶

show ¶

Measure ¶

Attributes¶

onset property writable ¶

units_are_seconds property ¶

units_are_quarters property ¶

offset property writable ¶

part property ¶

score property ¶

staff property ¶

measure property ¶

Functions¶

set ¶

get ¶

has ¶

time_shift ¶

onset `property` `writable` ¶

units_are_seconds `property` ¶

units_are_quarters `property` ¶

offset `property` `writable` ¶

part `property` ¶

score `property` ¶

staff `property` ¶

measure `property` ¶

onset `property` `writable` ¶

units_are_seconds `property` ¶

units_are_quarters `property` ¶

offset `property` `writable` ¶

part `property` ¶

score `property` ¶

staff `property` ¶

measure `property` ¶

tied_duration `property` ¶

tied_offset `property` ¶

step `property` ¶

name `property` ¶

name_with_octave `property` ¶

pitch_class `property` `writable` ¶

octave `property` `writable` ¶

key_num `property` ¶

onset `property` `writable` ¶

units_are_seconds `property` ¶

units_are_quarters `property` ¶

offset `property` `writable` ¶

part `property` ¶

score `property` ¶

staff `property` ¶

measure `property` ¶

onset `property` `writable` ¶

units_are_seconds `property` ¶

units_are_quarters `property` ¶

offset `property` `writable` ¶

part `property` ¶

score `property` ¶

staff `property` ¶

measure `property` ¶

onset `property` `writable` ¶

units_are_seconds `property` ¶

units_are_quarters `property` ¶

offset `property` `writable` ¶

part `property` ¶

score `property` ¶

staff `property` ¶

measure `property` ¶

onset `property` `writable` ¶

units_are_seconds `property` ¶

units_are_quarters `property` ¶

offset `property` `writable` ¶

part `property` ¶