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

from_events: Two timed things on different timelines correspond.
from_projection: An event is projected onto a timeline with no matching event.
nomatch: An event has no equivalent on the other timeline.
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_coordinate	Dispatch a singular or plural timeline-key claim query.
get_coordinate_for	Return the start anchor coordinate for one member timeline.
get_coordinates_for	Return start-anchor coordinates for timeline identities.
get_interval_for	Return the asserted interval for one member 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_coordinate

alignment.MatchClaim.get_coordinate(
    at,
    timeline_id=None,
    *,
    format='id_coordinate',
    rounding='round',
)

Dispatch a singular or plural timeline-key claim query.

Parameters

Name	Type	Description	Default
at	`str` \| `KeyCollection`	One member timeline ID or a collection of member IDs.	required
timeline_id	None	Must be `None` because `at` carries the keys.	`None`
format	`CoordinateFormat`	Requested coordinate output format.	`'id_coordinate'`
rounding	`Rounding`	Integral projection mode.	`'round'`

Returns

Name	Type	Description
	`CoordinateResult` \| `list`[`CoordinateResult`] \| `pd`.`Series`	The selected precise-getter result.

get_coordinate_for

alignment.MatchClaim.get_coordinate_for(
    timeline_id,
    *,
    format='id_coordinate',
    rounding='round',
)

Return the start anchor coordinate for one member timeline.

Parameters

Name	Type	Description	Default
timeline_id	`str`	The timeline to get coordinates for.	required
format	`CoordinateFormat`	Requested coordinate output format.	`'id_coordinate'`
rounding	`Rounding`	Integral projection mode.	`'round'`

Returns

Name	Type	Description
	`CoordinateResult` \| `pd`.`Series`	The requested start-coordinate projection.

Raises

Name	Type	Description
	`ValueError`	If the claim is non-synchronous.
	`KeyError`	If the timeline is not in this claim.

get_coordinates_for

alignment.MatchClaim.get_coordinates_for(
    timeline_ids,
    *,
    format='id_coordinate',
    rounding='round',
)

Return start-anchor coordinates for timeline identities.

Parameters

Name	Type	Description	Default
timeline_ids	`KeyCollection`	Member timeline IDs in retrieval order.	required
format	`CoordinateFormat`	Requested coordinate output format.	`'id_coordinate'`
rounding	`Rounding`	Integral projection mode.	`'round'`

Returns

Name	Type	Description
	`list`[`CoordinateResult`] \| `pd`.`Series`	A list of projections or canonical-value Series.

get_interval_for

alignment.MatchClaim.get_interval_for(timeline_id)

Return the asserted interval for one member timeline.

Parameters

Name	Type	Description	Default
timeline_id	`str`	Member timeline ID.	required

Returns

Name	Type	Description
	`Interval`	The typed asserted interval.

Raises

Name	Type	Description
	`ValueError`	If the claim is non-synchronous or instantaneous.
	`KeyError`	If the timeline is not in the claim.

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.