MatchStamp

alignment.MatchStamp(
    coordinates=dict(),
    anchor_edges=list(),
    inferred_edges=list(),
    units=dict(),
    axis=None,
    source=None,
    source_id=None,
    is_interpolated=False,
    conversion_maps=False,
)

A synchronized timestamp across multiple timelines.

A MatchStamp represents a single coordinate (or instant) that has been synchronized across multiple timelines via explicit anchors and/or inferred group membership.

Contains one coordinate per participating timeline, where coordinates are linked via explicit anchors or inferred group membership.

Attributes

Name	Type	Description
coordinates	dict[str, float]	Dict of timeline_id -> coordinate.
anchor_edges	list[tuple[str, str]]	List of (tl_a, tl_b) pairs that are explicitly anchored.
inferred_edges	list[tuple[str, str]]	List of (tl_a, tl_b) pairs inferred via groups.
units	dict[str, str]	Coordinate unit name for each timeline.
axis	float | None	Coordinate used to query the stamp.
source	'AlignmentBundle | None'	Bundle that produced the stamp.
source_id	str | None	Timeline ID used for the query.
is_interpolated	bool	Whether the stamp used interpolated transfer.
conversion_maps	ConversionMapsSpec	Conversion maps available to unit lookup and display. Opt-in: defaults to False.

Examples

>>> stamp = MatchStamp(
...     coordinates={"score": 100.0, "audio": 45.5, "video": 1365.0},
...     anchor_edges=[("score", "audio")],
...     inferred_edges=[("audio", "video")],
... )
>>> stamp.get("audio")
45.5

Methods

Name	Description
filter_by_timelines	Create filtered stamp with subset of timelines.
from_dict	Deserialize from dictionary.
get	Get coordinate for a specific timeline.
get_group_coordinates	Get all coordinates for timelines in a specific group.
get_unit	Get the query coordinate converted to a unit.
has_timeline	Check if timeline is in this stamp.
to_dict	Materialize the stamp in a flat, grouped, or graph representation.

filter_by_timelines

alignment.MatchStamp.filter_by_timelines(timeline_ids=None, id_pattern=None)

Create filtered stamp with subset of timelines.

Parameters

Name	Type	Description	Default
timeline_ids	set[str] | None	Only include these timelines (None = all).	None
id_pattern	str | None	Regex filter for timeline IDs.	None

Returns

Name	Type	Description
	'MatchStamp'	New MatchStamp with filtered timelines.

from_dict

alignment.MatchStamp.from_dict(data)

Deserialize from dictionary.

get

alignment.MatchStamp.get(timeline_id, default=None)

Get coordinate for a specific timeline.

Parameters

Name	Type	Description	Default
timeline_id	str	The timeline to get coordinate for.	required
default	float | None	Value returned when the timeline is absent.	None

Returns

Name	Type	Description
	float | None	The coordinate, or the default if the timeline is absent.

get_group_coordinates

alignment.MatchStamp.get_group_coordinates(group)

Get all coordinates for timelines in a specific group.

Parameters

Name	Type	Description	Default
group	'TimelineGroup'	The TimelineGroup to filter by.	required

Returns

Name	Type	Description
	dict[str, float]	Dict of timeline_id -> coordinate for timelines in the group.

get_unit

alignment.MatchStamp.get_unit(unit)

Get the query coordinate converted to a unit.

Unit conversion is delegated to the source timeline’s owning group so the same conversion-map selection rules as TimeStamp apply.

Parameters

Name	Type	Description	Default
unit	TimeUnit	The target unit.	required

Returns

Name	Type	Description
	float | None	The converted coordinate, or None when it cannot be resolved.

has_timeline

alignment.MatchStamp.has_timeline(timeline_id)

Check if timeline is in this stamp.

to_dict

alignment.MatchStamp.to_dict(format='flat')

Materialize the stamp in a flat, grouped, or graph representation.

Parameters

Name	Type	Description	Default
format	Literal['flat', 'prefix', 'nested', 'graph']	Output representation. "graph" preserves the MatchGraph storage shape.	'flat'

Returns

Name	Type	Description
	dict[str, Any]	The requested dictionary representation.

Raises

Name	Type	Description
	ValueError	If a grouped format is requested without a source bundle, or if the format is unknown.