mutwo.events.abc

Abstract base classes for events (definition of public API).

Classes:

ComplexEvent(iterable)	Abstract Event-Object, which contains other Event-Objects.
Event()	Abstract Event-Object

class ComplexEvent(iterable)

Bases: mutwo.events.abc.Event, List[mutwo.events.abc.T], Generic[mutwo.events.abc.T]

Abstract Event-Object, which contains other Event-Objects.

Methods:

copy()	Return a deep copy of the ComplexEvent.
destructive_copy()	Adapted deep copy method that returns a new object for every leaf.
get_event_from_indices(indices)	Get nested Event from a sequence of indices.
get_parameter(parameter_name)	Return event attribute with the entered name.
mutate_parameter(parameter_name, function)	Mutate parameter with a function.
set_parameter(parameter_name, object_or_function)	Sets parameter to new value for all children events.
split_child_at(absolute_time)	Split child event in two events at absolute_time.
squash_in(start, event_to_squash_in)	Time-based insert of a new event into the present event.
tie_by(condition[, process_surviving_event, ...])	Condition-based deletion of neighboring events.

Attributes:

duration

The duration of an event (which can be any number).

Parameters

iterable (typing.Iterable[T]) –

copy()

Return a deep copy of the ComplexEvent.

Return type

mutwo.events.abc.ComplexEvent[mutwo.events.abc.T]

destructive_copy()

Adapted deep copy method that returns a new object for every leaf.

It’s called ‘destructive’, because it forgets potential repetitions of the same object in compound objects. Instead of reproducing the original structure of the compound object that shall be copied, every repetition of the same reference will return a new unique independent object.

The following example shall illustrate the difference between copy.deepcopy and destructive_copy:

>>> import copy
>>> from mutwo.events import basic
>>> my_simple_event_0 = basic.SimpleEvent(2)
>>> my_simple_event_1 = basic.SimpleEvent(3)
>>> my_sequential_event = basic.SequentialEvent([my_simple_event_0, my_simple_event_1, my_simple_event_0])
>>> deepcopied_event = copy.deepcopy(my_sequential_event)
>>> destructivecopied_event = my_sequential_event.destructive_copy()
>>> deepcopied_event[0].duration = 10  # setting the duration of the first event
>>> destructivecopied_event[0].duration = 10
>>> # return True because the first and the third objects share the same
>>> # reference (both are the same copy of 'my_simple_event_0')
>>> deepcopied_event[0].duration == deepcopied_event[2].duration
True
>>> # return False because destructive_copy forgets the shared reference
>>> destructivecopied_event[0].duration == destructivecopied_event[2].duration
False

Return type

mutwo.events.abc.ComplexEvent[mutwo.events.abc.T]

get_event_from_indices(indices)

Get nested Event from a sequence of indices.

Parameters

indices (typing.Sequence[int]) – The indices of the nested Event.

Return type

mutwo.events.abc.Event

Example:

>>> from mutwo.events import basic
>>> nested_sequential_event = basic.SequentialEvent([basic.SequentialEvent([basic.SimpleEvent(2)])])
>>> nested_sequential_event.get_event_from_indices((0, 0))
SimpleEvent(duration = 2)
>>> # this is equal to:
>>> nested_sequential_event[0][0]
SimpleEvent(duration = 2)

get_parameter(parameter_name)

Return event attribute with the entered name.

Parameters

parameter_name (str) – The name of the attribute that shall be returned.

Returns

Return tuple containing the assigned values for each contained event. If an event doesn’t posses the asked parameter, mutwo will simply add None to the tuple for the respective event.

Return type

Tuple[Any, …]

Example:

>>> from mutwo.events import basic
>>> sequential_event = basic.SequentialEvent([basic.SimpleEvent(2), basic.SimpleEvent(3)])
>>> sequential_event.get_parameter('duration')
(2, 3)

mutate_parameter(parameter_name, function)

Mutate parameter with a function.

Parameters

• parameter_name (str) – The name of the parameter which shall be mutated.

