mutwo.events.basic

Generic event classes which can be used in multiple contexts.

The different events differ in their timing structure and whether they are nested or not:

Classes:

SequentialEvent(iterable)

Event-Object which contains other Events which happen in a linear order.

SimpleEvent(new_duration)

Event-Object which doesn't contain other Event-Objects (the node or leaf).

SimultaneousEvent(iterable)

Event-Object which contains other Event-Objects which happen at the same time.
class SequentialEvent(iterable)[source]

Bases: mutwo.events.abc.ComplexEvent, Generic[mutwo.events.basic.T]

Event-Object which contains other Events which happen in a linear order.

Methods:

copy()

Return a deep copy of the ComplexEvent.

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_event_at(absolute_time)

Get event which is active at the passed absolute_time.

get_event_from_indices(indices)

Get nested Event from a sequence of indices.

get_event_index_at(absolute_time)

Get index of event which is active at the passed absolute_time.

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.

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:

absolute_times

Return absolute point in time for each event.

duration

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

start_and_end_time_per_event

Return start and end time for each event.
Parameters

iterable (typing.Iterable[T]) –

copy()

Return a deep copy of the ComplexEvent.

Return type

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

cut_off(start, end)[source]

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.basic.SequentialEvent[mutwo.events.basic.T]]

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)])
cut_out(start, end)[source]

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.basic.SequentialEvent[mutwo.events.basic.T]]

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)])
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_at(absolute_time)[source]

Get event which is active at the passed absolute_time.

Parameters

absolute_time (Union[float, fractions.Fraction]) – The absolute time where the method shall search for the active event.

Return type

mutwo.events.basic.T

Example:

>>> from mutwo.events import basic
>>> sequential_event = basic.SequentialEvent([basic.SimpleEvent(2), basic.SimpleEvent(3)])
>>> sequential_event.get_event_at(1)
SimpleEvent(duration = 2)
>>> sequential_event.get_event_at(3)
SimpleEvent(duration = 3)
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_event_index_at(absolute_time)[source]

Get index of event which is active at the passed absolute_time.

Parameters

absolute_time (Union[float, fractions.Fraction]) – The absolute time where the method shall search for the active event.

Return type

int

Example:

>>> from mutwo.events import basic
>>> sequential_event = basic.SequentialEvent([basic.SimpleEvent(2), basic.SimpleEvent(3)])
>>> sequential_event.get_event_index_at(1)
0
>>> sequential_event.get_event_index_at(3)
1
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)
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))
split_child_at(absolute_time)[source]

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.basic.SequentialEvent[mutwo.events.basic.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)])
squash_in(start, event_to_squash_in)[source]

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.basic.SequentialEvent[mutwo.events.basic.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]]

property absolute_times: Tuple[Union[float, fractions.Fraction], ...]

Return absolute point in time for each event.

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.

property start_and_end_time_per_event: Tuple[Tuple[Union[float, fractions.Fraction], Union[float, fractions.Fraction]], ...]

Return start and end time for each event.

class SimpleEvent(new_duration)[source]

Bases: mutwo.events.abc.Event

Event-Object which doesn’t contain other Event-Objects (the node or leaf).

Parameters

new_duration (parameters.abc.DurationType) – The duration of the SimpleEvent. This can be any number. The unit of the duration is up to the interpretation of the user and the respective converter routine that will be used.

Example:

>>> from mutwo.events import basic
>>> simple_event = basic.SimpleEvent(2)
>>> print(simple_event)
SimpleEvent(duration = 2)

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 event parameter to new value.

split_at(absolute_time)

Split event in two events at absolute_time.

Attributes:

duration

The duration of an event (which can be any number).
cut_off(start, end)[source]

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.basic.SimpleEvent]

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)])
cut_out(start, end)[source]

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.basic.SimpleEvent]

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)])
destructive_copy()[source]

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

get_parameter(parameter_name)[source]

Return event attribute with the entered name.

Parameter_name

The name of the attribute that shall be returned.

Returns

Return the value that has been assigned to the passed parameter_name. If an event doesn’t posses the asked parameter, the method will simply return None.

Parameters

parameter_name (str) –

Return type

Any

Example:

>>> from mutwo.events import basic
>>> simple_event = basic.SimpleEvent(2)
>>> simple_event.pitch = 200
>>> simple_event.get_parameter('pitch')
200
>>> simple_event.get_parameter('pitches')
None
mutate_parameter(parameter_name, function)[source]

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.basic.SimpleEvent]

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)[source]

Sets event parameter to new value.

Parameters

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

  • object_or_function (Union[Callable[[mutwo.parameters.abc.Parameter], mutwo.parameters.abc.Parameter], 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.basic.SimpleEvent]

Example:

>>> from mutwo.events import basic
>>> simple_event = basic.SimpleEvent(2)
>>> simple_event.set_parameter('duration', lambda old_duration: old_duration * 2)
>>> simple_event.duration
4
>>> simple_event.set_parameter('duration', 3)
>>> simple_event.duration
3
>>> simple_event.set_parameter('unknown_parameter', 10, set_unassigned_parameter=False)  # this will be ignored
>>> simple_event.unknown_parameter
AttributeError: 'SimpleEvent' object has no attribute 'unknown_parameter'
>>> simple_event.set_parameter('unknown_parameter', 10, set_unassigned_parameter=True)  # this will be written
>>> simple_event.unknown_parameter
10
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))
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 SimultaneousEvent(iterable)[source]

Bases: mutwo.events.abc.ComplexEvent, Generic[mutwo.events.basic.T]

Event-Object which contains other Event-Objects which happen at the same time.

Methods:

copy()

Return a deep copy of the ComplexEvent.

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_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_at(absolute_time)

Split event in two events at absolute_time.

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]

cut_off(start, end)[source]

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.basic.SimultaneousEvent[mutwo.events.basic.T]]

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)])
cut_out(start, end)[source]

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.basic.SimultaneousEvent[mutwo.events.basic.T]]

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)])
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)
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))
split_child_at(absolute_time)[source]

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.basic.SimultaneousEvent[mutwo.events.basic.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)])
squash_in(start, event_to_squash_in)[source]

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.basic.SimultaneousEvent[mutwo.events.basic.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]]

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.