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 
1106
1107
1108
1109
1110
1111
1112
1113
def __init__(self,
             parent: Optional["EventGroup"] = None,
             onset: float = 0.0, clef: str = "treble"):
    super().__init__(parent, onset, 0)
    if clef not in ["treble", "bass", "alto", "tenor",
                  "percussion", "treble8vb"]:
        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.

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 
1168
1169
1170
1171
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.

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 
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
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.

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

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 
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
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 
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
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 
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
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 
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
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)

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 
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
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 
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
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 
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
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 
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
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 
1608
1609
1610
1611
1612
1613
1614
1615
1616
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 
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
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 
1634
1635
1636
1637
1638
1639
1640
1641
1642
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 
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
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 
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
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
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 
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
def last(self) -> Optional[Event]:
    """Retrieve the last event in the content list.

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

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

list_all 

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

Find all instances of a specific type within the EventGroup.

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

Parameters:

  • elem_type (Type[Event]) –

    The type of event to search for.

Returns:

  • list[Event] –

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

Source code in amads/core/basics.py 
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
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 
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
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 
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
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 
1844
1845
1846
1847
1848
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 
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
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
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

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 
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
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.

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 
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
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 
1844
1845
1846
1847
1848
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 
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
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 
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
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)

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 
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
def ismonophonic(self) -> bool:
    """
    Determine if content is monophonic (non-overlapping notes).

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

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

insert_emptycopy_into 

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

Create a deep copy of the EventGroup except for content.

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

Parameters:

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

    The new parent to insert the copied Event into.

Returns:

  • EventGroup –

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

Source code in amads/core/basics.py 
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
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 
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
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 
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
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 
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
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 
1608
1609
1610
1611
1612
1613
1614
1615
1616
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 
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
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 
1634
1635
1636
1637
1638
1639
1640
1641
1642
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 
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
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 
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
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
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 
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
def last(self) -> Optional[Event]:
    """Retrieve the last event in the content list.

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

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

list_all 

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

Find all instances of a specific type within the EventGroup.

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

Parameters:

  • elem_type (Type[Event]) –

    The type of event to search for.

Returns:

  • list[Event] –

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

Source code in amads/core/basics.py 
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
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 
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
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 
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
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
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

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 
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
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)

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 
2161
2162
2163
2164
2165
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.

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 
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
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 
1844
1845
1846
1847
1848
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 
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
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 
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
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)

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 
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
def ismonophonic(self) -> bool:
    """
    Determine if content is monophonic (non-overlapping notes).

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

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

insert_emptycopy_into 

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

Create a deep copy of the EventGroup except for content.

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

Parameters:

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

    The new parent to insert the copied Event into.

Returns:

  • EventGroup –

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

Source code in amads/core/basics.py 
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
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 
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
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 
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
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 
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
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 
1608
1609
1610
1611
1612
1613
1614
1615
1616
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 
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
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 
1634
1635
1636
1637
1638
1639
1640
1641
1642
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 
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
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 
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
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
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 
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
def last(self) -> Optional[Event]:
    """Retrieve the last event in the content list.

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

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

list_all 

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

Find all instances of a specific type within the EventGroup.

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

Parameters:

  • elem_type (Type[Event]) –

    The type of event to search for.

Returns:

  • list[Event] –

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

Source code in amads/core/basics.py 
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
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 
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
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 
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
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 
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
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
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

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 
2223
2224
2225
2226
2227
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.

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 
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
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 
1844
1845
1846
1847
1848
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 
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
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 
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
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)

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 
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
def ismonophonic(self) -> bool:
    """
    Determine if content is monophonic (non-overlapping notes).

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

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

insert_emptycopy_into 

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

Create a deep copy of the EventGroup except for content.

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

Parameters:

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

    The new parent to insert the copied Event into.

Returns:

  • EventGroup –

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

Source code in amads/core/basics.py 
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
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 
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
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 
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
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 
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
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 
1608
1609
1610
1611
1612
1613
1614
1615
1616
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 
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
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 
1634
1635
1636
1637
1638
1639
1640
1641
1642
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 
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
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 
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
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
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 
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
def last(self) -> Optional[Event]:
    """Retrieve the last event in the content list.

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

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

list_all 

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

Find all instances of a specific type within the EventGroup.

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

Parameters:

  • elem_type (Type[Event]) –

    The type of event to search for.

Returns:

  • list[Event] –

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

Source code in amads/core/basics.py 
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
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 
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
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 
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
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 
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
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
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

_is_well_formed 

_is_well_formed()

Test if Chord conforms to strict hierarchy of Chord-Note

Source code in amads/core/basics.py 
2230
2231
2232
2233
2234
2235
2236
2237
2238
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.

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 
 99
100
101
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 
131
132
133
134
135
136
137
138
139
140
141
142
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 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
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 
176
177
178
179
180
181
182
183
184
185
186
187
188
189
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 
191
192
193
194
195
196
197
198
199
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
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 
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
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 
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
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 
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
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 
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
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 
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
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 <= 0:
        return 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 
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
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)

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 
40
41
42
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 
44
45
46
47
48
49
50
51
52
def copy(self) -> "MapQuarter":
    """return a copy of this MapQuarter

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