• function (Union[Callable[[mutwo.parameters.abc.Parameter], None], Any]) – The function which mutates the parameter. The function gets as an input the assigned value for the passed parameter_name of the respective object. The function shouldn’t return anything, but simply calls a method of the parameter value.

Return type

Optional[mutwo.events.abc.ComplexEvent[mutwo.events.abc.T]]

This method is useful when a particular parameter has been assigned to objects that know methods which mutate themselves. Then ‘mutate_parameter’ is a convenient wrapper to call the methods of those parameters for all children events.

Example:

>>> from mutwo.events import basic, music
>>> from mutwo.parameters import pitches
>>> sequential_event = basic.SequentialEvent([music.NoteLike([pitches.WesternPitch('c', 4), pitches.WesternPitch('e', 4)], 2, 1)])
>>> sequential_event.mutate_parameter('pitch_or_pitches', lambda pitch_or_pitches: [pitch.add(12) for pitch in pitch_or_pitches])
>>> # now all pitches should be one octave higher (from 4 to 5)
>>> sequential_event.get_parameter('pitch_or_pitches')
([WesternPitch(c5), WesternPitch(e5)],)

set_parameter(parameter_name, object_or_function, set_unassigned_parameter=True)

Sets parameter to new value for all children events.

Parameters

• parameter_name (str) – The name of the parameter which values shall be changed.

• object_or_function (Union[Callable[[object], object], Any]) – For setting the parameter either a new value can be passed directly or a function can be passed. The function gets as an argument the previous value that has had been assigned to the respective object and has to return a new value that will be assigned to the object.

• set_unassigned_parameter (bool) – If set to False a new parameter will only be assigned to an Event if the Event already has a attribute with the respective parameter_name. If the Event doesn’t know the attribute yet and set_unassigned_parameter is False, the method call will simply be ignored.

Return type

Optional[mutwo.events.abc.ComplexEvent[mutwo.events.abc.T]]

Example:

>>> from mutwo.events import basic
>>> sequential_event = basic.SequentialEvent([basic.SimpleEvent(2), basic.SimpleEvent(3)])
>>> sequential_event.set_parameter('duration', lambda duration: duration * 2)
>>> sequential_event.get_parameter('duration')
(4, 6)

abstract split_child_at(absolute_time)

Split child event in two events at absolute_time.

Parameters

absolute_time (Union[float, fractions.Fraction]) – where child event shall be split

Return type

Optional[mutwo.events.abc.ComplexEvent[mutwo.events.abc.T]]

Example:

>>> from mutwo.events import basic
>>> sequential_event = basic.SequentialEvent([basic.SimpleEvent(3)])
>>> sequential_event.split_child_at(1)
>>> sequential_event
SequentialEvent([SimpleEvent(duration = 1), SimpleEvent(duration = 2)])

abstract squash_in(start, event_to_squash_in)

Time-based insert of a new event into the present event.

Parameters

• start (Union[float, fractions.Fraction]) – Absolute time where the event shall be inserted.

• event_to_squash_in (mutwo.events.abc.Event) – the event that shall be squashed into the present event.

Return type

Optional[mutwo.events.abc.ComplexEvent[mutwo.events.abc.T]]

Squash in a new event to the present event.

Example:

>>> from mutwo.events import basic
>>> sequential_event = basic.SequentialEvent([basic.SimpleEvent(3)])
>>> sequential_event.squash_in(1, basic.SimpleEvent(1.5))
>>> print(sequential_event)
SequentialEvent([SimpleEvent(duration = 1), SimpleEvent(duration = 1.5), SimpleEvent(duration = 0.5)])

tie_by(condition, process_surviving_event=<function ComplexEvent.<lambda>>, event_type_to_examine=<class 'mutwo.events.abc.Event'>, event_to_remove=True)

Condition-based deletion of neighboring events.

Parameters

• condition (Callable[[mutwo.events.abc.Event, mutwo.events.abc.Event], bool]) – Function which compares two neighboring events and decides whether one of those events shall be removed. The function should return True for deletion and False for keeping both events.

