MatchClaim

alignment.MatchClaim()

A claim that two events or coordinates on different timelines correspond.

A MatchClaim always knows which two timelines it connects via top-level timeline_a_id and timeline_b_id fields. Anchors are only present for synchronous claims.

Four cases

1. from_events: Two timed things on different timelines correspond.
2. from_projection: An event is projected onto a timeline with no matching event.
3. nomatch: An event has no equivalent on the other timeline.
4. implicit: Implicit claim generated by MatchGraph group extension.

Attributes

Name	Type	Description
timeline_a_id	str	First timeline’s unique identifier.
timeline_b_id	str	Second timeline’s unique identifier.
start_anchor	AlignmentAnchor | None	AlignmentAnchor for event starts (None for non-synchronous).
end_anchor	AlignmentAnchor | None	AlignmentAnchor for event ends (None for instants or non-synchronous claims).
is_synchronous	bool	True if temporally synchronous matches.
is_explicit	bool	True if directly claimed, False if inferred.
metadata	MatchMetadata | None	Provenance information (agent, criteria, certainty).
source_claim_id	str | None	For implicit claims, the ID of the claim that generated this one.
event_a_id	str | None	ID of the event on timeline A (if known).
event_a_name	str | None	Name/label of the event on timeline A (if known).
event_b_id	str | None	ID of the event on timeline B (if known).
event_b_name	str | None	Name/label of the event on timeline B (if known).
source_coordinate	Coordinate | None	Unmatched source-side coordinate for a NOMATCH claim. None for synchronous claims, whose coordinate is held by the anchor instead.
id	str	Unique identifier for this claim.

Examples

>>> # Synchronous instant match via factory
>>> claim = MatchClaim.from_events(
...     event_a={"id": "e001", "name": "Note C4", "start": 100.0},
...     tl_a_id="score:1",
...     event_b={"id": "e042", "name": "Note C4", "start": 45.5},
...     tl_b_id="recording:1",
...     unit_a=TimeUnit.quarters,
...     unit_b=TimeUnit.seconds,
... )
>>> claim.event_a_id
'e001'
>>> claim.event_a_name
'Note C4'

>>> # Non-synchronous claim (no anchors)
>>> claim = MatchClaim.nomatch(
...     event={"id": "orphan", "start": 100.0},
...     source_tl_id="score:1",
...     target_tl_id="recording:1",
...     unit=TimeUnit.quarters,
... )
>>> claim.start_anchor is None
True

Methods

Name	Description
connects	Check if this claim connects to a specific timeline.
connects_both	Check if this claim connects two specific timelines.
from_dict	Deserialize from dictionary.
from_events	Case (a): Two timed things on different timelines correspond.
from_projection	Case (b): An event is projected onto a timeline with no matching event.
from_row	Reconstruct a claim from a struct-shaped Arrow row dict.
get_coordinates_for	Get start and end coordinates for a specific timeline.
get_matchstamp	Return a MatchStamp for this claim’s start anchor.
implicit	Case (d): Implicit claim generated by MatchGraph group extension.
nomatch	Case (c): An event has no equivalent on the other timeline.
set_bundle	Associate this claim with an AlignmentBundle.
to_dict	Serialize to dictionary for storage.

connects

alignment.MatchClaim.connects(timeline_id)

Check if this claim connects to a specific timeline.

Parameters

Name	Type	Description	Default
timeline_id	str	The timeline to check.	required

Returns

Name	Type	Description
	bool	True if the claim involves this timeline.

connects_both

alignment.MatchClaim.connects_both(timeline_a_id, timeline_b_id)

Check if this claim connects two specific timelines.

Parameters

Name	Type	Description	Default
timeline_a_id	str	First timeline.	required
timeline_b_id	str	Second timeline.	required

Returns

Name	Type	Description
	bool	True if the claim connects exactly these two timelines.

from_dict

alignment.MatchClaim.from_dict(data)

Deserialize from dictionary.

