Skip to content

Classses Representing Basic Score Elements

from amads.core import *

Note: importing amads.core imports amads.core.basics, amads.core.distribution and amads.core.timemap.

Clef 

Clef(
    parent: Optional[EventGroup] = None,
    onset: float = 0.0,
    clef: str = "treble",
)

Bases: Event

Clef is a zero-duration Event with clef information.

Parameters:

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

    The containing object or None.

  • onset (float, default: 0.0 ) –

    The onset (start) time. An initial value of None might be assigned when the Clef is inserted into an EventGroup.

  • clef (str, default: 'treble' ) –

    The clef name, one of "treble", "bass", "alto", "tenor", "percussion", "treble8vb" (Other clefs may be added later.)

Attributes:

  • parent (Optional[EventGroup]) –

    The containing object or None.

  • _onset (float) –

    The onset (start) time.

  • duration (float) –

    Always zero for this subclass.

  • clef (str) –

    The clef name, one of "treble", "bass", "alto", "tenor", "percussion", "treble8vb" (Other clefs may be added later.)

Source code in amads/core/basics.py 
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
def __init__(self,
             parent: Optional["EventGroup"] = None,
             onset: float = 0.0, clef: str = "treble"):
    super().__init__(parent, onset, 0)
    if clef not in [
        "treble", "alto", "tenor", "bass",
        "treble8va", "treble8vb",
        "bass8va", "bass8vb",
        "percussion",
        "soprano"
    ]:
        raise ValueError(f"Invalid clef: {clef}")
    self.clef = clef

Attributes

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.

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.

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

__repr__ 

__repr__() -> str

All Event subclasses inherit this to use str().

Thus, a list of Events is printed using their str methods

Source code in amads/core/basics.py 
120
121
122
123
124
125
def __repr__(self) -> str:
    """All Event subclasses inherit this to use str().

    Thus, a list of Events is printed using their __str__ methods
    """
    return str(self)

_event_times 

_event_times(dur: bool = True) -> str

produce onset and duration string for str

Source code in amads/core/basics.py 
135
136
137
138
139
140
141
def _event_times(self, dur: bool = True) -> str:
    """produce onset and duration string for __str__
    """
    duration = self.duration
    if duration is not None:
        duration = f"{self.duration:0.3f}"
    return f"{self._event_onset()}, duration={duration}"

time_shift 

time_shift(increment: float) -> Event

Change the onset by an increment.

Parameters:

  • increment (float) –

    The time increment (in quarters or seconds).

Returns:

  • Event –

    The object. This method modifies the Event.

Source code in amads/core/basics.py 
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
def time_shift(self, increment: float) -> "Event":
    """
    Change the onset by an increment.

    Parameters
    ----------
    increment : float
        The time increment (in quarters or seconds).

    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 
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
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

_quantize 

_quantize(divisions: int) -> Event

Modify onset and offset to a multiple of divisions per quarter note.

This method modifies the Event in place. It also handles tied notes.

E.g., use divisions=4 for sixteenth notes. If a Note tied to or from other notes quantizes to a zero duration, reduce the chain of tied notes to eliminate zero-length notes. See Collection.quantize for additional details.

self.onset and self.duration must be non-None.

Parameters:

  • divisions (int) –

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

Returns:

  • Event –

    self, after quantization.

Source code in amads/core/basics.py 
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
def _quantize(self, divisions: int) -> "Event":
    """Modify onset and offset to a multiple of divisions per quarter note.

    This method modifies the Event in place. It also handles tied notes.

    E.g., use divisions=4 for sixteenth notes. If a
    Note tied to or from other notes quantizes to a zero
    duration, reduce the chain of tied notes to eliminate
    zero-length notes. See Collection.quantize for
    additional details.

    self.onset and self.duration must be non-None.

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

    Returns
    -------
    Event
        self, after quantization.
    """
    if self._onset is None or self.duration is None:
        raise ValueError(
            "Cannot quantize Event with None onset or duration")
    self.onset = round(self.onset * divisions) / divisions
    quantized_offset = round(self.offset * divisions) / divisions

    # tied note cases: Given any two tied notes where the first has a
    # quantized duration of zero, we want to eliminate the first one
    # because it is almost certainly at the end of a measure and ties
    # to the "real" note at the start of the next measure. In the
    # special case where the tied-to note quantizes to a zero duration,
    # we still want it to appear at the beginning of the measure, and
    # our convention is to set its duration to one quantum as long as
    # the original string of tied notes had a non-zero duration.
    # (Zero duration is preserved however for cases like meta-events
    # and grace notes which have zero duration before quantization.)
    #     Otherwise, if there are two tied notes and the first has a
    # non-zero and the second has zero quantized duration, we assume
    # that the note extended just barely across the bar line and we
    # eliminate the second note.
    #     Note that since we cannot look back to see if we are at the
    # end of a tie, we need to look forward using Note.tie.

    if (self.duration == 0 and
        (not isinstance(self, Note) or self.tie == None)):
        return self  # do not change duration if it is originally zero

    while isinstance(self, Note) and self.tie:  # check tied-to note:
        tie = self.tie  # the note our tie connects to
        onset = round(tie.onset * divisions) / divisions  # type: ignore
        offset = round(tie.offset * divisions) / divisions  # type: ignore
        duration = offset - onset  # quantized duration
        # if we tie from non-zero quantized duration to zero quantized
        # duration, eliminate the tied-to note
        if (quantized_offset - self.onset > 0 and   # type: ignore
            duration == 0):                         # type: ignore
            self.tie = tie.tie  # in case tie continues
            # remove tied_to note from its parent
            if tie.parent:
                tie.parent.remove(tie)
            # print("removed tied-to note", tied_to,
            #       "because duration quantized to zero")
        elif quantized_offset - self.onset == 0:    # type: ignore
            # remove self from its parent; prefer tied_to note
            # before removing, transfer duration from self to
            # tied_to to avoid strange case where the tied group
            # originally had a non-zero duration so we want the
            # tied_to duration to be non-zero:
            tie.duration += self.duration
            if self.parent:
                self.parent.remove(self)
            # tied_to will be revisited and quantized so no more work here
            return self
        else:  # both notes have non-zero durations
            break

    # now that potential ties are handled, set the duration of self
    if self.duration != 0:  # only modify non-zero durations
        self.duration = quantized_offset - self.onset  # type: ignore
        if self.duration == 0:  # do not allow duration to become zero:
            self.duration = 1 / divisions 
    # else: original zero duration remains zero after quantization
    return self

_convert_to_seconds 

_convert_to_seconds(time_map: TimeMap) -> None

Convert the event's duration and onset to seconds.

Parameters:

  • time_map (TimeMap) –

    The TimeMap object used for conversion.

Source code in amads/core/basics.py 
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
def _convert_to_seconds(self, time_map: TimeMap) -> None:
    """Convert the event's duration and onset to seconds.

    Parameters
    ----------
    time_map : TimeMap
        The TimeMap object used for conversion.
    """
    if self._onset is None or self.duration is None:
        raise ValueError(
            "Cannot convert Event with None onset or duration")
    onset_time = time_map.quarter_to_time(self.onset)       # type: ignore
    offset_time = time_map.quarter_to_time(self.offset)     # type: ignore
    self.onset = onset_time
    self.duration = offset_time - onset_time

_convert_to_quarters 

_convert_to_quarters(time_map: TimeMap) -> None

Convert the event's duration and onset to quarters.

Parameters:

  • time_map (TimeMap) –

    The TimeMap object used for conversion.

Source code in amads/core/basics.py 
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
def _convert_to_quarters(self, time_map: TimeMap) -> None:
    """Convert the event's duration and onset to quarters.

    Parameters
    ----------
    time_map : TimeMap
        The TimeMap object used for conversion.
    """
    if self._onset is None or self.duration is None:
        raise ValueError(
            "Cannot convert Event with None onset or duration")
    onset_quarters = time_map.time_to_quarter(self.onset)
    offset_quarters = time_map.time_to_quarter(self.offset)
    self.onset = onset_quarters
    self.duration = offset_quarters - onset_quarters

KeySignature 

KeySignature(
    parent: Optional[EventGroup] = None,
    onset: float = 0.0,
    key_sig: int = 0,
)

Bases: Event

KeySignature is a zero-duration Event with key signature information.

Parameters:

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

    The containing object or None.

  • onset (float, default: 0.0 ) –

    The onset (start) time. An initial value of None might be assigned when the KeySignature is inserted into an EventGroup.

  • key_sig (int, default: 0 ) –

    An integer representing the number of sharps (if positive) and flats (if negative), e.g., -3 for Eb major or C minor.

Attributes:

  • parent (Optional[EventGroup]) –

    The containing object or None.

  • _onset (float) –

    The onset (start) time.

  • duration (float) –

    Always zero for this subclass.

  • key_sig (int) –

    An integer representing the number of sharps and flats.

Source code in amads/core/basics.py 
1207
1208
1209
1210
def __init__(self, parent: Optional["EventGroup"] = None,
             onset: float = 0.0, key_sig: int = 0):
    super().__init__(parent=parent, onset=onset, duration=0)
    self.key_sig = key_sig

Attributes

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.

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.

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

__repr__ 

__repr__() -> str

All Event subclasses inherit this to use str().

Thus, a list of Events is printed using their str methods

Source code in amads/core/basics.py 
120
121
122
123
124
125
def __repr__(self) -> str:
    """All Event subclasses inherit this to use str().

    Thus, a list of Events is printed using their __str__ methods
    """
    return str(self)

_event_times 

_event_times(dur: bool = True) -> str

produce onset and duration string for str

Source code in amads/core/basics.py 
135
136
137
138
139
140
141
def _event_times(self, dur: bool = True) -> str:
    """produce onset and duration string for __str__
    """
    duration = self.duration
    if duration is not None:
        duration = f"{self.duration:0.3f}"
    return f"{self._event_onset()}, duration={duration}"

time_shift 

time_shift(increment: float) -> Event

Change the onset by an increment.

Parameters:

  • increment (float) –

    The time increment (in quarters or seconds).

Returns:

  • Event –

    The object. This method modifies the Event.

Source code in amads/core/basics.py 
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
def time_shift(self, increment: float) -> "Event":
    """
    Change the onset by an increment.

    Parameters
    ----------
    increment : float
        The time increment (in quarters or seconds).

    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 
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
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

_quantize 

_quantize(divisions: int) -> Event

Modify onset and offset to a multiple of divisions per quarter note.

This method modifies the Event in place. It also handles tied notes.

E.g., use divisions=4 for sixteenth notes. If a Note tied to or from other notes quantizes to a zero duration, reduce the chain of tied notes to eliminate zero-length notes. See Collection.quantize for additional details.

self.onset and self.duration must be non-None.

Parameters:

  • divisions (int) –

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

Returns:

  • Event –

    self, after quantization.

