GroupTimestamp

timelines.GroupTimestamp(
    coordinates,
    units=dict(),
    row_index=-1,
    source=None,
    source_id=None,
    axis=None,
    conversion_maps=True,
)

A synchronized instant across all timelines in a group.

This is a view object created from a row in the group’s timestamp table. Not stored directly - the table is the source of truth.

Attributes

Name	Type	Description
coordinates	dict[str, float | None]	Dictionary mapping timeline/cmap IDs to coordinates. None values indicate the timeline is not present at this instant.
units	dict[str, str]	Dictionary mapping timeline/cmap IDs to their unit strings. Used for display purposes.
row_index	int	Index of this timestamp in the source table. -1 indicates an interpolated timestamp (not from a table row).

Examples

>>> ts = group.get_timestamp_at_index(0)
>>> ts["dgt1:1"]  # Get coordinate for dgt1
0.0
>>> ts.present_timelines  # Which timelines have values here
['dgt1:1', 'audio:1']

See Also

TimeStamp: The unified timestamp class from timetoalign.core.

Methods

Name	Description
get	Get coordinate for a timeline.
get_unit	Get the row coordinate converted to a specific unit.
to_dict	Materialize the stored row coordinates as a dictionary.

get

timelines.GroupTimestamp.get(timeline_id, default=None)

Get coordinate for a timeline.

Parameters

Name	Type	Description	Default
timeline_id	str	The timeline to look up.	required
default	float | None	Value to return if timeline not in coordinates.	None

Returns

Name	Type	Description
	float | None	The coordinate value, or default if not found.

get_unit

timelines.GroupTimestamp.get_unit(unit)

Get the row coordinate converted to a specific unit.

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 permitted C-Map is available.

to_dict

timelines.GroupTimestamp.to_dict(include_children=True, conversion_units=None)

Materialize the stored row coordinates as a dictionary.

Parameters

Name	Type	Description	Default
include_children	bool	Retained for the shared Stamp interface.	True
conversion_units	list[TimeUnit] | Literal['all'] | None	Retained for the shared Stamp interface.	None

Returns

Name	Type	Description
	dict[str, float | None]	Dictionary mapping timeline IDs to stored coordinate values.