• process_surviving_event (Callable[[mutwo.events.abc.Event, mutwo.events.abc.Event], None]) – Function which gets two arguments: first the surviving event and second the event which shall be removed. The function should process the surviving event depending on the removed event. By default, mutwo will simply add the duration of the removed event to the duration of the surviving event.

• event_type_to_examine (Type[mutwo.events.abc.Event]) – Defines which events shall be compared. If one only wants to process the leaves, this should perhaps be mutwo.events.basic.SimpleEvent.

• event_to_remove (bool) – True if the second (left) event shall be removed and False if the first (right) event shall be removed.

Return type

Optional[mutwo.events.abc.ComplexEvent[mutwo.events.abc.T]]

abstract property duration: Union[float, fractions.Fraction]

The duration of an event (which can be any number).

The unit of the duration is up to the interpretation of the user and the respective conversion routine that will be used. For instance when using CsoundScoreConverter, the duration will be understood as seconds, while MidiFileConverter will read duration as beats.

class Event

Bases: abc.ABC

Abstract Event-Object

Methods:

cut_off(start, end)	Time-based deletion / shortening of the respective event.
cut_out(start, end)	Time-based slicing of the respective event.
destructive_copy()	Adapted deep copy method that returns a new object for every leaf.
get_parameter(parameter_name)	Return event attribute with the entered name.
mutate_parameter(parameter_name, function)	Mutate parameter with a function.
set_parameter(parameter_name, object_or_function)	Sets parameter to new value for all children events.
split_at(absolute_time)	Split event in two events at absolute_time.

Attributes:

duration

The duration of an event (which can be any number).

abstract cut_off(start, end)

Time-based deletion / shortening of the respective event.

Parameters

• start (Union[float, fractions.Fraction]) – number that indicates absolute time when the cut off shall start.

• end (Union[float, fractions.Fraction]) – number that indicates the absolute time when the cut off shall end.

Return type

Optional[mutwo.events.abc.Event]

Example:

>>> from mutwo.events import basic
>>> sequential_event = basic.SequentialEvent([basic.SimpleEvent(3), basic.SimpleEvent(2)])
>>> sequential_event.cut_off(1, 3)
>>> print(sequential_event)
SequentialEvent([SimpleEvent(duration = 1), SimpleEvent(duration = 1)])

abstract cut_out(start, end)

Time-based slicing of the respective event.

Parameters

• start (Union[float, fractions.Fraction]) – number that indicates the point when the cut out shall start.

• end (Union[float, fractions.Fraction]) – number that indicates the point when the cut up shall end.

Return type

Optional[mutwo.events.abc.Event]

Example:

>>> from mutwo.events import basic
>>> sequential_event = basic.SequentialEvent([basic.SimpleEvent(3), basic.SimpleEvent(2)])
>>> sequential_event.cut_out(1, 4)
>>> print(sequential_event)
SequentialEvent([SimpleEvent(duration = 2), SimpleEvent(duration = 1)])

abstract destructive_copy()

Adapted deep copy method that returns a new object for every leaf.

It’s called ‘destructive’, because it forgets potential repetitions of the same object in compound objects. Instead of reproducing the original structure of the compound object that shall be copied, every repetition of the same reference will return a new unique independent object.

The following example shall illustrate the difference between copy.deepcopy and destructive_copy:

>>> import copy
>>> from mutwo.events import basic
>>> my_simple_event_0 = basic.SimpleEvent(2)
>>> my_simple_event_1 = basic.SimpleEvent(3)
>>> my_sequential_event = basic.SequentialEvent([my_simple_event_0, my_simple_event_1, my_simple_event_0])
>>> deepcopied_event = copy.deepcopy(my_sequential_event)
>>> destructivecopied_event = my_sequential_event.destructive_copy()
>>> deepcopied_event[0].duration = 10  # setting the duration of the first event
>>> destructivecopied_event[0].duration = 10
>>> # return True because the first and the third objects share the same
>>> # reference (both are the same copy of 'my_simple_event_0')
>>> deepcopied_event[0].duration == deepcopied_event[2].duration
True
>>> # return False because destructive_copy forgets the shared reference
>>> destructivecopied_event[0].duration == destructivecopied_event[2].duration
False

