treegraphduals 0.1.0__py3-none-any.whl

treegraphduals/__init__.py

@@ -0,0 +1,30 @@
+"""Trees, their duals, graphs, and time series.
+
+An extension of *The Horizontal Tunnelability Graph is Dual to Level Set Trees*
+(Khan, University of Nevada, Reno, 2023).
+
+The library is organized into subpackages, imported explicitly so that a bare
+``import treegraphduals`` stays free of plotting dependencies:
+
+- :mod:`treegraphduals.core` -- tree and graph data structures
+- :mod:`treegraphduals.timeseries` -- time series analysis and tree conversions
+- :mod:`treegraphduals.visualizations` -- plotting (requires matplotlib)
+
+Examples
+--------
+>>> from treegraphduals.core import Tree
+>>> tree = Tree(n_nodes=3, root=0)
+>>> tree.add_edge(0, 1)
+>>> tree.add_edge(0, 2)
+>>> tree.n_edges
+2
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("treegraphduals")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

treegraphduals/agents/__init__.py

@@ -0,0 +1,4 @@
+"""LangGraph-based tooling: verification assistant and experiment-exploration loop.
+
+Secondary to the core research; see the ``agents`` optional dependency group.
+"""

treegraphduals/core/__init__.py

@@ -0,0 +1,28 @@
+"""Core package initialization."""
+
+from .base_graph import BaseGraph, GraphRepresentation
+from .binary_tree import BinaryTree
+from .dag import DAG
+from .erdos_renyi import ErdosRenyi
+from .forest import Forest
+from .galton_watson import GaltonWatsonTree
+from .graph import Graph
+from .multigraph import Multigraph
+from .polytree import Polytree
+from .real_tree import RealTree
+from .tree import Tree
+
+__all__ = [
+    "DAG",
+    "BaseGraph",
+    "BinaryTree",
+    "ErdosRenyi",
+    "Forest",
+    "GaltonWatsonTree",
+    "Graph",
+    "GraphRepresentation",
+    "Multigraph",
+    "Polytree",
+    "RealTree",
+    "Tree",
+]

treegraphduals/core/base_graph.py

@@ -0,0 +1,303 @@
+"""
+Generic representation and base graph classes with multi-library compatibility.
+
+Supports NetworkX, igraph, numpy arrays, scipy sparse matrices, and other representations.
+BaseGraph(ABC)
+├── DAG
+│   └── Polytree
+├── Tree
+│   └── BinaryTree
+│       ├── GaltonWatsonTree
+│   └── Forest
+├── GeneralGraph
+│   ├── Multigraph
+│   └── ErdosRenyi
+└── RealTree (separate - different math)
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+import numpy as np
+
+
+class GraphRepresentation:
+    """
+    Lightweight internal representation of a graph.
+
+    Stores graph data in an efficient format and provides conversions
+    to networkx, igraph, and scipy graph libraries and various graph representations.
+    """
+
+    def __init__(self, n_nodes: int):
+        self.n_nodes = n_nodes
+        self.edges: list[tuple[int, int]] = []
+        self.edge_attrs: dict[tuple[int, int], dict[str, Any]] = {}
+        self.node_attrs: dict[int, dict[str, Any]] = {i: {} for i in range(n_nodes)}
+
+        # Cache for converted representations
+        self._networkx_cache = None
+        self._igraph_cache = None
+        self._adjacency_cache = None
+        self._dirty = False  # Track if graph has been modified
+
+    def add_edge(self, u: int, v: int, **attrs):
+        """Add an edge with optional attributes."""
+        edge = (u, v)
+        if edge not in self.edges:
+            self.edges.append(edge)
+        self.edge_attrs[edge] = attrs
+        self._invalidate_caches()
+
+    def add_node_attr(self, node: int, key: str, value: Any):
+        """Add attribute to a node."""
+        self.node_attrs[node][key] = value
+        self._invalidate_caches()
+
+    def _invalidate_caches(self):
+        """Invalidate cached representations when graph is modified."""
+        self._networkx_cache = None
+        self._igraph_cache = None
+        self._adjacency_cache = None
+        self._dirty = True
+
+    def to_networkx(self, directed: bool = True):
+        """Convert to NetworkX graph."""
+        if self._networkx_cache is not None and not self._dirty:
+            return self._networkx_cache
+
+        try:
+            import networkx as nx
+        except ImportError:
+            raise ImportError(
+                "NetworkX is required for this conversion. Install with: pip install networkx or per your package manager's syntax"
+            )
+
+        G = nx.DiGraph() if directed else nx.Graph()
+        G.add_nodes_from(range(self.n_nodes))
+
+        # Add node attributes
+        for node, attrs in self.node_attrs.items():
+            for key, value in attrs.items():
+                G.nodes[node][key] = value
+
+        # Add edges with attributes
+        for u, v in self.edges:
+            attrs = self.edge_attrs.get((u, v), {})
+            G.add_edge(u, v, **attrs)
+
+        self._networkx_cache = G
+        self._dirty = False
+        return G
+
+    def to_igraph(self, directed: bool = True):
+        """Convert to igraph graph."""
+        if self._igraph_cache is not None and not self._dirty:
+            return self._igraph_cache
+
+        try:
+            import igraph as ig
+        except ImportError:
+            raise ImportError(
+                "igraph is required for this conversion. Install with: pip install igraph or per your package manager's syntax"
+            )
+
+        g = ig.Graph(n=self.n_nodes, directed=directed)
+
+        # Add edges
+        if self.edges:
+            g.add_edges(self.edges)
+
+        # Add edge attributes
+        for edge_idx, (u, v) in enumerate(self.edges):
+            attrs = self.edge_attrs.get((u, v), {})
+            for key, value in attrs.items():
+                if key not in g.es.attributes():
+                    g.es[key] = [None] * g.ecount()
+                g.es[edge_idx][key] = value
+
+        # Add node attributes
+        for node, attrs in self.node_attrs.items():
+            for key, value in attrs.items():
+                if key not in g.vs.attributes():
+                    g.vs[key] = [None] * g.vcount()
+                g.vs[node][key] = value
+
+        self._igraph_cache = g
+        self._dirty = False
+        return g
+
+    def to_adjacency_matrix(
+        self, weighted: bool = False, weight_attr: str = "length"
+    ) -> np.ndarray:
+        """
+        Convert to adjacency matrix (numpy array).
+
+        Parameters
+        ----------
+        weighted : bool
+            If True, use edge weights. If False, binary adjacency.
+        weight_attr : str
+            Edge attribute to use for weights.
+        """
+        if not weighted and self._adjacency_cache is not None:
+            return self._adjacency_cache
+
+        adj = np.zeros((self.n_nodes, self.n_nodes))
+
+        for u, v in self.edges:
+            if weighted and weight_attr in self.edge_attrs.get((u, v), {}):
+                adj[u, v] = self.edge_attrs[(u, v)][weight_attr]
+            else:
+                adj[u, v] = 1
+
+        if not weighted:
+            self._adjacency_cache = adj
+
+        return adj
+
+    def to_sparse_matrix(self, weighted: bool = False, weight_attr: str = "length"):
+        """Convert to scipy sparse matrix (CSR format)."""
+        try:
+            from scipy.sparse import csr_matrix
+        except ImportError:
+            raise ImportError(
+                "scipy is required for sparse matrices. Install with: pip install scipy or per your package manager's syntax"
+            )
+
+        adj = self.to_adjacency_matrix(weighted=weighted, weight_attr=weight_attr)
+        return csr_matrix(adj)
+
+    @classmethod
+    def from_networkx(cls, G):
+        """Create from NetworkX graph."""
+        n_nodes = G.number_of_nodes()
+        graph_rep = cls(n_nodes)
+
+        # Add edges with attributes
+        for u, v, attrs in G.edges(data=True):
+            graph_rep.add_edge(u, v, **attrs)
+
+        # Add node attributes
+        for node, attrs in G.nodes(data=True):
+            for key, value in attrs.items():
+                graph_rep.add_node_attr(node, key, value)
+
+        return graph_rep
+
+    @classmethod
+    def from_igraph(cls, g):
+        """Create from igraph graph."""
+        n_nodes = g.vcount()
+        graph_rep = cls(n_nodes)
+
+        # Add edges with attributes
+        for edge in g.es:
+            u, v = edge.tuple
+            attrs = {key: edge[key] for key in edge.attributes()}
+            graph_rep.add_edge(u, v, **attrs)
+
+        # Add node attributes
+        for node_idx in range(n_nodes):
+            vertex = g.vs[node_idx]
+            for key in vertex.attributes():
+                graph_rep.add_node_attr(node_idx, key, vertex[key])
+
+        return graph_rep
+
+    @classmethod
+    def from_adjacency_matrix(cls, adj: np.ndarray, weighted: bool = False):
+        """Create from adjacency matrix."""
+        n_nodes = adj.shape[0]
+        graph_rep = cls(n_nodes)
+
+        rows, cols = np.nonzero(adj)
+        for u, v in zip(rows, cols):
+            if weighted:
+                graph_rep.add_edge(int(u), int(v), weight=float(adj[u, v]))
+            else:
+                graph_rep.add_edge(int(u), int(v))
+
+        return graph_rep
+
+
+class BaseGraph(ABC):
+    """
+    Abstract base class for all graph structures.
+
+    This provides a unified interface while maintaining compatibility
+    with multiple graph libraries.
+    """
+
+    def __init__(self, n_nodes: int = 0):
+        self._graph = GraphRepresentation(n_nodes)
+
+    @property
+    def n_nodes(self) -> int:
+        """Number of nodes in the graph."""
+        return self._graph.n_nodes
+
+    @property
+    def n_edges(self) -> int:
+        """Number of edges in the graph."""
+        return len(self._graph.edges)
+
+    def add_edge(self, u: int, v: int, **attrs):
+        """Add an edge with optional attributes."""
+        self._graph.add_edge(u, v, **attrs)
+
+    def add_node_attr(self, node: int, key: str, value: Any):
+        """Add attribute to a node."""
+        self._graph.add_node_attr(node, key, value)
+
+    # Conversion methods
+    def to_networkx(self, directed: bool = True):
+        """Export to NetworkX graph."""
+        return self._graph.to_networkx(directed=directed)
+
+    def to_igraph(self, directed: bool = True):
+        """Export to igraph graph."""
+        return self._graph.to_igraph(directed=directed)
+
+    def to_adjacency_matrix(
+        self, weighted: bool = False, weight_attr: str = "length"
+    ) -> np.ndarray:
+        """Export to numpy adjacency matrix."""
+        return self._graph.to_adjacency_matrix(
+            weighted=weighted, weight_attr=weight_attr
+        )
+
+    def to_sparse_matrix(self, weighted: bool = False, weight_attr: str = "length"):
+        """Export to scipy sparse matrix."""
+        return self._graph.to_sparse_matrix(weighted=weighted, weight_attr=weight_attr)
+
+    @classmethod
+    def from_networkx(cls, G):
+        """Create from NetworkX graph."""
+        instance = cls(G.number_of_nodes())
+        instance._graph = GraphRepresentation.from_networkx(G)
+        return instance
+
+    @classmethod
+    def from_igraph(cls, g):
+        """Create from igraph graph."""
+        instance = cls(g.vcount())
+        instance._graph = GraphRepresentation.from_igraph(g)
+        return instance
+
+    @classmethod
+    def from_adjacency_matrix(cls, adj: np.ndarray, weighted: bool = False):
+        """Create from adjacency matrix."""
+        instance = cls(adj.shape[0])
+        instance._graph = GraphRepresentation.from_adjacency_matrix(adj, weighted)
+        return instance
+
+    @abstractmethod
+    def validate(self) -> bool:
+        """Validate that the graph satisfies structural constraints."""
+
+    def __repr__(self):
+        """Return a summary of the graph's node and edge counts."""
+        return (
+            f"{self.__class__.__name__}(n_nodes={self.n_nodes}, n_edges={self.n_edges})"
+        )

