MatchGraph

alignment.MatchGraph(
    claims=None,
    *,
    units=None,
    axis=None,
    source=None,
    source_id=None,
)

A graph of MatchClaims connecting events across timelines/groups.

The MatchGraph builds a networkx graph where: - Nodes: (timeline_id, coordinate) tuples - Edges: synchronous AlignmentAnchors (explicit or implicit)

Only synchronous claims produce graph edges. Non-synchronous claims (conceptual matches, NOMATCH) are stored in _claims but do not create nodes or edges.

Each Hendrix M-box (M1–M15) is a separate MatchGraph. The system is NOT a global graph; MatchGraphs are created on demand.

Attributes

Name	Type	Description
claims	list[MatchClaim]	List of all MatchClaims in this graph (synchronous and non-synchronous).

Examples

>>> # Build graph from claims
>>> graph = MatchGraph(claims=[claim1, claim2])

>>> # Extend via group membership
>>> extended = graph.extend_to_groups(groups, timeline_to_group)

>>> # Get synchronized timestamps
>>> stamps = graph.get_stamps()

Methods

Name	Description
extend_to_groups	Extend anchors to full group timestamps via implicit claims.
filter	Create filtered view of the graph.
from_dict	Deserialize from dictionary.
get_connected_nodes	Get all public nodes connected to a given node.
get_connected_timelines	Get all timelines connected to a given timeline.
get_coordinate	Dispatch a scalar or plural exact graph-position query.
get_coordinate_at	Resolve one exact graph node to a target component coordinate.
get_coordinates_at	Resolve exact graph nodes for a coordinate collection.
get_coordinates_for	Return the sorted graph coordinate column for one timeline.
get_matchstamp	Get the single MatchStamp for this graph.
get_nodes_for_timeline	Get all public graph nodes for a specific timeline.
get_stamps	Get all MatchStamps from the graph.
split_components	Split this graph into one MatchGraph per connected component.
to_dict	Serialize to dictionary.

extend_to_groups

alignment.MatchGraph.extend_to_groups(
    groups,
    timeline_to_group,
    include_inferred=True,
    *,
    timeline_ids=None,
    id_pattern=None,
    include_domains=None,
    include_units=None,
)

Extend anchors to full group timestamps via implicit claims.

For each coordinate in the graph, if it belongs to a Group, computes the equivalent coordinate for every other member of that Group and adds an implicit MatchClaim (case d) plus the corresponding edge. Filters control which timelines receive implicit claims.

Parameters

Name	Type	Description	Default
groups	dict[str, 'TimelineGroup']	Dict of group_id -> TimelineGroup.	required
timeline_to_group	dict[str, str]	Dict of timeline_id -> group_id.	required
include_inferred	bool	Whether to add inferred edges.	True
timeline_ids	set[str] | None	Only extend to these timeline IDs.	None
id_pattern	str | None	Regex filter for timeline IDs.	None
include_domains	set[Domain] | None	Only extend to timelines in these domains.	None
include_units	set[TimeUnit] | None	Only extend to timelines with these units.	None

Returns

Name	Type	Description
	'MatchGraph'	New MatchGraph with extended edges (or self if not extending).

filter

alignment.MatchGraph.filter(
    synchronous_only=False,
    explicit_only=False,
    *,
    timeline_ids=None,
    id_pattern=None,
    include_domains=None,
    include_units=None,
)

Create filtered view of the graph.

Parameters

Name	Type	Description	Default
synchronous_only	bool	Include only synchronous edges.	False
explicit_only	bool	Include only explicit edges (no inferred).	False
timeline_ids	set[str] | None	Only include these timeline IDs.	None
id_pattern	str | None	Regex filter for timeline IDs.	None
include_domains	set[Domain] | None	Only include timelines in these domains.	None
include_units	set[TimeUnit] | None	Only include timelines with these units.	None

Returns

Name	Type	Description
	'MatchGraph'	New MatchGraph with filtered edges/nodes.

from_dict

alignment.MatchGraph.from_dict(data)

Deserialize from dictionary.

get_connected_nodes

alignment.MatchGraph.get_connected_nodes(node)