Two normalisations precede validation: an absent timeline ID is taken from the start anchor, and a missing or null id becomes the empty string that triggers ID generation.

from_events

alignment.MatchClaim.from_events(
    event_a,
    tl_a_id,
    event_b,
    tl_b_id,
    *,
    unit_a,
    unit_b,
    coord_key='start',
    end_coord_key=None,
    is_synchronous=True,
    metadata=None,
)

Case (a): Two timed things on different timelines correspond.

Parameters

Name	Type	Description	Default
event_a	dict[str, Any]	Event dict from timeline A (must contain coord_key). May also contain id and name fields.	required
tl_a_id	str	Timeline A’s ID.	required
event_b	dict[str, Any]	Event dict from timeline B (must contain coord_key). May also contain id and name fields.	required
tl_b_id	str	Timeline B’s ID.	required
unit_a	TimeUnit | str	Unit of timeline A’s coordinates.	required
unit_b	TimeUnit | str	Unit of timeline B’s coordinates.	required
coord_key	str	Key for start coordinate in event dicts.	'start'
end_coord_key	str | None	Key for end coordinate (creates interval match).	None
is_synchronous	bool	Whether events are temporally synchronous.	True
metadata	MatchMetadata | None	Provenance information.	None

Returns

Name	Type	Description
	'MatchClaim'	A synchronous MatchClaim with 1 or 2 anchors and event info.

from_projection

alignment.MatchClaim.from_projection(
    event,
    source_tl_id,
    target_tl_id,
    target_coord,
    *,
    source_unit,
    target_unit=None,
    coord_key='start',
    target_end_coord=None,
    end_coord_key=None,
    metadata=None,
)

Case (b): An event is projected onto a timeline with no matching event.

The source event has a coordinate; the target coordinate is specified explicitly (e.g., computed by interpolation or DTW).

Parameters

Name	Type	Description	Default
event	dict[str, Any]	Event dict from the source timeline. May contain id and name fields.	required
source_tl_id	str	Source timeline’s ID.	required
target_tl_id	str	Target timeline’s ID.	required
target_coord	CoordinateSpec	Projected coordinate specification on the target timeline.	required
source_unit	TimeUnit | str	Unit of the source timeline’s coordinates.	required
target_unit	TimeUnit | str | None	Unit of the target timeline’s coordinates.	None
coord_key	str	Key for start coordinate in event dict.	'start'
target_end_coord	CoordinateSpec | None	Projected end coordinate specification (creates interval match).	None
end_coord_key	str | None	Key for end coordinate in event dict.	None
metadata	MatchMetadata | None	Provenance information.	None

Returns

Name	Type	Description
	'MatchClaim'	A synchronous MatchClaim with 1 or 2 anchors and source event info.

from_row

alignment.MatchClaim.from_row(row)

Reconstruct a claim from a struct-shaped Arrow row dict.

This is the entry point SemanticField.__getitem__ uses to materialise a scalar from the backing struct column. The row dict carries the nested start_anchor / end_anchor / metadata sub-dicts (or None for absent slots), so the shape is exactly the one :meth:from_dict already accepts.

Parameters

Name	Type	Description	Default
row	dict[str, Any]	The .as_py() dict of one struct-column element.	required

Returns

Name	Type	Description
	'MatchClaim'	A reconstructed :class:MatchClaim.

get_coordinates_for

alignment.MatchClaim.get_coordinates_for(timeline_id)

Get start and end coordinates for a specific timeline.

Parameters

Name	Type	Description	Default
timeline_id	str	The timeline to get coordinates for.	required

Returns

Name	Type	Description
	tuple[Coordinate, Coordinate | None]	Tuple of (start_coord, end_coord). end_coord is None for instants.

Raises

Name	Type	Description
	ValueError	If timeline is not in this claim or claim has no anchors.

get_matchstamp

alignment.MatchClaim.get_matchstamp(
    bundle=None,
    from_graph=True,
    conversion_maps=False,
)

Return a MatchStamp for this claim’s start anchor.