Source code in amads/core/basics.py 
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
def _quantize(self, divisions: int) -> "Event":
    """Modify onset and offset to a multiple of divisions per quarter note.

    This method modifies the Event in place. It also handles tied notes.

    E.g., use divisions=4 for sixteenth notes. If a
    Note tied to or from other notes quantizes to a zero
    duration, reduce the chain of tied notes to eliminate
    zero-length notes. See Collection.quantize for
    additional details.

    self.onset and self.duration must be non-None.

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

    Returns
    -------
    Event
        self, after quantization.
    """
    if self._onset is None or self.duration is None:
        raise ValueError(
            "Cannot quantize Event with None onset or duration")
    self.onset = round(self.onset * divisions) / divisions
    quantized_offset = round(self.offset * divisions) / divisions

    # tied note cases: Given any two tied notes where the first has a
    # quantized duration of zero, we want to eliminate the first one
    # because it is almost certainly at the end of a measure and ties
    # to the "real" note at the start of the next measure. In the
    # special case where the tied-to note quantizes to a zero duration,
    # we still want it to appear at the beginning of the measure, and
    # our convention is to set its duration to one quantum as long as
    # the original string of tied notes had a non-zero duration.
    # (Zero duration is preserved however for cases like meta-events
    # and grace notes which have zero duration before quantization.)
    #     Otherwise, if there are two tied notes and the first has a
    # non-zero and the second has zero quantized duration, we assume
    # that the note extended just barely across the bar line and we
    # eliminate the second note.
    #     Note that since we cannot look back to see if we are at the
    # end of a tie, we need to look forward using Note.tie.

    if (self.duration == 0 and
        (not isinstance(self, Note) or self.tie == None)):
        return self  # do not change duration if it is originally zero

    while isinstance(self, Note) and self.tie:  # check tied-to note:
        tie = self.tie  # the note our tie connects to
        onset = round(tie.onset * divisions) / divisions  # type: ignore
        offset = round(tie.offset * divisions) / divisions  # type: ignore
        duration = offset - onset  # quantized duration
        # if we tie from non-zero quantized duration to zero quantized
        # duration, eliminate the tied-to note
        if (quantized_offset - self.onset > 0 and   # type: ignore
            duration == 0):                         # type: ignore
            self.tie = tie.tie  # in case tie continues
            # remove tied_to note from its parent
            if tie.parent:
                tie.parent.remove(tie)
            # print("removed tied-to note", tied_to,
            #       "because duration quantized to zero")
        elif quantized_offset - self.onset == 0:    # type: ignore
            # remove self from its parent; prefer tied_to note
            # before removing, transfer duration from self to
            # tied_to to avoid strange case where the tied group
            # originally had a non-zero duration so we want the
            # tied_to duration to be non-zero:
            tie.duration += self.duration
            if self.parent:
                self.parent.remove(self)
            # tied_to will be revisited and quantized so no more work here
            return self
        else:  # both notes have non-zero durations
            break

    # now that potential ties are handled, set the duration of self
    if self.duration != 0:  # only modify non-zero durations
        self.duration = quantized_offset - self.onset  # type: ignore
        if self.duration == 0:  # do not allow duration to become zero:
            self.duration = 1 / divisions 
    # else: original zero duration remains zero after quantization
    return self

_convert_to_seconds 

_convert_to_seconds(time_map: TimeMap) -> None

Convert the event's duration and onset to seconds.

Parameters:

  • time_map (TimeMap) –

    The TimeMap object used for conversion.

Source code in amads/core/basics.py 
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
def _convert_to_seconds(self, time_map: TimeMap) -> None:
    """Convert the event's duration and onset to seconds.

    Parameters
    ----------
    time_map : TimeMap
        The TimeMap object used for conversion.
    """
    if self._onset is None or self.duration is None:
        raise ValueError(
            "Cannot convert Event with None onset or duration")
    onset_time = time_map.quarter_to_time(self.onset)       # type: ignore
    offset_time = time_map.quarter_to_time(self.offset)     # type: ignore
    self.onset = onset_time
    self.duration = offset_time - onset_time

_convert_to_quarters 

_convert_to_quarters(time_map: TimeMap) -> None

Convert the event's duration and onset to quarters.

Parameters:

  • time_map (TimeMap) –

    The TimeMap object used for conversion.

Source code in amads/core/basics.py 
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
def _convert_to_quarters(self, time_map: TimeMap) -> None:
    """Convert the event's duration and onset to quarters.

    Parameters
    ----------
    time_map : TimeMap
        The TimeMap object used for conversion.
    """
    if self._onset is None or self.duration is None:
        raise ValueError(
            "Cannot convert Event with None onset or duration")
    onset_quarters = time_map.time_to_quarter(self.onset)
    offset_quarters = time_map.time_to_quarter(self.offset)
    self.onset = onset_quarters
    self.duration = offset_quarters - onset_quarters

EventGroup 

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

Bases: Event

A collection of Event objects. (An abstract class.)

Use one of the subclasses: Score, Part, Staff, Measure or Chord.

Normally, you create any EventGroup (Chord, Measure, Staff, Part, Score) with no content, then add content. You can add content in bulk by simply setting the content attribute to a list of Events whose parent attributes have been set to the EventGroup. You can also add one event at a time, by calling the EventGroup's insert method. (This will change the event parent from None to the group.) It is recommended to specify all onsets and durations explicitly, including the onset of the group itself.

Alternatively, you can provide content when the group is constructed. Chord, Measure, Staff, Part, and Score all have *args parameters so that you can write something like:

Score(Part(Staff(Measure(Note(...), Note(...)),
Measure(Note(...), Note(...)))))

In this case, it is recommended that you leave the onsets of content and chord unknown (None, the default). Then, as each event or group becomes content for a parent, the onsets will be set automatically, organizing events sequentially (in Measures and Staves) or concurrently (in Chords, Parts, Scores).

The use of unknown (None) onsets is offered as a convenience for simple cases. The main risk is that onsets are considered to be relative to the group onset if the group onset is not known. E.g. if onsets are specified within the content of an EventGroup (Chord, Measure, Staff, Part, Score) but the group onset is unknown (None), and then you assign (or a parent assigns) an onset value to the group, the content onsets (even “known” ones) will all be shifted by the assigned onset. This happens only when changing an onset from None to a number. Subsequent changes to the group onset will not adjust the content onsets, which are considered absolute times once the group onset is known.

EventGroup is subclassed to form Concurrence and Sequence. A Concurrence defaults to placing all events at onset 0, while Sequence defaults to placing events sequentially such that event inter-onset intervals are their durations. The EventGroup behaves like Concurrence, so the Concurrence implementation is minimal, while the Sequence needs several methods to override EventGroup behavior to support sequential behavior.

Parameters:

  • parent (Optional[EventGroup]) –

    The containing object or None.

  • onset (float | None) –

    The onset (start) time.

  • duration (Optional[float]) –

    The duration in quarters or seconds.

  • content (Optional[list]) –

    A list of Event objects to be added to the group. The parent of each Event is set to this EventGroup, and it is an error if any Event already has a parent.

Attributes:

  • parent (Optional[EventGroup]) –

    The containing object or None.

  • _onset (Optional[float]) –

    The onset (start) time.

  • duration (float) –

    The duration in quarters or seconds.

  • content (list[Event]) –

    Elements contained within this collection.

Source code in amads/core/basics.py 
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
def __init__(self, parent: Optional["EventGroup"],
             onset: Optional[float], duration: Optional[float],
             content: Optional[list[Event]]):
    # pass 0 for duration because Event constructor wants a number,
    # but we will set duration later based on duration parameter or
    # based on content if duration is None:
    super().__init__(parent=parent, onset=onset, duration=0)
    if content is None:
        content = []
    # member_onset is the default onset for children
    member_onset = 0 if onset is None else onset
    prev_onset = member_onset
    for elem in content:  # check and set parents
        if elem.parent and elem.parent != self:
            raise ValueError("Event already has a (different) parent")
        elem.parent = self  # type: ignore
        if elem._onset is None:
            elem.onset = member_onset
        elif elem._onset < prev_onset:
            raise ValueError("content is not in onset time order")
        # # Rounding can cause notes to get re-ordered when they should
        # # be simultaneous. This finds notes that are within 1 usec and
        # # overwrites the onsets after the first note so they are all
        # # equal. Then get_sorted_notes() will sort these by pitch:
        # elif elem._onset < prev_onset + 1.0e-6:
        #     elem._onset = prev_onset
        else:
            prev_onset = elem._onset

    if duration is None:  # compute duration from content
        max_offset = 0
        for elem in content:
            max_offset = max(max_offset, elem.offset)
        duration = max_offset
        if onset:
            duration = max_offset - onset
    self.duration = duration  # type: ignore (duration is now number)
    self.content = content

Attributes

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.

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.

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

__repr__ 

__repr__() -> str

All Event subclasses inherit this to use str().

Thus, a list of Events is printed using their str methods

Source code in amads/core/basics.py 
120
121
122
123
124
125
def __repr__(self) -> str:
    """All Event subclasses inherit this to use str().

    Thus, a list of Events is printed using their __str__ methods
    """
    return str(self)

_event_times 

_event_times(dur: bool = True) -> str

produce onset and duration string for str

Source code in amads/core/basics.py 
135
136
137
138
139
140
141
def _event_times(self, dur: bool = True) -> str:
    """produce onset and duration string for __str__
    """
    duration = self.duration
    if duration is not None:
        duration = f"{self.duration:0.3f}"
    return f"{self._event_onset()}, duration={duration}"

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 
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
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

_find_copied_version 

_find_copied_version(
    original_note: Note, exclude: Note
) -> Optional[Note]

Find the copied version of a note in self.

Parameters:

  • original_note (Note) –

    The note that was copied

Source code in amads/core/basics.py 
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
def _find_copied_version(self, original_note: Note,
                         exclude: Note) -> Optional[Note]:
    """Find the copied version of a note in self.

    Parameters
    ----------
    original_note: Note
        The note that was copied
    """
    for note in self.find_all(Note):
        note = cast(Note, note)
        if (note != exclude and note.onset == original_note.onset and
            note.pitch == original_note.pitch and
            note.duration == original_note.duration):
            return note
    return None

_add_slice_children 

_add_slice_children(
    source: EventGroup,
    start: float,
    end: float,
    mode: str,
    truncate: str,
    min_duration: float,
) -> tuple[float, float]

Helper method for slice to populate the content of self. Assumes that source is a component of a flat score and that self is a Sequence with no content.

Returns:

  • float –

    The minimum onset of the content added to self.

Source code in amads/core/basics.py 
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
def _add_slice_children(self, source: "EventGroup", start: float,
        end: float, mode: str, truncate: str,
        min_duration: float) -> tuple[float, float]:
    """Helper method for slice to populate the content of self.
    Assumes that source is a component of a flat score and that self
    is a Sequence with no content.

    Returns
    -------
    float
        The minimum onset of the content added to self.
    """
    # Begin by finding all content to be included. Since score is flat,
    # source can only be a Score, a Part, or a Staff. So if a component is
    # not a Note, we copy all children (Parts or Staffs) into content
    # and recurse to add a slice of *their* content.
    min_onset = float("inf")
    max_offset = float("-inf")
    content = source.content
    if len(content) == 0:
        return min_onset, max_offset
    if not isinstance(content[0], Note):
        for elem in content:
            if isinstance(elem, EventGroup):
                elem_copy = elem.insert_emptycopy_into(self)
                e_min, e_max = elem._add_slice_children(elem_copy, start,
                                       end, mode, truncate, min_duration)
                min_onset = min(min_onset, e_min)
                max_offset = max(max_offset, e_max)
        return min_onset, max_offset

    assert(isinstance(source, Sequence))  # content is a list of Notes

    for elem in content:
        copied = None
        if mode == "onsets":
            if elem.onset >= start and elem.onset < end:
                copied = elem.insert_copy_into(self)  # copy elem into self
        elif mode == "overlaps":
            if elem.onset < end and elem.offset > start:
                copied = elem.insert_copy_into(self)  # copy elem into self
        elif mode == "offsets":
            if elem.offset > start and elem.offset <= end:
                copied = elem.insert_copy_into(self)  # copy elem into self
        elif mode == "strict":
            if elem.onset >= start and elem.offset <= end:
                copied = elem.insert_copy_into(self)  # copy elem into self
        else:
            raise ValueError(f"invalid mode {mode} for slice")
        if copied:
            min_onset = min(min_onset, copied.onset)
            max_offset = max(max_offset, copied.offset)

    if truncate == "keep":
        return min_onset, max_offset
    if truncate in ["truncate", "beginning"]:
        # if we are truncating notes that start before start, we can save
        # some time by only looking at elements where onset < start
        j = len(content)
        for i, elem in enumerate(content):
            if elem.onset > start:
                j = i
                break  # now j indexes the first element with onset > start
        min_onset = source._truncate_note_beginnings(content[0 : j], start)
    if truncate in ["truncate", "dur", "duration", "end", "ending"]:
        # any note can end after end, so we have to look at all of them:
        max_offset = source._truncate_note_endings(content, end)

    # now remove any notes that are too short after truncation:
    if min_duration > 0:
        min_onset = float("inf")
        max_offset = float("-inf")
        filtered = []
        for elem in content:
            if elem.duration >= min_duration:
                filtered.append(elem)
                min_onset = min(min_onset, elem.onset)
                max_offset = max(max_offset, elem.offset)
        source.content = filtered
    return min_onset, max_offset

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 
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
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

