timetoalign 0.0.1__py3-none-any.whl

tta/timelines.py

@@ -0,0 +1,2192 @@
+from __future__ import annotations
+
+from fractions import Fraction
+from numbers import Number
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Iterable,
+    Iterator,
+    Optional,
+    Self,
+    Sequence,
+    Set,
+    Type,
+    TypeAlias,
+    Union,
+)
+
+import numpy as np
+import pandas as pd
+from pandas._typing import SequenceNotStr
+
+from processing.metaframes import DF, DS, Meta, pd_concat
+from processing.tta import utils
+from processing.tta.conversions import (
+    C,
+    ConcatenationMap,
+    ConversionMap,
+    Coordinate,
+    FixedCoordinateTypeObject,
+    get_coordinate_type,
+    get_coordinate_value,
+    make_coordinate,
+    treat_instants_argument,
+    treat_intervals_argument,
+)
+from processing.tta.events import (
+    AudioSilo,
+    Event,
+    InstantEvent,
+    IntervalEvent,
+    MidiDataFrameSilo,
+    MidiInstantEvent,
+    MidiIntervalEvent,
+    PEvent,
+    PEventSilo,
+)
+from processing.tta.registry import (
+    ID_str,
+    ensure_registration,
+    get_object_by_id,
+    iter_objects_by_ids,
+)
+from processing.tta.utils import (
+    EventCategory,
+    IndexType,
+    InstantType,
+    NumberType,
+    TimeUnit,
+    TraversalOrder,
+)
+
+Coord: TypeAlias = Union[Number, Coordinate]
+
+
+def recursion_limit_is_reached(recursion_limit: Optional[int], limit=1) -> bool:
+    """Checks if the recursion limit has been reached.
+
+    Args:
+        recursion_limit: The current recursion limit.
+
+    Returns:
+        True if the limit is reached, False otherwise.
+    """
+    return recursion_limit is not None and recursion_limit < limit
+
+
+def decrement_if_not_none(recursion_limit: Optional[int]) -> Optional[int]:
+    """Decrements the recursion limit if it's not None.
+
+    Args:
+        recursion_limit: The current recursion limit.
+
+    Returns:
+        The decremented limit or None.
+    """
+    if recursion_limit is None:
+        return
+    return int(recursion_limit) - 1
+
+
+def expand_event_categories(
+    event_categories: Optional[Iterable[EventCategory] | EventCategory],
+) -> Set[EventCategory]:
+    """Expands 'event' category to include instant and interval event types.
+
+    Args:
+        event_categories: A single category or an iterable of categories.
+
+    Returns:
+        A set of expanded EventCategory members.
+    """
+    if event_categories is None:
+        return set()
+    values = [EventCategory(c) for c in utils.make_argument_iterable(event_categories)]
+    if EventCategory.event in values:
+        values.remove(EventCategory.event)
+        values.extend([EventCategory.inst_evt, EventCategory.intv_evt])
+    return set(values)
+
+
+def resolve_event_type_arg(
+    event_type_arg: Optional[Type[InstantEvent | IntervalEvent]],
+    event_silo_class: Type[PEventSilo],
+    timeline_class: Type[Timeline],
+    default_arg_name: str,
+):
+    if event_type_arg is None:
+        if silo_inst_default := getattr(event_silo_class, default_arg_name, None):
+            return silo_inst_default
+        return getattr(timeline_class, default_arg_name)
+    return event_type_arg
+
+
+class Timeline(FixedCoordinateTypeObject):
+    """Represents a timeline, accommodating events and other timelines (segments)."""
+
+    _locked: bool = False
+    """This is set to True when the timeline is a segment embedded in a parent timeline.
+    Operations that change a timeline's length are not allowed on a locked timeline.
+    """
+    _default_instant_event_type = InstantEvent
+    _default_interval_event_type = IntervalEvent
+
+    @classmethod
+    def from_events(
+        cls,
+        events: Iterable[Event] | Event,
+        unit: Optional[TimeUnit | str] = None,
+        number_type: Optional[NumberType] = None,
+        **kwargs,
+    ) -> Timeline:
+        """Creates a Timeline from a collection of events.
+
+        Note: Event IDs may differ from those generated by this timeline.
+
+        Args:
+            events: Event(s) to populate the timeline.
+            unit: TimeUnit for the timeline.
+            number_type: NumberType for the timeline.
+            **kwargs: Additional arguments for Timeline initialization.
+
+        Returns:
+            A new Timeline instance.
+        """
+        events = utils.make_argument_iterable(events)
+        infer_unit, infer_type = unit is None, number_type is None
+        if (infer_unit or infer_type) and events:
+            first_event = events[0]
+            if infer_unit:
+                unit = first_event.unit
+            if infer_type:
+                number_type = first_event.number_type
+        if not events:
+            return cls(unit=unit, number_type=number_type, **kwargs)
+        length = C(max(e.end.value for e in events), (unit, number_type))
+        tl = cls(length, **kwargs)
+        tl.add_events(events, allow_expansion=True)
+        return tl
+
+    @classmethod
+    def from_event_silo(
+        cls,
+        event_silo: PEventSilo,
+        instant_event_type: Optional[Type[InstantEvent]] = None,
+        interval_event_type: Optional[Type[IntervalEvent]] = None,
+        **kwargs,
+    ) -> Self:
+        timeline = cls(**kwargs)
+        id_prefix = f"{timeline.id}/ev"
+        InstEvt = resolve_event_type_arg(
+            instant_event_type, event_silo, cls, "_default_instant_event_type"
+        )
+        IntvEvt = resolve_event_type_arg(
+            interval_event_type, event_silo, cls, "_default_interval_event_type"
+        )
+        timeline._add_instant_events(
+            list(
+                event_silo.iter_instant_events(event_type=InstEvt, id_prefix=id_prefix)
+            )
+        )
+        timeline._add_interval_events(
+            list(
+                event_silo.iter_interval_events(event_type=IntvEvt, id_prefix=id_prefix)
+            )
+        )
+        return timeline
+
+    @classmethod
+    def from_concatenated_segments(
+        cls, segments: Iterable[Timeline] | Timeline, **kwargs
+    ) -> Timeline:
+        """Creates a Timeline by concatenating segments sequentially.
+
+        Args:
+            segments: Timeline segment(s) to concatenate.
+            **kwargs: Additional arguments for Timeline initialization.
+
+        Returns:
+            A new Timeline instance.
+
+        Raises:
+            ValueError: If segments have different coordinate types.
+        """
+        coordinate_types = {(seg.unit, seg.number_type) for seg in segments}
+        if len(coordinate_types) != 1:
+            raise ValueError(
+                f"Segments need to have a single coordinate type, got: {coordinate_types}"
+            )
+        ct = coordinate_types.pop()
+        init_args = dict(unit=ct[0], number_type=ct[1], **kwargs)
+        tl = cls(**init_args)
+        tl.append_segments(segments)
+        return tl
+
+    @classmethod
+    def from_timeline(
+        cls,
+        timeline: Timeline,
+        length: Coord = 0,
+        id_prefix: str = "tl",
+        uid: Optional[str] = None,
+        meta: Optional[dict] = None,
+    ):
+        """Creates an empty Timeline from another Timeline with the same coordinate type."""
+        if not isinstance(timeline, Timeline):
+            other_class_name = cls.__class__.__name__
+            raise ValueError(
+                f"Cannot create new {other_class_name} from a {timeline.class_name}."
+            )
+        new_timeline = cls(
+            unit=timeline.unit,
+            number_type=timeline.number_type,
+            id_prefix=id_prefix,
+            uid=uid,
+            meta=meta,
+        )
+        new_timeline.length = length
+        return new_timeline
+
+    def __init__(
+        self,
+        length: Coord = 0,
+        unit: Optional[TimeUnit | str] = None,
+        number_type: Optional[NumberType] = None,
+        id_prefix: str = "tl",
+        uid: Optional[str] = None,
+        meta: Optional[dict] = None,
+    ):
+        """Initializes a Timeline.
+
+        Args:
+            length: The length of the timeline.
+            unit: The time unit of the timeline.
+            number_type: The number type for coordinates.
+            id_prefix: Prefix for automatically generated ID.
+            uid: Unique identifier.
+            meta: Metadata dictionary.
+        """
+        length = make_coordinate(
+            value=length,
+            unit=unit,
+            number_type=number_type,
+            default_unit=self._default_unit,
+            default_number_type=self._default_number_type,
+        )
+        super().__init__(
+            unit=length.unit,
+            number_type=length.number_type,
+            id_prefix=id_prefix,
+            uid=uid,
+        )
+        self._meta = Meta() if meta is None else Meta(meta)
+        self._length = None
+        self.length = length
+        self._instants: DF = make_inst_df_from_segment(self, meta=self.meta)
+        """DataFrame keeping track of all things located on this timeline. The index comprises
+        all instants in chronological order including duplicates. Each row represents one
+        event which can correspond to beginning or end of an IntervalEvent or Segment,
+        or to an InstantEvent, according to the columns
+        ["id", "class_name", "instant_type", "event_category", "length"]:
+
+            * ID of the event or segment which the instant corresponds to
+            * name of the event's class for type distinction
+            * :class:`InstantType` ("start", "end", or "inst")
+            * :class:`EventCategory` ("seg", "inst_evt", "intv_evt")
+            * the length of the event (undefined for InstantEvents).
+
+        From this core representation all sorts of derivative representations can be created
+        flexibly, including SyncMaps.
+        """
+        self._intervals: DF = make_intv_df_from_segment(self, meta=self.meta)
+        """DataFrame keeping track of all IntervalEvents and Segments located on this timeline.
+        This is similar to :attr:`_instants` except that this :class.`DF` has a sorted IntervalIndex
+        and does not represent InstantEvents nor the interval spanning this Timeline. The columns
+        ["id", "class_name", "event_category", "length"] represent:
+
+            * ID of the event or segment which the instant corresponds to
+            * name of the event's class for type distinction
+            * :class:`EventCategory` ("seg", "intv_evt")
+            * the length of the event.
+        """
+
+    def __repr__(self):
+        return f"{self.class_name}(id={self.id!r}, length={self.length})"
+
+    @property
+    def length(self) -> Coordinate:
+        """The total length of the timeline."""
+        return self._length
+
+    @length.setter
+    def length(self, new_length: Coord):
+        if self._length is None:
+            self._length = self.make_coordinate(new_length)
+            self.logger.debug(
+                f"{self.id}: {self.class_name}.length set to {self._length}"
+            )
+            return
+        if new_length == self._length:
+            return
+        if self._locked:
+            raise ValueError(f"Cannot change length of locked timeline {self.id}.")
+        if new_length < self._length:
+            all_instants = self.get_instants(include_self=False)
+            later_events = all_instants.index > new_length
+            if later_events.any():
+                raise ValueError(
+                    f"The length of {self.id} cannot be reduced from {self._length} to "
+                    f"{new_length} because there are {later_events.sum()} instants occurring "
+                    f"after that."
+                )
+        new_length_coordinate = self.make_coordinate(new_length)
+        self._length = new_length_coordinate
+
+        # now the timeline's end instant needs to be adapted both in ._instants and in ._intervals
+        new_length = new_length_coordinate.value  # making sure it's just a number
+        # adapting instants index
+        inst_mask = (self._instants["id"] == self.id) & (
+            self._instants["instant_type"] == InstantType.end
+        )
+        index_values = self._instants.index.to_numpy()
+        try:
+            index_values[inst_mask] = new_length
+        except IndexError:
+            missing_id = self._instants.query("id.isna()")
+            self.logger.warning(f"The following events are missing ids: {missing_id}")
+            index_values[inst_mask.fillna(False)] = new_length
+        self._instants.index = pd.Index(index_values, name=self._instants.index.name)
+        self._instants = utils.sort_instants(self._instants)
+        # adapting intervals index
+        intv_mask = self._intervals["id"] == self.id
+        self._intervals.index = utils.new_interval_index(
+            self._intervals.index, mask=intv_mask, new_right=new_length
+        )
+        self._intervals.loc[intv_mask.values, "length"] = str(
+            new_length
+        )  # for now, all columns hold strings
+        self._intervals.sort_index(inplace=True, key=utils.longer_intervals_first)
+        self.logger.debug(
+            f"{self.id}: {self.class_name}.length updated to {self._length}"
+        )
+
+    @property
+    def origin(self) -> Coordinate:
+        """The origin (start point) of the timeline, typically 0."""
+        return self.make_coordinate(0)
+
+    @property
+    def instant(self) -> Coordinate:
+        """Alias for the origin of the timeline."""
+        return self.origin
+
+    @property
+    def interval(self) -> tuple[Number, Number]:
+        """A tuple representing the (start_value, end_value) of the timeline."""
+        return (self.start.value, self.end.value)
+
+    @property
+    def start(self) -> Coordinate:
+        """The start coordinate of the timeline."""
+        return self.origin
+
+    @property
+    def end(self) -> Coordinate:
+        """The end coordinate of the timeline."""
+        return self.length
+
+    @property
+    def meta(self) -> Meta:
+        """Metadata associated with the timeline."""
+        return Meta(
+            id=self.id,
+            length=self.length,
+            unit=self.unit,
+            number_type=self.number_type,
+            **self._meta,
+        )
+
+    @property
+    def conversion_maps(self):
+        return dict(self._cmaps)
+
+    @property
+    def zero(self) -> Number:
+        """A zero value in the timeline's number type."""
+        return self.make_number(0)
+
+    @property
+    def n_instant_events(self) -> int:
+        """Number of instant events directly on this timeline."""
+        return int(self._make_event_category_mask(EventCategory.instant_event).sum())
+
+    @property
+    def n_interval_events(self) -> int:
+        """Number of interval events directly on this timeline."""
+        return int(self._make_event_category_mask(EventCategory.interval_event).sum())
+
+    @property
+    def n_segments(self) -> int:
+        """Number of segments directly on this timeline."""
+        return int(self._make_event_category_mask(EventCategory.segment).sum())
+
+    def get_property_values(self, **kwargs) -> dict:
+        """Retrieves a dictionary of common timeline properties.
+
+        Args:
+            **kwargs: Additional properties to include.
+
+        Returns:
+            A dictionary of property names and their values.
+        """
+        return dict(
+            id=self.id,
+            coordinate_type=self.coordinate_type,
+            unit=self.unit,
+            number_type=self.number_type,
+            start=self.start,
+            end=self.end,
+            length=self.length,
+            n_instant_events=self.n_instant_events,
+            n_interval_events=self.n_interval_events,
+            n_segments=self.n_segments,
+        )
+
+    def add_events(
+        self,
+        events: Event | PEvent | Iterable[Event | PEvent],
+        allow_expansion: bool = False,
+    ):
+        """Adds event(s) to the timeline.
+
+        Args:
+            events: The event or iterable of events to add.
+            allow_expansion: If True, allows the timeline to expand if an event exceeds its length.
+
+        Raises:
+            ValueError: If an event type is invalid or expansion is prohibited.
+        """
+        events = utils.make_argument_iterable(events)
+        inst, intv, invalid = [], [], []
+        for event in events:
+            try:
+                if event.end > self.length and (self._locked or not allow_expansion):
+                    error_msg = self._make_error_message_for_prohibited_expansion(
+                        event, event.start
+                    )
+                    raise ValueError(error_msg)
+            except TypeError:
+                event_info = f"{event.__class__.__name__}"
+                if event_id := getattr(event, "id", None):
+                    event_info += f" ({event_id})"
+                if event_unit := getattr(event, "unit", None):
+                    event_info += f" with unit {event_unit}"
+                else:
+                    event_info += " which has no unit."
+                raise TypeError(
+                    f"{self.class_name} {self.id} is measured in {self.unit} and cannot "
+                    f"accomodate {event_info}."
+                )
+            if hasattr(event, "instant"):  # implements the PInstantEvent Protocol
+                inst.append(event)
+            elif hasattr(event, "start"):
+                intv.append(event)
+            else:
+                invalid.append(event)
+        if inst:
+            self._add_instant_events(inst)
+        if intv:
+            self._add_interval_events(intv)
+        if invalid:
+            invalid_types = [type(event).__name__ for event in invalid]
+            raise ValueError(
+                f"The following events have neither 'instant' nor 'start': {invalid_types}"
+            )
+
+    def _add_instant_events(self, events: InstantEvent | Iterable[InstantEvent]):
+        """Internal helper to add instant events.
+
+        Args:
+            events: The instant event(s) to add.
+        """
+        events = utils.make_argument_iterable(events)
+        new_inst_df = make_inst_df_from_inst_events(events=events, meta=self.meta)
+        self._update_instants(new_inst_df)
+
+    def _add_interval_events(
+        self, events: IntervalEvent | Iterable[IntervalEvent]  # Corrected type hint
+    ):
+        """Internal helper to add interval events.
+
+        Args:
+            events: The interval event(s) to add.
+        """
+        events = utils.make_argument_iterable(events)
+        new_inst_df = make_inst_df_from_intv_events(events=events, meta=self.meta)
+        self._update_instants(new_inst_df)
+        new_intv_df = make_intv_df_from_intv_events(events=events, meta=self.meta)
+        self._update_intervals(new_intv_df)
+
+    def add_instants(
+        self,
+        instants: Iterable[Coord] | Coord,
+        objects: Iterable[object] | object,
+        allow_expansion: bool = False,
+    ):
+        """Adds instants and their associated objects to the timeline. Objects can be external
+        in which case they will be registered with an ID based on their type. This mechanism
+        creates implicit InstantEvents in the sense that the added objects will not themselves be
+        associated with any time-related information and any such information (e.g. of existing
+        Event objects) will be ignored.
+        """
+        instants = pd.Index(treat_instants_argument(instants, ensure_unit=self.unit))
+        objects = list(utils.make_argument_iterable(objects))
+        if not len(objects):
+            self.logger.warning("Received no objects to to add")
+            return
+        if instants.max() > self.length and (self._locked or not allow_expansion):
+            obj = objects[instants.argmax()]
+            error_msg = self._make_error_message_for_prohibited_expansion(
+                obj, instants.max()
+            )
+            raise ValueError(error_msg)
+        new_inst_df = make_inst_df_from_objs_and_index(
+            objs=objects, index=instants, meta=self.meta
+        )
+        self._update_instants(new_inst_df)
+
+    def add_intervals(
+        self,
+        intervals: (
+            pd.IntervalIndex
+            | Iterable[tuple[Coord, Coord]]
+            | tuple[Coord, Coord]
+            | pd.Interval
+        ),
+        objects: Iterable[object] | object,
+        allow_expansion: bool = False,
+    ):
+        """Adds intervals and their associated objects to the timeline. Objects can be external
+        in which case they will be registered with an ID based on their type. This mechanism
+        creates implicit IntervalEvents in the sense that the added objects will not themselves be
+        associated with any time-related information and any such information (e.g. of existing
+        Event objects) will be ignored.
+        """
+        objects = list(utils.make_argument_iterable(objects))
+        if not len(objects):
+            self.logger.warning("Received no objects to to add")
+            return
+        iix = treat_intervals_argument(
+            intervals, ensure_unit=self.unit, make_iterable_singular=len(objects) == 1
+        )
+        if iix.right.max() > self.length and (self._locked or not allow_expansion):
+            obj = objects[iix.right.argmax()]
+            error_msg = self._make_error_message_for_prohibited_expansion(
+                obj, iix.right.max()
+            )
+            raise ValueError(error_msg)
+        new_inst_df = make_inst_df_from_objs_and_index(
+            objs=objects, index=iix.left, meta=self.meta
+        )
+        self._update_instants(new_inst_df)
+        new_intv_df = make_intv_df_from_objs_and_index(
+            objs=objects, intervals=iix, meta=self.meta
+        )
+        self._update_intervals(new_intv_df)
+
+    def count_events(
+        self,
+        instant_events: bool = True,
+        interval_events: bool = True,
+        segments: bool = False,
+    ) -> int:
+        """Counts events on the timeline based on specified types.
+
+        Args:
+            instant_events: If True, count instant events.
+            interval_events: If True, count interval events.
+            segments: If True, count segments.
+
+        Returns:
+            The total count of specified event types.
+        """
+        event_count = 0
+        if instant_events:
+            event_count += self.n_instant_events
+        if interval_events:
+            event_count += self.n_interval_events
+        if segments:
+            event_count += self.n_segments
+        return event_count
+
+    def validate_segment(
+        self, segment: Timeline, start: Coordinate, allow_expansion: bool = False
+    ):
+        """Checks if a segment can be added to this timeline.
+
+        Args:
+            segment: The segment to validate.
+            start: The proposed start coordinate for the segment on this timeline.
+            allow_expansion: If True, allows timeline expansion.
+
+        Raises:
+            AssertionError: If segment is not of the same class.
+            NotImplementedError: If coordinate types require conversion.
+            ValueError: If adding the segment would cause prohibited expansion.
+        """
+        assert isinstance(segment, self.__class__), (
+            f"{segment} (a {segment.name}) is not a {self.class_name} and cannot be "
+            f"added."
+        )
+        if segment.coordinate_type != self.coordinate_type:
+            NotImplementedError(
+                f"{segment.coordinate_type}s need conversion to {self.coordinate_type}"
+            )
+        new_length = start + segment.length
+        if new_length > self.length and (self._locked or not allow_expansion):
+            error_msg = self._make_error_message_for_prohibited_expansion(
+                segment, start
+            )
+            raise ValueError(error_msg)
+
+    def add_segments(
+        self,
+        segments: Iterable[Timeline] | Timeline,
+        starts: Iterable[Coordinate] | Coordinate,
+        allow_expansion: bool = False,
+    ):
+        """Adds segment(s) to the timeline at specified start times.
+
+        Args:
+            segments: The segment or iterable of segments to add.
+            starts: The start coordinate or iterable of start coordinates.
+            allow_expansion: If True, allows the timeline to expand.
+
+        Raises:
+            AssertionError: If the number of segments and starts do not match.
+        """
+        segments = list(utils.make_argument_iterable(segments))
+        starts = list(utils.make_argument_iterable(starts))
+        assert len(segments) == len(
+            starts
+        ), f"Got {len(starts)} starts for {len(segments)} segments."
+        start_coordinates = []
+        for start_val in starts:
+            if isinstance(start_val, Coordinate):
+                if start_val.unit != self.unit:
+                    raise NotImplementedError(
+                        f"The start coordinates's {start_val.unit} needs conversion to"
+                        f" {self.unit}"
+                    )
+                start_coordinates.append(start_val)
+            else:
+                start_coordinates.append(self.make_coordinate(start_val))
+        for i, segment in enumerate(segments):
+            self.validate_segment(
+                segment, start=start_coordinates[i], allow_expansion=allow_expansion
+            )
+        self._add_segments(segments=segments, starts=start_coordinates)
+
+    def _add_segments(
+        self,
+        segments: Iterable[Timeline] | Timeline,
+        starts: Iterable[Coordinate] | Coordinate,
+    ):
+        """Internal helper to add segments without validation.
+
+        Args:
+            segments: The segment(s) to add.
+            starts: The start coordinate(s) for the segments.
+        """
+        segments = utils.make_argument_iterable(segments)
+        starts = utils.make_argument_iterable(starts)
+        intv_dfs, inst_dfs = [], []
+        for segment, start in zip(segments, starts):
+            intv_dfs.append(
+                make_intv_df_from_segment(segment=segment, meta=self.meta, start=start)
+            )
+            inst_dfs.append(
+                make_inst_df_from_segment(segment=segment, meta=self.meta, start=start)
+            )
+            segment._locked = True
+            self.logger.debug(
+                f"Added segment {segment.id} to {self.id} @ {self.make_coordinate(start)}."
+            )
+        self._update_intervals(*intv_dfs)
+        self._update_instants(*inst_dfs)
+
+    def append_segments(self, segments: Iterable[Timeline] | Timeline):
+        """Appends segment(s) to the end of the timeline, allowing expansion.
+
+        Args:
+            segments: The segment or iterable of segments to append.
+        """
+        segments = utils.make_argument_iterable(segments)
+        for segment in segments:
+            self.add_segments(
+                segments=segment, starts=self.length, allow_expansion=True
+            )
+
+    def create_segment(
+        self,
+        start: Coordinate | Number,
+        end: Optional[Coordinate | Number] = None,
+        length: Optional[Coordinate | Number] = None,
+        id_prefix: str = "tl",
+        uid: Optional[str] = None,
+        meta: Optional[dict] = None,
+        allow_expansion: bool = False,
+    ) -> Self:
+        utils.validate_interval_args(start=start, end=end, length=length)
+        if length is None:
+            length = end - start
+        segment = self.from_timeline(
+            timeline=self, length=length, id_prefix=id_prefix, uid=uid, meta=meta
+        )
+        self.add_segments(
+            segments=segment, starts=start, allow_expansion=allow_expansion
+        )
+        return segment
+
+    def convert_to(
+        self,
+        values: pd.Series | np.ndarray | Sequence[Coord] | Coord,
+        target_unit: TimeUnit,
+        target_type: Optional[NumberType] = None,
+        custom_converter_func: Optional[
+            Callable[[Union[Number, np.ndarray]], Union[Number, np.ndarray]]
+        ] = None,
+    ) -> Any:
+        try:
+            # first, try to use one of the added or default maps
+            return super().convert_to(
+                values=values,
+                target_unit=target_unit,
+                target_type=target_type,
+                custom_converter_func=custom_converter_func,
+            )
+        except ValueError:
+            # if it fails (because no such map is available) try to construct one
+            cmap_from_segments = self.make_conversion_map(
+                target_unit=target_unit,
+                target_type=target_type,
+                custom_converter_func=custom_converter_func,
+            )
+            return cmap_from_segments(values)
+
+    def get_instants(
+        self,
+        instant_types: Optional[Iterable[InstantType] | InstantType] = None,
+        event_categories: Optional[Iterable[EventCategory] | EventCategory] = None,
+        class_names: Optional[Iterable[str] | str] = None,
+        recursion_limit: Optional[int] = None,
+        include_self: bool = True,
+    ) -> DF:
+        """Retrieves instants from this timeline and optionally its segments.
+
+        Args:
+            instant_types: Filter by InstantType(s).
+            event_categories: Filter by EventCategory(s).
+            class_names: Filter by class name(s).
+            recursion_limit: Depth for recursive segment traversal.
+            include_self: If True, include start and end of this timeline itself.
+
+        Returns:
+            A DataFrame of filtered instants.
+        """
+        mask = self._make_instants_mask(
+            instant_types=instant_types,
+            event_categories=event_categories,
+            class_names=class_names,
+            include_self=include_self,
+        )
+        instants = self._instants[mask]
+        if self.n_segments == 0 or recursion_limit_is_reached(recursion_limit):
+            return instants.copy()
+        recursion_limit = decrement_if_not_none(recursion_limit)
+        instants_dfs = [instants]
+        segment_mask = self._make_instants_mask(
+            instant_types=InstantType.start,
+            event_categories=EventCategory.seg,
+            include_self=False,
+        )
+        for start, segment_id in self._instants.loc[segment_mask, "id"].items():
+            segment = get_object_by_id(segment_id)
+            segment_instants = segment.get_instants(
+                instant_types=instant_types,
+                event_categories=event_categories,
+                class_names=class_names,
+                recursion_limit=recursion_limit,
+                include_self=False,
+            )
+            if segment_instants.empty:
+                continue
+            instants_dfs.append(
+                segment_instants.set_axis(segment_instants.index + start)
+            )
+        return pd_concat(instants_dfs, meta=self.meta).sort_index()
+
+    def get_timestamps(
+        self,
+        conversion_maps: Optional[
+            Iterable[ConversionMap | TimeUnit] | ConversionMap | TimeUnit
+        ] = None,
+        recursion_limit: Optional[int] = None,
+        complete_self: bool = True,
+    ) -> Optional[DF]:
+        """Generates a DataFrame of timestamps, recursively including segments concatenated on the right.
+
+        Args:
+            conversion_maps:
+                CoordinatesMap(s) or TimeUnit(s) used to create columns in addition to the ones created by
+                the
+            recursion_limit: Depth for recursive segment traversal.
+            complete_self:
+                If True, After recursively constructing timestamps, the coordinates of the main timeline are still
+                present only where it encompasses events. By default, the gaps coming from positions on child timelines
+                are filled based on the axis. Set False to prevent that.
+
+        Returns:
+            A DataFrame with original and converted timestamps.
+        """
+        timestamps_df = self.make_timestamps(conversion_maps=conversion_maps)
+        if recursion_limit_is_reached(recursion_limit):
+            return timestamps_df
+
+        recursion_limit = decrement_if_not_none(recursion_limit)
+        timestamps_dfs = [] if timestamps_df is None else [timestamps_df]
+        for start, segment in self.iter_segments(
+            recursion_limit=0, traversal_order=TraversalOrder.sorted, include_self=False
+        ):
+            seg_timestamps = segment.get_timestamps(
+                conversion_maps=conversion_maps,
+                recursion_limit=recursion_limit,
+                complete_self=complete_self,
+            )
+            seg_timestamps.index += start.value
+            timestamps_dfs.append(seg_timestamps)
+        if not timestamps_dfs:
+            return
+        if len(timestamps_dfs) == 1:
+            return timestamps_dfs[0]
+        timestamps = pd_concat(timestamps_dfs, axis=1).sort_index()
+        if not complete_self:
+            return timestamps
+        coordinates = timestamps.index
+        completed_self_timestamps = self.make_timestamps(
+            conversion_maps=conversion_maps, values=coordinates
+        )
+        if timestamps_df is None:
+            return pd_concat([completed_self_timestamps, timestamps], axis=1)
+        return pd_concat(
+            [completed_self_timestamps, pd_concat(timestamps_dfs[1:], axis=1)], axis=1
+        )
+
+    def get_intervals(
+        self,
+        event_categories: Optional[Iterable[EventCategory] | EventCategory] = None,
+        class_names: Optional[Iterable[str] | str] = None,
+        recursion_limit: Optional[int] = None,
+        include_self: bool = True,
+    ) -> DF:
+        """Retrieves intervals for events and segments.
+
+        Args:
+            event_categories: Filter by EventCategory(s).
+            class_names: Filter by class name(s).
+            recursion_limit: Depth for recursive segment traversal.
+            include_self: If True, include intervals from this timeline itself.
+
+        Returns:
+            A DataFrame of filtered intervals.
+        """
+        mask = self._make_intervals_mask(
+            event_categories=event_categories,
+            class_names=class_names,
+            include_self=include_self,
+        )
+        intervals = self._intervals[mask]
+        if self.n_segments == 0 or recursion_limit_is_reached(recursion_limit):
+            return intervals.copy()
+        recursion_limit = decrement_if_not_none(recursion_limit)
+        interval_dfs = [intervals]
+        segment_mask = self._make_instants_mask(
+            instant_types=InstantType.start,
+            event_categories=EventCategory.seg,
+            include_self=False,
+        )
+        for start, segment_id in self._instants.loc[segment_mask, "id"].items():
+            segment = get_object_by_id(segment_id)
+            segment_intervals = segment.get_intervals(
+                event_categories=event_categories,
+                class_names=class_names,
+                recursion_limit=recursion_limit,
+                include_self=False,
+            )
+            if segment_intervals.empty:
+                continue
+            interval_dfs.append(
+                segment_intervals.set_axis(
+                    utils.shift_interval_index(segment_intervals.index, start)
+                )
+            )
+        return pd_concat(interval_dfs, meta=self.meta).sort_index(
+            key=utils.longer_intervals_first
+        )
+
+    def get_events(
+        self,
+        index_type: IndexType = IndexType.instant,
+        event_categories: Optional[
+            Iterable[EventCategory], EventCategory
+        ] = EventCategory.events,
+        class_names: Optional[Iterable[str] | str] = None,
+        recursion_limit: Optional[int] = None,
+        **column2field,
+    ) -> DF:
+        """Retrieves events with their properties, indexed by specified type.
+
+        Args:
+            index_type: Type of index for the resulting DataFrame.
+            event_categories: Filter by EventCategory.
+            class_names: Filter by class name(s).
+            recursion_limit: Depth for recursive segment traversal.
+            **column2field: Mapping of DataFrame column names to metadata.
+
+        Returns:
+            A DataFrame of events and their properties.
+        """
+        event_categories = expand_event_categories(event_categories)
+        index_type = IndexType(index_type)
+        if index_type == IndexType.intervals:
+            df = self.get_intervals(
+                event_categories=event_categories,
+                class_names=class_names,
+                recursion_limit=recursion_limit,
+            )
+        else:
+            instant_type = InstantType(index_type.value)
+            if instant_type == InstantType.instant:
+                instant_type = None
+            df = self.get_instants(
+                instant_types=instant_type,
+                event_categories=event_categories,
+                class_names=class_names,
+                recursion_limit=recursion_limit,
+            )
+        if len(df) == 0:
+            return df
+        id_is_duplicate = df.duplicated(subset="id")
+        if id_is_duplicate.any():
+            event_ids = df["id"].unique()
+        else:
+            event_ids = df["id"]
+        event_records = [
+            evt.get_property_values(**column2field)  # ToDo: use get_event_properties()
+            for evt in iter_objects_by_ids(*event_ids)
+        ]
+        if id_is_duplicate.any():
+            events = pd.DataFrame.from_records(event_records)
+            return pd.merge(df, events, how="left", on="id").set_axis(df.index)
+        events = pd.DataFrame.from_records(event_records, index=df.index)
+        return pd_concat([df, events.drop(columns="id")], axis=1, meta=df._meta)
+
+    def get_segment_by_id(
+        self,
+        segment_id: str,
+    ) -> Timeline:
+        """Retrieves a segment by its ID.
+
+        Args:
+            segment_id: The ID of the segment to retrieve.
+
+        Returns:
+            The Timeline object for the segment.
+
+        Raises:
+            TypeError: If the object found is not a Timeline.
+        """
+        segment = get_object_by_id(segment_id)
+        if not isinstance(segment, Timeline):
+            raise TypeError(
+                f"The object associated with ID {segment_id} is not a Timeline but a "
+                f"{type(segment).__name__}."
+            )
+        return segment
+
+    def get_segments_by_ids(
+        self, segment_ids: Iterable[str] | str
+    ) -> Dict[str, Timeline]:
+        """Retrieves multiple segments by their IDs.
+
+        Args:
+            segment_ids: An iterable of segment IDs or a single segment ID.
+
+        Returns:
+            A dictionary mapping segment IDs to Timeline objects.
+        """
+        segment_ids = utils.make_argument_iterable(segment_ids)
+        return {seg_id: self.get_segment_by_id(seg_id) for seg_id in segment_ids}
+
+    def iter_conversion_maps(
+        self,
+        target_units: Iterable[TimeUnit] | TimeUnit,
+        recursion_limit: Optional[int] = None,
+        traversal_order: TraversalOrder = TraversalOrder.sorted,
+        include_self: bool = True,
+    ) -> Iterator[tuple[Coordinate, list[ConversionMap]]]:
+        """Iterates over conversion maps for this timeline and its segments.
+
+        Args:
+            target_units: The target TimeUnit for conversion.
+            recursion_limit: Depth for recursive segment traversal.
+            traversal_order: Order of traversal (breadth_first, depth_first, sorted).
+            include_self: If True, yield cmaps of this timeline first.
+
+
+        Yields:
+            Tuples of (start_coordinate, CoordinatesMap).
+        """
+        for start, segment in self.iter_segments(
+            recursion_limit=recursion_limit,
+            traversal_order=traversal_order,
+            include_self=include_self,
+        ):
+            yield start, segment.get_conversion_maps(target_units=target_units)
+
+    def _iter_segments(
+        self,
+        shift_start: Number = 0,
+        recursion_limit: Optional[int] = None,
+        breadth_first=False,
+        include_self: bool = True,
+    ) -> Iterator[tuple[Coordinate, Timeline]]:
+        """Internal helper to iterate over segments recursively.
+
+        Args:
+            shift_start: Offset to apply to segment start times.
+            recursion_limit: Depth for recursion.
+            breadth_first: If True, traverse breadth-first.
+            include_self: If True, yield this timeline first.
+
+        Yields:
+            Tuples of (shifted_start_coordinate, SegmentTimeline).
+        """
+        if include_self:
+            yield self.make_coordinate(shift_start), self
+        if self.n_segments == 0 or recursion_limit_is_reached(recursion_limit, limit=0):
+            reason = (
+                "No segments" if self.n_segments == 0 else "Recursion limit reached"
+            )
+            self.logger.debug(
+                f"{self.id}._iter_segments({shift_start=}, {recursion_limit=}, {include_self=}):"
+                f" {reason}"
+            )
+            return
+        recursion_limit = decrement_if_not_none(recursion_limit)
+        segment_mask = self._make_instants_mask(
+            instant_types=InstantType.start,
+            event_categories=EventCategory.seg,
+            include_self=False,
+        )
+        self.logger.debug(
+            f"{self.id}._iter_segments({shift_start=}, {recursion_limit=}, {include_self=}): Yielding "
+            f"from {segment_mask.sum()} segments {'breadth' if breadth_first else 'depth'}-first."
+        )
+        if breadth_first:
+            this_level = []
+            for start, segment_id in self._instants.loc[segment_mask, "id"].items():
+                segment = get_object_by_id(segment_id)
+                shifted_segment_start = self.make_coordinate(start + shift_start)
+                this_level.append((shifted_segment_start, segment))
+                yield shifted_segment_start, segment
+            for shifted_segment_start, segment in this_level:
+                yield from segment._iter_segments(
+                    shift_start=shifted_segment_start,
+                    recursion_limit=recursion_limit,
+                    breadth_first=breadth_first,
+                    include_self=False,
+                )
+        else:
+            # depth first
+            for start, segment_id in self._instants.loc[segment_mask, "id"].items():
+                segment = get_object_by_id(segment_id)
+                shifted_segment_start = self.make_coordinate(start + shift_start)
+                yield from segment._iter_segments(
+                    shift_start=shifted_segment_start,
+                    recursion_limit=recursion_limit,
+                    breadth_first=breadth_first,
+                    include_self=True,
+                )
+
+    def iter_segments(
+        self,
+        shift_start: Number = 0,
+        recursion_limit: Optional[int] = None,
+        traversal_order: TraversalOrder = TraversalOrder.sorted,
+        include_self: bool = True,
+    ) -> Iterator[tuple[Coordinate, Timeline]]:
+        """Iterates over this timeline and its segments.
+
+        Args:
+            shift_start: Offset to apply to segment start times.
+            recursion_limit: Depth for recursive segment traversal.
+            traversal_order: Order of traversal (breadth_first, depth_first, sorted).
+            include_self: If True, yield this timeline first (or as per sorted order).
+
+        Yields:
+            Tuples of (shifted_start_coordinate, SegmentTimeline).
+        """
+        traversal_order = TraversalOrder(traversal_order)
+        if traversal_order == TraversalOrder.breadth_first:
+            breadth_first = True
+        else:
+            # for sorted order, we go depth-first
+            breadth_first = False
+        if traversal_order == TraversalOrder.sorted:
+            yield from sorted(
+                self._iter_segments(
+                    shift_start=shift_start,
+                    recursion_limit=recursion_limit,
+                    breadth_first=breadth_first,
+                    include_self=include_self,
+                ),
+                key=lambda tup: (tup[0], -tup[1].length.value),
+            )
+        else:
+            yield from self._iter_segments(
+                shift_start=shift_start,
+                recursion_limit=recursion_limit,
+                breadth_first=breadth_first,
+                include_self=include_self,
+            )
+
+    def make_conversion_map(
+        self,
+        target_unit: TimeUnit,
+        target_type: Optional[NumberType] = None,
+        custom_converter_func: Optional[
+            Callable[[Union[Number, np.ndarray]], Union[Number, np.ndarray]]
+        ] = None,
+        recursion_limit: Optional[int] = None,
+    ) -> Optional[ConversionMap]:
+        """Creates a CoordinatesMap or list of maps for this timeline.
+
+        Note: If recursive, currently returns a list of (start, map) tuples.
+        A single concatenated map for recursive cases is a ToDo.
+
+        Args:
+            target_unit: The target TimeUnit.
+            target_type: The target NumberType.
+            custom_converter_func: Custom conversion function.
+            recursion_limit: Depth for recursive segment traversal.
+
+        Returns:
+            A single CoordinatesMap or a list of (start, CoordinatesMap) tuples.
+        """
+        cmap_line = self.make_cmap_line(
+            target_units=target_unit, recursion_limit=recursion_limit
+        )
+        if cmap_line.n_interval_events == 0:
+            raise ValueError(f"No cmaps available for unit {target_unit}.")
+        cmap_regions = cmap_line.get_intervals()
+        if not cmap_regions.index.is_non_overlapping_monotonic:
+            raise NotImplementedError(
+                f"The cmaps for unit {target_unit} cannot be concatenated into "
+                f"a correct map: {cmap_regions.id}"
+            )
+        return ConcatenationMap(cmap_regions.id)
+
+    def get_coordinates(
+        self,
+        values: Iterable[Number] = None,
+        name: Optional[str] = None,
+        unique: bool = True,
+        as_objects: bool = False,
+    ) -> DS:
+        """Creates a pandas Series of coordinates from given values or internal instants.
+
+        Args:
+            values: Values to use for the coordinate column. Defaults to internal instants.
+            name: Name for the Series. Defaults to timeline ID.
+            unique: If True, drop duplicate index values.
+            as_objects: If True, values will be Coordinate objects; otherwise, numerical.
+
+        Returns:
+            A pandas Series representing the coordinate column.
+        """
+        if values is None:
+            values = self._instants.index
+        if isinstance(values, pd.Index):
+            index = values
+        else:
+            index = pd.Index(values, name="axis")
+        if unique:
+            index = index.drop_duplicates()
+        if as_objects:
+            coordinate_type = get_coordinate_type(self.coordinate_type)
+            values = index.map(lambda x: Coordinate(x, coordinate_type))
+            dtype = None
+        else:
+            values = index
+            dtype = self.number_type.value
+            if dtype == int:
+                dtype = "Int64"  # Use pandas nullable integer type
+            if dtype == Fraction:
+                dtype = object
+        name = self.id if name is None else name
+        return DS(values, index=index, dtype=dtype, name=name, meta=self.meta)
+
+    def make_cmap_line(
+        self,
+        target_units: Optional[Iterable[TimeUnit] | TimeUnit] = None,
+        recursion_limit: Optional[int] = None,
+        include_self: bool = True,
+    ) -> CmapLine:
+        cmaps, cmap_intervals = [], []
+        for start, segment in self.iter_segments(
+            recursion_limit=recursion_limit,
+            traversal_order=TraversalOrder.depth_first,
+            include_self=include_self,
+        ):
+            segment_cmaps = segment.get_conversion_maps(target_units=target_units)
+            if not segment_cmaps:
+                continue
+            cmaps.extend(segment_cmaps)
+            shifted_interval = segment.pd_interval + start.value
+            cmap_intervals.extend([shifted_interval] * len(segment_cmaps))
+        cl = CmapLine(self.length, id_prefix=f"{self.id}/cl")
+        cl.add_intervals(intervals=cmap_intervals, objects=cmaps)
+        return cl
+
+    def make_empty_copy(
+        self,
+        length: Coord = 0,
+        id_prefix: str = "tl",
+        uid: Optional[str] = None,
+        meta: Optional[dict] = None,
+    ) -> Self:
+        """Returns a new timeline with the same timeline and coordinate type and length 0
+        (unless another length is specified).
+        """
+        return self.from_timeline(
+            timeline=self, length=length, id_prefix=id_prefix, uid=uid, meta=meta
+        )
+
+    def make_sync_map(
+        self,
+        fill_value: Optional[Any] = None,
+        index_type: IndexType = IndexType.instant,
+        event_categories: Optional[Iterable[EventCategory] | EventCategory] = None,
+        class_names: Optional[Iterable[str] | str] = None,
+        recursion_limit: Optional[int] = None,
+        group_by: Optional[tuple[str, ...] | list[str]] = ("instant_type",),
+        unstack: Optional[tuple[str, ...] | list[str]] = ("instant_type",),
+        timestamps: bool = True,
+        **column2field,
+    ) -> pd.DataFrame:
+        """Creates a synchronization map (SyncMap) from events.
+
+        This method will evolve in at least two ways:
+
+            1. Other units may be used to create different SyncMaps for the same timeline.
+            2. A closeness epsilon, binning/quantization function, and similar things can be used
+               to group temporally close coordinates.
+
+        Args:
+            fill_value:
+                Only relevant when `unstack` is specified. In this case, the SyncMap is cast to
+                wide format with as many column levels as `unstack` arguments and empty cells are
+                filled with this value. With the default `fill_value` = None, empty cells are left
+                as `pd.NA` (null). The cleanest fill_value is `[]` because all existing values
+                are lists of IDs.
+            instant_type: Type of instant to use for indexing the SyncMap.
+            event_categories: Filter events by category.
+            class_names: Filter events by class name.
+            recursion_limit: Depth for recursive segment traversal.
+            group_by:
+                A list of columns. Used to control for which value combinations event IDs are to be
+                aggregated into lists. If `unstack` is not specified, n group_by columns will result
+                in n+1 index levels (the first level is always unique coordinates). If m of the
+                n group_by columns are also specified for `unstack`, the column index has m levels
+                and the row index n-m + 1 levels.
+            unstack: Levels to unstack for wide format. Needs to be a subset of `group_by`.
+            timestamps:
+                By default, all conversion maps are applied and timeline coordinates enriched
+                accordingly. Set False to prevent and only get timeline coordinates.
+            **column2field: Mapping of DataFrame column names to event property names.
+
+        Returns:
+            A DataFrame representing the SyncMap.
+        """
+        events = self.get_events(
+            index_type=index_type,
+            event_categories=event_categories,
+            class_names=class_names,
+            recursion_limit=recursion_limit,
+            **column2field,
+        ).reset_index(names="instants")
+        gpb_columns = ["instants"]
+        if group_by:
+            group_by = utils.make_argument_iterable(group_by)
+            gpb_columns.extend(group_by)
+        assert "id" not in gpb_columns, "Cannot group by the 'id' column."
+        sync_map_long = events.groupby(gpb_columns).id.aggregate(list)
+        if unstack:
+            unstack = utils.make_argument_iterable(unstack)
+            sync_map = (
+                sync_map_long.unstack(unstack, fill_value=fill_value).sort_index(
+                    axis=1, key=lambda idx: idx.to_frame().replace(dict(ends="stop"))
+                )
+                # the key is making sure that end columns comes after start columns ("stop" is arbitrary)
+            )
+        else:
+            sync_map = sync_map_long
+        if timestamps:
+            timestamps = self.get_timestamps()
+            # reindexed_ts = timestamps.reindex(sync_map.index.get_level_values(0))
+            return pd_concat([timestamps, sync_map], axis=1)
+        return sync_map
+
+    def make_timestamps(
+        self,
+        conversion_maps: Optional[
+            Iterable[ConversionMap | TimeUnit] | ConversionMap | TimeUnit
+        ] = None,
+        values: Iterable[Number] = None,
+    ) -> Optional[DF]:
+        """Generates a DataFrame of timestamps, optionally converted to other units.
+
+        Args:
+            conversion_maps: CoordinatesMap(s) or TimeUnit(s) for additional columns.
+
+        Returns:
+            A DataFrame with original and converted timestamps, or None if empty.
+        """
+        coordinates = self.get_coordinates(values=values)
+        if coordinates.empty:
+            return None
+        columns = [coordinates]
+        conversion_maps = self._resolve_cmaps_arg(conversion_maps)
+        for cmap in conversion_maps.values():
+            if cmap is None:
+                continue
+            converted_coordinates = cmap.convert_series(coordinates)
+            columns.append(converted_coordinates)
+        if len(columns) == 1:
+            return coordinates.to_frame()
+        return pd_concat(columns, axis=1, meta=self.meta)
+
+    def _resolve_cmaps_arg(
+        self,
+        conversion_maps: Optional[
+            Iterable[ConversionMap | TimeUnit | ID_str]
+            | ConversionMap
+            | TimeUnit
+            | ID_str
+        ] = None,
+        include_added: bool = True,
+    ) -> dict[TimeUnit | ID_str, Optional[ConversionMap]]:
+        """Converts various conversion map arguments to a dictionary.
+
+        Args:
+            conversion_maps: CoordinatesMap(s) or TimeUnit(s).
+            include_added:
+                By default, conversion maps added to this object are always included, e.g. when
+                creating TimeStamps. Set False if you want to retrieve only cmaps for the arguments.
+
+        Returns:
+            A dictionary mapping target TimeUnit to CoordinatesMap.
+        """
+        conversion_maps = utils.make_argument_iterable(conversion_maps)
+        result = self.conversion_maps if include_added else {}
+        if not conversion_maps:
+            return result
+        for cmap_arg in conversion_maps:
+            if isinstance(cmap_arg, str):
+                cmap = self._resolve_cmap_argument(cmap_arg)
+                result[cmap_arg] = cmap
+            elif isinstance(cmap_arg, ConversionMap):
+                result[cmap_arg.id] = cmap_arg
+            else:
+                raise ValueError(f"Cannot interpret {cmap_arg} as CoordinatesMap.")
+        return result
+
+    def _resolve_cmap_argument(
+        self, conversion_map: Optional[ConversionMap | TimeUnit | ID_str]
+    ) -> Optional[ConversionMap]:
+        """Resolves a conversion map argument to a CoordinatesMap instance.
+
+        Args:
+            conversion_map_arg: A CoordinatesMap, TimeUnit, or string representing a TimeUnit.
+
+        Returns:
+            A CoordinatesMap instance or None.
+
+        Raises:
+            ValueError: If the argument cannot be interpreted as a CoordinatesMap.
+        """
+        if conversion_map is None:
+            return
+        if isinstance(conversion_map, ConversionMap):
+            return conversion_map
+        if isinstance(conversion_map, str):
+            try:
+                unit = TimeUnit(conversion_map)
+            except ValueError:
+                self.logger.debug(
+                    f"{conversion_map} is not a TimeUnit and interpreted as id."
+                )
+                return get_object_by_id(conversion_map)
+            return self.get_conversion_maps(unit)
+        raise ValueError(f"Cannot interpret {conversion_map} as CoordinatesMap.")
+
+    def _make_event_category_mask(
+        self, event_category: EventCategory, exclude_self: bool = True
+    ) -> pd.Series:
+        """Creates a boolean mask for a given event category.
+
+        Args:
+            event_category: The EventCategory to filter by.
+            exclude_self: If True and category is 'segment', exclude this timeline itself.
+
+        Returns:
+            A pandas Series boolean mask.
+        """
+        ev_cat = EventCategory(event_category)
+        if ev_cat == EventCategory.inst_evt:
+            if self._instants.empty:
+                return pd.Series(dtype=bool)
+            return self._instants.event_category == ev_cat
+        if self._intervals.empty:
+            return pd.Series(dtype=bool)
+        result = self._intervals.event_category == ev_cat
+        if ev_cat == EventCategory.seg and exclude_self:
+            result &= self._intervals["id"] != self.id
+        return result
+
+    def _make_error_message_for_prohibited_expansion(
+        self, event: Event | Timeline, start: Coordinate
+    ) -> str:
+        """Generates an error message for prohibited timeline expansion.
+
+        Args:
+            event: The event or timeline causing the potential expansion.
+            start: The start coordinate of the event/timeline.
+
+        Returns:
+            A formatted error message string.
+        """
+        new_length = start + event.length
+        reason = (
+            "the timeline is locked" if self._locked else "'allow_expansion' is False"
+        )
+        error_msg = (
+            f"Adding {event.__class__.__name__} of length {event.length} to {self.id} @ {start} "
+            f"would result in an expansion to {new_length} but {reason}."
+        )
+        return error_msg
+
+    def _make_instants_mask(
+        self,
+        instant_types: Optional[Iterable[InstantType] | InstantType] = None,
+        event_categories: Optional[Iterable[EventCategory] | EventCategory] = None,
+        class_names: Optional[Iterable[str] | str] = None,
+        include_self: bool = True,
+    ) -> pd.Series:
+        """Creates a boolean mask for filtering instants.
+
+        Args:
+            instant_types: Filter by InstantType(s).
+            event_categories: Filter by EventCategory(s).
+            class_names: Filter by class name(s).
+            include_self: If True, do not exclude this timeline's own segment representation.
+
+        Returns:
+            A pandas Series boolean mask against `_instants`.
+        """
+        if self._instants.empty:
+            return pd.Series(dtype=bool)
+        instant_types = [
+            InstantType(t) for t in utils.make_argument_iterable(instant_types)
+        ]
+        event_categories = expand_event_categories(event_categories)
+        class_names = utils.make_argument_iterable(class_names)
+        mask = pd.Series(True, index=self._instants.index)
+        if instant_types:
+            mask &= self._instants.instant_type.isin(instant_types)
+        if event_categories:
+            mask &= self._instants.event_category.isin(event_categories)
+        if class_names:
+            mask &= self._instants.class_name.isin(class_names)
+        if not include_self:
+            mask &= self._instants["id"] != self.id
+        return mask
+
+    def _make_intervals_mask(
+        self,
+        event_categories: Optional[Iterable[EventCategory] | EventCategory] = None,
+        class_names: Optional[Iterable[str] | str] = None,
+        include_self: bool = True,
+    ) -> pd.Series:
+        """Creates a boolean mask for filtering intervals.
+
+        Args:
+            event_categories: Filter by EventCategory(s).
+            class_names: Filter by class name(s).
+            include_self: If True, do not exclude this timeline's own segment representation.
+
+        Returns:
+            A pandas Series boolean mask against `_intervals`.
+        """
+        if self._intervals.empty:
+            return pd.Series(dtype=bool)
+        event_categories = expand_event_categories(event_categories)
+        class_names = utils.make_argument_iterable(class_names)
+        mask = pd.Series(True, index=self._intervals.index)
+        if event_categories:
+            mask &= self._intervals.event_category.isin(event_categories)
+        if class_names:
+            mask &= self._intervals.class_name.isin(class_names)
+        if not include_self:
+            mask &= self._intervals["id"] != self.id
+        return mask
+
+    def _update_instants(self, *new_instants: DF):
+        """Updates the internal `_instants` DataFrame.
+
+        Args:
+            *new_instants: DataFrame(s) containing new instants to add.
+        """
+        if len(new_instants) == 0:
+            return
+        if self._instants.empty:
+            if len(new_instants) == 1:
+                new_inst_df = new_instants[0]
+            else:
+                new_inst_df = pd_concat(new_instants, meta=self.meta)
+        else:
+            new_inst_df = pd_concat(
+                [self._instants] + list(new_instants), meta=self.meta
+            )
+        self._instants = utils.sort_instants(new_inst_df)
+        self._update_length_from_instants()
+
+    def _update_intervals(self, *new_intervals: DF):
+        """Updates the internal `_intervals` DataFrame.
+
+        Args:
+            *new_intervals: DataFrame(s) containing new intervals to add.
+        """
+        if self._intervals.empty:
+            self._intervals = pd_concat(new_intervals, meta=self.meta).sort_index()
+        else:
+            new_intv_df = pd_concat(
+                [self._intervals] + list(new_intervals), meta=self.meta
+            )
+            self._intervals = new_intv_df.sort_index()
+
+    def _update_length_from_instants(self):
+        current_length = self._instants.index.max()
+        if current_length > self.length:
+            self.length = current_length  # setter turns the value into a coordinate
+
+    def _is_other_comparable(self, other: Any) -> bool:
+        """Checks if another object is a comparable Timeline.
+
+        Args:
+            other: The object to compare.
+
+        Returns:
+            True if comparable, False otherwise.
+        """
+        return isinstance(other, Timeline) and other.unit == self.unit
+
+    def __lt__(self, other: Any) -> bool:
+        """Compares this timeline's length to another's if comparable.
+
+        Args:
+            other: The object to compare.
+
+        Returns:
+            True if this timeline is shorter, False otherwise or if not comparable.
+        """
+        if not self._is_other_comparable(other):
+            return NotImplemented
+        return self.length < other.length
+
+    def __gt__(self, other: Any) -> bool:
+        """Compares this timeline's length to another's if comparable.
+
+        Args:
+            other: The object to compare.
+
+        Returns:
+            True if this timeline is longer, False otherwise or if not comparable.
+        """
+        if not self._is_other_comparable(other):
+            return NotImplemented
+        return self.length > other.length
+
+    def __getitem__(
+        self, item: str | Any
+    ) -> Any:  # More specific type for item if possible
+        """Retrieves an object by ID if item is a string, otherwise defers to super.
+
+        Args:
+            item: The ID string or other key.
+
+        Returns:
+            The retrieved object or result from superclass.
+        """
+        if isinstance(item, str):
+            return get_object_by_id(item)
+        return super().__getitem__(item)
+
+
+class CmapLine(Timeline):
+    """This type of timeline is specifically meant for holding :class:`ConversionMap` objects as
+    implicit interval events. Typically constructed via :meth:`Timeline.make_cmap_line`.
+    """
+
+    def __init__(
+        self,
+        length: Coord = 0,
+        unit: Optional[TimeUnit | str] = None,
+        number_type: Optional[NumberType] = None,
+        id_prefix: str = "cl",
+        uid: Optional[str] = None,
+        meta: Optional[dict] = None,
+    ):
+        """Initializes a CmapLine.
+
+        Args:
+            length: The length of the CmapLine.
+            unit: The time unit of the CmapLine.
+            number_type: The number type for coordinates.
+            id_prefix: Prefix for automatically generated ID.
+            uid: Unique identifier.
+            meta: Metadata dictionary.
+        """
+        super().__init__(
+            length=length,
+            unit=unit,
+            number_type=number_type,
+            id_prefix=id_prefix,
+            uid=uid,
+            meta=meta,
+        )
+
+    def get_instants(
+        self,
+        instant_types: Optional[Iterable[InstantType] | InstantType] = None,
+        event_categories: Optional[
+            Iterable[EventCategory] | EventCategory
+        ] = EventCategory.interval_events,
+        class_names: Optional[Iterable[str] | str] = None,
+        recursion_limit: Optional[int] = None,
+        include_self: bool = True,
+    ) -> DF:
+        return super().get_instants(
+            instant_types=instant_types,
+            event_categories=event_categories,
+            class_names=class_names,
+            recursion_limit=recursion_limit,
+            include_self=include_self,
+        )
+
+    def get_intervals(
+        self,
+        event_categories: Optional[
+            Iterable[EventCategory] | EventCategory
+        ] = EventCategory.interval_events,
+        class_names: Optional[Iterable[str] | str] = None,
+        recursion_limit: Optional[int] = None,
+        include_self: bool = False,
+    ) -> DF:
+        return super().get_intervals(
+            event_categories=event_categories,
+            class_names=class_names,
+            recursion_limit=recursion_limit,
+            include_self=include_self,
+        )
+
+
+class _ContinuousMixin:
+    """Mixin for timelines with continuous number types (float, fraction)."""
+
+    _allowed_number_types = (NumberType.float, NumberType.fraction)
+
+
+class _DiscreteMixin:
+    """Mixin for timelines with discrete number types (int)."""
+
+    _allowed_number_types = NumberType.int
+    _default_number_type = NumberType.int
+
+
+class LogicalTimeline(Timeline):
+    """A timeline representing musical time."""
+
+    _allowed_units = utils.get_time_units("musical", ("continuous", "discrete"))
+
+
+class PhysicalTimeline(Timeline):
+    """A timeline representing physical time."""
+
+    _allowed_units = utils.get_time_units("physical", ("continuous", "discrete"))
+
+
+class GraphicalTimeline(Timeline):
+    """A timeline representing graphical space/time."""
+
+    _allowed_units = utils.get_time_units("graphical", ("continuous", "discrete"))
+
+
+class ContinuousLogicalTimeline(_ContinuousMixin, LogicalTimeline):
+    """A musical timeline with continuous coordinates."""
+
+    _allowed_units = utils.get_time_units("musical", "continuous")
+    _default_unit = TimeUnit.quarters
+    _default_number_type = NumberType.fraction
+
+
+class DiscreteLogicalTimeline(_DiscreteMixin, LogicalTimeline):
+    """A musical timeline with discrete coordinates."""
+
+    _allowed_units = utils.get_time_units("musical", "discrete")
+    _default_unit = TimeUnit.ticks
+    _default_number_type = NumberType.int
+    _default_instant_event_type = MidiInstantEvent
+    _default_interval_event_type = MidiIntervalEvent
+
+    @classmethod
+    def from_midi_file(cls, filepath: str, **kwargs) -> Self:
+        """Creates a DiscreteLogicalTimeline from a MIDI file.
+
+        Args:
+            filepath: Path to the MIDI file.
+            **kwargs: Additional arguments for timeline initialization.
+
+        Returns:
+            A new DiscreteLogicalTimeline instance populated with MIDI events.
+        """
+        event_silo = MidiDataFrameSilo.from_filepath(filepath)
+        return event_silo.make_timeline(timeline_class=cls, **kwargs)
+
+
+class ContinuousPhysicalTimeline(_ContinuousMixin, PhysicalTimeline):
+    """A physical timeline with continuous coordinates."""
+
+    _allowed_units = utils.get_time_units("physical", "continuous")
+    _default_unit = TimeUnit.seconds
+    _default_number_type = NumberType.float
+
+
+class DiscretePhysicalTimeline(_DiscreteMixin, PhysicalTimeline):
+    """A physical timeline with discrete coordinates."""
+
+    _allowed_units = utils.get_time_units("physical", "discrete")
+    _default_unit = TimeUnit.samples
+
+    @classmethod
+    def from_audio_file(cls, filepath: str, **kwargs) -> DiscretePhysicalTimeline:
+        """Creates a DiscretePhysicalTimeline from an audio file.
+
+        Args:
+            filepath: Path to the audio file.
+            **kwargs: Additional arguments for timeline initialization.
+
+        Returns:
+            A new DiscretePhysicalTimeline instance.
+        """
+        silo = AudioSilo.from_filepath(filepath)
+        return silo.make_timeline(timeline_class=cls, **kwargs)
+
+
+class ContinuousGraphicalTimeline(_ContinuousMixin, GraphicalTimeline):
+    """A graphical timeline with continuous coordinates."""
+
+    _allowed_units = utils.get_time_units("graphical", "continuous")
+    _default_unit = TimeUnit.meters
+
+
+class DiscreteGraphicalTimeline(_DiscreteMixin, GraphicalTimeline):
+    """A graphical timeline with discrete coordinates."""
+
+    _allowed_units = utils.get_time_units("graphical", "discrete")
+    _default_unit = TimeUnit.pixels
+
+
+# region intervals dataframe helpers
+
+
+def replace_fractions_with_floats(intervals: list[tuple[Number, Number]]):
+    """This assumes that the number types of all intervals are identical so we don't need to check
+    every type.
+    """
+    if not intervals:
+        return intervals
+    first_iv = intervals[0]
+    left, _ = first_iv
+    if not isinstance(left, Fraction):
+        return intervals
+    return [(float(left), float(right)) for left, right in intervals]
+
+
+def make_intervals_df(
+    rows: list[Sequence],
+    intervals: list[tuple[Number, Number]],
+    meta: Meta | dict,
+    **column_meta,
+) -> DF:
+    """Creates a DataFrame with an IntervalIndex.
+
+    Args:
+        rows: Data for the DataFrame rows.
+        intervals: List of (left, right) tuples for IntervalIndex.
+        meta: Metadata for the DataFrame.
+        **column_meta: Additional metadata for columns.
+
+    Returns:
+        A DataFrame with specified intervals.
+    """
+    if isinstance(intervals, pd.IntervalIndex):
+        iix = intervals
+    else:
+        intervals = replace_fractions_with_floats(intervals)
+        iix = pd.IntervalIndex.from_tuples(intervals, closed="left")
+    return DF(
+        rows,
+        columns=["id", "class_name", "event_category", "length"],
+        index=iix,
+        dtype="string",
+        meta=Meta(meta),
+        **column_meta,
+    ).rename_axis("axis")
+
+
+def make_empty_intv_df(meta: Meta | dict, **column_meta) -> DF:
+    """Creates an empty DataFrame suitable for interval data.
+
+    Args:
+        meta: Metadata for the DataFrame.
+        **column_meta: Additional metadata for columns.
+
+    Returns:
+        An empty DataFrame for intervals.
+    """
+    return make_intervals_df([], intervals=[], meta=Meta(meta), **column_meta)
+
+
+def make_intv_df_from_segment(
+    segment: Timeline,
+    meta: Meta | dict,
+    start: Optional[Coordinate | Number] = None,
+    **column_meta,
+) -> DF:
+    """Creates a single-row interval DataFrame from a segment.
+
+    Args:
+        segment: The timeline segment.
+        meta: Metadata for the DataFrame.
+        start: Optional start offset for the segment's interval.
+        **column_meta: Additional metadata for columns.
+
+    Returns:
+        A DataFrame representing the segment as an interval.
+    """
+    if start is None:
+        start = segment.origin
+    start_value = get_coordinate_value(start)
+    seg_length = segment.length.value
+    end_value = start_value + seg_length
+    interval = (start_value, end_value)
+    return make_intervals_df(
+        [[segment.id, segment.class_name, EventCategory.seg, seg_length]],
+        intervals=[interval],
+        meta=Meta(meta),
+        **column_meta,
+    )
+
+
+def make_intv_df_from_intv_events(
+    events: Iterable[IntervalEvent], meta: Meta | dict, **column_meta
+) -> DF:
+    """Creates an interval DataFrame from a collection of IntervalEvents.
+
+    Args:
+        events: Iterable of IntervalEvent objects.
+        meta: Metadata for the DataFrame.
+        **column_meta: Additional metadata for columns.
+
+    Returns:
+        A DataFrame representing the interval events.
+    """
+    rows, intervals = [], []
+    for event in events:
+        start, end = get_coordinate_value(event.start), get_coordinate_value(event.end)
+        if end is None:
+            length = get_coordinate_value(event.length)
+            end = start + length
+        else:
+            length = end - start
+        event_id = ensure_registration(event)
+        rows.append(
+            [event_id, event.__class__.__name__, EventCategory.intv_evt, length]
+        )
+        intervals.append((start, end))
+    return make_intervals_df(rows, intervals=intervals, meta=Meta(meta), **column_meta)
+
+
+def make_intv_df_from_objs_and_index(
+    objs: Iterable[object], intervals: pd.Index, meta: Meta | dict, **column_meta
+) -> DF:
+    """Creates an interval DataFrame from a collection of IntervalEvents.
+
+    Args:
+        objs: Iterable of objects.
+        index: Index corresponding to [start, end) intervals on the corresponding timeline's axis.
+        meta: Metadata for the DataFrame.
+        **column_meta: Additional metadata for columns.
+
+    Returns:
+        A DataFrame representing the interval events.
+    """
+    rows = []
+    for obj, intv in zip(objs, intervals):
+        obj_id = ensure_registration(obj)
+        rows.append(
+            [obj_id, obj.__class__.__name__, EventCategory.intv_evt, intv.length]
+        )
+    return make_intervals_df(rows, intervals=intervals, meta=Meta(meta), **column_meta)
+
+
+# endregion intervals dataframe helpers
+# region instants dataframe helpers
+
+
+def make_instants_df(
+    rows: list[Sequence], index: SequenceNotStr, meta: Meta | dict, **column_meta
+) -> DF:
+    """Creates a DataFrame for instant data.
+
+    Args:
+        rows: Data for the DataFrame rows.
+        index: Index values for the instants.
+        meta: Metadata for the DataFrame.
+        **column_meta: Additional metadata for columns.
+
+    Returns:
+        A DataFrame representing instants.
+    """
+    return DF(
+        rows,
+        columns=["id", "class_name", "instant_type", "event_category"],
+        index=index,
+        dtype="string",
+        meta=meta,
+        **column_meta,
+    ).rename_axis("axis")
+
+
+def make_empty_inst_df(meta: Meta | dict, **column_meta) -> DF:
+    """Creates an empty DataFrame suitable for instant data.
+
+    Args:
+        meta: Metadata for the DataFrame.
+        **column_meta: Additional metadata for columns.
+
+    Returns:
+        An empty DataFrame for instants.
+    """
+    return make_instants_df([], index=[], meta=Meta(meta), **column_meta)
+
+
+def make_inst_df_from_inst_events(
+    events: Iterable[InstantEvent],
+    meta: Meta | dict,
+    ensure_unique_coordinate_type: bool = True,
+    **column_meta,
+) -> DF:
+    """Creates an instant DataFrame from a collection of InstantEvents.
+
+    Args:
+        events: Iterable of InstantEvent objects.
+        meta: Metadata for the DataFrame.
+        ensure_unique_coordinate_type: If True, assert all events share a coordinate type.
+        **column_meta: Additional metadata for columns.
+
+    Returns:
+        A DataFrame representing the instant events.
+    """
+    rows, index = [], []
+    units, number_types = set(), set()
+    for event in events:
+        event_id = ensure_registration(event)
+        rows.append(
+            [
+                event_id,
+                event.__class__.__name__,
+                InstantType.inst,
+                EventCategory.inst_evt,
+            ]
+        )
+        index.append(event.instant.value)
+        units.add(event.instant.unit)
+        number_types.add(event.instant.number_type)
+    single_unit = len(units) == 1
+    single_number_type = len(number_types) == 1
+    if ensure_unique_coordinate_type:
+        assert (
+            single_unit
+        ), f"The events' coordinates have {len(units)} different units: {units}"
+        assert single_number_type, (
+            f"The events' coordinates have {len(number_types)} different number types: "
+            f"{number_types}"
+        )
+    meta.update(
+        dict(
+            unit=units.pop() if single_unit else list(units),
+            number_type=(
+                number_types.pop() if single_number_type else list(number_types)
+            ),
+        )
+    )
+    return make_instants_df(rows, index=index, meta=meta, **column_meta)
+
+
+def make_inst_df_from_objs_and_index(
+    objs: Iterable[object], index: pd.Index, meta: Meta | dict, **column_meta
+) -> DF:
+    """Creates an instant DataFrame from a collection of InstantEvents.
+
+    Args:
+        objs: Iterable of objects.
+        index: Index corresponding to instants on the timeline's axis.
+        meta: Metadata for the DataFrame.
+        ensure_unique_coordinate_type: If True, assert all events share a coordinate type.
+        **column_meta: Additional metadata for columns.
+
+    Returns:
+        A DataFrame representing the instant events.
+    """
+    rows = []
+    for obj in objs:
+        obj_id = ensure_registration(obj)
+        rows.append(
+            [obj_id, obj.__class__.__name__, InstantType.inst, EventCategory.inst_evt]
+        )
+    return make_instants_df(rows, index=index, meta=meta, **column_meta)
+
+
+def make_inst_df_from_intv_events(
+    events: Iterable[IntervalEvent],
+    meta: Meta | dict,
+    ensure_unique_coordinate_type: bool = True,
+    **column_meta,
+) -> DF:
+    """Creates an instant DataFrame from start/end points of IntervalEvents.
+
+    Args:
+        events: Iterable of IntervalEvent objects.
+        meta: Metadata for the DataFrame.
+        ensure_unique_coordinate_type: If True, assert all points share a coordinate type.
+        **column_meta: Additional metadata for columns.
+
+    Returns:
+        A DataFrame representing the start and end instants of interval events.
+    """
+    rows, index = [], []
+    units, number_types = set(), set()
+    for event in events:
+        event_id = ensure_registration(event)
+        rows.extend(
+            [
+                [
+                    event_id,
+                    event.__class__.__name__,
+                    InstantType.start,
+                    EventCategory.intv_evt,
+                ],
+                [
+                    event_id,
+                    event.__class__.__name__,
+                    InstantType.end,
+                    EventCategory.intv_evt,
+                ],
+            ]
+        )
+        index.extend(
+            [get_coordinate_value(event.start), get_coordinate_value(event.end)]
+        )
+        try:
+            units.update([event.start.unit, event.end.unit])
+            number_types.update([event.start.number_type, event.end.number_type])
+        except AttributeError:
+            pass  # external event type
+    single_unit = len(units) <= 1
+    single_number_type = len(number_types) <= 1
+    if ensure_unique_coordinate_type:
+        assert (
+            single_unit
+        ), f"The events' coordinates have {len(units)} different units: {units}"
+        assert single_number_type, (
+            f"The events' coordinates have {len(number_types)} different number types: "
+            f"{number_types}"
+        )
+    if len(units):
+        meta["unit"] = units.pop() if single_unit else list(units)
+    else:
+        meta["unit"] = None
+    if len(number_types):
+        meta["number_type"] = (
+            number_types.pop() if single_number_type else list(number_types)
+        )
+    else:
+        meta["number_type"] = None
+    return make_instants_df(rows, index=index, meta=meta, **column_meta)
+
+
+def make_inst_df_from_segment(
+    segment: Timeline,
+    meta: Meta | dict,
+    start: Optional[Coordinate | Number] = None,
+    **column_meta,
+) -> DF:
+    """Creates a two-row instant DataFrame for a segment's start and end.
+
+    Args:
+        segment: The timeline segment.
+        meta: Metadata for the DataFrame.
+        start: Optional start offset for the segment.
+        **column_meta: Additional metadata for columns.
+
+    Returns:
+        A DataFrame representing the segment's start and end instants.
+    """
+    if start is None:
+        start = segment.origin
+    start_value = get_coordinate_value(start)
+    seg_length = segment.length.value
+    end_value = start_value + seg_length
+    return make_instants_df(
+        [
+            [segment.id, segment.class_name, InstantType.start, EventCategory.seg],
+            [segment.id, segment.class_name, InstantType.end, EventCategory.seg],
+        ],
+        index=(start_value, end_value),
+        meta=meta,
+        **column_meta,
+    )
+
+
+# endregion instants dataframe helpers
+
+if __name__ == "__main__":
+    tl = Timeline("s", float, 20)
+    tl.add_segments(Timeline("s", float, 10), 5)
+    print(tl._instants)
+    print(tl._intervals)