mutwo.timeline_interfaces ¶

Place events with absolute start and end times on a time line.

Mutwo events usually follow an approach of relative placement in time. This means each event has a duration, and if there is a sequence of events the second event will start after the first event finishes. So the start and end time of any event dependent on all events which happens before the given event. This package implements the possibility to model events with independent start and end times in mutwo.

Object	Documentation
`mutwo.timeline_interfaces.EventPlacement`	Place any event at specific start and end times.
`mutwo.timeline_interfaces.TimeLine`	Timeline to place events on.
`mutwo.timeline_interfaces.Conflict`	A conflict represents two overlapping `EventPlacement`
`mutwo.timeline_interfaces.ConflictResolutionStrategy`	Abstract base class for overlapping solving classes.
`mutwo.timeline_interfaces.AlwaysLeftStrategy`	Always picks the left `EventPlacement`.
`mutwo.timeline_interfaces.AlternatingStrategy`	Alterate between the left and the right `EventPlacement`.
`mutwo.timeline_interfaces.TagCountStrategy`	Pick `EventPlacement` according to tag count.

class EventPlacement(event, start_or_start_range, end_or_end_range)[source]¶

Bases: MutwoObject

Place any event at specific start and end times.

Parameters:

event (core_events.Concurrence[core_events.Chronon | core_events.Consecution | core_events.Concurrence]) – The event to be placed on a TimeLine. This needs to be filled with events with a tag property. Each child event represents a specific object (e.g. instrument or player) The tag is necessary to concatenate two events on a TimeLine which belong to the same object (e.g. same instrument or same player).
start_or_start_range (UnspecificTimeOrTimeRange) – Sets when the event starts. This can be a single mutwo.core_parameters.abc.Duration or a ranges.Range of two durations. In the second case the placement is flexible within the given area.
end_or_end_range (UnspecificTimeOrTimeRange) – Sets when the event ends. This can be a single mutwo.core_parameters.abc.Duration or a ranges.Range of two durations. In the second case the placement is flexible within the given area.

Warning:

An EventPlacement itself is not an event and can’t be treated like an event.

Public Data Attributes:

`tag_tuple`
`start_or_start_range`
`end_or_end_range`
`duration`
`mean_start`
`mean_end`
`min_start`
`max_start`
`min_end`
`max_end`
`time_range`

Public Methods:

`is_overlapping`(other)
`move_by`(duration)
`copy`()	Return a deep copy of mutwo object.

Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.

copy()[source]¶

Return a deep copy of mutwo object.

Return type:: EventPlacement

is_overlapping(other)[source]¶

Parameters:: other (EventPlacement) –
Return type:: bool

move_by(duration)[source]¶

Parameters:: duration (UnspecificTime) –
Return type:: EventPlacement

property duration: Duration¶

property end_or_end_range: mutwo.core_parameters.abc.Duration | ranges.Range.Range¶

property max_end: Duration¶

property max_start: Duration¶

property mean_end: Duration¶

property mean_start: Duration¶

property min_end: Duration¶

property min_start: Duration¶

property start_or_start_range: mutwo.core_parameters.abc.Duration | ranges.Range.Range¶

property tag_tuple: tuple[str, ...]¶

property time_range: Range¶

class TimeLine(event_placement_sequence=[], duration=None)[source]¶

Bases: MutwoObject

Timeline to place events on.

Parameters:

duration (Optional[UnspecificTime]) – If this is set to None the duration property of the TimeLine is dynamically calculated (by the end times of all registered EventPlacement. If the duration is not None, then the duration is statically set to this time. If the user tries to register an EventPlacement with end > duration this would raise an error. Default to None.
event_placement_sequence (Sequence[EventPlacement]) –

Warning:

An TimeLine itself is not an event and can’t be treated like an event.

Public Data Attributes:

`duration`
`event_placement_tuple`
`tag_set`

Public Methods:

`register`(event_placement)	Register a new `EventPlacement` on given `TimeLine`.
`unregister`(event_placement)	Unregister an `EventPlacement` which is part of `TimeLine`.
`sort`()	Sort all `EventPlacement` by start time (and if equal by end time).
`get_event_placement`(tag, index, *[, sort])	Find specific `EventPlacement`
`resolve_conflicts`([...])	Resolve overlapping `EventPlacement` in `TimeLine`.

Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.

get_event_placement(tag, index, *, sort=True)[source]¶

Find specific EventPlacement

Parameters:

tag (str) – The tag which the EventPlacement should include.
index (int) – The index of the EventPlacement
sort (bool) – Can be set to False when sequentially calling get_event_placement without changing the TimeLine. When sort = False, but the TimeLine (or any EventPlacement inside the time TimeLine) has changed unexpected results may happen. If you want to be sure not to break anything, just leave it as True. Default to True.

Return type:

EventPlacement

register(event_placement)[source]¶

Register a new EventPlacement on given TimeLine.

Parameters:: event_placement (EventPlacement) – The EventPlacement which should be placed on the TimeLine.

resolve_conflicts(conflict_resolution_strategy_sequence=[<mutwo.timeline_interfaces.timelines.AlwaysLeftStrategy object>], is_conflict=<function TimeLine.<lambda>>, *, sort=True)[source]¶

Resolve overlapping EventPlacement in TimeLine.

Parameters:

conflict_resolution_strategy_sequence (Sequence[ConflictResolutionStrategy]) – Provide the ConflictResolutionStrategy you want to use here. If multiple are added, the algorithm initially tries the first one and if this doesn’t work it continues with the next strategy. Default to [AlwaysLeftStrategy()].
is_conflict (Callable[[EventPlacement, EventPlacement], bool]) – Function which takes two EventPlacement and which returns either True if the placements are conflicting and return False if not. This function doesn’t need to check if two placements are overlapping, this is done seperately and independently. A conflict is created only in case is_conflict returns True and the placements are overlapping. By default this function simply checks if the event placements share any common tag. The logic behind this is the assumption that tag equals instruments and that an instrument can’t play two different event placements at the same time.
sort (bool) – Can be set to False when sequentially calling resolve_conflicts without changing the TimeLine. When sort = False, but the TimeLine (or any EventPlacement inside the time TimeLine) has changed unexpected results may happen. If you want to be sure not to break anything, just leave it as True. Default to True.

Raises:

UnresolvedConflict – If none of the provided ConflictResolutionStrategy could solve the conflict.

sort()[source]¶

Sort all EventPlacement by start time (and if equal by end time).

Return type:: TimeLine

unregister(event_placement)[source]¶

Unregister an EventPlacement which is part of TimeLine.

Parameters:: event_placement (EventPlacement) – The EventPlacement which should be removed from the TimeLine.
Raises:: EventPlacementNotFoundError – If EventPlacement isn’t inside TimeLine.

property duration: Duration¶

property event_placement_tuple: tuple[mutwo.timeline_interfaces.timelines.EventPlacement, ...]¶

property tag_set: set[str]¶

class Conflict(left, right)[source]¶

Bases: MutwoObject

A conflict represents two overlapping EventPlacement

Parameters:

left (EventPlacement) – The earlier EventPlacement.
right (EventPlacement) – The later EventPlacement.

Two overlapping EventPlacement are mostly only a problem if their instruments are the same. Nevertheless the precise definition of a Conflict depends on the callable passed to the ‘is_conflict’ parameter of the TimeLine.resolve_conflicts() method.

Public Data Attributes:

`left`
`right`

Public Methods:

Inherited from MutwoObject

copy()

Return a deep copy of mutwo object.

left: EventPlacement¶

right: EventPlacement¶

class ConflictResolutionStrategy[source]¶

Bases: ABC

Abstract base class for overlapping solving classes.

You only need to the define the resolve_conflict method.

Public Methods:

resolve_conflict(timeline, conflict)

Resolve conflict between two overlapping EventPlacement.

abstract resolve_conflict(timeline, conflict)[source]¶

Resolve conflict between two overlapping EventPlacement.

Parameters:

timeline (TimeLine) – The timeline which hosts the conflict. Can be used in order to remove one or both of the conflicting event placements.
conflict (Conflict) – A Conflict object which hosts the two overlapping EventPlacement.

Return type:

bool

This method should return True if the class managed to resolve the conflict. If it returns any negative boolean value (e.g. None mutwo assumes that the conflict couldn’t be resolved).

The concrete strategy how the conflict is resolved is up to the resolution strategy class: either the conflicting event placements are removed, or the timeline is adjusted in other ways (e.g. stretched) so that the event placements aren’t overlapping anymore.

class AlwaysLeftStrategy[source]¶

Bases: ConflictResolutionStrategy

Always picks the left EventPlacement.

Public Methods:

resolve_conflict(timeline, conflict)

Resolve conflict between two overlapping EventPlacement.

Inherited from ConflictResolutionStrategy

resolve_conflict(timeline, conflict)

Resolve conflict between two overlapping EventPlacement.

resolve_conflict(timeline, conflict)[source]¶

Resolve conflict between two overlapping EventPlacement.

Parameters:

timeline (TimeLine) – The timeline which hosts the conflict. Can be used in order to remove one or both of the conflicting event placements.
conflict (Conflict) – A Conflict object which hosts the two overlapping EventPlacement.

Return type:

bool

This method should return True if the class managed to resolve the conflict. If it returns any negative boolean value (e.g. None mutwo assumes that the conflict couldn’t be resolved).

The concrete strategy how the conflict is resolved is up to the resolution strategy class: either the conflicting event placements are removed, or the timeline is adjusted in other ways (e.g. stretched) so that the event placements aren’t overlapping anymore.

class AlternatingStrategy[source]¶

Bases: ConflictResolutionStrategy

Alterate between the left and the right EventPlacement.

Public Methods:

resolve_conflict(timeline, conflict)

Resolve conflict between two overlapping EventPlacement.

Inherited from ConflictResolutionStrategy

resolve_conflict(timeline, conflict)

Resolve conflict between two overlapping EventPlacement.

resolve_conflict(timeline, conflict)[source]¶

Resolve conflict between two overlapping EventPlacement.

Parameters:

timeline (TimeLine) – The timeline which hosts the conflict. Can be used in order to remove one or both of the conflicting event placements.
conflict (Conflict) – A Conflict object which hosts the two overlapping EventPlacement.

Return type:

bool

This method should return True if the class managed to resolve the conflict. If it returns any negative boolean value (e.g. None mutwo assumes that the conflict couldn’t be resolved).

The concrete strategy how the conflict is resolved is up to the resolution strategy class: either the conflicting event placements are removed, or the timeline is adjusted in other ways (e.g. stretched) so that the event placements aren’t overlapping anymore.

class TagCountStrategy(prefer_more=True)[source]¶

Bases: ConflictResolutionStrategy

Pick EventPlacement according to tag count.

Parameters:: prefer_more (bool) – If set to True the strategy drops the EventPlacement with fewer tags. If set to False it drops the EventPlacement with more tags. Default to True.

If two EventPlacement have an equal amount of tags, this strategy won’t be able to solve the conflict.

Public Methods:

resolve_conflict(timeline, conflict)

Resolve conflict between two overlapping EventPlacement.

Inherited from ConflictResolutionStrategy

resolve_conflict(timeline, conflict)

Resolve conflict between two overlapping EventPlacement.

resolve_conflict(timeline, conflict)[source]¶

Resolve conflict between two overlapping EventPlacement.

Parameters:

timeline (TimeLine) – The timeline which hosts the conflict. Can be used in order to remove one or both of the conflicting event placements.
conflict (Conflict) – A Conflict object which hosts the two overlapping EventPlacement.

Return type:

bool

This method should return True if the class managed to resolve the conflict. If it returns any negative boolean value (e.g. None mutwo assumes that the conflict couldn’t be resolved).

The concrete strategy how the conflict is resolved is up to the resolution strategy class: either the conflicting event placements are removed, or the timeline is adjusted in other ways (e.g. stretched) so that the event placements aren’t overlapping anymore.

mutwo.timeline_interfaces¶

mutwo.timeline_interfaces ¶