time_shift 

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

Change the onset by an increment, affecting all content.

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.

Source code in amads/core/basics.py 
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
def time_shift(self, increment: float,
               content_only: bool = False) -> "EventGroup":
    """
    Change the onset by an increment, affecting all content.

    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`.
    """
    if not content_only:
        self._onset += increment  # type: ignore (onset is now number)
    for elem in self.content:
        elem.time_shift(increment)
    return self

_convert_to_seconds 

_convert_to_seconds(time_map: TimeMap) -> None

Convert the event's duration and onset to seconds using the provided TimeMap. Convert content as well.

Parameters:

  • time_map (TimeMap) –

    The TimeMap object used for conversion.

Source code in amads/core/basics.py 
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
def _convert_to_seconds(self, time_map: TimeMap) -> None:
    """Convert the event's duration and onset to seconds using the
    provided TimeMap. Convert content as well.

    Parameters
    ----------
    time_map : TimeMap
        The TimeMap object used for conversion.
    """
    super()._convert_to_seconds(time_map)
    for elem in self.content:
        elem._convert_to_seconds(time_map)

_convert_to_quarters 

_convert_to_quarters(time_map: TimeMap) -> None

Convert the event's duration and onset to quarters using the provided TimeMap. Convert content as well.

Parameters:

  • time_map (TimeMap) –

    The TimeMap object used for conversion.

Source code in amads/core/basics.py 
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
def _convert_to_quarters(self, time_map: TimeMap) -> None:
    """Convert the event's duration and onset to quarters using the
    provided TimeMap. Convert content as well.

    Parameters
    ----------
    time_map : TimeMap
        The TimeMap object used for conversion.
    """
    onset_quarters = time_map.time_to_quarter(self.onset)
    offset_quarters = time_map.time_to_quarter(self.onset + self.duration)
    self.onset = onset_quarters
    self.duration = offset_quarters - onset_quarters
    for elem in self.content:
        elem._convert_to_quarters(time_map)

_copy_parents 

_copy_parents(start: float, end: float) -> EventGroup

Helper method for slice to populate the ancestors of self in result.

This method is called by slice to populate the ancestors of self in the result Score. The ancestors are populated with empty copies of the original ancestors.

Returns:

  • EventGroup –

    A copy of self with ancestors copied up to the Score.

Raises:

  • ValueError –

    If self is not part of a Score.

Source code in amads/core/basics.py 
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
def _copy_parents(self, start: float, end: float) -> "EventGroup":
    """Helper method for slice to populate the ancestors of self in result.

    This method is called by `slice` to populate the ancestors of self in
    the result Score. The ancestors are populated with empty copies of the
    original ancestors.

    Returns
    -------
    EventGroup
        A copy of self with ancestors copied up to the Score.

    Raises
    ------
    ValueError
        If self is not part of a Score.
    """
    # Algorithm: recursively populate ancestors from self up to score.
    if self is None:
        raise ValueError("slice can only be called on Sequences that are "
                         "part of a Score")
    elif isinstance(self, Score):  # base case: self is a Score
        return self # return copy of self
    else:  # copy parent & up; return copy of self inserted into parent copy
        parent = cast(EventGroup, self.parent)._copy_parents(start, end)
        parent.onset = start
        parent.offset = end
        # insert copy of self into parent copy:
        return self.insert_emptycopy_into(parent)

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 
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
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 
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
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 
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
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)

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 
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
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_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 
1778
1779
1780
1781
1782
1783
1784
1785
1786
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 
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
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 
1804
1805
1806
1807
1808
1809
1810
1811
1812
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 
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
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)