Get all public nodes connected to a given node.

Parameters

Name	Type	Description	Default
node	IdCoordinate	Canonical identified graph coordinate.	required

Returns

Name	Type	Description
	list[IdCoordinate]	Canonical identified neighboring coordinates.

Raises

Name	Type	Description
	TypeError	If node is not an IdCoordinate.
	ValueError	If its unit is not native to its timeline.

get_connected_timelines

alignment.MatchGraph.get_connected_timelines(timeline_id)

Get all timelines connected to a given timeline.

Parameters

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

Returns

Name	Type	Description
	set[str]	Set of connected timeline IDs.

get_coordinate

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

Dispatch a scalar or plural exact graph-position query.

Parameters

Name	Type	Description	Default
at	CoordinateInput | CoordinateCollection	One graph position or a coordinate collection.	required
timeline_id	str | None	Requested result timeline when required.	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_at

alignment.MatchGraph.get_coordinate_at(
    at,
    timeline_id=None,
    *,
    format='id_coordinate',
    rounding='round',
)

Resolve one exact graph node to a target component coordinate.

Parameters

Name	Type	Description	Default
at	CoordinateInput	Exact graph-node position.	required
timeline_id	str | None	Requested result timeline, or the unique other node.	None
format	CoordinateFormat	Requested coordinate output format.	'id_coordinate'
rounding	Rounding	Integral projection mode.	'round'

Returns

Name	Type	Description
	CoordinateResult | pd.Series	One exact connected-coordinate projection or a length-one Series.

get_coordinates_at

alignment.MatchGraph.get_coordinates_at(
    at,
    timeline_id=None,
    *,
    format='id_coordinate',
    rounding='round',
)

Resolve exact graph nodes for a coordinate collection.

Parameters

Name	Type	Description	Default
at	CoordinateCollection	Exact graph-node positions to resolve atomically.	required
timeline_id	str | None	Requested result timeline.	None
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_coordinates_for

alignment.MatchGraph.get_coordinates_for(
    timeline_id,
    *,
    format='id_coordinate',
    rounding='round',
)

Return the sorted graph coordinate column for one 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
	list[CoordinateResult] | pd.Series	Typed coordinate projections in sorted order.

get_matchstamp

alignment.MatchGraph.get_matchstamp()

Get the single MatchStamp for this graph.

One MatchGraph = one MatchStamp. The MatchStamp is the union of all coordinates reachable through the graph’s edges.

If the graph contains multiple disconnected components, this method raises ValueError – each component should be its own MatchGraph. Use split_components() to separate them first, or use the multi-component get_stamps() method.

Returns

Name	Type	Description
	'MatchStamp'	Single MatchStamp spanning all timelines in the graph.

Raises

Name	Type	Description
	ValueError	If the graph has multiple disconnected components.
	ValueError	If the graph has no synchronous claims (no nodes).

See Also

split_components: Split a multi-component graph into separate MatchGraph objects. get_stamps: Multi-component method returning one stamp per component.

get_nodes_for_timeline

alignment.MatchGraph.get_nodes_for_timeline(timeline_id)

Get all public graph nodes for a specific timeline.

Parameters

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

Returns

Name	Type	Description
	list[IdCoordinate]	Canonical identified coordinates in graph insertion order.

Raises

Name	Type	Description
	TypeError	If timeline_id is not a string.
	KeyError	If the timeline is unknown.

get_stamps

alignment.MatchGraph.get_stamps()

Get all MatchStamps from the graph.

Returns one MatchStamp per connected component, each containing all coordinates reachable from that component.

Returns: List of MatchStamps, one per connected component.

split_components

alignment.MatchGraph.split_components()

Split this graph into one MatchGraph per connected component.

Each returned MatchGraph represents a single connected component and can be queried with get_matchstamp().

Returns

Name	Type	Description
	list['MatchGraph']	List of MatchGraph objects, one per connected component.
	list['MatchGraph']	Empty list if the graph has no synchronous claims.

to_dict

alignment.MatchGraph.to_dict()

Serialize to dictionary.

Note: This serializes the claims, not the full graph. The graph can be rebuilt from claims.