With from_graph=True (the default), the method builds or retrieves the full MatchGraph for this claim’s coordinate from the bundle’s cache and returns the FULL MatchStamp combining timestamps from ALL groups connected at this coordinate.

With from_graph=False, constructs a reduced MatchStamp from only the two timelines in this claim (no graph construction needed).

Parameters

Name	Type	Description	Default
bundle	'AlignmentBundle | None'	The AlignmentBundle containing this claim. Required for from_graph=True. Provides group info and the MatchGraph cache.	None
from_graph	bool	If True (default), build/retrieve the full MatchGraph and return the FULL MatchStamp across ALL connected groups. If False, return a reduced 2-timeline MatchStamp.	True
conversion_maps	'ConversionMapsSpec'	C-map conversions available through unit lookup. Opt-in: defaults to False.	False

Returns

Name	Type	Description
	'MatchStamp | None'	MatchStamp with coordinates, or None if this claim is
	'MatchStamp | None'	non-synchronous (NOMATCH).

Raises

Name	Type	Description
	ValueError	If from_graph=True but no bundle is available (neither passed nor set via set_bundle()).

Examples

Full stamp (default – from graph, all groups)::

>>> stamp = claim.get_matchstamp()  # uses claim's bundle
>>> stamp.n_timelines
23  # score + 22 performers at this coordinate

Reduced stamp (two timelines only)::

>>> stamp = claim.get_matchstamp(from_graph=False)
>>> stamp.n_timelines
2   # just the two timelines in this claim

implicit

alignment.MatchClaim.implicit(
    tl_a_id,
    coord_a,
    tl_b_id,
    coord_b,
    *,
    unit_a=None,
    unit_b=None,
    source_claim=None,
    metadata=None,
)

Case (d): Implicit claim generated by MatchGraph group extension.

Parameters

Name	Type	Description	Default
tl_a_id	str	First timeline’s ID.	required
coord_a	CoordinateSpec	Coordinate specification on timeline A.	required
tl_b_id	str	Second timeline’s ID.	required
coord_b	CoordinateSpec	Coordinate specification on timeline B.	required
unit_a	TimeUnit | str | None	Unit of timeline A’s coordinate.	None
unit_b	TimeUnit | str | None	Unit of timeline B’s coordinate.	None
source_claim	'MatchClaim | None'	The claim that generated this one.	None
metadata	MatchMetadata | None	Provenance information.	None

Returns

Name	Type	Description
	'MatchClaim'	A synchronous, non-explicit MatchClaim with one anchor.

nomatch

alignment.MatchClaim.nomatch(
    event,
    source_tl_id,
    target_tl_id,
    *,
    unit,
    metadata=None,
)

Case (c): An event has no equivalent on the other timeline.

Creates a non-synchronous claim with no anchors (NOMATCH sentinel).

Parameters

Name	Type	Description	Default
event	dict[str, Any]	Event dict from the source timeline. May contain id and name fields.	required
source_tl_id	str	Source timeline’s ID.	required
target_tl_id	str	Target timeline’s ID.	required
unit	TimeUnit | str	Unit of the source timeline’s coordinate.	required
metadata	MatchMetadata | None	Provenance information.	None

Returns

Name	Type	Description
	'MatchClaim'	A non-synchronous MatchClaim with no anchors but source event
	'MatchClaim'	info. The source-side coordinate (event["start"]) is
	'MatchClaim'	preserved as source_coordinate for display.

set_bundle

alignment.MatchClaim.set_bundle(bundle)

Associate this claim with an AlignmentBundle.

This is called automatically when claims are added to a bundle. Once set, get_matchstamp(from_graph=True) can be called without passing the bundle explicitly.

Parameters

Name	Type	Description	Default
bundle	Any	The AlignmentBundle containing this claim.	required

to_dict

alignment.MatchClaim.to_dict()

Serialize to dictionary for storage.

The values come straight from model_dump; only the key order and the omission of an absent source_claim_id are applied on top, since both are part of the stored shape.