MatchClaim

MatchClaim(
    timeline_a_id,
    timeline_b_id,
    start_anchor=None,
    end_anchor=None,
    is_synchronous=True,
    is_explicit=True,
    metadata=None,
    source_claim_id=None,
    id='',
    _bundle=None,
)

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: (a) from_events: Two timed things on different timelines correspond. (b) from_projection: An event is projected onto a timeline with no matching event. (c) nomatch: An event has no equivalent on the other timeline. (d) implicit: Implicit claim generated by MatchGraph group extension.

Attributes: timeline_a_id: First timeline’s unique identifier. timeline_b_id: Second timeline’s unique identifier. start_anchor: AlignmentAnchor for event starts (None for non-synchronous). end_anchor: AlignmentAnchor for event ends (None for instants or non-synchronous claims). is_synchronous: True if temporally synchronous matches. is_explicit: True if directly claimed, False if inferred. metadata: Provenance information (agent, criteria, certainty). source_claim_id: For implicit claims, the ID of the claim that generated this one. id: Unique identifier for this claim.

Examples: >>> # Synchronous instant match via factory >>> claim = MatchClaim.from_events( … event_a={“start”: 100.0}, … tl_a_id=“score:1”, … event_b={“start”: 45.5}, … tl_b_id=“recording:1”, … )

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

Attributes

Name	Description
anchors	Get all anchors in this claim (0, 1, or 2).
bundle	The AlignmentBundle this claim belongs to, if set.
is_interval	Whether this is an interval match (has end anchor).
timelines	Return tuple of timeline IDs.

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.
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

MatchClaim.connects(timeline_id)

Check if this claim connects to a specific timeline.

Args: timeline_id: The timeline to check.

Returns: True if the claim involves this timeline.

connects_both

MatchClaim.connects_both(timeline_a_id, timeline_b_id)

Check if this claim connects two specific timelines.

Args: timeline_a_id: First timeline. timeline_b_id: Second timeline.

Returns: True if the claim connects exactly these two timelines.

from_dict

MatchClaim.from_dict(data)

Deserialize from dictionary.

from_events

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

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

Args: event_a: Event dict from timeline A (must contain coord_key). tl_a_id: Timeline A’s ID. event_b: Event dict from timeline B (must contain coord_key). tl_b_id: Timeline B’s ID. coord_key: Key for start coordinate in event dicts. end_coord_key: Key for end coordinate (creates interval match). is_synchronous: Whether events are temporally synchronous. metadata: Provenance information.

Returns: A synchronous MatchClaim with 1 or 2 anchors.

from_projection

MatchClaim.from_projection(
    event,
    source_tl_id,
    target_tl_id,
    target_coord,
    *,
    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).

Args: event: Event dict from the source timeline. source_tl_id: Source timeline’s ID. target_tl_id: Target timeline’s ID. target_coord: Projected coordinate on the target timeline. coord_key: Key for start coordinate in event dict. target_end_coord: Projected end coordinate (creates interval match). end_coord_key: Key for end coordinate in event dict. metadata: Provenance information.

Returns: A synchronous MatchClaim with 1 or 2 anchors.

get_coordinates_for

MatchClaim.get_coordinates_for(timeline_id)

Get start and end coordinates for a specific timeline.

Args: timeline_id: The timeline to get coordinates for.

Returns: Tuple of (start_coord, end_coord). end_coord is None for instants.

Raises: ValueError: If timeline is not in this claim or claim has no anchors.

get_matchstamp

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

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).

Args: bundle: The AlignmentBundle containing this claim. Required for from_graph=True. Provides group info and the MatchGraph cache. from_graph: 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. conversion_maps: Include C-map conversions (reserved for future use).

Returns: MatchStamp with coordinates, or None if this claim is non-synchronous (NOMATCH).

Raises: 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

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

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

Args: tl_a_id: First timeline’s ID. coord_a: Coordinate on timeline A. tl_b_id: Second timeline’s ID. coord_b: Coordinate on timeline B. source_claim: The claim that generated this one. metadata: Provenance information.

Returns: A synchronous, non-explicit MatchClaim with one anchor.

nomatch

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

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

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

Args: event: Event dict from the source timeline. source_tl_id: Source timeline’s ID. target_tl_id: Target timeline’s ID. metadata: Provenance information.

Returns: A non-synchronous MatchClaim with no anchors.

set_bundle

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.

Args: bundle: The AlignmentBundle containing this claim.

to_dict

MatchClaim.to_dict()

Serialize to dictionary for storage.