pathview-plus 2.0.0__py3-none-any.whl

pathview/__init__.py

@@ -0,0 +1,124 @@
+"""
+pathview — Python implementation of R pathview + SBGNview features.
+
+Complete pathway visualization system supporting:
+- KEGG pathways (KGML format)
+- SBGN pathways (Reactome, MetaCyc, PANTHER, SMPDB)
+- Multiple rendering modes (PNG overlay, SVG vector, PDF graph)
+- Highlighting and post-processing
+- Spline curve rendering
+
+Public API
+----------
+    # Core visualization
+    from pathview import pathview
+    
+    # Data utilities
+    from pathview import sim_mol_data, mol_sum, node_color
+    
+    # ID mapping
+    from pathview import id2eg, eg2id, cpd_id_map
+    
+    # Parsing (KEGG)
+    from pathview import parse_kgml, node_info
+    
+    # Parsing (SBGN)
+    from pathview import parse_sbgn, sbgn_to_df
+    
+    # Database downloaders
+    from pathview import (
+        download_kegg, download_reactome, download_metacyc,
+        list_reactome_pathways, detect_database
+    )
+    
+    # Highlighting & post-processing
+    from pathview import (
+        PathwayResult, highlight_nodes, highlight_edges,
+        highlight_path, change_labels
+    )
+    
+    # Rendering modes
+    from pathview import keggview_native, keggview_graph, keggview_svg
+    
+    # Spline curves
+    from pathview import (
+        cubic_bezier, quadratic_bezier, catmull_rom_spline,
+        route_edge_spline, bezier_to_svg_path
+    )
+"""
+
+__version__ = "2.0.0"
+__authors__ = 'Richard Allen White III, Jose Luis Figueroa III'
+__description__ = "KEGG + SBGN pathway visualization with Python"
+
+
+from .color_mapping import draw_color_key, make_colormap, node_color
+from .databases import (DATABASE_INFO, detect_database, download_metacyc,
+                         download_panther, download_reactome, download_smpdb,
+                         list_reactome_pathways)
+from .highlighting import (PathwayResult, change_labels, highlight_edges,
+                            highlight_nodes, highlight_path)
+from .id_mapping import cpd_id_map, eg2id, id2eg
+from .kegg_api import SpeciesInfo, download_kegg, kegg_species_code
+from .kgml_parser import (KGMLEdge, KGMLNode, KGMLPathway, KGMLReaction,
+                           node_info, parse_kgml)
+from .mol_data import mol_sum, sim_mol_data
+from .node_mapping import node_map
+from .rendering import kegg_legend, keggview_graph, keggview_native
+from .sbgn_parser import (SBGN_ARC_CLASSES, SBGN_GLYPH_CLASSES, SBGNArc,
+                           SBGNGlyph, SBGNPathway, parse_sbgn, sbgn_to_df)
+from .splines import (bezier_to_svg_path, catmull_rom_spline, cubic_bezier,
+                       quadratic_bezier, route_edge_spline, smooth_path_svg)
+from .svg_rendering import keggview_svg, render_edge_svg, render_node_svg
+from .utils import max_abs, random_pick, wordwrap
+
+__all__ = [
+    # Core pipeline
+    "pathview",
+    
+    # Data simulation & aggregation
+    "sim_mol_data", "mol_sum",
+    
+    # ID mapping
+    "id2eg", "eg2id", "cpd_id_map",
+    
+    # KEGG API
+    "kegg_species_code", "download_kegg", "SpeciesInfo",
+    
+    # Database downloads (SBGN)
+    "download_reactome", "download_metacyc", "download_panther", "download_smpdb",
+    "list_reactome_pathways", "detect_database", "DATABASE_INFO",
+    
+    # Parsing (KGML)
+    "parse_kgml", "node_info",
+    "KGMLPathway", "KGMLNode", "KGMLEdge", "KGMLReaction",
+    
+    # Parsing (SBGN)
+    "parse_sbgn", "sbgn_to_df",
+    "SBGNPathway", "SBGNGlyph", "SBGNArc",
+    "SBGN_GLYPH_CLASSES", "SBGN_ARC_CLASSES",
+    
+    # Node mapping
+    "node_map",
+    
+    # Colors
+    "node_color", "make_colormap", "draw_color_key",
+    
+    # Rendering (PNG, PDF, SVG)
+    "keggview_native", "keggview_graph", "keggview_svg", "kegg_legend",
+    "render_node_svg", "render_edge_svg",
+    
+    # Highlighting & post-processing
+    "PathwayResult", "highlight_nodes", "highlight_edges",
+    "highlight_path", "change_labels",
+    
+    # Spline curves
+    "cubic_bezier", "quadratic_bezier", "catmull_rom_spline",
+    "route_edge_spline", "bezier_to_svg_path", "smooth_path_svg",
+    
+    # Utilities
+    "wordwrap", "max_abs", "random_pick",
+]
+
+# Import pathview last to avoid circular imports
+from .pathview import pathview  # noqa: E402

