napistu 0.2.5.dev7__py3-none-any.whl → 0.3.1__py3-none-any.whl

napistu/network/ig_utils.py

@@ -0,0 +1,351 @@
+"""
+General utilities for working with igraph.Graph objects.
+
+This module contains utilities that can be broadly applied to any igraph.Graph
+object, not specific to NapistuGraph subclasses.
+"""
+
+from __future__ import annotations
+
+import logging
+import random
+from typing import Any, Optional, Sequence
+
+import igraph as ig
+import numpy as np
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+
+def get_graph_summary(graph: ig.Graph) -> dict[str, Any]:
+    """
+    Calculate common summary statistics for an igraph network.
+
+    Parameters
+    ----------
+    graph : ig.Graph
+        The input network.
+
+    Returns
+    -------
+    dict
+        A dictionary of summary statistics with the following keys:
+        - n_edges (int): number of edges
+        - n_vertices (int): number of vertices
+        - n_components (int): number of weakly connected components
+        - stats_component_sizes (dict): summary statistics for the component sizes
+        - top10_large_components (list[dict]): the top 10 largest components with 10 example vertices
+        - top10_smallest_components (list[dict]): the top 10 smallest components with 10 example vertices
+        - average_path_length (float): the average shortest path length between all vertices
+        - top10_betweenness (list[dict]): the top 10 vertices by betweenness centrality
+        - top10_harmonic_centrality (list[dict]): the top 10 vertices by harmonic centrality
+    """
+    stats = {}
+    stats["n_edges"] = graph.ecount()
+    stats["n_vertices"] = graph.vcount()
+    components = graph.components(mode="weak")
+    stats["n_components"] = len(components)
+    component_sizes = [len(c) for c in components]
+    stats["stats_component_sizes"] = pd.Series(component_sizes).describe().to_dict()
+
+    # get the top 10 largest components and 10 example nodes
+    stats["top10_large_components"] = _get_top_n_component_stats(
+        graph, components, component_sizes, n=10, ascending=False
+    )
+    stats["top10_smallest_components"] = _get_top_n_component_stats(
+        graph, components, component_sizes, n=10, ascending=True
+    )
+
+    stats["average_path_length"] = graph.average_path_length()
+
+    # Top 10 by betweenness and harmonic centrality
+    betweenness = graph.betweenness()
+    stats["top10_betweenness"] = _get_top_n_nodes(
+        graph, betweenness, "betweenness", n=10
+    )
+    harmonic = graph.harmonic_centrality()
+    stats["top10_harmonic_centrality"] = _get_top_n_nodes(
+        graph, harmonic, "harmonic_centrality", n=10
+    )
+
+    return stats
+
+
+def filter_to_largest_subgraph(graph: ig.Graph) -> ig.Graph:
+    """
+    Filter an igraph to its largest weakly connected component.
+
+    Parameters
+    ----------
+    graph : ig.Graph
+        The input network.
+
+    Returns
+    -------
+    ig.Graph
+        The largest weakly connected component.
+    """
+    component_members = graph.components(mode="weak")
+    component_sizes = [len(x) for x in component_members]
+
+    top_component_members = [
+        m
+        for s, m in zip(component_sizes, component_members)
+        if s == max(component_sizes)
+    ][0]
+
+    largest_subgraph = graph.induced_subgraph(top_component_members)
+    return largest_subgraph
+
+
+def graph_to_pandas_dfs(graph: ig.Graph) -> tuple[pd.DataFrame, pd.DataFrame]:
+    """
+    Convert an igraph to Pandas DataFrames for vertices and edges.
+
+    Parameters
+    ----------
+    graph : ig.Graph
+        An igraph network.
+
+    Returns
+    -------
+    vertices : pandas.DataFrame
+        A table with one row per vertex.
+    edges : pandas.DataFrame
+        A table with one row per edge.
+    """
+    vertices = pd.DataFrame(
+        [{**{"index": v.index}, **v.attributes()} for v in graph.vs]
+    )
+    edges = pd.DataFrame(
+        [
+            {**{"source": e.source, "target": e.target}, **e.attributes()}
+            for e in graph.es
+        ]
+    )
+    return vertices, edges
+
+
+def create_induced_subgraph(
+    graph: ig.Graph,
+    vertices: Optional[list[str]] = None,
+    n_vertices: int = 5000,
+) -> ig.Graph:
+    """
+    Create a subgraph from an igraph including a set of vertices and their connections.
+
+    Parameters
+    ----------
+    graph : ig.Graph
+        The input network.
+    vertices : list, optional
+        List of vertex names to include. If None, a random sample is selected.
+    n_vertices : int, optional
+        Number of vertices to sample if `vertices` is None. Default is 5000.
+
+    Returns
+    -------
+    ig.Graph
+        The induced subgraph.
+    """
+    if vertices is not None:
+        selected_vertices = vertices
+    else:
+        # Assume vertices have a 'name' attribute, fallback to indices
+        if "name" in graph.vs.attributes():
+            vertex_names = graph.vs["name"]
+        else:
+            vertex_names = list(range(graph.vcount()))
+        selected_vertices = random.sample(
+            vertex_names, min(n_vertices, len(vertex_names))
+        )
+
+    subgraph = graph.induced_subgraph(selected_vertices)
+    return subgraph
+
+
+def validate_edge_attributes(graph: ig.Graph, edge_attributes: list[str]) -> None:
+    """
+    Validate that all required edge attributes exist in an igraph.
+
+    Parameters
+    ----------
+    graph : ig.Graph
+        The network.
+    edge_attributes : list of str
+        List of edge attribute names to check.
+
+    Returns
+    -------
+    None
+
+    Raises
+    ------
+    TypeError
+        If "edge_attributes" is not a list or str.
+    ValueError
+        If any required edge attribute is missing from the graph.
+    """
+    if isinstance(edge_attributes, list):
+        attrs = edge_attributes
+    elif isinstance(edge_attributes, str):
+        attrs = [edge_attributes]
+    else:
+        raise TypeError('"edge_attributes" must be a list or str')
+
+    available_attributes = graph.es[0].attributes().keys() if graph.ecount() > 0 else []
+    missing_attributes = set(attrs).difference(available_attributes)
+    n_missing_attrs = len(missing_attributes)
+
+    if n_missing_attrs > 0:
+        raise ValueError(
+            f"{n_missing_attrs} edge attributes were missing ({', '.join(missing_attributes)}). "
+            f"The available edge attributes are {', '.join(available_attributes)}"
+        )
+
+    return None
+
+
+def validate_vertex_attributes(graph: ig.Graph, vertex_attributes: list[str]) -> None:
+    """
+    Validate that all required vertex attributes exist in an igraph.
+
+    Parameters
+    ----------
+    graph : ig.Graph
+        The network.
+    vertex_attributes : list of str
+        List of vertex attribute names to check.
+
+    Returns
+    -------
+    None
+
+    Raises
+    ------
+    TypeError
+        If "vertex_attributes" is not a list or str.
+    ValueError
+        If any required vertex attribute is missing from the graph.
+    """
+    if isinstance(vertex_attributes, list):
+        attrs = vertex_attributes
+    elif isinstance(vertex_attributes, str):
+        attrs = [vertex_attributes]
+    else:
+        raise TypeError('"vertex_attributes" must be a list or str')
+
+    available_attributes = graph.vs[0].attributes().keys() if graph.vcount() > 0 else []
+    missing_attributes = set(attrs).difference(available_attributes)
+    n_missing_attrs = len(missing_attributes)
+
+    if n_missing_attrs > 0:
+        raise ValueError(
+            f"{n_missing_attrs} vertex attributes were missing ({', '.join(missing_attributes)}). "
+            f"The available vertex attributes are {', '.join(available_attributes)}"
+        )
+
+    return None
+
+
+# Internal utility functions
+
+
+def _get_top_n_idx(arr: Sequence, n: int, ascending: bool = False) -> Sequence[int]:
+    """Returns the indices of the top n values in an array
+
+    Args:
+        arr (Sequence): An array of values
+        n (int): The number of top values to return
+        ascending (bool, optional): Whether to return the top or bottom n values. Defaults to False.
+
+    Returns:
+        Sequence[int]: The indices of the top n values
+    """
+    order = np.argsort(arr)
+    if ascending:
+        return order[:n]  # type: ignore
+    else:
+        return order[-n:][::-1]  # type: ignore
+
+
+def _get_top_n_objects(
+    object_vals: Sequence, objects: Sequence, n: int = 10, ascending: bool = False
+) -> list:
+    """Get the top N objects based on a ranking measure."""
+    idxs = _get_top_n_idx(object_vals, n, ascending=ascending)
+    top_objects = [objects[idx] for idx in idxs]
+    return top_objects
+
+
+def _get_top_n_component_stats(
+    graph: ig.Graph,
+    components,
+    component_sizes: Sequence[int],
+    n: int = 10,
+    ascending: bool = False,
+) -> list[dict[str, Any]]:
+    """
+    Summarize the top N components' network properties.
+
+    Parameters
+    ----------
+    graph : ig.Graph
+        The network.
+    components : list
+        List of components (as lists of vertex indices).
+    component_sizes : Sequence[int]
+        Sizes of each component.
+    n : int, optional
+        Number of top components to return. Default is 10.
+    ascending : bool, optional
+        If True, return smallest components; otherwise, largest. Default is False.
+
+    Returns
+    -------
+    list of dict
+        Each dict contains:
+        - 'n': size of the component
+        - 'examples': up to 10 example vertex attribute dicts from the component
+    """
+    top_components = _get_top_n_objects(component_sizes, components, n, ascending)
+    top_component_stats = [
+        {"n": len(c), "examples": [graph.vs[n].attributes() for n in c[:10]]}
+        for c in top_components
+    ]
+    return top_component_stats
+
+
+def _get_top_n_nodes(
+    graph: ig.Graph,
+    vals: Sequence,
+    val_name: str,
+    n: int = 10,
+    ascending: bool = False,
+) -> list[dict[str, Any]]:
+    """
+    Get the top N nodes by a node attribute.
+
+    Parameters
+    ----------
+    graph : ig.Graph
+        The network.
+    vals : Sequence
+        Sequence of node attribute values.
+    val_name : str
+        Name of the attribute.
+    n : int, optional
+        Number of top nodes to return. Default is 10.
+    ascending : bool, optional
+        If True, return nodes with smallest values; otherwise, largest. Default is False.
+
+    Returns
+    -------
+    list of dict
+        Each dict contains the value and the node's attributes.
+    """
+    top_idxs = _get_top_n_idx(vals, n, ascending=ascending)
+    top_node_attrs = [graph.vs[idx].attributes() for idx in top_idxs]
+    top_vals = [vals[idx] for idx in top_idxs]
+    return [{val_name: val, **node} for val, node in zip(top_vals, top_node_attrs)]