Return type

mutwo.events.abc.Event

abstract get_parameter(parameter_name)

Return event attribute with the entered name.

Parameters

parameter_name (str) – The name of the attribute that shall be returned.

Returns

Return tuple containing the assigned values for each contained event. If an event doesn’t posses the asked parameter, mutwo will simply add None to the tuple for the respective event.

Return type

Union[Tuple[Any, …], Any]

Example:

>>> from mutwo.events import basic
>>> sequential_event = basic.SequentialEvent([basic.SimpleEvent(2), basic.SimpleEvent(3)])
>>> sequential_event.get_parameter('duration')
(2, 3)

abstract mutate_parameter(parameter_name, function)

Mutate parameter with a function.

Parameters

• parameter_name (str) – The name of the parameter which shall be mutated.

• function (Union[Callable[[mutwo.parameters.abc.Parameter], None], Any]) – The function which mutates the parameter. The function gets as an input the assigned value for the passed parameter_name of the respective object. The function shouldn’t return anything, but simply calls a method of the parameter value.

Return type

None

This method is useful when a particular parameter has been assigned to objects that know methods which mutate themselves. Then ‘mutate_parameter’ is a convenient wrapper to call the methods of those parameters for all children events.

Example:

>>> from mutwo.events import basic, music
>>> from mutwo.parameters import pitches
>>> sequential_event = basic.SequentialEvent([music.NoteLike([pitches.WesternPitch('c', 4), pitches.WesternPitch('e', 4)], 2, 1)])
>>> sequential_event.mutate_parameter('pitch_or_pitches', lambda pitch_or_pitches: [pitch.add(12) for pitch in pitch_or_pitches])
>>> # now all pitches should be one octave higher (from 4 to 5)
>>> sequential_event.get_parameter('pitch_or_pitches')
([WesternPitch(c5), WesternPitch(e5)],)

abstract set_parameter(parameter_name, object_or_function, set_unassigned_parameter=True)

Sets parameter to new value for all children events.

Parameters

• parameter_name (str) – The name of the parameter which values shall be changed.

• object_or_function (Union[Callable[[object], object], Any]) – For setting the parameter either a new value can be passed directly or a function can be passed. The function gets as an argument the previous value that has had been assigned to the respective object and has to return a new value that will be assigned to the object.

• set_unassigned_parameter (bool) – If set to False a new parameter will only be assigned to an Event if the Event already has a attribute with the respective parameter_name. If the Event doesn’t know the attribute yet and set_unassigned_parameter is False, the method call will simply be ignored.

Return type

None

Example:

>>> from mutwo.events import basic
>>> sequential_event = basic.SequentialEvent([basic.SimpleEvent(2), basic.SimpleEvent(3)])
>>> sequential_event.set_parameter('duration', lambda duration: duration * 2)
>>> sequential_event.get_parameter('duration')
(4, 6)

split_at(absolute_time)

Split event in two events at absolute_time.

Parameters

absolute_time (Union[float, fractions.Fraction]) – where event shall be split

Returns

Two events that result from splitting the present event.

Return type

Tuple[mutwo.events.abc.Event, mutwo.events.abc.Event]

Example:

>>> from mutwo.events import basic
>>> sequential_event = basic.SequentialEvent([basic.SimpleEvent(3)])
>>> sequential_event.split_at(1)
(SequentialEvent([SimpleEvent(duration = 1)]), SequentialEvent([SimpleEvent(duration = 2)]))
>>> sequential_event[0].split_at(1)
(SimpleEvent(duration = 1), SimpleEvent(duration = 2))

abstract property duration: Union[float, fractions.Fraction]

The duration of an event (which can be any number).

The unit of the duration is up to the interpretation of the user and the respective conversion routine that will be used. For instance when using CsoundScoreConverter, the duration will be understood as seconds, while MidiFileConverter will read duration as beats.