pathview/color_mapping.py

@@ -0,0 +1,153 @@
+"""
+color_mapping.py
+Colour-scale utilities:
+  - make_colormap  : build a three-point diverging LinearSegmentedColormap
+  - node_color     : map numeric node values → hex colour strings
+  - draw_color_key : render a colour-bar legend onto a Matplotlib Axes
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+import matplotlib.pyplot as plt
+import numpy as np
+import polars as pl
+from matplotlib.colors import LinearSegmentedColormap, Normalize
+
+from .constants import SumMethod
+
+
+# ---------------------------------------------------------------------------
+# Colormap construction
+# ---------------------------------------------------------------------------
+
+def make_colormap(
+    low: str = "green",
+    mid: str = "gray",
+    high: str = "red",
+    n: int = 256,
+) -> LinearSegmentedColormap:
+    """
+    Build a three-point diverging colour map: low → mid → high.
+
+    Parameters
+    ----------
+    low, mid, high: Matplotlib colour strings or hex codes.
+    n:              Number of discrete colour levels.
+    """
+    return LinearSegmentedColormap.from_list("pv_cmap", [low, mid, high], N=n)
+
+
+# ---------------------------------------------------------------------------
+# Node colour mapping
+# ---------------------------------------------------------------------------
+
+def node_color(
+    plot_data: pl.DataFrame,
+    limit: float | tuple[float, float] = 1.0,
+    bins: int = 10,
+    both_dirs: bool = True,
+    discrete: bool = False,
+    low: str = "green",
+    mid: str = "gray",
+    high: str = "red",
+    na_col: str = "transparent",
+    trans_fun: Optional[Callable[[np.ndarray], np.ndarray]] = None,
+) -> pl.DataFrame:
+    """
+    Convert numeric node values to hex colour strings.
+
+    Parameters
+    ----------
+    plot_data: DataFrame with an 'id' column and one or more numeric value
+               columns.  Each numeric column produces a paired '*_col' column.
+    limit:     Scalar (symmetric ±limit) or (vmin, vmax) tuple.
+    bins:      Number of colour bins.
+    both_dirs: When True and *limit* is scalar, use ±limit range.
+    discrete:  Reserved for future discrete-colour support.
+    low/mid/high: Colour endpoints.
+    na_col:    Colour string for NaN values (default "transparent").
+    trans_fun: Optional transformation applied to values before colouring.
+
+    Returns a DataFrame with 'id' and one '*_col' column per input value column.
+    """
+    vmin, vmax = _resolve_limits(limit, both_dirs)
+    cmap = make_colormap(low, mid, high, n=bins)
+    norm = Normalize(vmin=vmin, vmax=vmax, clip=True)
+
+    value_cols = [c for c in plot_data.columns if c != "id"]
+    result: dict[str, list] = {"id": plot_data["id"].to_list()}
+
+    #TODO: Quick fix, please verify for accuracy
+    vec = np.vectorize(lambda x: int(x.lstrip("#"), 16) if isinstance(x, str) else x)
+    for col in value_cols:
+        vals = vec(plot_data[col].to_numpy()).astype(float)
+        if trans_fun is not None:
+            vals = trans_fun(vals)
+        result[f"{col}_col"] = [_value_to_hex(v, cmap, norm, na_col) for v in vals]
+
+    return pl.DataFrame(result)
+
+
+def _resolve_limits(
+    limit: float | tuple[float, float],
+    both_dirs: bool,
+) -> tuple[float, float]:
+    """Convert a scalar or tuple limit into (vmin, vmax)."""
+    if isinstance(limit, (int, float)):
+        return (-abs(limit), abs(limit)) if both_dirs else (0.0, float(limit))
+    return float(limit[0]), float(limit[1])
+
+
+def _value_to_hex(
+    v: float,
+    cmap: LinearSegmentedColormap,
+    norm: Normalize,
+    na_col: str,
+) -> str:
+    """Map a single float to a hex colour string, returning *na_col* for NaN."""
+    if np.isnan(v):
+        return na_col
+    r, g, b, _ = cmap(norm(v))
+    return "#{:02X}{:02X}{:02X}".format(int(r * 255), int(g * 255), int(b * 255))
+
+
+# ---------------------------------------------------------------------------
+# Colour-key legend
+# ---------------------------------------------------------------------------
+
+def draw_color_key(
+    ax: plt.Axes,
+    limit: float | tuple[float, float] = 1.0,
+    bins: int = 10,
+    both_dirs: bool = True,
+    discrete: bool = False,
+    low: str = "green",
+    mid: str = "gray",
+    high: str = "red",
+    label_size: float = 8,
+) -> None:
+    """
+    Draw a horizontal colour-bar legend as a Matplotlib colorbar.
+
+    Parameters
+    ----------
+    ax:         Axes on which to anchor the colorbar.
+    limit:      Colour scale limits (scalar or tuple).
+    bins:       Number of colour bins.
+    both_dirs:  Whether to show negative values.
+    label_size: Font size for tick labels.
+    """
+    vmin, vmax = _resolve_limits(limit, both_dirs)
+    cmap = make_colormap(low, mid, high)
+    norm = Normalize(vmin=vmin, vmax=vmax)
+
+    sm = plt.cm.ScalarMappable(cmap=cmap, norm=norm)
+    sm.set_array([])
+
+    cbar = plt.colorbar(sm, ax=ax, orientation="horizontal", fraction=0.046, pad=0.04)
+    ticks = [vmin, (vmin + vmax) / 2.0, vmax]
+    cbar.set_ticks(ticks)
+    cbar.set_ticklabels([f"{t:.2g}" for t in ticks])
+    cbar.ax.tick_params(labelsize=label_size)

pathview/constants.py

@@ -0,0 +1,27 @@
+"""
+constants.py
+Shared type aliases, literals, and package-wide constants.
+"""
+
+from typing import Callable, Literal, Optional
+
+import numpy as np
+
+# KEGG REST base URL
+KEGG_BASE = "https://rest.kegg.jp"
+
+# Supported aggregation methods for multi-probe summarisation
+SumMethod = Literal["sum", "mean", "median", "max", "max_abs", "random"]
+
+# KEGG node types recognised by the renderer
+NodeType = Literal["gene", "compound", "map", "ortholog", "group"]
+
+# Non-data columns present on every node DataFrame
+NODE_META_COLS = frozenset({
+    "entry_id", "name", "type", "x", "y",
+    "width", "height", "label", "shape",
+    "reaction", "component", "size", "kegg_names",
+})
+
+# Valid biological node types (used for filtering)
+VALID_NODE_TYPES = {"gene", "enzyme", "compound", "ortholog"}

pathview/databases.py

@@ -0,0 +1,309 @@
+"""
+databases.py
+Download SBGN-ML files from multiple pathway databases:
+  - Reactome (human pathways)
+  - MetaCyc (metabolic pathways)
+  - PANTHER (protein pathways)
+  - SMPDB (small molecule pathways)
+
+Public API
+----------
+  download_reactome  : Download Reactome pathway
+  download_metacyc   : Download MetaCyc pathway
+  list_pathways      : List available pathways from a database
+"""
+
+from __future__ import annotations
+
+import warnings
+from pathlib import Path
+from typing import Optional
+
+import requests
+
+
+# ---------------------------------------------------------------------------
+# Reactome downloader
+# ---------------------------------------------------------------------------
+
+_REACTOME_BASE = "https://reactome.org/ContentService/exporter/sbgn"
+
+def download_reactome(
+    pathway_id: str,
+    output_dir: Path = Path("."),
+    species: str = "Homo sapiens",
+) -> Optional[Path]:
+    """
+    Download a Reactome pathway in SBGN-ML format.
+    
+    Parameters
+    ----------
+    pathway_id:  Reactome stable ID (e.g., "R-HSA-109582" for Hemostasis)
+    output_dir:  Directory to save the .sbgn file
+    species:     Species name (default: "Homo sapiens")
+    
+    Returns
+    -------
+    Path to downloaded file, or None if download failed
+    
+    Example
+    -------
+    >>> path = download_reactome("R-HSA-109582", output_dir=Path("./pathways"))
+    >>> print(f"Downloaded to {path}")
+    
+    Note
+    ----
+    Reactome pathway IDs follow the format: R-[species code]-[number]
+    - R-HSA-* : Homo sapiens
+    - R-MMU-* : Mus musculus
+    - R-RNO-* : Rattus norvegicus
+    """
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Reactome API endpoint
+    url = f"{_REACTOME_BASE}/{pathway_id}.sbgn"
+    
+    output_path = output_dir / f"{pathway_id}.sbgn"
+    
+    print(f"Info: Downloading Reactome pathway {pathway_id}...")
+    try:
+        resp = requests.get(url, timeout=60)
+        resp.raise_for_status()
+        output_path.write_text(resp.text, encoding="utf-8")
+        print(f"Info: Downloaded → {output_path}")
+        return output_path
+    except Exception as exc:
+        warnings.warn(f"Failed to download {pathway_id}: {exc}")
+        return None
+
+
+# ---------------------------------------------------------------------------
+# MetaCyc downloader
+# ---------------------------------------------------------------------------
+
+_METACYC_BASE = "https://biocyc.org/META/pathway"
+
+def download_metacyc(
+    pathway_id: str,
+    output_dir: Path = Path("."),
+) -> Optional[Path]:
+    """
+    Download a MetaCyc pathway in SBGN-ML format.
+    
+    Parameters
+    ----------
+    pathway_id:  MetaCyc pathway ID (e.g., "PWY-7210" for pyrimidine deoxyribonucleotides biosynthesis)
+    output_dir:  Directory to save the .sbgn file
+    
+    Returns
+    -------
+    Path to downloaded file, or None if download failed
+    
+    Example
+    -------
+    >>> path = download_metacyc("PWY-7210", output_dir=Path("./pathways"))
+    
+    Note
+    ----
+    MetaCyc requires registration for API access. This function uses the
+    public web interface and may not work for all pathways.
+    """
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Try BioCyc SBGN export (may require authentication)
+    url = f"{_METACYC_BASE}?id={pathway_id}&export=sbgn"
+    output_path = output_dir / f"{pathway_id}.sbgn"
+    
+    print(f"Info: Downloading MetaCyc pathway {pathway_id}...")
+    try:
+        resp = requests.get(url, timeout=60)
+        resp.raise_for_status()
+        output_path.write_text(resp.text, encoding="utf-8")
+        print(f"Info: Downloaded → {output_path}")
+        return output_path
+    except Exception as exc:
+        warnings.warn(
+            f"Failed to download {pathway_id}: {exc}\n"
+            "Note: MetaCyc may require authentication for some pathways."
+        )
+        return None
+
+
+# ---------------------------------------------------------------------------
+# PANTHER downloader
+# ---------------------------------------------------------------------------
+
+def download_panther(
+    pathway_id: str,
+    output_dir: Path = Path("."),
+) -> Optional[Path]:
+    """
+    Download a PANTHER pathway in SBGN-ML format.
+    
+    Parameters
+    ----------
+    pathway_id:  PANTHER pathway ID (e.g., "P00001" for p53 pathway)
+    output_dir:  Directory to save the .sbgn file
+    
+    Returns
+    -------
+    Path to downloaded file, or None if download failed
+    
+    Note
+    ----
+    PANTHER pathways use pre-generated SBGN-ML files.
+    This function expects them to be hosted or provided locally.
+    """
+    warnings.warn(
+        "PANTHER SBGN downloads not yet implemented. "
+        "Please download SBGN-ML files manually from PANTHER website."
+    )
+    return None
+
+
+# ---------------------------------------------------------------------------
+# SMPDB downloader
+# ---------------------------------------------------------------------------
+
+_SMPDB_BASE = "https://smpdb.ca/pathways"
+
+def download_smpdb(
+    pathway_id: str,
+    output_dir: Path = Path("."),
+) -> Optional[Path]:
+    """
+    Download an SMPDB (Small Molecule Pathway Database) pathway.
+    
+    Parameters
+    ----------
+    pathway_id:  SMPDB pathway ID (e.g., "SMP0000001" for Glycolysis)
+    output_dir:  Directory to save the .sbgn file
+    
+    Returns
+    -------
+    Path to downloaded file, or None if download failed
+    
+    Note
+    ----
+    SMPDB provides downloadable pathway files. This function may need
+    adjustment based on current SMPDB API availability.
+    """
+    warnings.warn(
+        "SMPDB SBGN downloads not yet fully implemented. "
+        "Check https://smpdb.ca for pathway files."
+    )
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Pathway listing
+# ---------------------------------------------------------------------------
+
+def list_reactome_pathways(species: str = "Homo sapiens") -> list[dict]:
+    """
+    List available Reactome pathways for a species.
+    
+    Parameters
+    ----------
+    species: Species name (e.g., "Homo sapiens", "Mus musculus")
+    
+    Returns
+    -------
+    List of dicts with keys: id, name, species
+    
+    Example
+    -------
+    >>> pathways = list_reactome_pathways("Homo sapiens")
+    >>> for pw in pathways[:5]:
+    ...     print(f"{pw['id']}: {pw['name']}")
+    """
+    url = "https://reactome.org/ContentService/data/pathways/top/Homo%20sapiens"
+    
+    try:
+        resp = requests.get(url, timeout=30)
+        resp.raise_for_status()
+        data = resp.json()
+        
+        pathways = []
+        for item in data:
+            pathways.append({
+                "id": item.get("stId", ""),
+                "name": item.get("displayName", ""),
+                "species": species,
+            })
+        return pathways
+    except Exception as exc:
+        warnings.warn(f"Failed to list Reactome pathways: {exc}")
+        return []
+
+
+# ---------------------------------------------------------------------------
+# Database information
+# ---------------------------------------------------------------------------
+
+DATABASE_INFO = {
+    "reactome": {
+        "name": "Reactome",
+        "description": "Curated human pathway database",
+        "url": "https://reactome.org",
+        "id_pattern": "R-[SPECIES]-[NUMBER]",
+        "example": "R-HSA-109582",
+        "downloader": download_reactome,
+    },
+    "metacyc": {
+        "name": "MetaCyc",
+        "description": "Metabolic pathway database",
+        "url": "https://metacyc.org",
+        "id_pattern": "PWY-[NUMBER]",
+        "example": "PWY-7210",
+        "downloader": download_metacyc,
+    },
+    "panther": {
+        "name": "PANTHER",
+        "description": "Protein analysis through evolutionary relationships",
+        "url": "http://www.pantherdb.org",
+        "id_pattern": "P[NUMBER]",
+        "example": "P00001",
+        "downloader": download_panther,
+    },
+    "smpdb": {
+        "name": "SMPDB",
+        "description": "Small Molecule Pathway Database",
+        "url": "https://smpdb.ca",
+        "id_pattern": "SMP[NUMBER]",
+        "example": "SMP0000001",
+        "downloader": download_smpdb,
+    },
+}
+
+
+def detect_database(pathway_id: str) -> Optional[str]:
+    """
+    Detect which database a pathway ID belongs to.
+    
+    Parameters
+    ----------
+    pathway_id: Pathway identifier
+    
+    Returns
+    -------
+    Database name ("reactome", "metacyc", etc.) or None
+    
+    Example
+    -------
+    >>> detect_database("R-HSA-109582")
+    'reactome'
+    >>> detect_database("PWY-7210")
+    'metacyc'
+    """
+    if pathway_id.startswith("R-") and "-" in pathway_id[2:]:
+        return "reactome"
+    elif pathway_id.startswith("PWY-"):
+        return "metacyc"
+    elif pathway_id.startswith("P") and pathway_id[1:].isdigit():
+        return "panther"
+    elif pathway_id.startswith("SMP"):
+        return "smpdb"
+    return None