napistu/network/napistu_graph_core.py

@@ -0,0 +1,354 @@
+from __future__ import annotations
+
+import copy
+import logging
+from typing import Any, Optional
+
+import igraph as ig
+import pandas as pd
+
+from napistu.network.constants import (
+    NAPISTU_GRAPH_EDGES,
+    EDGE_REVERSAL_ATTRIBUTE_MAPPING,
+    EDGE_DIRECTION_MAPPING,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class NapistuGraph(ig.Graph):
+    """
+    A subclass of igraph.Graph with additional functionality for molecular network analysis.
+
+    This class extends igraph.Graph with domain-specific methods and metadata tracking
+    for biological pathway and molecular interaction networks. All standard igraph
+    methods are available, plus additional functionality for edge reversal and
+    metadata management.
+
+    Parameters
+    ----------
+    *args : tuple
+        Positional arguments passed to igraph.Graph constructor
+    **kwargs : dict
+        Keyword arguments passed to igraph.Graph constructor
+
+    Attributes
+    ----------
+    is_reversed : bool
+        Whether the graph edges have been reversed from their original direction
+    graph_type : str or None
+        Type of graph (e.g., 'bipartite', 'regulatory', 'surrogate')
+    weighting_strategy : str or None
+        Strategy used for edge weighting (e.g., 'topology', 'mixed', 'calibrated')
+
+    Methods
+    -------
+    from_igraph(graph, **metadata)
+        Create a NapistuGraph from an existing igraph.Graph
+    reverse_edges()
+        Reverse all edges in the graph in-place
+    set_metadata(**kwargs)
+        Set metadata for the graph in-place
+    get_metadata(key=None)
+        Get metadata from the graph
+    copy()
+        Create a deep copy of the NapistuGraph
+
+    Examples
+    --------
+    Create a NapistuGraph from scratch:
+
+    >>> ng = NapistuGraph(directed=True)
+    >>> ng.add_vertices(3)
+    >>> ng.add_edges([(0, 1), (1, 2)])
+
+    Convert from existing igraph:
+
+    >>> import igraph as ig
+    >>> g = ig.Graph.Erdos_Renyi(10, 0.3)
+    >>> ng = NapistuGraph.from_igraph(g, graph_type='random')
+
+    Reverse edges and check state:
+
+    >>> ng.reverse_edges()
+    >>> print(ng.is_reversed)
+    True
+
+    Set and retrieve metadata:
+
+    >>> ng.set_metadata(experiment_id='exp_001', date='2024-01-01')
+    >>> print(ng.get_metadata('experiment_id'))
+    'exp_001'
+
+    Notes
+    -----
+    NapistuGraph inherits from igraph.Graph, so all standard igraph methods
+    (degree, shortest_paths, betweenness, etc.) are available. The additional
+    functionality is designed specifically for molecular network analysis.
+
+    Edge reversal swaps 'from'/'to' attributes, negates stoichiometry values,
+    and updates direction metadata according to predefined mapping rules.
+    """
+
+    def __init__(self, *args, **kwargs):
+        """
+        Initialize a NapistuGraph.
+
+        Accepts all the same arguments as igraph.Graph constructor.
+        """
+        super().__init__(*args, **kwargs)
+
+        # Initialize metadata
+        self._metadata = {
+            "is_reversed": False,
+            "graph_type": None,
+            "weighting_strategy": None,
+            "creation_params": {},
+        }
+
+    @classmethod
+    def from_igraph(cls, graph: ig.Graph, **metadata) -> "NapistuGraph":
+        """
+        Create a NapistuGraph from an existing igraph.Graph.
+
+        Parameters
+        ----------
+        graph : ig.Graph
+            The igraph to convert
+        **metadata : dict
+            Additional metadata to store with the graph
+
+        Returns
+        -------
+        NapistuGraph
+            A new NapistuGraph instance
+        """
+        # Create new instance with same structure
+        new_graph = cls(
+            n=graph.vcount(),
+            edges=[(e.source, e.target) for e in graph.es],
+            directed=graph.is_directed(),
+        )
+
+        # Copy all vertex attributes
+        for attr in graph.vs.attributes():
+            new_graph.vs[attr] = graph.vs[attr]
+
+        # Copy all edge attributes
+        for attr in graph.es.attributes():
+            new_graph.es[attr] = graph.es[attr]
+
+        # Copy graph attributes
+        for attr in graph.attributes():
+            new_graph[attr] = graph[attr]
+
+        # Set metadata
+        new_graph._metadata.update(metadata)
+
+        return new_graph
+
+    def reverse_edges(self) -> None:
+        """
+        Reverse all edges in the graph.
+
+        This swaps edge directions and updates all associated attributes
+        according to the edge reversal mapping utilities. Modifies the graph in-place.
+
+        Returns
+        -------
+        None
+        """
+        # Get current edge dataframe
+        edges_df = self.get_edge_dataframe()
+
+        # Apply systematic attribute swapping using utilities
+        reversed_edges_df = _apply_edge_reversal_mapping(edges_df)
+
+        # Handle special cases using utilities
+        reversed_edges_df = _handle_special_reversal_cases(reversed_edges_df)
+
+        # Update edge attributes
+        for attr in reversed_edges_df.columns:
+            if attr in self.es.attributes():
+                self.es[attr] = reversed_edges_df[attr].values
+
+        # Update metadata
+        self._metadata["is_reversed"] = not self._metadata["is_reversed"]
+
+        logger.info(
+            f"Reversed graph edges. Current state: reversed={self._metadata['is_reversed']}"
+        )
+
+        return None
+
+    @property
+    def is_reversed(self) -> bool:
+        """Check if the graph has been reversed."""
+        return self._metadata["is_reversed"]
+
+    @property
+    def graph_type(self) -> Optional[str]:
+        """Get the graph type (bipartite, regulatory, etc.)."""
+        return self._metadata["graph_type"]
+
+    @property
+    def weighting_strategy(self) -> Optional[str]:
+        """Get the weighting strategy used."""
+        return self._metadata["weighting_strategy"]
+
+    def set_metadata(self, **kwargs) -> None:
+        """
+        Set metadata for the graph.
+
+        Modifies the graph's metadata in-place.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Metadata key-value pairs to set
+        """
+        self._metadata.update(kwargs)
+
+        return None
+
+    def get_metadata(self, key: Optional[str] = None) -> Any:
+        """
+        Get metadata from the graph.
+
+        Parameters
+        ----------
+        key : str, optional
+            Specific metadata key to retrieve. If None, returns all metadata.
+
+        Returns
+        -------
+        Any
+            The requested metadata value, or all metadata if key is None
+        """
+        if key is None:
+            return self._metadata.copy()
+        return self._metadata.get(key)
+
+    def copy(self) -> "NapistuGraph":
+        """
+        Create a deep copy of the NapistuGraph.
+
+        Returns
+        -------
+        NapistuGraph
+            A deep copy of this graph including metadata
+        """
+        # Use igraph's copy method to get the graph structure and attributes
+        new_graph = super().copy()
+
+        # Convert to NapistuGraph and copy metadata
+        napistu_copy = NapistuGraph.from_igraph(new_graph)
+        napistu_copy._metadata = copy.deepcopy(self._metadata)
+
+        return napistu_copy
+
+    def __str__(self) -> str:
+        """String representation including metadata."""
+        base_str = super().__str__()
+        metadata_str = (
+            f"Reversed: {self.is_reversed}, "
+            f"Type: {self.graph_type}, "
+            f"Weighting: {self.weighting_strategy}"
+        )
+        return f"{base_str}\nNapistuGraph metadata: {metadata_str}"
+
+    def __repr__(self) -> str:
+        """Detailed representation."""
+        return self.__str__()
+
+
+def _apply_edge_reversal_mapping(edges_df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Apply systematic attribute mapping for edge reversal.
+
+    This function swaps paired attributes according to EDGE_REVERSAL_ATTRIBUTE_MAPPING.
+    For example, 'from' becomes 'to', 'weights' becomes 'upstream_weights', etc.
+
+    Parameters
+    ----------
+    edges_df : pd.DataFrame
+        Current edge attributes
+
+    Returns
+    -------
+    pd.DataFrame
+        Edge dataframe with swapped attributes
+
+    Warnings
+    --------
+    Logs warnings when expected attribute pairs are missing
+    """
+    # Find which attributes have pairs in the mapping
+    available_attrs = set(edges_df.columns)
+
+    # Find pairs where both attributes exist
+    valid_mapping = {}
+    missing_pairs = []
+
+    for source_attr, target_attr in EDGE_REVERSAL_ATTRIBUTE_MAPPING.items():
+        if source_attr in available_attrs:
+            if target_attr in available_attrs:
+                valid_mapping[source_attr] = target_attr
+            else:
+                missing_pairs.append(f"{source_attr} -> {target_attr}")
+
+    # Warn about attributes that can't be swapped
+    if missing_pairs:
+        logger.warning(
+            f"The following edge attributes cannot be swapped during reversal "
+            f"because their paired attribute is missing: {', '.join(missing_pairs)}"
+        )
+
+    return edges_df.rename(columns=valid_mapping)
+
+
+def _handle_special_reversal_cases(edges_df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Handle special cases that need more than simple attribute swapping.
+
+    This includes:
+    - Flipping stoichiometry signs (* -1)
+    - Mapping direction enums (forward <-> reverse)
+
+    Parameters
+    ----------
+    edges_df : pd.DataFrame
+        Edge dataframe after basic attribute swapping
+
+    Returns
+    -------
+    pd.DataFrame
+        Edge dataframe with special cases handled
+
+    Warnings
+    --------
+    Logs warnings when expected attributes are missing
+    """
+    result_df = edges_df.copy()
+
+    # Handle stoichiometry sign flip
+    if NAPISTU_GRAPH_EDGES.STOICHIOMETRY in result_df.columns:
+        result_df[NAPISTU_GRAPH_EDGES.STOICHIOMETRY] *= -1
+    else:
+        logger.warning(
+            f"Missing expected '{NAPISTU_GRAPH_EDGES.STOICHIOMETRY}' attribute during edge reversal. "
+            "Stoichiometry signs will not be flipped."
+        )
+
+    # Handle direction enum mapping
+    if NAPISTU_GRAPH_EDGES.DIRECTION in result_df.columns:
+        result_df[NAPISTU_GRAPH_EDGES.DIRECTION] = result_df[
+            NAPISTU_GRAPH_EDGES.DIRECTION
+        ].map(EDGE_DIRECTION_MAPPING)
+    else:
+        logger.warning(
+            f"Missing expected '{NAPISTU_GRAPH_EDGES.DIRECTION}' attribute during edge reversal. "
+            "Direction metadata will not be updated."
+        )
+
+    return result_df