TimeStamp

TimeStamp(axis, source, source_id, row_index=-1, conversion_maps=True)

A synchronized instant across a timeline hierarchy.

Lightweight object that computes coordinates on access via InterpolationMaps. Works identically for Timeline (with children) and TimelineGroup (with members).

The TimeStamp represents a cross-section through the timeline structure at a specific axis coordinate. All related timelines’ coordinates can be retrieved via get() or subscript access.

Attributes

Name	Type	Description
axis	float	The root/reference coordinate value.
source	TimeStampSource	The Timeline or TimelineGroup this timestamp belongs to.
source_id	str	ID of the source (for serialization).
row_index	int	If from a table row, the index. -1 if interpolated.

Examples

>>> ts = timeline.get_timestamp(5.0)
>>> ts.axis  # The root coordinate
5.0
>>> ts["child:1"]  # Get coordinate on child timeline
2.5
>>> ts.get("child:2", default=0.0)  # With default
0.0

>>> # Convert to different unit
>>> ts.get_unit(TimeUnit.seconds)
10.5

Methods

Name	Description
get	Get coordinate on another timeline.
get_conversion	Get the raw output of a conversion map addressed by name/selector.
get_unit	Get coordinate converted to a specific unit.
to_dict	Materialize all coordinates as a dictionary.

get

TimeStamp.get(timeline_id, default=None)

Get coordinate on another timeline.

Returns default (None) when the queried coordinate falls outside the related timeline’s span – for instance, asking a child whose parent-side interval is [10, 30) for the coordinate at axis 5.

For Timeline sources, child coordinates are resolved via exact offset arithmetic (no interpolation). For TimelineGroup sources, coordinates are resolved via InterpolationMap.

Parameters

Name	Type	Description	Default
timeline_id	str	The timeline to get coordinate for.	required
default	float | None	Value to return if timeline not reachable or out of span.	None

Returns

Name	Type	Description
	float | None	Coordinate on the target timeline, or default if not
	float | None	reachable or the axis is outside the target’s span.

get_conversion

TimeStamp.get_conversion(key)

Get the raw output of a conversion map addressed by name/selector.

Searches the source and every descendant/member present at this axis for a C-Map whose name, id, selector, or target-unit name is key, and evaluates it at that timeline’s coordinate.

Parameters

Name	Type	Description	Default
key	str	A conversion-map name, id, selector, or target-unit name.	required

Returns

Name	Type	Description
	Any	The C-Map’s output at this instant, or None if unreachable.

get_unit

TimeStamp.get_unit(unit)

Get coordinate converted to a specific unit.

Works with any map registered by add_conversion_map, called directly regardless of concrete type (TableMap, ScalarMap, LinearMap, InterpolationMap, …).

Searches the source and every descendant/member timeline for a C-Map with this target unit, evaluating it at the timeline’s own coordinate. A timestamp therefore surfaces unit conversions registered at any depth of the hierarchy, not just on the queried timeline.

Parameters

Name	Type	Description	Default
unit	'TimeUnit'	The target unit for conversion.	required

Returns

Name	Type	Description
	float | None	Converted coordinate, or None if no C-Map available.

to_dict

TimeStamp.to_dict(include_children=True, conversion_units=None)

Materialize all coordinates as a dictionary.

Parameters

Name	Type	Description	Default
include_children	bool	Include child/member timeline coordinates.	True
conversion_units	list['TimeUnit'] | Literal['all'] | None	C-Map conversions to include. - None: No C-Map conversions - “all”: Every C-Map across the subtree, of every kind (unit conversions, labels, structured values) - list: Specific units only	None

Returns

Name	Type	Description
	dict[str, Any]	Dict mapping timeline_id/unit_name/cmap-label to value.