MatchGraph

MatchGraph(claims=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: claims: 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()

>>> # Legacy API (deprecated)
>>> start_stamp, end_stamp = graph.get_match_stamps()

Attributes

Name	Description
claims	List of all MatchClaims in this graph (synchronous and non-synchronous).
n_claims	Number of claims in this graph.
n_components	Number of connected components in the graph.
n_edges	Number of edges in the graph.
n_nodes	Number of nodes in the graph.
non_synchronous_claims	List of non-synchronous MatchClaims (NOMATCH, conceptual).
synchronous_claims	List of only synchronous MatchClaims (those with anchors/edges).
timeline_ids	Set of all timeline IDs in the graph.

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_all_stamps	Get all unique MatchStamps from the graph.
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_match_stamps	Extract MatchStamps from the graph.
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

MatchGraph.extend_to_groups(
    groups,
    timeline_to_group,
    include_inferred=True,
    *,
    timelines=None,
    include_timelines=None,
    exclude_timelines=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.

Args: groups: Dict of group_id -> TimelineGroup. timeline_to_group: Dict of timeline_id -> group_id. include_inferred: Whether to add inferred edges. timelines: Optional dict of timeline_id -> Timeline for resolving domain/unit filters. Required if include_domains or include_units are set. include_timelines: Only extend to these timeline IDs. exclude_timelines: Do not extend to these timeline IDs. include_domains: Only extend to timelines in these domains. Requires timelines parameter. include_units: Only extend to timelines with these units. Requires timelines parameter.

Returns: New MatchGraph with extended edges (or self if not extending).

filter

MatchGraph.filter(
    synchronous_only=False,
    explicit_only=False,
    include_timelines=None,
    exclude_timelines=None,
    include_domains=None,
    include_units=None,
    *,
    timelines=None,
)

Create filtered view of the graph.

Args: synchronous_only: Include only synchronous edges. explicit_only: Include only explicit edges (no inferred). include_timelines: Only include these timeline IDs. exclude_timelines: Exclude these timeline IDs. include_domains: Only include timelines in these domains. Requires timelines parameter. include_units: Only include timelines with these units. Requires timelines parameter. timelines: Dict of timeline_id -> Timeline for resolving domain/unit filters.

Returns: New MatchGraph with filtered edges/nodes.

from_dict

MatchGraph.from_dict(data)

Deserialize from dictionary.

get_all_stamps

MatchGraph.get_all_stamps()

Get all unique MatchStamps from the graph.

.. deprecated:: Use get_stamps() instead. This is an alias retained for backward compatibility.

Returns: List of MatchStamps, one per connected component.

get_connected_nodes

MatchGraph.get_connected_nodes(node)

Get all nodes connected to a given node.

Args: node: The (timeline_id, coordinate) node.

Returns: List of connected nodes.

get_connected_timelines

MatchGraph.get_connected_timelines(timeline_id)

Get all timelines connected to a given timeline.

Args: timeline_id: The timeline to check.

Returns: Set of connected timeline IDs.

get_coordinates_for_timeline

MatchGraph.get_coordinates_for_timeline(timeline_id)

Get all coordinates for a specific timeline.

Args: timeline_id: The timeline to get coordinates for.

Returns: List of coordinates, sorted.

get_match_stamps

MatchGraph.get_match_stamps()

Extract MatchStamps from the graph.

.. deprecated:: Use get_stamps() for all MatchStamps by connected component. This method is retained for backward compatibility.

Returns: (start_stamp, end_stamp) - end_stamp is None for instant matches.

Note: For a graph built from multiple interval claims, this returns stamps for the first synchronous claim’s coordinates. Use get_stamps() for all unique timestamps.

get_matchstamp

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 legacy get_stamps() method.

Returns: Single MatchStamp spanning all timelines in the graph.

Raises: 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: Legacy method returning one stamp per component.

get_nodes_for_timeline

MatchGraph.get_nodes_for_timeline(timeline_id)

Get all nodes for a specific timeline.

Args: timeline_id: The timeline to get nodes for.

Returns: List of (timeline_id, coordinate) nodes.

get_stamps

MatchGraph.get_stamps(expand_groups=False, expand_cmaps=False)

Get all MatchStamps from the graph.

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

Args: expand_groups: If True, for each coordinate in a stamp that belongs to a Group, add within-group coordinates for all other members. (Requires extend_to_groups() to have been called first, or group information to be present in the graph.) expand_cmaps: If True, add C-map conversion results to the stamp. (Reserved for future use.)

Returns: List of MatchStamps, one per connected component.

split_components

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: List of MatchGraph objects, one per connected component. Empty list if the graph has no synchronous claims.

to_dict

MatchGraph.to_dict()

Serialize to dictionary.

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