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 nodes connected to a given node. |
| get_connected_timelines | Get all timelines connected to a given timeline. |
| get_coordinates_for_timeline | Get all coordinates for a specific timeline. |
| get_matchstamp | Get the single MatchStamp for this graph. |
| get_nodes_for_timeline | Get all 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 nodes connected to a given node.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| node | GraphNode |
The (timeline_id, coordinate) node. | required |
Returns
| Name | Type | Description |
|---|---|---|
list[GraphNode] |
List of connected nodes. |
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_coordinates_for_timeline
alignment.MatchGraph.get_coordinates_for_timeline(timeline_id)Get all coordinates for a specific timeline.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| timeline_id | str |
The timeline to get coordinates for. | required |
Returns
| Name | Type | Description |
|---|---|---|
list[float] |
List of coordinates, sorted. |
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 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[GraphNode] |
List of (timeline_id, coordinate) nodes. |
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.