pathview-plus 2.0.0__py3-none-any.whl

pathview/highlighting.py

@@ -0,0 +1,375 @@
+"""
+highlighting.py
+Layer-by-layer pathway graph modifications.
+
+Implements a ggplot2-style composable interface for post-hoc pathway
+customization. Users can highlight specific nodes or paths, change colors,
+adjust labels, and more — all without re-running the full rendering pipeline.
+
+Usage
+-----
+    from pathview import pathview, highlight_nodes, highlight_edges
+    
+    result = pathview("04110", gene_data=data, species="hsa")
+    
+    # Compose modifications with +
+    modified = (result
+                + highlight_nodes(["1956", "2099"], color="red", width=4)
+                + highlight_edges([("1956", "2099")], color="blue", width=3))
+    
+    # Save modified version
+    modified.save("highlighted.png")
+
+Public API
+----------
+  PathwayResult : Container for pathway rendering results
+  highlight_nodes : Highlight specific nodes
+  highlight_edges : Highlight specific edges
+  highlight_path  : Highlight an entire path
+  change_labels   : Update node labels
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Optional
+
+import numpy as np
+import polars as pl
+from PIL import Image
+
+
+# ---------------------------------------------------------------------------
+# PathwayResult container
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PathwayResult:
+    """
+    Container for pathway rendering results.
+    
+    Supports composable modifications via the + operator.
+    Stores both the rendered image and the underlying data so modifications
+    can be applied without full re-rendering.
+    """
+    pathway_id: str
+    plot_data_gene: Optional[pl.DataFrame] = None
+    plot_data_cpd: Optional[pl.DataFrame] = None
+    output_path: Optional[Path] = None
+    image_array: Optional[np.ndarray] = None
+    modifications: list[Callable] = field(default_factory=list)
+    
+    def __add__(self, modifier: Callable) -> PathwayResult:
+        """
+        Apply a modification function and return a new PathwayResult.
+        
+        This implements ggplot2-style layer composition:
+        
+            result = pathview(...) + highlight_nodes(...) + highlight_edges(...)
+        """
+        new_result = PathwayResult(
+            pathway_id=self.pathway_id,
+            plot_data_gene=self.plot_data_gene,
+            plot_data_cpd=self.plot_data_cpd,
+            output_path=self.output_path,
+            image_array=self.image_array.copy() if self.image_array is not None else None,
+            modifications=self.modifications + [modifier],
+        )
+        # Apply the modification
+        modifier(new_result)
+        return new_result
+    
+    def save(self, path: str | Path, format: str = "png") -> None:
+        """Save the modified pathway to a file."""
+        if self.image_array is None:
+            raise ValueError("No image data to save")
+        
+        img = Image.fromarray(self.image_array)
+        if format.lower() == "pdf":
+            img.save(path, "PDF", resolution=300.0)
+        else:
+            img.save(path, format.upper())
+        print(f"Info: Saved modified pathway → {path}")
+    
+    def show(self) -> None:
+        """Display the pathway using PIL."""
+        if self.image_array is None:
+            raise ValueError("No image data to display")
+        Image.fromarray(self.image_array).show()
+
+
+# ---------------------------------------------------------------------------
+# Node highlighting
+# ---------------------------------------------------------------------------
+
+def highlight_nodes(
+    node_ids: list[str],
+    color: str = "red",
+    width: int = 4,
+    opacity: float = 1.0,
+) -> Callable[[PathwayResult], None]:
+    """
+    Highlight specified nodes by changing their border.
+    
+    Parameters
+    ----------
+    node_ids: List of node IDs to highlight (Entrez IDs or KEGG IDs)
+    color:    Border color (hex or named color)
+    width:    Border width in pixels
+    opacity:  Border opacity (0-1)
+    
+    Returns a modifier function that can be added to a PathwayResult.
+    
+    Example
+    -------
+    >>> result = pathview("04110", gene_data=data)
+    >>> highlighted = result + highlight_nodes(["1956", "2099"], color="red", width=4)
+    >>> highlighted.save("highlighted.png")
+    """
+    def modifier(result: PathwayResult) -> None:
+        if result.image_array is None:
+            return
+        
+        # Find node positions
+        nodes_to_highlight = []
+        if result.plot_data_gene is not None:
+            genes = result.plot_data_gene.filter(
+                pl.col("kegg_names").is_in(node_ids)
+            )
+            if not genes.is_empty():
+                nodes_to_highlight.append(genes)
+        
+        if result.plot_data_cpd is not None:
+            cpds = result.plot_data_cpd.filter(
+                pl.col("kegg_names").is_in(node_ids)
+            )
+            if not cpds.is_empty():
+                nodes_to_highlight.append(cpds)
+        
+        # Draw highlights
+        img_height = result.image_array.shape[0]
+        rgb = _hex_to_rgb(color)
+        
+        for df in nodes_to_highlight:
+            for row in df.iter_rows(named=True):
+                cx, cy = row["x"], row["y"]
+                hw, hh = row["width"] / 2, row["height"] / 2
+                _draw_border(
+                    result.image_array, 
+                    cx=cx, cy=cy, 
+                    half_width=hw, half_height=hh,
+                    img_height=img_height,
+                    rgb=rgb, thickness=width, opacity=opacity
+                )
+    
+    return modifier
+
+
+# ---------------------------------------------------------------------------
+# Edge highlighting
+# ---------------------------------------------------------------------------
+
+def highlight_edges(
+    edge_pairs: list[tuple[str, str]],
+    color: str = "blue",
+    width: int = 3,
+) -> Callable[[PathwayResult], None]:
+    """
+    Highlight specified edges (connections between nodes).
+    
+    Parameters
+    ----------
+    edge_pairs: List of (source_id, target_id) tuples
+    color:      Edge color
+    width:      Edge width in pixels
+    
+    Returns a modifier function.
+    
+    Example
+    -------
+    >>> result + highlight_edges([("1956", "2099"), ("2099", "5594")])
+    """
+    def modifier(result: PathwayResult) -> None:
+        if result.image_array is None:
+            return
+        
+        # Find node positions for edge endpoints
+        gene_pos = {}
+        if result.plot_data_gene is not None:
+            for row in result.plot_data_gene.iter_rows(named=True):
+                gene_pos[row["kegg_names"]] = (row["x"], row["y"])
+        
+        img_height = result.image_array.shape[0]
+        rgb = _hex_to_rgb(color)
+        
+        # Draw lines between pairs
+        for source_id, target_id in edge_pairs:
+            if source_id in gene_pos and target_id in gene_pos:
+                x1, y1 = gene_pos[source_id]
+                x2, y2 = gene_pos[target_id]
+                _draw_line(
+                    result.image_array,
+                    x1=x1, y1=y1, x2=x2, y2=y2,
+                    img_height=img_height,
+                    rgb=rgb, thickness=width
+                )
+    
+    return modifier
+
+
+# ---------------------------------------------------------------------------
+# Path highlighting
+# ---------------------------------------------------------------------------
+
+def highlight_path(
+    path_node_ids: list[str],
+    color: str = "orange",
+    node_width: int = 3,
+    edge_width: int = 2,
+) -> Callable[[PathwayResult], None]:
+    """
+    Highlight an entire path (nodes and edges).
+    
+    Parameters
+    ----------
+    path_node_ids: Ordered list of node IDs forming a path
+    color:         Color for both nodes and edges
+    node_width:    Border width for nodes
+    edge_width:    Width for connecting edges
+    
+    Returns a modifier function.
+    
+    Example
+    -------
+    >>> result + highlight_path(["1956", "2099", "5594", "207"], color="orange")
+    """
+    # Build edge pairs from consecutive nodes
+    edge_pairs = list(zip(path_node_ids[:-1], path_node_ids[1:]))
+    
+    def modifier(result: PathwayResult) -> None:
+        # Apply both node and edge highlighting
+        highlight_nodes(path_node_ids, color=color, width=node_width)(result)
+        highlight_edges(edge_pairs, color=color, width=edge_width)(result)
+    
+    return modifier
+
+
+# ---------------------------------------------------------------------------
+# Label modification
+# ---------------------------------------------------------------------------
+
+def change_labels(
+    label_map: dict[str, str],
+    font_size: int = 11,
+    color: str = "black",
+) -> Callable[[PathwayResult], None]:
+    """
+    Change labels for specified nodes.
+    
+    Parameters
+    ----------
+    label_map:  Dict mapping node_id → new_label
+    font_size:  Font size for new labels
+    color:      Text color
+    
+    Returns a modifier function.
+    
+    Example
+    -------
+    >>> result + change_labels({"1956": "EGFR*", "2099": "ESR1*"})
+    """
+    def modifier(result: PathwayResult) -> None:
+        # This would require text rendering on the image
+        # For now, store the label changes for future re-rendering
+        if not hasattr(result, '_label_changes'):
+            result._label_changes = {}
+        result._label_changes.update(label_map)
+    
+    return modifier
+
+
+# ---------------------------------------------------------------------------
+# Drawing primitives
+# ---------------------------------------------------------------------------
+
+def _hex_to_rgb(hex_color: str) -> tuple[int, int, int]:
+    """Convert hex color to RGB tuple."""
+    hex_color = hex_color.lstrip("#")
+    return tuple(int(hex_color[i:i+2], 16) for i in (0, 2, 4))
+
+
+def _draw_border(
+    img: np.ndarray,
+    cx: float,
+    cy: float,
+    half_width: float,
+    half_height: float,
+    img_height: int,
+    rgb: tuple[int, int, int],
+    thickness: int,
+    opacity: float,
+) -> None:
+    """Draw a rectangle border on the image array."""
+    # Convert KGML coordinates to image coordinates
+    py = int(img_height - cy)
+    px = int(cx)
+    hw, hh = int(half_width), int(half_height)
+    
+    # Draw rectangle border (4 sides)
+    for t in range(thickness):
+        # Top
+        img[max(0, py - hh - t):min(img.shape[0], py - hh - t + 1),
+            max(0, px - hw):min(img.shape[1], px + hw)] = rgb
+        # Bottom
+        img[max(0, py + hh + t):min(img.shape[0], py + hh + t + 1),
+            max(0, px - hw):min(img.shape[1], px + hw)] = rgb
+        # Left
+        img[max(0, py - hh):min(img.shape[0], py + hh),
+            max(0, px - hw - t):min(img.shape[1], px - hw - t + 1)] = rgb
+        # Right
+        img[max(0, py - hh):min(img.shape[0], py + hh),
+            max(0, px + hw + t):min(img.shape[1], px + hw + t + 1)] = rgb
+
+
+def _draw_line(
+    img: np.ndarray,
+    x1: float,
+    y1: float,
+    x2: float,
+    y2: float,
+    img_height: int,
+    rgb: tuple[int, int, int],
+    thickness: int,
+) -> None:
+    """Draw a line on the image array using Bresenham's algorithm."""
+    # Convert coordinates
+    px1, py1 = int(x1), int(img_height - y1)
+    px2, py2 = int(x2), int(img_height - y2)
+    
+    # Bresenham's line algorithm
+    dx = abs(px2 - px1)
+    dy = abs(py2 - py1)
+    sx = 1 if px1 < px2 else -1
+    sy = 1 if py1 < py2 else -1
+    err = dx - dy
+    
+    while True:
+        # Draw thick point
+        for t in range(-thickness // 2, thickness // 2 + 1):
+            for u in range(-thickness // 2, thickness // 2 + 1):
+                py = py1 + t
+                px = px1 + u
+                if 0 <= py < img.shape[0] and 0 <= px < img.shape[1]:
+                    img[py, px] = rgb
+        
+        if px1 == px2 and py1 == py2:
+            break
+        
+        e2 = 2 * err
+        if e2 > -dy:
+            err -= dy
+            px1 += sx
+        if e2 < dx:
+            err += dx
+            py1 += sy

pathview/id_mapping.py

@@ -0,0 +1,170 @@
+"""
+id_mapping.py
+Gene and compound identifier mapping:
+  - id2eg        : arbitrary gene ID  → Entrez Gene ID  (MyGene.info)
+  - eg2id        : Entrez Gene ID     → any gene ID     (MyGene.info)
+  - cpd_id_map   : compound ID        → KEGG compound   (KEGG REST conv)
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Optional
+
+import polars as pl
+import requests
+
+from .constants import KEGG_BASE
+
+
+# ---------------------------------------------------------------------------
+# Gene ID mapping  (MyGene.info REST API)
+# ---------------------------------------------------------------------------
+
+_SCOPE_MAP = {
+    "symbol":  "symbol",
+    "alias":   "alias",
+    "uniprot": "uniprot",
+    "ensembl": "ensembl.gene",
+    "refseq":  "refseq",
+}
+
+_MYGENE_URL = "https://mygene.info/v3/querymany"
+
+
+def _query_mygene(
+    ids: list[str],
+    scopes: str,
+    field: str,
+    species: str,
+) -> dict[str, Optional[str]]:
+    """
+    POST a batch query to MyGene.info and return a {query_id: field_value} dict.
+    Returns an empty-value dict on network failure.
+    """
+    payload = {
+        "q":         ",".join(ids),
+        "scopes":    scopes,
+        "species":   species,
+        "fields":    field,
+        "returnall": "true",
+    }
+    try:
+        resp = requests.post(_MYGENE_URL, data=payload, timeout=30)
+        resp.raise_for_status()
+        hits = resp.json()
+    except Exception as exc:
+        warnings.warn(f"MyGene.info query failed: {exc}")
+        return {i: None for i in ids}
+
+    lookup: dict[str, Optional[str]] = {}
+    for hit in hits:
+        qid = hit.get("query", "")
+        val = hit.get(field)
+        if isinstance(val, list):
+            val = val[0] if val else None
+        if qid and qid not in lookup:
+            lookup[qid] = str(val) if val is not None else None
+
+    return lookup
+
+
+def id2eg(ids: list[str], category: str, org: str = "Hs") -> pl.DataFrame:
+    """
+    Map arbitrary gene IDs to Entrez Gene IDs.
+
+    Parameters
+    ----------
+    ids:      Input gene identifiers.
+    category: ID type of *ids* (e.g. "SYMBOL", "ENSEMBL", "UNIPROT").
+    org:      Species for MyGene.info (e.g. "Hs", "Mm", "hsa").
+
+    Returns a two-column DataFrame: [category, "ENTREZID"].
+
+    Raises ValueError if *category* is already an Entrez type.
+    """
+    if category.lower() in ("entrez", "eg", "entrezid"):
+        raise ValueError("Input IDs are already Entrez Gene IDs.")
+
+    scope = _SCOPE_MAP.get(category.lower(), category.lower())
+    lookup = _query_mygene(ids, scopes=scope, field="entrezgene", species=org)
+    return pl.DataFrame({category: ids, "ENTREZID": [lookup.get(i) for i in ids]})
+
+
+def eg2id(
+    eg_ids: list[str],
+    category: str = "SYMBOL",
+    org: str = "Hs",
+) -> pl.DataFrame:
+    """
+    Map Entrez Gene IDs to another identifier type.
+
+    Parameters
+    ----------
+    eg_ids:   Entrez Gene IDs to convert.
+    category: Target ID type (e.g. "SYMBOL", "UNIPROT", "ENSEMBL").
+    org:      Species for MyGene.info.
+
+    Returns a two-column DataFrame: ["ENTREZID", category].
+
+    Raises ValueError if *category* is an Entrez type.
+    """
+    if category.lower() in ("entrez", "eg", "entrezid"):
+        raise ValueError("Output category cannot be Entrez Gene ID.")
+
+    field_map = {
+        "symbol":  "symbol",
+        "name":    "name",
+        "uniprot": "uniprot",
+        "ensembl": "ensembl.gene",
+        "alias":   "alias",
+    }
+    field = field_map.get(category.lower(), category.lower())
+    lookup = _query_mygene(eg_ids, scopes="entrezgene", field=field, species=org)
+    return pl.DataFrame({"ENTREZID": eg_ids, category: [lookup.get(i) for i in eg_ids]})
+
+
+# ---------------------------------------------------------------------------
+# Compound ID mapping  (KEGG REST conv endpoint)
+# ---------------------------------------------------------------------------
+
+_CPD_TYPE_MAP = {
+    "pubchem": "pubchem",
+    "chebi":   "chebi",
+    "kegg":    "cpd",
+}
+
+
+def cpd_id_map(
+    in_ids: list[str],
+    in_type: str,
+    out_type: str = "KEGG",
+) -> pl.DataFrame:
+    """
+    Map compound IDs between identifier systems using KEGG REST.
+
+    Parameters
+    ----------
+    in_ids:   Input compound identifiers.
+    in_type:  Source ID type (e.g. "PUBCHEM", "CHEBI", "KEGG").
+    out_type: Target ID type (default "KEGG").
+
+    Returns a two-column DataFrame: [in_type, out_type].
+    """
+    src = _CPD_TYPE_MAP.get(in_type.lower(),  in_type.lower())
+    dst = _CPD_TYPE_MAP.get(out_type.lower(), out_type.lower())
+
+    out_ids: list[Optional[str]] = []
+    for cid in in_ids:
+        url = f"{KEGG_BASE}/conv/{dst}/{src}:{cid}"
+        try:
+            resp = requests.get(url, timeout=15)
+            if resp.ok and resp.text.strip():
+                parts = resp.text.strip().split("\t")
+                out_ids.append(parts[1].split(":")[1] if len(parts) > 1 else None)
+            else:
+                out_ids.append(None)
+        except Exception:
+            out_ids.append(None)
+
+    return pl.DataFrame({in_type: in_ids, out_type: out_ids})

pathview/kegg_api.py

@@ -0,0 +1,143 @@
+"""
+kegg_api.py
+KEGG REST API interactions:
+  - SpeciesInfo      : dataclass holding per-species KEGG metadata
+  - kegg_species_code: resolve a species name / abbreviation to SpeciesInfo
+  - download_kegg    : fetch KGML (xml) and/or pathway image (png) files
+"""
+
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import requests
+
+from .constants import KEGG_BASE
+
+
+# ---------------------------------------------------------------------------
+# Species resolution
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class SpeciesInfo:
+    """Immutable container for KEGG species metadata."""
+    kegg_code:      str
+    entrez_gnodes:  bool
+    kegg_geneid:    Optional[str]
+    ncbi_geneid:    Optional[str]
+    ncbi_proteinid: Optional[str]
+    uniprot:        Optional[str]
+
+
+_KO_SPECIES = SpeciesInfo(
+    kegg_code="ko",
+    entrez_gnodes=False,
+    kegg_geneid="K01488",
+    ncbi_geneid=None,
+    ncbi_proteinid=None,
+    uniprot=None,
+)
+
+
+def kegg_species_code(species: str = "hsa") -> SpeciesInfo:
+    """
+    Resolve *species* (KEGG code, common name, or taxon) to a SpeciesInfo.
+
+    Queries ``rest.kegg.jp/list/organism`` and matches any column.
+    Raises ValueError for unknown species.
+    """
+    if species == "ko":
+        return _KO_SPECIES
+
+    url = f"{KEGG_BASE}/list/organism"
+    try:
+        resp = requests.get(url, timeout=30)
+        resp.raise_for_status()
+    except Exception as exc:
+        raise RuntimeError(f"Failed to fetch KEGG organism list: {exc}") from exc
+
+    query = species.lower()
+    for line in resp.text.splitlines():
+        parts = line.split("\t")
+        if len(parts) < 3:
+            continue
+        if query in (p.lower() for p in parts):
+            return SpeciesInfo(
+                kegg_code=parts[1],
+                entrez_gnodes=True,
+                kegg_geneid=None,
+                ncbi_geneid=None,
+                ncbi_proteinid=None,
+                uniprot=None,
+            )
+
+    raise ValueError(
+        f"Unknown species '{species}'. "
+        "Check https://rest.kegg.jp/list/organism for valid codes."
+    )
+
+
+# ---------------------------------------------------------------------------
+# File download
+# ---------------------------------------------------------------------------
+
+def download_kegg(
+    pathway_id: str,
+    species: str = "hsa",
+    kegg_dir: Path = Path("."),
+    file_type: list[str] | None = None,
+) -> dict[str, str]:
+    """
+    Download KEGG KGML and/or pathway image for *pathway_id*.
+
+    Parameters
+    ----------
+    pathway_id: Numeric pathway ID, e.g. "04110" (species prefix is added
+                automatically if absent).
+    species:    KEGG species code used to build the full pathway ID.
+    kegg_dir:   Directory where files are saved.
+    file_type:  Subset of ["xml", "png"] to download (default: both).
+
+    Returns a dict mapping the full pathway ID to "succeed" or "failed".
+    """
+    if file_type is None:
+        file_type = ["xml", "png"]
+
+    kegg_dir = Path(kegg_dir)
+    kegg_dir.mkdir(parents=True, exist_ok=True)
+
+    full_id = pathway_id if pathway_id.startswith(species) else f"{species}{pathway_id}"
+
+    _url_templates = {
+        "xml": f"{KEGG_BASE}/get/{full_id}/kgml",
+        "png": f"{KEGG_BASE}/get/{full_id}/image",
+    }
+    _targets = {
+        "xml": kegg_dir / f"{full_id}.xml",
+        "png": kegg_dir / f"{full_id}.png",
+    }
+
+    status = {full_id: "succeed"}
+
+    for ftype in file_type:
+        url    = _url_templates[ftype]
+        target = _targets[ftype]
+        print(f"Info: Downloading {ftype} for {full_id} …")
+        try:
+            resp = requests.get(url, timeout=60)
+            resp.raise_for_status()
+            if ftype == "png":
+                target.write_bytes(resp.content)
+            else:
+                target.write_text(resp.text, encoding="utf-8")
+        except Exception as exc:
+            warnings.warn(f"Download of {full_id} {ftype} failed: {exc}")
+            status[full_id] = "failed"
+            if target.exists():
+                target.unlink()
+
+    return status