Source code in amads/core/basics.py 
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
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)
    """
    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 
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
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

_leaf_elements 

_leaf_elements() -> list[Event]

Return a list of all leaf elements in this EventGroup.

Source code in amads/core/basics.py 
1893
1894
1895
1896
1897
1898
1899
1900
1901
def _leaf_elements(self) -> list[Event]:
    """Return a list of all leaf elements in this EventGroup."""
    result = []
    for elem in self.content:
        if isinstance(elem, EventGroup):
            result.extend(elem._leaf_elements())
        else:
            result.append(elem)
    return result

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 
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
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 
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
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 
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
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

"Since _quantize is called recursively on children, this method is needed to redirect EventGroup._quantize to quantize

Source code in amads/core/basics.py 
2025
2026
2027
2028
2029
def _quantize(self, divisions: int) -> "EventGroup":
    """"Since `_quantize` is called recursively on children, this method is
    needed to redirect `EventGroup._quantize` to `quantize`
    """
    return self.quantize(divisions)

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:

  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.

Source code in amads/core/basics.py 
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
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

_add_measure_children 

_add_measure_children(
    source: EventGroup,
    start: float,
    end: float,
    start_time: float,
    end_time: float,
) -> tuple[float, float]

Helper method for to populate the content with selected measures. Assumes that self is a component of a full score and that this Staff (self) has no content yet.

Since only measures within start and end are copied, the copied measures and other content all have onsets and offsets within copy range and do not need to be adjusted.

Assumes that notes crossing measure boundaries are tied and that ties to notes outside the copied measures should be broken, truncating the copied note to the measure boundary.

Returns:

  • tuple[float, float] –

    The minimum onset and maximum offset of the content added to self.

Source code in amads/core/basics.py 
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
def _add_measure_children(self, source: "EventGroup", start: float,
                          end: float, start_time: float,
                          end_time: float) -> tuple[float, float]:
    """Helper method for to populate the content with
    selected measures. Assumes that self is a component of a full score and
    that this Staff (self) has no content yet.

    Since only measures within start and end are copied, the copied
    measures and other content all have onsets and offsets within
    copy range and do not need to be adjusted.

    Assumes that notes crossing measure boundaries are tied and that
    ties to notes outside the copied measures should be broken, truncating
    the copied note to the measure boundary.

    Returns
    -------
    tuple[float, float]
        The minimum onset and maximum offset of the content added to self.
    """
    # Assume that whatever EventGroup(s) contain measures, they will *only*
    # contain measures, so we can check content[0] to find the measure
    # level. Recursively copy the structure from this level down to the
    # measure level whether or not any measures are encountered.
    #     Also assume any level with measures is well formed with all
    # measures contiguous, in order, starting at zero, and with durations
    # in compliance with time signatures.
    min_onset = float("inf")
    max_offset = float("-inf")
    if len(source.content) == 0:
        return min_onset, max_offset
    if isinstance(source.content[0], Measure):
        # find and copy the measures that are in the range
        start = round(start)
        end = round(end)
        for i, elem in enumerate(source.content):
            assert isinstance(elem, Measure), \
                   "expected Measures at this level"
            if i >= start and i < end:
                min_onset = min(min_onset, elem.onset)
                max_offset = max(max_offset, elem.offset)
                _ = elem.insert_copy_into(self)  # copy elem into self
        # if copied content has tied notes, the links will still refer
        # to the original notes, so we need to update the ties to
        # refer to the copied notes in self. If a tied-to note is outside
        # the copied content, we set the copied note's tie to None to
        # truncate the note.
        for note in self.find_all(Note):
            if note.tie is not None: # note is copied, but it still
                # references the original note. So pass original note
                # to find_copied_version and update note.tie. There is
                # a (theoretical?) possibility of two identical and tied 
                # grace notes with the same pitch and (zero) duration,
                # so we exclude note from the search for the copied
                # note to avoid creating a tie from note to itself.
                note.tie = self._find_copied_version(note.tie, note)
        return min_onset, max_offset
    # we are not at the measure level, copy all content and recurse:
    for elem in source.content:
        if isinstance(elem, EventGroup):
            elem_copy = elem.insert_emptycopy_into(self)
            elem_copy.onset = max(elem_copy.onset, start_time)
            elem_copy.offset = min(elem_copy.offset, end_time)
            e_min, e_max = elem_copy._add_measure_children(elem, start,
                                             end, start_time, end_time)
            min_onset = min(min_onset, e_min)
            max_offset = max(max_offset, e_max)
    return min_onset, max_offset

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 
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
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 
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
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 = self._add_slice_children(self, result,
                                              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

Sequence 

Sequence(
    parent: Optional[EventGroup],
    onset: Optional[float] = None,
    duration: Optional[float] = None,
    content: Optional[list[Event]] = None,
)

Bases: EventGroup

Sequence (abstract class) represents a temporal sequence of music events.

Parameters:

  • parent (Optional[EventGroup]) –

    The containing object or None.

  • onset (Optional[float], default: None ) –

    The onset (start) time. None means unknown, to be set when Sequence is added to a parent.

  • 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 in content, or 0 if there is no content.)

  • content (Optional[list[Event]], default: None ) –

    A list of Event objects to be added to the group. Content events with onsets of None are set to the offset of the previous event in the sequence. The first event onset is the specified group onset, or zero if onset is None.

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

Source code in amads/core/basics.py 
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
def __init__(self, parent: Optional[EventGroup],
             onset: Optional[float] = None,
             duration: Optional[float] = None,
             content: Optional[list[Event]] = None):
    # if onset is given, we need to set all content onsets to form a
    # sequence before running super().__init__()
    if content is None:
        content = []
    prev_onset : float = 0.0
    prev_offset : float = 0.0
    if not onset is None:
        prev_onset = onset
        prev_offset = onset
    for elem in content:
        # parent will be set in EventGroup's constructor
        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
    # now that onset times are all set, we can run EventGroup's
    # constructor to set parents, duration, content
    super().__init__(parent, onset, duration, content)

Attributes

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.

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.

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

__repr__ 

__repr__() -> str

All Event subclasses inherit this to use str().

Thus, a list of Events is printed using their str methods

Source code in amads/core/basics.py 
120
121
122
123
124
125
def __repr__(self) -> str:
    """All Event subclasses inherit this to use str().

    Thus, a list of Events is printed using their __str__ methods
    """
    return str(self)

_event_times 

_event_times(dur: bool = True) -> str

produce onset and duration string for str

Source code in amads/core/basics.py 
135
136
137
138
139
140
141
def _event_times(self, dur: bool = True) -> str:
    """produce onset and duration string for __str__
    """
    duration = self.duration
    if duration is not None:
        duration = f"{self.duration:0.3f}"
    return f"{self._event_onset()}, duration={duration}"

time_shift 

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

Change the onset by an increment, affecting all content.

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.

Source code in amads/core/basics.py 
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
def time_shift(self, increment: float,
               content_only: bool = False) -> "EventGroup":
    """
    Change the onset by an increment, affecting all content.

    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`.
    """
    if not content_only:
        self._onset += increment  # type: ignore (onset is now number)
    for elem in self.content:
        elem.time_shift(increment)
    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 
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
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

_quantize 

_quantize(divisions: int) -> EventGroup

"Since _quantize is called recursively on children, this method is needed to redirect EventGroup._quantize to quantize

Source code in amads/core/basics.py 
2025
2026
2027
2028
2029
def _quantize(self, divisions: int) -> "EventGroup":
    """"Since `_quantize` is called recursively on children, this method is
    needed to redirect `EventGroup._quantize` to `quantize`
    """
    return self.quantize(divisions)

_convert_to_seconds 

_convert_to_seconds(time_map: TimeMap) -> None

Convert the event's duration and onset to seconds using the provided TimeMap. Convert content as well.

Parameters:

  • time_map (TimeMap) –

    The TimeMap object used for conversion.

Source code in amads/core/basics.py 
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
def _convert_to_seconds(self, time_map: TimeMap) -> None:
    """Convert the event's duration and onset to seconds using the
    provided TimeMap. Convert content as well.

    Parameters
    ----------
    time_map : TimeMap
        The TimeMap object used for conversion.
    """
    super()._convert_to_seconds(time_map)
    for elem in self.content:
        elem._convert_to_seconds(time_map)

_convert_to_quarters 

_convert_to_quarters(time_map: TimeMap) -> None

Convert the event's duration and onset to quarters using the provided TimeMap. Convert content as well.

Parameters:

  • time_map (TimeMap) –

    The TimeMap object used for conversion.

Source code in amads/core/basics.py 
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
def _convert_to_quarters(self, time_map: TimeMap) -> None:
    """Convert the event's duration and onset to quarters using the
    provided TimeMap. Convert content as well.

    Parameters
    ----------
    time_map : TimeMap
        The TimeMap object used for conversion.
    """
    onset_quarters = time_map.time_to_quarter(self.onset)
    offset_quarters = time_map.time_to_quarter(self.onset + self.duration)
    self.onset = onset_quarters
    self.duration = offset_quarters - onset_quarters
    for elem in self.content:
        elem._convert_to_quarters(time_map)

_find_copied_version 

_find_copied_version(
    original_note: Note, exclude: Note
) -> Optional[Note]

Find the copied version of a note in self.

Parameters:

  • original_note (Note) –

    The note that was copied

Source code in amads/core/basics.py 
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
def _find_copied_version(self, original_note: Note,
                         exclude: Note) -> Optional[Note]:
    """Find the copied version of a note in self.

    Parameters
    ----------
    original_note: Note
        The note that was copied
    """
    for note in self.find_all(Note):
        note = cast(Note, note)
        if (note != exclude and note.onset == original_note.onset and
            note.pitch == original_note.pitch and
            note.duration == original_note.duration):
            return note
    return None

_add_slice_children 

_add_slice_children(
    source: EventGroup,
    start: float,
    end: float,
    mode: str,
    truncate: str,
    min_duration: float,
) -> tuple[float, float]

Helper method for slice to populate the content of self. Assumes that source is a component of a flat score and that self is a Sequence with no content.

Returns:

  • float –

    The minimum onset of the content added to self.

Source code in amads/core/basics.py 
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
def _add_slice_children(self, source: "EventGroup", start: float,
        end: float, mode: str, truncate: str,
        min_duration: float) -> tuple[float, float]:
    """Helper method for slice to populate the content of self.
    Assumes that source is a component of a flat score and that self
    is a Sequence with no content.

    Returns
    -------
    float
        The minimum onset of the content added to self.
    """
    # Begin by finding all content to be included. Since score is flat,
    # source can only be a Score, a Part, or a Staff. So if a component is
    # not a Note, we copy all children (Parts or Staffs) into content
    # and recurse to add a slice of *their* content.
    min_onset = float("inf")
    max_offset = float("-inf")
    content = source.content
    if len(content) == 0:
        return min_onset, max_offset
    if not isinstance(content[0], Note):
        for elem in content:
            if isinstance(elem, EventGroup):
                elem_copy = elem.insert_emptycopy_into(self)
                e_min, e_max = elem._add_slice_children(elem_copy, start,
                                       end, mode, truncate, min_duration)
                min_onset = min(min_onset, e_min)
                max_offset = max(max_offset, e_max)
        return min_onset, max_offset

    assert(isinstance(source, Sequence))  # content is a list of Notes

    for elem in content:
        copied = None
        if mode == "onsets":
            if elem.onset >= start and elem.onset < end:
                copied = elem.insert_copy_into(self)  # copy elem into self
        elif mode == "overlaps":
            if elem.onset < end and elem.offset > start:
                copied = elem.insert_copy_into(self)  # copy elem into self
        elif mode == "offsets":
            if elem.offset > start and elem.offset <= end:
                copied = elem.insert_copy_into(self)  # copy elem into self
        elif mode == "strict":
            if elem.onset >= start and elem.offset <= end:
                copied = elem.insert_copy_into(self)  # copy elem into self
        else:
            raise ValueError(f"invalid mode {mode} for slice")
        if copied:
            min_onset = min(min_onset, copied.onset)
            max_offset = max(max_offset, copied.offset)

    if truncate == "keep":
        return min_onset, max_offset
    if truncate in ["truncate", "beginning"]:
        # if we are truncating notes that start before start, we can save
        # some time by only looking at elements where onset < start
        j = len(content)
        for i, elem in enumerate(content):
            if elem.onset > start:
                j = i
                break  # now j indexes the first element with onset > start
        min_onset = source._truncate_note_beginnings(content[0 : j], start)
    if truncate in ["truncate", "dur", "duration", "end", "ending"]:
        # any note can end after end, so we have to look at all of them:
        max_offset = source._truncate_note_endings(content, end)

    # now remove any notes that are too short after truncation:
    if min_duration > 0:
        min_onset = float("inf")
        max_offset = float("-inf")
        filtered = []
        for elem in content:
            if elem.duration >= min_duration:
                filtered.append(elem)
                min_onset = min(min_onset, elem.onset)
                max_offset = max(max_offset, elem.offset)
        source.content = filtered
    return min_onset, max_offset

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 
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
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

_copy_parents 

_copy_parents(start: float, end: float) -> EventGroup

Helper method for slice to populate the ancestors of self in result.

This method is called by slice to populate the ancestors of self in the result Score. The ancestors are populated with empty copies of the original ancestors.

Returns:

  • EventGroup –

    A copy of self with ancestors copied up to the Score.

Raises:

  • ValueError –

    If self is not part of a Score.

Source code in amads/core/basics.py 
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
def _copy_parents(self, start: float, end: float) -> "EventGroup":
    """Helper method for slice to populate the ancestors of self in result.

    This method is called by `slice` to populate the ancestors of self in
    the result Score. The ancestors are populated with empty copies of the
    original ancestors.

    Returns
    -------
    EventGroup
        A copy of self with ancestors copied up to the Score.

    Raises
    ------
    ValueError
        If self is not part of a Score.
    """
    # Algorithm: recursively populate ancestors from self up to score.
    if self is None:
        raise ValueError("slice can only be called on Sequences that are "
                         "part of a Score")
    elif isinstance(self, Score):  # base case: self is a Score
        return self # return copy of self
    else:  # copy parent & up; return copy of self inserted into parent copy
        parent = cast(EventGroup, self.parent)._copy_parents(start, end)
        parent.onset = start
        parent.offset = end
        # insert copy of self into parent copy:
        return self.insert_emptycopy_into(parent)

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 
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
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 
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
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 
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
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)

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 
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
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_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 
1778
1779
1780
1781
1782
1783
1784
1785
1786
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 
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
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 
1804
1805
1806
1807
1808
1809
1810
1811
1812
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 
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
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)

Source code in amads/core/basics.py 
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
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)
    """
    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 
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
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

_leaf_elements 

_leaf_elements() -> list[Event]

Return a list of all leaf elements in this EventGroup.

Source code in amads/core/basics.py 
1893
1894
1895
1896
1897
1898
1899
1900
1901
def _leaf_elements(self) -> list[Event]:
    """Return a list of all leaf elements in this EventGroup."""
    result = []
    for elem in self.content:
        if isinstance(elem, EventGroup):
            result.extend(elem._leaf_elements())
        else:
            result.append(elem)
    return result

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 
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
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 
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
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:

  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.

Source code in amads/core/basics.py 
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
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

_add_measure_children 

_add_measure_children(
    source: EventGroup,
    start: float,
    end: float,
    start_time: float,
    end_time: float,
) -> tuple[float, float]

Helper method for to populate the content with selected measures. Assumes that self is a component of a full score and that this Staff (self) has no content yet.

Since only measures within start and end are copied, the copied measures and other content all have onsets and offsets within copy range and do not need to be adjusted.

Assumes that notes crossing measure boundaries are tied and that ties to notes outside the copied measures should be broken, truncating the copied note to the measure boundary.

Returns:

  • tuple[float, float] –

    The minimum onset and maximum offset of the content added to self.

Source code in amads/core/basics.py 
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
def _add_measure_children(self, source: "EventGroup", start: float,
                          end: float, start_time: float,
                          end_time: float) -> tuple[float, float]:
    """Helper method for to populate the content with
    selected measures. Assumes that self is a component of a full score and
    that this Staff (self) has no content yet.

    Since only measures within start and end are copied, the copied
    measures and other content all have onsets and offsets within
    copy range and do not need to be adjusted.

    Assumes that notes crossing measure boundaries are tied and that
    ties to notes outside the copied measures should be broken, truncating
    the copied note to the measure boundary.

    Returns
    -------
    tuple[float, float]
        The minimum onset and maximum offset of the content added to self.
    """
    # Assume that whatever EventGroup(s) contain measures, they will *only*
    # contain measures, so we can check content[0] to find the measure
    # level. Recursively copy the structure from this level down to the
    # measure level whether or not any measures are encountered.
    #     Also assume any level with measures is well formed with all
    # measures contiguous, in order, starting at zero, and with durations
    # in compliance with time signatures.
    min_onset = float("inf")
    max_offset = float("-inf")
    if len(source.content) == 0:
        return min_onset, max_offset
    if isinstance(source.content[0], Measure):
        # find and copy the measures that are in the range
        start = round(start)
        end = round(end)
        for i, elem in enumerate(source.content):
            assert isinstance(elem, Measure), \
                   "expected Measures at this level"
            if i >= start and i < end:
                min_onset = min(min_onset, elem.onset)
                max_offset = max(max_offset, elem.offset)
                _ = elem.insert_copy_into(self)  # copy elem into self
        # if copied content has tied notes, the links will still refer
        # to the original notes, so we need to update the ties to
        # refer to the copied notes in self. If a tied-to note is outside
        # the copied content, we set the copied note's tie to None to
        # truncate the note.
        for note in self.find_all(Note):
            if note.tie is not None: # note is copied, but it still
                # references the original note. So pass original note
                # to find_copied_version and update note.tie. There is
                # a (theoretical?) possibility of two identical and tied 
                # grace notes with the same pitch and (zero) duration,
                # so we exclude note from the search for the copied
                # note to avoid creating a tie from note to itself.
                note.tie = self._find_copied_version(note.tie, note)
        return min_onset, max_offset
    # we are not at the measure level, copy all content and recurse:
    for elem in source.content:
        if isinstance(elem, EventGroup):
            elem_copy = elem.insert_emptycopy_into(self)
            elem_copy.onset = max(elem_copy.onset, start_time)
            elem_copy.offset = min(elem_copy.offset, end_time)
            e_min, e_max = elem_copy._add_measure_children(elem, start,
                                             end, start_time, end_time)
            min_onset = min(min_onset, e_min)
            max_offset = max(max_offset, e_max)
    return min_onset, max_offset

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 
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
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 
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
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 = self._add_slice_children(self, result,
                                              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

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 
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
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)

_truncate_note_beginnings 

_truncate_note_beginnings(notes: list[Note], start: float) -> float

Helper method for slice to truncate an element according to the specified mode. Makes a copy of the element (with no parent) and applies the truncate method to the copy. This algorithm clips the beginning and ending in separate operations, which might result in extra copies. If very short tied notes are created, they are removed.

Returns:

  • float –

    The minimum onset of the elements

Source code in amads/core/basics.py 
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
def _truncate_note_beginnings(self, notes: list[Note],
                              start: float) -> float:
    """Helper method for slice to truncate an element according to the
    specified mode. Makes a copy of the element (with no parent) and
    applies the truncate method to the copy.  This algorithm clips the
    beginning and ending in separate operations, which might result in
    extra copies. If very short tied notes are created, they are removed.

    Returns
    -------
    float
        The minimum onset of the elements
    """
    min_onset = float("inf")
    for elem in notes:
        if elem.onset < start:
            elem.duration -= start - elem.onset
            elem.onset = start
        min_onset = min(min_onset, elem.onset)
    return min_onset

Concurrence 

Concurrence(
    parent: Optional[EventGroup] = None,
    onset: Optional[float] = None,
    duration: Optional[float] = None,
    content: Optional[list[Event]] = None,
)

Bases: EventGroup

Concurrence (abstract class) represents a group of simultaneous children.

However, children can have a non-zero onset to represent events organized in time). Thus, the main distinction between Concurrence and Sequence is that a Sequence can be constructed with pack=True to force sequential timing of the content. Note that a Sequence can have overlapping or entirely simultaneous Events as well.

Parameters:

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

    The containing object or None.

  • onset (Optional[float], default: None ) –

    The onset (start) time. None means unknown, to be set when Sequence is added to a parent.

  • 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 in content, or 0 if there is no content.)

  • content (Optional[list[Event]], default: None ) –

    A list of Event objects to be added to the group. Content events with onsets of None are set to the offset of the concurrence, or zero if onset is None.

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

Source code in amads/core/basics.py 
2634
2635
2636
2637
2638
def __init__(self, parent: Optional["EventGroup"] = None,
             onset: Optional[float] = None,
             duration: Optional[float] = None,
             content: Optional[list[Event]] = None):
    super().__init__(parent, onset, duration, content)

Attributes

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.

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.

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

__repr__ 

__repr__() -> str

All Event subclasses inherit this to use str().

Thus, a list of Events is printed using their str methods

Source code in amads/core/basics.py 
120
121
122
123
124
125
def __repr__(self) -> str:
    """All Event subclasses inherit this to use str().

    Thus, a list of Events is printed using their __str__ methods
    """
    return str(self)

_event_times 

_event_times(dur: bool = True) -> str

produce onset and duration string for str

Source code in amads/core/basics.py 
135
136
137
138
139
140
141
def _event_times(self, dur: bool = True) -> str:
    """produce onset and duration string for __str__
    """
    duration = self.duration
    if duration is not None:
        duration = f"{self.duration:0.3f}"
    return f"{self._event_onset()}, duration={duration}"

time_shift 

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

Change the onset by an increment, affecting all content.

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.

Source code in amads/core/basics.py 
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
def time_shift(self, increment: float,
               content_only: bool = False) -> "EventGroup":
    """
    Change the onset by an increment, affecting all content.

    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`.
    """
    if not content_only:
        self._onset += increment  # type: ignore (onset is now number)
    for elem in self.content:
        elem.time_shift(increment)
    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 
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
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

_quantize 

_quantize(divisions: int) -> EventGroup

"Since _quantize is called recursively on children, this method is needed to redirect EventGroup._quantize to quantize

Source code in amads/core/basics.py 
2025
2026
2027
2028
2029
def _quantize(self, divisions: int) -> "EventGroup":
    """"Since `_quantize` is called recursively on children, this method is
    needed to redirect `EventGroup._quantize` to `quantize`
    """
    return self.quantize(divisions)

_convert_to_seconds 

_convert_to_seconds(time_map: TimeMap) -> None

Convert the event's duration and onset to seconds using the provided TimeMap. Convert content as well.

Parameters:

  • time_map (TimeMap) –

    The TimeMap object used for conversion.

Source code in amads/core/basics.py 
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
def _convert_to_seconds(self, time_map: TimeMap) -> None:
    """Convert the event's duration and onset to seconds using the
    provided TimeMap. Convert content as well.

    Parameters
    ----------
    time_map : TimeMap
        The TimeMap object used for conversion.
    """
    super()._convert_to_seconds(time_map)
    for elem in self.content:
        elem._convert_to_seconds(time_map)

_convert_to_quarters 

_convert_to_quarters(time_map: TimeMap) -> None

Convert the event's duration and onset to quarters using the provided TimeMap. Convert content as well.

Parameters:

  • time_map (TimeMap) –

    The TimeMap object used for conversion.

Source code in amads/core/basics.py 
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
def _convert_to_quarters(self, time_map: TimeMap) -> None:
    """Convert the event's duration and onset to quarters using the
    provided TimeMap. Convert content as well.

    Parameters
    ----------
    time_map : TimeMap
        The TimeMap object used for conversion.
    """
    onset_quarters = time_map.time_to_quarter(self.onset)
    offset_quarters = time_map.time_to_quarter(self.onset + self.duration)
    self.onset = onset_quarters
    self.duration = offset_quarters - onset_quarters
    for elem in self.content:
        elem._convert_to_quarters(time_map)

_find_copied_version 

_find_copied_version(
    original_note: Note, exclude: Note
) -> Optional[Note]

Find the copied version of a note in self.

Parameters:

  • original_note (Note) –

    The note that was copied

Source code in amads/core/basics.py 
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
def _find_copied_version(self, original_note: Note,
                         exclude: Note) -> Optional[Note]:
    """Find the copied version of a note in self.

    Parameters
    ----------
    original_note: Note
        The note that was copied
    """
    for note in self.find_all(Note):
        note = cast(Note, note)
        if (note != exclude and note.onset == original_note.onset and
            note.pitch == original_note.pitch and
            note.duration == original_note.duration):
            return note
    return None

_add_slice_children 

_add_slice_children(
    source: EventGroup,
    start: float,
    end: float,
    mode: str,
    truncate: str,
    min_duration: float,
) -> tuple[float, float]

Helper method for slice to populate the content of self. Assumes that source is a component of a flat score and that self is a Sequence with no content.

Returns:

  • float –

    The minimum onset of the content added to self.

Source code in amads/core/basics.py 
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
def _add_slice_children(self, source: "EventGroup", start: float,
        end: float, mode: str, truncate: str,
        min_duration: float) -> tuple[float, float]:
    """Helper method for slice to populate the content of self.
    Assumes that source is a component of a flat score and that self
    is a Sequence with no content.

    Returns
    -------
    float
        The minimum onset of the content added to self.
    """
    # Begin by finding all content to be included. Since score is flat,
    # source can only be a Score, a Part, or a Staff. So if a component is
    # not a Note, we copy all children (Parts or Staffs) into content
    # and recurse to add a slice of *their* content.
    min_onset = float("inf")
    max_offset = float("-inf")
    content = source.content
    if len(content) == 0:
        return min_onset, max_offset
    if not isinstance(content[0], Note):
        for elem in content:
            if isinstance(elem, EventGroup):
                elem_copy = elem.insert_emptycopy_into(self)
                e_min, e_max = elem._add_slice_children(elem_copy, start,
                                       end, mode, truncate, min_duration)
                min_onset = min(min_onset, e_min)
                max_offset = max(max_offset, e_max)
        return min_onset, max_offset

    assert(isinstance(source, Sequence))  # content is a list of Notes

    for elem in content:
        copied = None
        if mode == "onsets":
            if elem.onset >= start and elem.onset < end:
                copied = elem.insert_copy_into(self)  # copy elem into self
        elif mode == "overlaps":
            if elem.onset < end and elem.offset > start:
                copied = elem.insert_copy_into(self)  # copy elem into self
        elif mode == "offsets":
            if elem.offset > start and elem.offset <= end:
                copied = elem.insert_copy_into(self)  # copy elem into self
        elif mode == "strict":
            if elem.onset >= start and elem.offset <= end:
                copied = elem.insert_copy_into(self)  # copy elem into self
        else:
            raise ValueError(f"invalid mode {mode} for slice")
        if copied:
            min_onset = min(min_onset, copied.onset)
            max_offset = max(max_offset, copied.offset)

    if truncate == "keep":
        return min_onset, max_offset
    if truncate in ["truncate", "beginning"]:
        # if we are truncating notes that start before start, we can save
        # some time by only looking at elements where onset < start
        j = len(content)
        for i, elem in enumerate(content):
            if elem.onset > start:
                j = i
                break  # now j indexes the first element with onset > start
        min_onset = source._truncate_note_beginnings(content[0 : j], start)
    if truncate in ["truncate", "dur", "duration", "end", "ending"]:
        # any note can end after end, so we have to look at all of them:
        max_offset = source._truncate_note_endings(content, end)

    # now remove any notes that are too short after truncation:
    if min_duration > 0:
        min_onset = float("inf")
        max_offset = float("-inf")
        filtered = []
        for elem in content:
            if elem.duration >= min_duration:
                filtered.append(elem)
                min_onset = min(min_onset, elem.onset)
                max_offset = max(max_offset, elem.offset)
        source.content = filtered
    return min_onset, max_offset

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 
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
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

_copy_parents 

_copy_parents(start: float, end: float) -> EventGroup

Helper method for slice to populate the ancestors of self in result.

This method is called by slice to populate the ancestors of self in the result Score. The ancestors are populated with empty copies of the original ancestors.

Returns:

  • EventGroup –

    A copy of self with ancestors copied up to the Score.

Raises:

  • ValueError –

    If self is not part of a Score.

Source code in amads/core/basics.py 
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
def _copy_parents(self, start: float, end: float) -> "EventGroup":
    """Helper method for slice to populate the ancestors of self in result.

    This method is called by `slice` to populate the ancestors of self in
    the result Score. The ancestors are populated with empty copies of the
    original ancestors.

    Returns
    -------
    EventGroup
        A copy of self with ancestors copied up to the Score.

    Raises
    ------
    ValueError
        If self is not part of a Score.
    """
    # Algorithm: recursively populate ancestors from self up to score.
    if self is None:
        raise ValueError("slice can only be called on Sequences that are "
                         "part of a Score")
    elif isinstance(self, Score):  # base case: self is a Score
        return self # return copy of self
    else:  # copy parent & up; return copy of self inserted into parent copy
        parent = cast(EventGroup, self.parent)._copy_parents(start, end)
        parent.onset = start
        parent.offset = end
        # insert copy of self into parent copy:
        return self.insert_emptycopy_into(parent)

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 
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
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 
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
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 
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
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)

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 
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
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_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 
1778
1779
1780
1781
1782
1783
1784
1785
1786
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 
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
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 
1804
1805
1806
1807
1808
1809
1810
1811
1812
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 
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
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)

Source code in amads/core/basics.py 
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
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)
    """
    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 
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
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