treegraphduals/core/binary_tree.py

@@ -0,0 +1,286 @@
+"""
+Binary tree data structure with multi-library compatibility.
+
+Extends Tree with binary-specific constraints and operations.
+"""
+
+import numpy as np
+
+from .tree import Tree
+
+
+class BinaryTree(Tree):
+    """
+    Binary tree where each node has at most 2 children.
+
+    Maintains explicit left/right child tracking for binary-specific operations.
+    Also stores whether the tree is 'planted' (root has degree 1).
+    """
+
+    def __init__(self, n_nodes: int = 0, root: int | None = None, planted: bool = True):
+        super().__init__(n_nodes, root)
+
+        # Binary tree specific structures
+        self.left_child: np.ndarray = np.full(n_nodes, -1, dtype=np.int32)
+        self.right_child: np.ndarray = np.full(n_nodes, -1, dtype=np.int32)
+        self.planted = planted  # Whether root has degree 1
+
+    def add_edge(
+        self,
+        parent: int,
+        child: int,
+        side: str | None = None,
+        length: float = 1.0,
+        **attrs,
+    ):
+        """
+        Add an edge from parent to child.
+
+        Parameters
+        ----------
+        parent : int
+            Parent node index
+        child : int
+            Child node index
+        side : str, optional
+            'left' or 'right'. If None, will be determined automatically.
+        length : float
+            Edge length
+        **attrs
+            Additional edge attributes
+        """
+        # Validate binary constraint
+        if len(self.children[parent]) >= 2:
+            raise ValueError(
+                f"Node {parent} already has 2 children. Binary tree constraint violated."
+            )
+
+        # Determine side if not specified
+        if side is None:
+            if self.left_child[parent] == -1:
+                side = "left"
+            elif self.right_child[parent] == -1:
+                side = "right"
+            else:
+                raise ValueError(f"Node {parent} already has 2 children")
+
+        # Update left/right tracking
+        if side == "left":
+            if self.left_child[parent] != -1:
+                raise ValueError(f"Node {parent} already has a left child")
+            self.left_child[parent] = child
+        elif side == "right":
+            if self.right_child[parent] != -1:
+                raise ValueError(f"Node {parent} already has a right child")
+            self.right_child[parent] = child
+        else:
+            raise ValueError(f"side must be 'left' or 'right', got {side}")
+
+        # Call parent add_edge
+        super().add_edge(parent, child, length=length, **attrs)
+
+        # Store side as edge attribute
+        self._graph.edge_attrs[(parent, child)]["side"] = side
+
+    def get_left_child(self, node: int) -> int:
+        """Get left child of node. Returns -1 if no left child."""
+        return int(self.left_child[node])
+
+    def get_right_child(self, node: int) -> int:
+        """Get right child of node. Returns -1 if no right child."""
+        return int(self.right_child[node])
+
+    def is_left_child(self, node: int) -> bool:
+        """Check if node is a left child of its parent."""
+        if self.is_root(node):
+            return False
+        parent = self.parent[node]
+        return self.left_child[parent] == node
+
+    def is_right_child(self, node: int) -> bool:
+        """Check if node is a right child of its parent."""
+        if self.is_root(node):
+            return False
+        parent = self.parent[node]
+        return self.right_child[parent] == node
+
+    def get_sibling(self, node: int) -> int:
+        """Get sibling of node. Returns -1 if no sibling or node is root."""
+        if self.is_root(node):
+            return -1
+
+        parent = self.parent[node]
+        if self.is_left_child(node):
+            return self.right_child[parent]
+        else:
+            return self.left_child[parent]
+
+    def depth_first_search_lr(self, start: int | None = None) -> list[int]:
+        """
+        Depth-first search with explicit left-right ordering.
+
+        Returns nodes in order: leftmost leaf → root → rightmost leaf
+        (standard DFS for binary trees).
+        """
+        if start is None:
+            start = self.root
+
+        order = []
+
+        def dfs(node):
+            if node == -1:
+                return
+            dfs(self.left_child[node])
+            order.append(node)
+            dfs(self.right_child[node])
+
+        dfs(start)
+        return order
+
+    def get_leaves_lr(self) -> list[int]:
+        """Get leaves in left-to-right order."""
+        return [node for node in self.depth_first_search_lr() if self.is_leaf(node)]
+
+    def validate(self) -> bool:
+        """
+        Validate binary tree structure.
+
+        Checks Tree constraints plus:
+        - Each node has at most 2 children
+        - Left/right child arrays are consistent with children lists
+        """
+        # Check parent tree validation
+        if not super().validate():
+            return False
+
+        # Check binary constraint
+        for node in range(self.n_nodes):
+            if len(self.children[node]) > 2:
+                return False
+
+            # Check consistency of left/right with children list
+            left = self.left_child[node]
+            right = self.right_child[node]
+            children_set = set(self.children[node])
+
+            expected_children = set()
+            if left != -1:
+                expected_children.add(left)
+            if right != -1:
+                expected_children.add(right)
+
+            if children_set != expected_children:
+                return False
+
+        return True
+
+    @classmethod
+    def from_parent_array(
+        cls,
+        parent_array: np.ndarray,
+        edge_lengths: np.ndarray | None = None,
+        left_right_order: list[tuple[int, str]] | None = None,
+        root: int | None = None,
+        planted: bool = True,
+    ) -> "BinaryTree":
+        """
+        Create binary tree from parent array.
+
+        Parameters
+        ----------
+        parent_array : np.ndarray
+            Parent array where parent_array[i] is parent of node i
+        edge_lengths : np.ndarray, optional
+            Edge lengths
+        left_right_order : List[Tuple[int, str]], optional
+            List of (node, side) tuples specifying whether each child is 'left' or 'right'.
+            If None, will assign left/right based on index order.
+        root : int, optional
+            Root node index
+        planted : bool
+            Whether the tree is planted (root has degree 1)
+
+        Returns
+        -------
+        BinaryTree instance
+        """
+        n_nodes = len(parent_array)
+
+        # Find root if not specified
+        if root is None:
+            root_candidates = np.where(
+                (parent_array == -1) | (parent_array == np.arange(n_nodes))
+            )[0]
+            if len(root_candidates) == 0:
+                raise ValueError("No root found in parent array")
+            root = int(root_candidates[0])
+
+        tree = cls(n_nodes=n_nodes, root=root, planted=planted)
+
+        # Build mapping of which children are left/right
+        if left_right_order is None:
+            # Default: first child is left, second is right (by index)
+            parent_children = {i: [] for i in range(n_nodes)}
+            for child in range(n_nodes):
+                if child != root and parent_array[child] != child:
+                    parent = int(parent_array[child])
+                    parent_children[parent].append(child)
+
+            # Sort children by index for consistent left/right assignment
+            for children in parent_children.values():
+                children.sort()
+
+        # Add edges
+        for child in range(n_nodes):
+            if child != root and parent_array[child] != child:
+                parent = int(parent_array[child])
+                length = 1.0 if edge_lengths is None else float(edge_lengths[child])
+
+                # Determine side
+                if left_right_order is not None:
+                    # Use provided left/right info
+                    side = next((s for n, s in left_right_order if n == child), None)
+                    if side is None:
+                        # Guess based on existing children
+                        side = "left" if tree.left_child[parent] == -1 else "right"
+                else:
+                    # Use index-based ordering
+                    children_of_parent = parent_children[parent]
+                    idx = children_of_parent.index(child)
+                    side = "left" if idx == 0 else "right"
+
+                tree.add_edge(parent, child, side=side, length=length)
+
+        return tree
+
+    def to_parent_array_with_sides(
+        self,
+    ) -> tuple[np.ndarray, np.ndarray, list[tuple[int, str]]]:
+        """
+        Export as parent array with left/right information.
+
+        Returns
+        -------
+        parent_array : np.ndarray
+        edge_lengths : np.ndarray
+        left_right_info : List[Tuple[int, str]]
+            List of (node, side) tuples
+        """
+        parent_arr, lengths = super().to_parent_array()
+
+        left_right_info = []
+        for node in range(self.n_nodes):
+            if not self.is_root(node):
+                side = "left" if self.is_left_child(node) else "right"
+                left_right_info.append((node, side))
+
+        return parent_arr, lengths, left_right_info
+
+    def __repr__(self):
+        """Return a summary of the tree's size, leaf count, depth, and plantedness."""
+        leaves = len(self.get_leaves())
+        max_depth = np.max(self.get_depth()) if self.n_nodes > 0 else 0
+        return (
+            f"BinaryTree(n_nodes={self.n_nodes}, n_leaves={leaves}, "
+            f"max_depth={max_depth}, planted={self.planted})"
+        )