MatchStamp

alignment.MatchStamp(
    coordinates=dict(),
    source_id='',
    anchor_edges=list(),
    inferred_edges=list(),
    source=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, Coordinate]	Dictionary of timeline ID to canonical 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.
axis	IdCoordinate	Identified source coordinate derived from storage.
source	'AlignmentBundle | None'	Bundle that produced the stamp.
source_id	str	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": Coordinate(100.0, TimeUnit.quarters),
...         "audio": Coordinate(45.5, TimeUnit.seconds),
...     },
...     source_id="score",
...     anchor_edges=[("score", "audio")],
... )
>>> stamp.get_coordinate_for("audio", format="float")
45.5

Methods

Name	Description
filter_by_timelines	Create filtered stamp with subset of timelines.
from_dict	Deserialize a graph-shaped typed wire dictionary.
get_conversion_for	Return an enabled conversion-map value by selector.
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 a graph-shaped typed wire dictionary.

Parameters

Name	Type	Description	Default
data	dict[str, Any]	Graph-shaped stamp payload.	required

Returns

Name	Type	Description
	'MatchStamp'	A canonical typed match stamp.

get_conversion_for

alignment.MatchStamp.get_conversion_for(key)

Return an enabled conversion-map value by selector.

Parameters

Name	Type	Description	Default
key	str	Map name, ID, selector, or target-unit name.	required

Returns

Name	Type	Description
	object	The map result without numeric projection.

Raises

Name	Type	Description
	KeyError	If no eligible conversion matches.

get_unit

alignment.MatchStamp.get_unit(
    unit,
    *,
    timeline_id=None,
    format='id_coordinate',
    rounding='round',
)

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
timeline_id	str | None	Optional stored axis to select explicitly.	None
format	CoordinateFormat	Requested coordinate output format.	'id_coordinate'
rounding	Rounding	Integral projection mode.	'round'

Returns

Name	Type	Description
	CoordinateResult | pd.Series	The converted coordinate projection.

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.