_leaf_elements 

_leaf_elements() -> list[Event]

Return a list of all leaf elements in this EventGroup.

Source code in amads/core/basics.py 
1893
1894
1895
1896
1897
1898
1899
1900
1901
def _leaf_elements(self) -> list[Event]:
    """Return a list of all leaf elements in this EventGroup."""
    result = []
    for elem in self.content:
        if isinstance(elem, EventGroup):
            result.extend(elem._leaf_elements())
        else:
            result.append(elem)
    return result

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 
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
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 
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
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 
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
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:

  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.

Source code in amads/core/basics.py 
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
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

_add_measure_children 

_add_measure_children(
    source: EventGroup,
    start: float,
    end: float,
    start_time: float,
    end_time: float,
) -> tuple[float, float]

Helper method for to populate the content with selected measures. Assumes that self is a component of a full score and that this Staff (self) has no content yet.

Since only measures within start and end are copied, the copied measures and other content all have onsets and offsets within copy range and do not need to be adjusted.

Assumes that notes crossing measure boundaries are tied and that ties to notes outside the copied measures should be broken, truncating the copied note to the measure boundary.

Returns:

  • tuple[float, float] –

    The minimum onset and maximum offset of the content added to self.

Source code in amads/core/basics.py 
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
def _add_measure_children(self, source: "EventGroup", start: float,
                          end: float, start_time: float,
                          end_time: float) -> tuple[float, float]:
    """Helper method for to populate the content with
    selected measures. Assumes that self is a component of a full score and
    that this Staff (self) has no content yet.

    Since only measures within start and end are copied, the copied
    measures and other content all have onsets and offsets within
    copy range and do not need to be adjusted.

    Assumes that notes crossing measure boundaries are tied and that
    ties to notes outside the copied measures should be broken, truncating
    the copied note to the measure boundary.

    Returns
    -------
    tuple[float, float]
        The minimum onset and maximum offset of the content added to self.
    """
    # Assume that whatever EventGroup(s) contain measures, they will *only*
    # contain measures, so we can check content[0] to find the measure
    # level. Recursively copy the structure from this level down to the
    # measure level whether or not any measures are encountered.
    #     Also assume any level with measures is well formed with all
    # measures contiguous, in order, starting at zero, and with durations
    # in compliance with time signatures.
    min_onset = float("inf")
    max_offset = float("-inf")
    if len(source.content) == 0:
        return min_onset, max_offset
    if isinstance(source.content[0], Measure):
        # find and copy the measures that are in the range
        start = round(start)
        end = round(end)
        for i, elem in enumerate(source.content):
            assert isinstance(elem, Measure), \
                   "expected Measures at this level"
            if i >= start and i < end:
                min_onset = min(min_onset, elem.onset)
                max_offset = max(max_offset, elem.offset)
                _ = elem.insert_copy_into(self)  # copy elem into self
        # if copied content has tied notes, the links will still refer
        # to the original notes, so we need to update the ties to
        # refer to the copied notes in self. If a tied-to note is outside
        # the copied content, we set the copied note's tie to None to
        # truncate the note.
        for note in self.find_all(Note):
            if note.tie is not None: # note is copied, but it still
                # references the original note. So pass original note
                # to find_copied_version and update note.tie. There is
                # a (theoretical?) possibility of two identical and tied 
                # grace notes with the same pitch and (zero) duration,
                # so we exclude note from the search for the copied
                # note to avoid creating a tie from note to itself.
                note.tie = self._find_copied_version(note.tie, note)
        return min_onset, max_offset
    # we are not at the measure level, copy all content and recurse:
    for elem in source.content:
        if isinstance(elem, EventGroup):
            elem_copy = elem.insert_emptycopy_into(self)
            elem_copy.onset = max(elem_copy.onset, start_time)
            elem_copy.offset = min(elem_copy.offset, end_time)
            e_min, e_max = elem_copy._add_measure_children(elem, start,
                                             end, start_time, end_time)
            min_onset = min(min_onset, e_min)
            max_offset = max(max_offset, e_max)
    return min_onset, max_offset

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 
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
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 
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
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 = self._add_slice_children(self, result,
                                              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

Chord 

Chord(
    *args: Event,
    parent: Optional[EventGroup] = None,
    onset: Optional[float] = None,
    duration: Optional[float] = None
)

Bases: Concurrence

A collection of notes played together.

Typically, chords represent notes that would share a stem, and note start times and durations match the start time and duration of the chord, but none of this is enforced. The order of notes is arbitrary.

Normally, a Chord is a member of a Measure. There is no requirement that simultaneous or overlapping notes be grouped into Chords, so the Chord class is merely an optional element of music structure representation.

See Constructor Details.

Representation note: An alternative representation would be to subclass Note and allow a list of pitches, which has the advantage of enforcing the shared onsets and durations. However, there can be ties connected differently to each note within the Chord, thus we use a Concurrence with Note objects as elements. Each Note.tie can be None (no tie) or tie to a Note in another Chord or Measure.

Parameters:

  • *args (Event, default: () ) –

    The Event objects to be added to the group. Content events with onsets of None are set to the onset of the chord, or zero if onset is None.

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

Attributes:

  • parent (Optional[EventGroup]) –

    The containing object or None.

  • _onset (Optional[float]) –

    The onset (start) time.

  • duration (float) –

    The duration in quarters or seconds.

  • content (list[Event]) –

    Elements contained within this collection.

Source code in amads/core/basics.py 
2696
2697
2698
2699
2700
def __init__(self, *args: Event,
             parent: Optional[EventGroup] = None,
             onset: Optional[float] = None,
             duration: Optional[float] = None):
    super().__init__(parent, onset, duration, list(args))

Attributes

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.

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.

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

__repr__ 

__repr__() -> str

All Event subclasses inherit this to use str().

Thus, a list of Events is printed using their str methods

Source code in amads/core/basics.py 
120
121
122
123
124
125
def __repr__(self) -> str:
    """All Event subclasses inherit this to use str().

    Thus, a list of Events is printed using their __str__ methods
    """
    return str(self)

_event_times 

_event_times(dur: bool = True) -> str

produce onset and duration string for str

Source code in amads/core/basics.py 
135
136
137
138
139
140
141
def _event_times(self, dur: bool = True) -> str:
    """produce onset and duration string for __str__
    """
    duration = self.duration
    if duration is not None:
        duration = f"{self.duration:0.3f}"
    return f"{self._event_onset()}, duration={duration}"

time_shift 

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

Change the onset by an increment, affecting all content.

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.

Source code in amads/core/basics.py 
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
def time_shift(self, increment: float,
               content_only: bool = False) -> "EventGroup":
    """
    Change the onset by an increment, affecting all content.

    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`.
    """
    if not content_only:
        self._onset += increment  # type: ignore (onset is now number)
    for elem in self.content:
        elem.time_shift(increment)
    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 
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
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

_quantize 

_quantize(divisions: int) -> EventGroup

"Since _quantize is called recursively on children, this method is needed to redirect EventGroup._quantize to quantize

Source code in amads/core/basics.py 
2025
2026
2027
2028
2029
def _quantize(self, divisions: int) -> "EventGroup":
    """"Since `_quantize` is called recursively on children, this method is
    needed to redirect `EventGroup._quantize` to `quantize`
    """
    return self.quantize(divisions)

_convert_to_seconds 

_convert_to_seconds(time_map: TimeMap) -> None

Convert the event's duration and onset to seconds using the provided TimeMap. Convert content as well.

Parameters:

  • time_map (TimeMap) –

    The TimeMap object used for conversion.

Source code in amads/core/basics.py 
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
def _convert_to_seconds(self, time_map: TimeMap) -> None:
    """Convert the event's duration and onset to seconds using the
    provided TimeMap. Convert content as well.

    Parameters
    ----------
    time_map : TimeMap
        The TimeMap object used for conversion.
    """
    super()._convert_to_seconds(time_map)
    for elem in self.content:
        elem._convert_to_seconds(time_map)

_convert_to_quarters 

_convert_to_quarters(time_map: TimeMap) -> None

Convert the event's duration and onset to quarters using the provided TimeMap. Convert content as well.

Parameters:

  • time_map (TimeMap) –

    The TimeMap object used for conversion.

Source code in amads/core/basics.py 
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
def _convert_to_quarters(self, time_map: TimeMap) -> None:
    """Convert the event's duration and onset to quarters using the
    provided TimeMap. Convert content as well.

    Parameters
    ----------
    time_map : TimeMap
        The TimeMap object used for conversion.
    """
    onset_quarters = time_map.time_to_quarter(self.onset)
    offset_quarters = time_map.time_to_quarter(self.onset + self.duration)
    self.onset = onset_quarters
    self.duration = offset_quarters - onset_quarters
    for elem in self.content:
        elem._convert_to_quarters(time_map)

_find_copied_version 

_find_copied_version(
    original_note: Note, exclude: Note
) -> Optional[Note]

Find the copied version of a note in self.

Parameters:

  • original_note (Note) –

    The note that was copied

Source code in amads/core/basics.py 
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
def _find_copied_version(self, original_note: Note,
                         exclude: Note) -> Optional[Note]:
    """Find the copied version of a note in self.

    Parameters
    ----------
    original_note: Note
        The note that was copied
    """
    for note in self.find_all(Note):
        note = cast(Note, note)
        if (note != exclude and note.onset == original_note.onset and
            note.pitch == original_note.pitch and
            note.duration == original_note.duration):
            return note
    return None

_add_slice_children 

_add_slice_children(
    source: EventGroup,
    start: float,
    end: float,
    mode: str,
    truncate: str,
    min_duration: float,
) -> tuple[float, float]

Helper method for slice to populate the content of self. Assumes that source is a component of a flat score and that self is a Sequence with no content.

Returns:

  • float –

    The minimum onset of the content added to self.

Source code in amads/core/basics.py 
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
def _add_slice_children(self, source: "EventGroup", start: float,
        end: float, mode: str, truncate: str,
        min_duration: float) -> tuple[float, float]:
    """Helper method for slice to populate the content of self.
    Assumes that source is a component of a flat score and that self
    is a Sequence with no content.

    Returns
    -------
    float
        The minimum onset of the content added to self.
    """
    # Begin by finding all content to be included. Since score is flat,
    # source can only be a Score, a Part, or a Staff. So if a component is
    # not a Note, we copy all children (Parts or Staffs) into content
    # and recurse to add a slice of *their* content.
    min_onset = float("inf")
    max_offset = float("-inf")
    content = source.content
    if len(content) == 0:
        return min_onset, max_offset
    if not isinstance(content[0], Note):
        for elem in content:
            if isinstance(elem, EventGroup):
                elem_copy = elem.insert_emptycopy_into(self)
                e_min, e_max = elem._add_slice_children(elem_copy, start,
                                       end, mode, truncate, min_duration)
                min_onset = min(min_onset, e_min)
                max_offset = max(max_offset, e_max)
        return min_onset, max_offset

    assert(isinstance(source, Sequence))  # content is a list of Notes

    for elem in content:
        copied = None
        if mode == "onsets":
            if elem.onset >= start and elem.onset < end:
                copied = elem.insert_copy_into(self)  # copy elem into self
        elif mode == "overlaps":
            if elem.onset < end and elem.offset > start:
                copied = elem.insert_copy_into(self)  # copy elem into self
        elif mode == "offsets":
            if elem.offset > start and elem.offset <= end:
                copied = elem.insert_copy_into(self)  # copy elem into self
        elif mode == "strict":
            if elem.onset >= start and elem.offset <= end:
                copied = elem.insert_copy_into(self)  # copy elem into self
        else:
            raise ValueError(f"invalid mode {mode} for slice")
        if copied:
            min_onset = min(min_onset, copied.onset)
            max_offset = max(max_offset, copied.offset)

    if truncate == "keep":
        return min_onset, max_offset
    if truncate in ["truncate", "beginning"]:
        # if we are truncating notes that start before start, we can save
        # some time by only looking at elements where onset < start
        j = len(content)
        for i, elem in enumerate(content):
            if elem.onset > start:
                j = i
                break  # now j indexes the first element with onset > start
        min_onset = source._truncate_note_beginnings(content[0 : j], start)
    if truncate in ["truncate", "dur", "duration", "end", "ending"]:
        # any note can end after end, so we have to look at all of them:
        max_offset = source._truncate_note_endings(content, end)

    # now remove any notes that are too short after truncation:
    if min_duration > 0:
        min_onset = float("inf")
        max_offset = float("-inf")
        filtered = []
        for elem in content:
            if elem.duration >= min_duration:
                filtered.append(elem)
                min_onset = min(min_onset, elem.onset)
                max_offset = max(max_offset, elem.offset)
        source.content = filtered
    return min_onset, max_offset

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 
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
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

_copy_parents 

_copy_parents(start: float, end: float) -> EventGroup

Helper method for slice to populate the ancestors of self in result.

This method is called by slice to populate the ancestors of self in the result Score. The ancestors are populated with empty copies of the original ancestors.

Returns:

  • EventGroup –

    A copy of self with ancestors copied up to the Score.

Raises:

  • ValueError –

    If self is not part of a Score.

Source code in amads/core/basics.py 
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
def _copy_parents(self, start: float, end: float) -> "EventGroup":
    """Helper method for slice to populate the ancestors of self in result.

    This method is called by `slice` to populate the ancestors of self in
    the result Score. The ancestors are populated with empty copies of the
    original ancestors.

    Returns
    -------
    EventGroup
        A copy of self with ancestors copied up to the Score.

    Raises
    ------
    ValueError
        If self is not part of a Score.
    """
    # Algorithm: recursively populate ancestors from self up to score.
    if self is None:
        raise ValueError("slice can only be called on Sequences that are "
                         "part of a Score")
    elif isinstance(self, Score):  # base case: self is a Score
        return self # return copy of self
    else:  # copy parent & up; return copy of self inserted into parent copy
        parent = cast(EventGroup, self.parent)._copy_parents(start, end)
        parent.onset = start
        parent.offset = end
        # insert copy of self into parent copy:
        return self.insert_emptycopy_into(parent)

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 
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
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 
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
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 
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
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)

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 
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
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_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 
1778
1779
1780
1781
1782
1783
1784
1785
1786
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 
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
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 
1804
1805
1806
1807
1808
1809
1810
1811
1812
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 
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
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)

