pathview-plus 2.0.0__py3-none-any.whl

pathview/sbgn_parser.py

@@ -0,0 +1,353 @@
+"""
+sbgn_parser.py
+Parse SBGN-ML (Systems Biology Graphical Notation ML) files.
+
+SBGN is used by Reactome, MetaCyc, MetaCrop, PANTHER, and SMPDB.
+Supports Process Description (PD), Entity Relationship (ER), and Activity Flow (AF) languages.
+
+Public API
+----------
+  parse_sbgn     : Path → SBGNPathway
+  sbgn_to_df     : SBGNPathway → pl.DataFrame (unified with KGML format)
+  
+SBGN vs KGML differences:
+  - Glyphs (nodes) instead of entries
+  - Arcs (edges) with Bezier splines
+  - Compartments (cellular locations)
+  - Clone markers for repeated entities
+  - Process nodes (reactions, associations)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+from xml.etree import ElementTree as ET
+
+import polars as pl
+
+
+# ---------------------------------------------------------------------------
+# Dataclasses
+# ---------------------------------------------------------------------------
+
+@dataclass
+class SBGNGlyph:
+    """One <glyph> element from SBGN-ML."""
+    glyph_id: str
+    glyph_class: str  # macromolecule, simple chemical, process, etc.
+    label: str = ""
+    x: Optional[float] = None
+    y: Optional[float] = None
+    width: Optional[float] = None
+    height: Optional[float] = None
+    compartment: Optional[str] = None
+    clone_marker: bool = False
+    state_variables: list[dict] = field(default_factory=list)
+    unit_of_information: list[dict] = field(default_factory=list)
+
+
+@dataclass
+class SBGNArc:
+    """One <arc> element from SBGN-ML."""
+    arc_id: str
+    arc_class: str  # production, consumption, catalysis, inhibition, etc.
+    source: str
+    target: str
+    spline_points: list[tuple[float, float]] = field(default_factory=list)
+
+
+@dataclass
+class SBGNPathway:
+    """Container for all parsed elements of an SBGN-ML file."""
+    pathway_id: str
+    pathway_name: str
+    glyphs: dict[str, SBGNGlyph] = field(default_factory=dict)
+    arcs: list[SBGNArc] = field(default_factory=list)
+    compartments: dict[str, SBGNGlyph] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# SBGN glyph classes mapping
+# ---------------------------------------------------------------------------
+
+# Map SBGN glyph classes to simplified types for unified interface
+_GLYPH_TYPE_MAP = {
+    # Entity pool nodes (EPN)
+    "macromolecule": "gene",
+    "simple chemical": "compound",
+    "nucleic acid feature": "gene",
+    "complex": "gene",
+    "multimer": "gene",
+    "unspecified entity": "gene",
+    
+    # Process nodes (PN)
+    "process": "process",
+    "omitted process": "process",
+    "uncertain process": "process",
+    "association": "process",
+    "dissociation": "process",
+    "phenotype": "process",
+    
+    # Container nodes
+    "compartment": "compartment",
+    "submap": "map",
+    
+    # Logical operators
+    "and": "operator",
+    "or": "operator",
+    "not": "operator",
+}
+
+
+# ---------------------------------------------------------------------------
+# XML parsing helpers
+# ---------------------------------------------------------------------------
+
+def _parse_bbox(elem: ET.Element) -> dict:
+    """Extract bounding box from <bbox> child element."""
+    bbox = elem.find(".//bbox", namespaces={"": "http://sbgn.org/libsbgn/0.2"})
+    if bbox is None:
+        bbox = elem.find("bbox")  # Try without namespace
+    
+    if bbox is not None:
+        return {
+            "x": float(bbox.get("x", 0)) + float(bbox.get("w", 46)) / 2,
+            "y": float(bbox.get("y", 0)) + float(bbox.get("h", 17)) / 2,
+            "width": float(bbox.get("w", 46)),
+            "height": float(bbox.get("h", 17)),
+        }
+    return {}
+
+
+def _parse_label(elem: ET.Element) -> str:
+    """Extract label text from <label> child element."""
+    label = elem.find(".//label", namespaces={"": "http://sbgn.org/libsbgn/0.2"})
+    if label is None:
+        label = elem.find("label")
+    
+    if label is not None:
+        return label.get("text", "")
+    return ""
+
+
+def _parse_state_variables(elem: ET.Element) -> list[dict]:
+    """Parse state variable glyphs (child glyphs with class='state variable')."""
+    states = []
+    for child in elem.findall(".//glyph[@class='state variable']"):
+        states.append({
+            "variable": child.get("variable", ""),
+            "value": child.get("value", ""),
+            "label": _parse_label(child),
+        })
+    return states
+
+
+def _parse_spline(arc_elem: ET.Element) -> list[tuple[float, float]]:
+    """
+    Parse spline curve from arc.
+    
+    SBGN-ML can have:
+    1. Straight lines: <start> and <end> points
+    2. Bezier curves: <start>, multiple <next>, <end> with control points
+    """
+    points = []
+    
+    # Start point
+    start = arc_elem.find("start")
+    if start is not None:
+        points.append((float(start.get("x", 0)), float(start.get("y", 0))))
+    
+    # Intermediate points (could be Bezier control points)
+    for pt in arc_elem.findall("next"):
+        points.append((float(pt.get("x", 0)), float(pt.get("y", 0))))
+    
+    # End point
+    end = arc_elem.find("end")
+    if end is not None:
+        points.append((float(end.get("x", 0)), float(end.get("y", 0))))
+    
+    return points
+
+
+# ---------------------------------------------------------------------------
+# Main parsing functions
+# ---------------------------------------------------------------------------
+
+def parse_sbgn(filepath: str | Path) -> SBGNPathway:
+    """
+    Parse an SBGN-ML file and return a populated SBGNPathway.
+    
+    Parameters
+    ----------
+    filepath: Path to the .sbgn or .xml SBGN-ML file
+    
+    Returns
+    -------
+    SBGNPathway object with all glyphs, arcs, and compartments
+    
+    Example
+    -------
+    >>> pathway = parse_sbgn("R-HSA-109582.sbgn")
+    >>> print(f"Found {len(pathway.glyphs)} glyphs")
+    >>> df = sbgn_to_df(pathway)
+    """
+    tree = ET.parse(filepath)
+    root = tree.getroot()
+    
+    # Handle namespace (SBGN files often use xmlns)
+    ns = {"sbgn": "http://sbgn.org/libsbgn/0.2"}
+    map_elem = root.find(".//sbgn:map", ns)
+    if map_elem is None:
+        map_elem = root.find("map")
+    if map_elem is None:
+        map_elem = root  # Fall back to root
+    
+    pathway = SBGNPathway(
+        pathway_id=map_elem.get("id", Path(filepath).stem),
+        pathway_name=map_elem.get("language", "SBGN-PD"),
+    )
+    
+    # Parse all glyphs
+    for glyph_elem in map_elem.findall(".//glyph"):
+        glyph_id = glyph_elem.get("id", "")
+        glyph_class = glyph_elem.get("class", "")
+        
+        if not glyph_id:
+            continue
+        
+        bbox = _parse_bbox(glyph_elem)
+        label = _parse_label(glyph_elem)
+        
+        glyph = SBGNGlyph(
+            glyph_id=glyph_id,
+            glyph_class=glyph_class,
+            label=label,
+            x=bbox.get("x"),
+            y=bbox.get("y"),
+            width=bbox.get("width"),
+            height=bbox.get("height"),
+            compartment=glyph_elem.get("compartmentRef"),
+            clone_marker="clone" in glyph_elem.attrib.get("clone", "").lower(),
+            state_variables=_parse_state_variables(glyph_elem),
+        )
+        
+        if glyph_class == "compartment":
+            pathway.compartments[glyph_id] = glyph
+        else:
+            pathway.glyphs[glyph_id] = glyph
+    
+    # Parse all arcs
+    for arc_elem in map_elem.findall(".//arc"):
+        arc_id = arc_elem.get("id", "")
+        arc_class = arc_elem.get("class", "")
+        source = arc_elem.get("source", "")
+        target = arc_elem.get("target", "")
+        
+        if not all([arc_id, source, target]):
+            continue
+        
+        arc = SBGNArc(
+            arc_id=arc_id,
+            arc_class=arc_class,
+            source=source,
+            target=target,
+            spline_points=_parse_spline(arc_elem),
+        )
+        pathway.arcs.append(arc)
+    
+    return pathway
+
+
+def sbgn_to_df(pathway: SBGNPathway) -> pl.DataFrame:
+    """
+    Convert SBGN pathway to a unified Polars DataFrame (compatible with KGML format).
+    
+    Parameters
+    ----------
+    pathway: Parsed SBGNPathway object
+    
+    Returns
+    -------
+    DataFrame with columns matching KGML node_info format:
+    entry_id, name, type, x, y, width, height, label, shape, etc.
+    
+    This allows SBGN pathways to use the same rendering pipeline as KEGG.
+    """
+    records = []
+    
+    for glyph_id, glyph in pathway.glyphs.items():
+        # Map SBGN class to simplified type
+        node_type = _GLYPH_TYPE_MAP.get(glyph.glyph_class, "unknown")
+        
+        # Determine shape
+        shape_map = {
+            "macromolecule": "roundedrectangle",
+            "simple chemical": "ellipse",
+            "complex": "octagon",
+            "process": "square",
+        }
+        shape = shape_map.get(glyph.glyph_class, "rectangle")
+        
+        records.append({
+            "entry_id": glyph_id,
+            "name": glyph_id,  # SBGN IDs are typically database IDs
+            "type": node_type,
+            "x": glyph.x,
+            "y": glyph.y,
+            "width": glyph.width,
+            "height": glyph.height,
+            "bgcolor": "#FFFFFF",
+            "label": glyph.label or glyph_id,
+            "shape": shape,
+            "reaction": "",
+            "component": "",
+            "size": 1,
+            "kegg_names": glyph_id,  # For ID mapping
+        })
+    
+    return pl.DataFrame(records) if records else pl.DataFrame()
+
+
+# ---------------------------------------------------------------------------
+# SBGN glyph class reference
+# ---------------------------------------------------------------------------
+
+SBGN_GLYPH_CLASSES = {
+    # Entity Pool Nodes (EPN)
+    "macromolecule": "Protein, gene product",
+    "simple chemical": "Small molecule, metabolite",
+    "nucleic acid feature": "DNA, RNA fragment",
+    "complex": "Molecular complex",
+    "multimer": "Homogeneous multimer",
+    "unspecified entity": "Unknown entity type",
+    
+    # Process Nodes (PN)
+    "process": "Biochemical process",
+    "omitted process": "Process details omitted",
+    "uncertain process": "Uncertain process",
+    "association": "Complex formation",
+    "dissociation": "Complex dissociation",
+    "phenotype": "Observable phenotype",
+    
+    # Containers
+    "compartment": "Cellular compartment",
+    "submap": "Link to another map",
+    
+    # Logical operators
+    "and": "Logical AND",
+    "or": "Logical OR",
+    "not": "Logical NOT",
+}
+
+SBGN_ARC_CLASSES = {
+    "production": "Product of process",
+    "consumption": "Consumed by process",
+    "catalysis": "Catalyzes process",
+    "modulation": "Modulates process",
+    "stimulation": "Stimulates process",
+    "inhibition": "Inhibits process",
+    "necessary stimulation": "Required stimulator",
+    "logic arc": "Logical operator connection",
+}

pathview/splines.py

@@ -0,0 +1,304 @@
+"""
+splines.py
+Bezier curve (spline) rendering for pathway edges.
+
+Provides smoother, more aesthetically pleasing edge routing compared to
+straight lines. Particularly useful for complex pathways with many crossings.
+
+Public API
+----------
+  cubic_bezier       : Calculate points along a cubic Bezier curve
+  quadratic_bezier   : Calculate points along a quadratic Bezier curve
+  catmull_rom_spline : Calculate smooth curve through control points
+  route_edge_spline  : Auto-route an edge avoiding obstacles
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+
+
+# ---------------------------------------------------------------------------
+# Bezier curves
+# ---------------------------------------------------------------------------
+
+def cubic_bezier(
+    p0: tuple[float, float],
+    p1: tuple[float, float],
+    p2: tuple[float, float],
+    p3: tuple[float, float],
+    n_points: int = 50,
+) -> np.ndarray:
+    """
+    Calculate points along a cubic Bezier curve.
+    
+    A cubic Bezier is defined by 4 control points:
+    - p0: start point
+    - p1: first control point
+    - p2: second control point
+    - p3: end point
+    
+    Parameters
+    ----------
+    p0, p1, p2, p3: Control points as (x, y) tuples
+    n_points:       Number of points to sample along the curve
+    
+    Returns
+    -------
+    Array of shape (n_points, 2) containing (x, y) coordinates.
+    
+    Example
+    -------
+    >>> curve = cubic_bezier((0, 0), (1, 2), (3, 2), (4, 0), n_points=100)
+    >>> plt.plot(curve[:, 0], curve[:, 1])
+    """
+    t = np.linspace(0, 1, n_points)[:, np.newaxis]
+    
+    # Cubic Bezier formula: B(t) = (1-t)³P₀ + 3(1-t)²tP₁ + 3(1-t)t²P₂ + t³P₃
+    p0 = np.array(p0)
+    p1 = np.array(p1)
+    p2 = np.array(p2)
+    p3 = np.array(p3)
+    
+    curve = (
+        (1 - t)**3 * p0
+        + 3 * (1 - t)**2 * t * p1
+        + 3 * (1 - t) * t**2 * p2
+        + t**3 * p3
+    )
+    return curve
+
+
+def quadratic_bezier(
+    p0: tuple[float, float],
+    p1: tuple[float, float],
+    p2: tuple[float, float],
+    n_points: int = 50,
+) -> np.ndarray:
+    """
+    Calculate points along a quadratic Bezier curve.
+    
+    A quadratic Bezier is defined by 3 control points:
+    - p0: start point
+    - p1: control point
+    - p2: end point
+    
+    Parameters
+    ----------
+    p0, p1, p2: Control points as (x, y) tuples
+    n_points:   Number of points to sample
+    
+    Returns array of shape (n_points, 2).
+    """
+    t = np.linspace(0, 1, n_points)[:, np.newaxis]
+    
+    # Quadratic Bezier: B(t) = (1-t)²P₀ + 2(1-t)tP₁ + t²P₂
+    p0 = np.array(p0)
+    p1 = np.array(p1)
+    p2 = np.array(p2)
+    
+    curve = (1 - t)**2 * p0 + 2 * (1 - t) * t * p1 + t**2 * p2
+    return curve
+
+
+# ---------------------------------------------------------------------------
+# Catmull-Rom splines
+# ---------------------------------------------------------------------------
+
+def catmull_rom_spline(
+    points: list[tuple[float, float]],
+    n_points: int = 50,
+    alpha: float = 0.5,
+) -> np.ndarray:
+    """
+    Calculate a smooth Catmull-Rom spline through control points.
+    
+    Catmull-Rom splines pass through all control points (interpolating spline)
+    and produce smooth curves. The 'alpha' parameter controls the
+    parameterization:
+    - alpha = 0.0: uniform (can produce loops)
+    - alpha = 0.5: centripetal (most common, no loops/cusps)
+    - alpha = 1.0: chordal
+    
+    Parameters
+    ----------
+    points:   List of (x, y) control points to interpolate
+    n_points: Number of points to sample between each pair
+    alpha:    Parameterization (0.5 = centripetal, recommended)
+    
+    Returns array of shape (total_points, 2).
+    
+    Example
+    -------
+    >>> control_pts = [(0, 0), (1, 2), (3, 1), (4, 3)]
+    >>> smooth_curve = catmull_rom_spline(control_pts, n_points=30)
+    """
+    if len(points) < 2:
+        return np.array(points)
+    
+    # Add phantom points at start and end
+    p = [points[0]] + points + [points[-1]]
+    curves = []
+    
+    for i in range(len(p) - 3):
+        p0, p1, p2, p3 = p[i], p[i+1], p[i+2], p[i+3]
+        
+        # Calculate segment lengths
+        t0 = 0
+        t1 = t0 + _distance(p0, p1) ** alpha
+        t2 = t1 + _distance(p1, p2) ** alpha
+        t3 = t2 + _distance(p2, p3) ** alpha
+        
+        # Sample points in the valid range [t1, t2]
+        t = np.linspace(t1, t2, n_points)
+        
+        # Catmull-Rom basis functions
+        for ti in t:
+            a1 = (t1 - ti) / (t1 - t0) * np.array(p0) + (ti - t0) / (t1 - t0) * np.array(p1)
+            a2 = (t2 - ti) / (t2 - t1) * np.array(p1) + (ti - t1) / (t2 - t1) * np.array(p2)
+            a3 = (t3 - ti) / (t3 - t2) * np.array(p2) + (ti - t2) / (t3 - t2) * np.array(p3)
+            
+            b1 = (t2 - ti) / (t2 - t0) * a1 + (ti - t0) / (t2 - t0) * a2
+            b2 = (t3 - ti) / (t3 - t1) * a2 + (ti - t1) / (t3 - t1) * a3
+            
+            c = (t2 - ti) / (t2 - t1) * b1 + (ti - t1) / (t2 - t1) * b2
+            curves.append(c)
+    
+    return np.array(curves)
+
+
+def _distance(p1: tuple[float, float], p2: tuple[float, float]) -> float:
+    """Euclidean distance between two points."""
+    return np.sqrt((p1[0] - p2[0])**2 + (p1[1] - p2[1])**2)
+
+
+# ---------------------------------------------------------------------------
+# Auto-routing
+# ---------------------------------------------------------------------------
+
+def route_edge_spline(
+    source: tuple[float, float],
+    target: tuple[float, float],
+    obstacles: Optional[list[tuple[float, float, float, float]]] = None,
+    routing_mode: str = "orthogonal",
+) -> np.ndarray:
+    """
+    Auto-route an edge between source and target, avoiding obstacles.
+    
+    This is a simplified routing algorithm. For production use, consider
+    more sophisticated routing like:
+    - A* pathfinding
+    - Visibility graphs
+    - Force-directed edge bundling
+    
+    Parameters
+    ----------
+    source:       (x, y) starting point
+    target:       (x, y) ending point
+    obstacles:    List of (x, y, width, height) rectangles to avoid
+    routing_mode: "straight", "orthogonal", or "curved"
+    
+    Returns array of points defining the routed path.
+    """
+    if routing_mode == "straight" or obstacles is None:
+        return np.array([source, target])
+    
+    if routing_mode == "orthogonal":
+        # Simple orthogonal routing (Manhattan-style)
+        sx, sy = source
+        tx, ty = target
+        midx = (sx + tx) / 2
+        
+        control_points = [
+            source,
+            (midx, sy),
+            (midx, ty),
+            target,
+        ]
+        return catmull_rom_spline(control_points, n_points=20)
+    
+    elif routing_mode == "curved":
+        # Gentle S-curve
+        sx, sy = source
+        tx, ty = target
+        
+        # Control points for cubic Bezier
+        dx = tx - sx
+        dy = ty - sy
+        c1 = (sx + dx * 0.3, sy + dy * 0.1)
+        c2 = (sx + dx * 0.7, sy + dy * 0.9)
+        
+        return cubic_bezier(source, c1, c2, target, n_points=30)
+    
+    return np.array([source, target])
+
+
+# ---------------------------------------------------------------------------
+# SVG path generation
+# ---------------------------------------------------------------------------
+
+def bezier_to_svg_path(
+    curve: np.ndarray,
+    close: bool = False,
+) -> str:
+    """
+    Convert a Bezier curve to SVG path data.
+    
+    Parameters
+    ----------
+    curve:  Array of shape (n, 2) containing (x, y) points
+    close:  Whether to close the path (Z command)
+    
+    Returns SVG path data string (for use in <path d="..."/>)
+    
+    Example
+    -------
+    >>> curve = cubic_bezier((10, 10), (50, 80), (150, 80), (200, 10))
+    >>> path_data = bezier_to_svg_path(curve)
+    >>> svg = f'<path d="{path_data}" stroke="black" fill="none"/>'
+    """
+    if len(curve) == 0:
+        return ""
+    
+    path_parts = [f"M {curve[0, 0]:.2f} {curve[0, 1]:.2f}"]
+    
+    for point in curve[1:]:
+        path_parts.append(f"L {point[0]:.2f} {point[1]:.2f}")
+    
+    if close:
+        path_parts.append("Z")
+    
+    return " ".join(path_parts)
+
+
+def smooth_path_svg(
+    points: list[tuple[float, float]],
+    tension: float = 0.5,
+) -> str:
+    """
+    Generate smooth SVG path using quadratic Bezier commands.
+    
+    Parameters
+    ----------
+    points:  List of (x, y) waypoints
+    tension: Curve tension (0 = sharp corners, 1 = very smooth)
+    
+    Returns SVG path data using S (smooth cubic bezier) commands.
+    """
+    if len(points) < 2:
+        return ""
+    
+    path_parts = [f"M {points[0][0]} {points[0][1]}"]
+    
+    for i in range(1, len(points)):
+        x, y = points[i]
+        if i == 1:
+            # First curve segment uses Q (quadratic)
+            path_parts.append(f"Q {x} {y} {x} {y}")
+        else:
+            # Subsequent segments use T (smooth continuation)
+            path_parts.append(f"T {x} {y}")
+    
+    return " ".join(path_parts)