Source code in amads/core/basics.py 
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
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)
    """
    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 
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
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

_leaf_elements 

_leaf_elements() -> list[Event]

Return a list of all leaf elements in this EventGroup.

Source code in amads/core/basics.py 
1893
1894
1895
1896
1897
1898
1899
1900
1901
def _leaf_elements(self) -> list[Event]:
    """Return a list of all leaf elements in this EventGroup."""
    result = []
    for elem in self.content:
        if isinstance(elem, EventGroup):
            result.extend(elem._leaf_elements())
        else:
            result.append(elem)
    return result

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 
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
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 
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
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 
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
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:

  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.

Source code in amads/core/basics.py 
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
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

_add_measure_children 

_add_measure_children(
    source: EventGroup,
    start: float,
    end: float,
    start_time: float,
    end_time: float,
) -> tuple[float, float]

Helper method for to populate the content with selected measures. Assumes that self is a component of a full score and that this Staff (self) has no content yet.

Since only measures within start and end are copied, the copied measures and other content all have onsets and offsets within copy range and do not need to be adjusted.

Assumes that notes crossing measure boundaries are tied and that ties to notes outside the copied measures should be broken, truncating the copied note to the measure boundary.

Returns:

  • tuple[float, float] –

    The minimum onset and maximum offset of the content added to self.

Source code in amads/core/basics.py 
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
def _add_measure_children(self, source: "EventGroup", start: float,
                          end: float, start_time: float,
                          end_time: float) -> tuple[float, float]:
    """Helper method for to populate the content with
    selected measures. Assumes that self is a component of a full score and
    that this Staff (self) has no content yet.

    Since only measures within start and end are copied, the copied
    measures and other content all have onsets and offsets within
    copy range and do not need to be adjusted.

    Assumes that notes crossing measure boundaries are tied and that
    ties to notes outside the copied measures should be broken, truncating
    the copied note to the measure boundary.

    Returns
    -------
    tuple[float, float]
        The minimum onset and maximum offset of the content added to self.
    """
    # Assume that whatever EventGroup(s) contain measures, they will *only*
    # contain measures, so we can check content[0] to find the measure
    # level. Recursively copy the structure from this level down to the
    # measure level whether or not any measures are encountered.
    #     Also assume any level with measures is well formed with all
    # measures contiguous, in order, starting at zero, and with durations
    # in compliance with time signatures.
    min_onset = float("inf")
    max_offset = float("-inf")
    if len(source.content) == 0:
        return min_onset, max_offset
    if isinstance(source.content[0], Measure):
        # find and copy the measures that are in the range
        start = round(start)
        end = round(end)
        for i, elem in enumerate(source.content):
            assert isinstance(elem, Measure), \
                   "expected Measures at this level"
            if i >= start and i < end:
                min_onset = min(min_onset, elem.onset)
                max_offset = max(max_offset, elem.offset)
                _ = elem.insert_copy_into(self)  # copy elem into self
        # if copied content has tied notes, the links will still refer
        # to the original notes, so we need to update the ties to
        # refer to the copied notes in self. If a tied-to note is outside
        # the copied content, we set the copied note's tie to None to
        # truncate the note.
        for note in self.find_all(Note):
            if note.tie is not None: # note is copied, but it still
                # references the original note. So pass original note
                # to find_copied_version and update note.tie. There is
                # a (theoretical?) possibility of two identical and tied 
                # grace notes with the same pitch and (zero) duration,
                # so we exclude note from the search for the copied
                # note to avoid creating a tie from note to itself.
                note.tie = self._find_copied_version(note.tie, note)
        return min_onset, max_offset
    # we are not at the measure level, copy all content and recurse:
    for elem in source.content:
        if isinstance(elem, EventGroup):
            elem_copy = elem.insert_emptycopy_into(self)
            elem_copy.onset = max(elem_copy.onset, start_time)
            elem_copy.offset = min(elem_copy.offset, end_time)
            e_min, e_max = elem_copy._add_measure_children(elem, start,
                                             end, start_time, end_time)
            min_onset = min(min_onset, e_min)
            max_offset = max(max_offset, e_max)
    return min_onset, max_offset

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 
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
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 
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
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 = self._add_slice_children(self, result,
                                              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 

_is_well_formed()

Test if Chord conforms to strict hierarchy of Chord-Note

Source code in amads/core/basics.py 
2703
2704
2705
2706
2707
2708
2709
2710
2711
def _is_well_formed(self):
    """Test if Chord conforms to strict hierarchy of Chord-Note
    """
    for note in self.content:
        # Chord can (in theory) contain many object types, so we can
        # only rule out things that are outside of the strict hierarchy:
        if isinstance(note, (Score, Part, Staff, Measure, Rest, Chord)):
            return False
    return True

TimeMap 

TimeMap(qpm=100.0)

Implement the time_map attribute of Score class.

Every Score has a time_map attribute whose value is a TimeMap that maintains a mapping between time in seconds and beats in quarters. A TimeMap encodes the information in a MIDI File tempo track as well as tempo information from a Music XML score.

This class holds a list representing tempo changes as a list of (time, quarter) pairs, which you can think of as tempo changes. More mathematically, they are breakpoints in a piece-wise linear function that maps from time to quarter or from quarter to time.

Since tempo is not continuous, the tempo at a breakpoint is defined to be the tempo just after the breakpoint.

The time map is defined from time changes[0].time to infinity, and from quarter changes[0].quarter to infinity. The first breakpoint should correspond to Score.onset.Before the first breakpoint, the time map is defined to have a slope of 1 quarter per second (i.e., 60 qpm). After the last breakpoint, the time map is defined to have a slope of last_tempo quarters per second.

Parameters:

  • qpm (float, default: 100.0 ) –

    Initial tempo in quarters per minute (default is 100.0).

Attributes:

  • changes (list of MapQuarter) –

    List of (time, quarter) breakpoints for piece-wise linear mapping.

  • last_tempo (float) –

    Final quarters per second (qps) for extrapolatation.

Examples:

>>> tm = TimeMap(qpm=120)
>>> tm.append_change(4.0, 60.0)  # change to 60 qpm at quarter 4
>>> tm.quarter_to_time(5.0)
3.0
>>> tm.time_to_quarter(3.0)
5.0
Source code in amads/core/timemap.py 
108
109
110
def __init__(self, qpm=100.0):
    self.changes = [MapQuarter(0.0, 0.0)]  # initial quarter
    self.last_tempo = qpm / 60.0  # 100 qpm default

Functions

deep_copy 

deep_copy() -> TimeMap

Make a full copy of this time map.

Returns:

  • TimeMap –

    A deep copy of this TimeMap instance.

Source code in amads/core/timemap.py 
140
141
142
143
144
145
146
147
148
149
150
151
def deep_copy(self) -> "TimeMap":
    """Make a full copy of this time map.

    Returns
    -------
    TimeMap
        A deep copy of this TimeMap instance.
    """
    newtm = TimeMap(qpm=self.last_tempo * 60)
    for i in self.changes[1:]:
        newtm.changes.append(i.copy())
    return newtm

append_change 

append_change(quarter: float, tempo: float) -> None

Append a tempo change at a given quarter.

Append a MapQuarter specifying a change to tempo at quarter. quarter must be at least as great as last MapQuarter's quarter. You cannot insert a tempo change before the end of the TimeMap. The tempo will hold forever beginning at quarter unless you call append_change again to change the tempo somewhere beyond quarter.

Parameters:

  • quarter (float) –

    The quarter measured in quarters where the tempo changes

  • tempo (float) –

    The new tempo at quarter measured in quarters per minute. Typically, this is the same as beats per minute (BPM), but only when a beat lasts one quarter.

Returns:

  • None –
Source code in amads/core/timemap.py 
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
def append_change(self, quarter: float, tempo: float) -> None:
    """Append a tempo change at a given quarter.

    Append a `MapQuarter` specifying a change to tempo at quarter.
    quarter must be at least as great as last MapQuarter's quarter.
    You cannot insert a tempo change before the end of the TimeMap.
    The `tempo` will hold forever beginning at `quarter` unless you call
    `append_change` again to change the tempo somewhere beyond
    `quarter`.

    Parameters
    ----------
    quarter: float
        The quarter measured in quarters where the tempo changes
    tempo: float
        The new tempo at quarter measured in quarters per minute.
        Typically, this is the same as beats per minute (BPM),
        but only when a beat lasts one quarter.

    Returns
    -------
    None
    """
    last_quarter = self.changes[-1].quarter  # get the last quarter
    assert quarter >= last_quarter
    if quarter > last_quarter:
        self.changes.append(
            MapQuarter(self.quarter_to_time(quarter), quarter)
        )
    self.last_tempo = tempo / 60.0  # from qpm to qps

get_time_at 

get_time_at(index: int) -> float

Get the time in seconds at a given index in the changes list.

Parameters:

  • index (int) –

    The index in the changes list.

Returns:

  • float –

    The time in seconds at the specified index.

Source code in amads/core/timemap.py 
185
186
187
188
189
190
191
192
193
194
195
196
197
198
def get_time_at(self, index: int) -> float:
    """Get the time in seconds at a given index in the changes list.

    Parameters
    ----------
    index : int
        The index in the changes list.

    Returns
    -------
    float
        The time in seconds at the specified index.
    """
    return self.changes[index].time

get_tempo_at 

get_tempo_at(index: int) -> float

Get the tempo at a given index in the changes list.

The tempo changes at each breakpoint. This method returns the tempo in QPM just after the breakpoint at the specified index.

Parameters:

  • index (int) –

    The index in the changes list.

Returns:

  • float –

    The tempo in quarters per minute immediately after the specified index.

  • The tempo at entry i is the tempo in effect JUST BEFORE entry i, –

Parameters:

  • index (int) –

    The index in the changes list.

Returns:

  • float –

    The tempo in quarters per minute (qpm) just after entry i.

Source code in amads/core/timemap.py 
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
def get_tempo_at(self, index: int) -> float:
    """Get the tempo at a given index in the changes list.

    The tempo changes at each breakpoint. This method returns
    the tempo in QPM just after the breakpoint at the specified
    index.

    Parameters
    ----------
    index : int
        The index in the changes list.

    Returns
    -------
    float
        The tempo in quarters per minute immediately after
        the specified index.

    The tempo at entry i is the tempo in effect JUST BEFORE entry i,

    Parameters
    ----------
    index : int
        The index in the changes list.

    Returns
    -------
    float
        The tempo in quarters per minute (qpm) just after entry i.
    """
    # two cases here: (1) we're at or beyond the last entry, so
    #   use last_tempo or extrapolate, OR
    #   (2) there's only one entry, so use last_tempo or
    #   return the default tempo
    if index < 0:
        raise ValueError("Index must be non-negative")
    if index >= len(self.changes) - 1:
        # special case: quarter >= last (time, quarter) pair
        # so extrapolate using last_tempo if it is there
        return self.last_tempo * 60.0
    mb0 = self.changes[index]
    mb1 = self.changes[index + 1]
    time_dif = mb1.time - mb0.time
    quarter_dif = mb1.quarter - mb0.quarter
    return quarter_dif * 60.0 / time_dif

_time_to_insert_index 

_time_to_insert_index(time: float) -> int

Find the insertion index for a given time in seconds.

Returns the index of the first MapQuarter whose time attribute is greater than the specified time. If time is greater than all entries, returns the length of self.changes.

This assumes that if you insert a tempo change at an existing time, the new change goes after the existing one. (But really, shouldn't you overwrite the existing one?)

Parameters:

  • time (float) –

    The time in seconds to locate.

Returns:

  • int –

    The insertion index for the given time.

Source code in amads/core/timemap.py 
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
def _time_to_insert_index(self, time: float) -> int:
    """Find the insertion index for a given time in seconds.

    Returns the index of the first MapQuarter whose `time` attribute
    is greater than the specified `time`. If `time` is greater than
    all entries, returns the length of `self.changes`.

    This assumes that if you insert a tempo change at an existing
    time, the new change goes *after* the existing one. (But
    really, shouldn't you overwrite the existing one?)

    Parameters
    ----------
    time : float
        The time in seconds to locate.

    Returns
    -------
    int
        The insertion index for the given time.
    """
    i = 0
    while i < len(self.changes) and time >= self.changes[i].time:
        i = i + 1
    return i

_quarter_to_insert_index 

_quarter_to_insert_index(quarter: float) -> int

Find the insertion index for a given quarter in seconds.

Returns the index of the first MapQuarter whose quarter attribute is greater than the specified quarter. If quarter is greater than all entries, returns the length of self.changes.

This assumes that if you insert a tempo change at an existing quarter, the new change goes after the existing one. (But really, shouldn't you overwrite the existing one?)

Parameters:

  • quarter (float) –

    The quarter note position to locate.

Returns:

  • int –
  • The insertion index for the given quarter position. –
Source code in amads/core/timemap.py 
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
def _quarter_to_insert_index(self, quarter: float) -> int:
    """Find the insertion index for a given quarter in seconds.

    Returns the index of the first MapQuarter whose `quarter`
    attribute is greater than the specified
    `quarter`. If `quarter` is greater than all entries, returns the
    length of `self.changes`.

    This assumes that if you insert a tempo change at an existing
    quarter, the new change goes *after* the existing one. (But
    really, shouldn't you overwrite the existing one?)

    Parameters
    ----------
    quarter : float
        The quarter note position to locate.

    Returns
    -------
    int
    The insertion index for the given quarter position.
    """
    i = 0
    while i < len(self.changes) and quarter >= self.changes[i].quarter:
        i = i + 1
    return i

quarter_to_time 

quarter_to_time(quarter: float) -> float

Convert time in quarters to time to seconds.

Parameters:

  • quarter (float) –

    A score position in changes.

Returns:

  • float –

    The time in seconds corresponding to quarter.

Source code in amads/core/timemap.py 
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
def quarter_to_time(self, quarter: float) -> float:
    """Convert time in quarters to time to seconds.

    Parameters
    ----------
    quarter: float
        A score position in changes.

    Returns
    -------
    float
        The time in seconds corresponding to `quarter`.
    """
    if quarter <= 0:  # there is no negative time or tempo before 0
        return quarter  # so just pretend like tempo is 60 qpm
    i = self._quarter_to_insert_index(quarter)
    return self.changes[i - 1].time + (
        quarter - self.changes[i - 1].quarter
    ) * 60.0 / self.get_tempo_at(i - 1)

quarter_to_tempo 

quarter_to_tempo(quarter: float) -> float

Get the tempo in qpm at a given quarter.

Parameters:

  • quarter (float) –

    A score position in changes.

Returns:

  • float –

    The tempo at quarter. If there is a tempo change here, returns the tempo on the right (after the change).

Source code in amads/core/timemap.py 
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
def quarter_to_tempo(self, quarter: float) -> float:
    """Get the tempo in qpm at a given quarter.

    Parameters
    ----------
    quarter: float
        A score position in changes.

    Returns
    -------
    float
        The tempo at `quarter`. If there is a tempo change here,
        returns the tempo on the right (after the change).
    """
    return self.get_tempo_at(self._quarter_to_insert_index(quarter) - 1)

time_to_quarter 

time_to_quarter(time: float) -> float

Convert time in seconds to quarter position.

Parameters:

  • time (float) –

    A score time in seconds.

Returns:

  • float –

    The score position in changes corresponding to time.

Source code in amads/core/timemap.py 
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
def time_to_quarter(self, time: float) -> float:
    """Convert time in seconds to quarter position.

    Parameters
    ----------
    time: float
        A score time in seconds.

    Returns
    -------
    float
        The score position in changes corresponding to `time`.
    """
    if time <= self.changes[0].time:
        return self.changes[0].quarter + time - self.changes[0].time
    i = self._time_to_insert_index(time)
    return (
        self.changes[i - 1].quarter
        + (time - self.changes[i - 1].time)
        * self.get_tempo_at(i - 1)
        / 60.0
    )

time_to_tempo 

time_to_tempo(time: float) -> float

Get the tempo in qpm at a given time (in seconds).

Parameters:

  • time (float) –

    A score time in seconds.

Returns:

  • float –

    The tempo at time. If there is a tempo change here, use the tempo on the right (aftr the change).

Source code in amads/core/timemap.py 
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
def time_to_tempo(self, time: float) -> float:
    """Get the tempo in qpm at a given time (in seconds).

    Parameters
    ----------
    time: float
        A score time in seconds.

    Returns
    -------
    float
        The tempo at `time`. If there is a tempo change here,
        use the tempo on the right (aftr the change).
    """
    return self.get_tempo_at(self._time_to_insert_index(time) - 1)

trim 

trim(start: float, end: float) -> None

Trim the time map to a specified range, given in seconds.

Source code in amads/core/timemap.py 
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
def trim(self, start: float, end: float) -> None:
    """Trim the time map to a specified range, given in seconds."""

    i = 0  # index into changes
    initial_quarter = self.time_to_quarter(start)
    final_bpm = self.time_to_tempo(end)

    while i < len(self.changes) and self.changes[i].time < start:
        i = i + 1
    # now i is index into changes of the first breakpoint at or after start
    # if breakpoint at i is after start, insert a breakpoint at start
    if i < len(self.changes) and (self.changes[i].time > start + 0.001):
        if i > 0:
            self.changes[i - 1].time = start
            self.changes[i - 1].quarter = initial_quarter
            i = i - 1  # will copy from i to 0
        else:
            self.changes.insert(0, MapQuarter(start, initial_quarter))
            i = 0  # no copy needed since first breakpoint is now at 0
    # else changes[i].time is within 0.001 of start, so copy from i to 0
    # now figure out where is last breakpoint before end
    j = i
    while j < len(self.changes) and self.changes[j].time < end:
        j = j + 1
    self.changes = self.changes[i:j]  # copy from i to j
    self.last_tempo = final_bpm / 60.0

_time_shift 

_time_shift(quarters: float) -> None

shift time map by quarters

When shifting forward, as when inserting beats at the beginning to fill out a measure with pickup notes, quarters are inserted at the beginning of the score at the initial tempo. The first breakpoint (usually 0,0) is unaltered, but others are incremented by the duration of the inital quarters (seconds) and quarters.

When shifting backward, e.g. quarters = -10, a breakpoint is inserted at time 10 if needed (but it's probably already there), breakpoints before 10 are removed, and all breakpoint times and beats are decremented.

Source code in amads/core/timemap.py 
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
def _time_shift(self, quarters: float) -> None:
    """shift time map by quarters

    When shifting forward, as when inserting beats at the beginning
    to fill out a measure with pickup notes, quarters are inserted
    at the beginning of the score at the initial tempo. The first
    breakpoint (usually 0,0) is unaltered, but others are incremented
    by the duration of the inital quarters (seconds) and quarters.

    When shifting backward, e.g. quarters = -10, a breakpoint is
    inserted at time 10 if needed (but it's probably already there),
    breakpoints before 10 are removed, and all breakpoint times and
    beats are decremented.
    """
    if quarters > 0:
        initial_tempo = self.get_tempo_at(0) / 60.0
        delta_time = quarters / initial_tempo
        for bp in self.changes[1:]:
            bp.time += delta_time
            bp.quarter += quarters
    elif quarters < 0:
        i = self._quarter_to_insert_index(-quarters)
        seconds = self.quarter_to_time(-quarters)
        # i is the breakpoint before -quarters, but if a breakpoint
        # already exists, it's at i - 1:
        if i > 0 and math.isclose(self.changes[i - 1].quarter, -quarters):
            i -= 1
        else:  # need to insert at i
            self.changes.insert(0, MapQuarter(seconds, -quarters))
        # i is now a breakpoint at -quarters with (seconds, -quarters)
        self.changes = self.changes[i:]
        for change in self.changes:
            change.time -= seconds
            change.quarter += quarters

MapQuarter 

MapQuarter(time: float, quarter: float)

Represents a (time, quarter) pair in a piece-wise linear mapping.

Parameters:

  • time (float) –

    The time in seconds.

  • quarter (float) –

    The corresponding quarter note position.

Attributes:

  • time (float) –

    The time in seconds.

  • quarter (float) –

    The corresponding quarter note position.

Methods:

  • copy –

    Return a copy of the MapQuarter instance.

Source code in amads/core/timemap.py 
42
43
44
def __init__(self, time: float, quarter: float):
    self.time = time
    self.quarter = quarter

Functions

copy 

copy() -> MapQuarter

return a copy of this MapQuarter

Returns:

  • MapQuarter –

    A copy of this MapQuarter instance.

Source code in amads/core/timemap.py 
46
47
48
49
50
51
52
53
54
def copy(self) -> "MapQuarter":
    """return a copy of this MapQuarter

    Returns
    -------
    MapQuarter
        A copy of this MapQuarter instance.
    """
    return MapQuarter(self.time, self.quarter)