bsplot 0.0.2__py3-none-any.whl

bsplot/bioicons.py

@@ -0,0 +1,777 @@
+"""
+Bioicons Interface for matplotlib icon plotting.
+
+This module provides an interface to fetch and plot scientific icons from 
+bioicons.com - a free, open-source library of scientific icons.
+
+The module can be used to annotate any matplotlib axis with scientific icons,
+making it ideal for creating publication-quality figures with consistent
+scientific iconography.
+
+Icons are organized by license/category/author on bioicons.com:
+- Licenses: CC-0, CC-BY-3.0, CC-BY-4.0, CC-BY-SA, MIT, BSD
+- Categories: Amino-Acids, Machine Learning, Animals, Blood Immunology, 
+              Cell culture, Chemistry, Genetics, Lab apparatus, etc.
+
+Usage:
+------
+    from bsplot.bioicons import BioIcons, plot_icon
+    
+    # Initialize the icons interface
+    icons = BioIcons()
+    
+    # Plot a single icon on any matplotlib axis
+    fig, ax = plt.subplots()
+    ax.plot([0, 1, 2], [1, 2, 1])  # Your plot
+    plot_icon("neuron", ax=ax, x=1, y=2, size=0.15)  # Add icon annotation
+    
+    # Or use the icons object for multiple icons
+    icons.plot("brain", ax=ax, x=0.5, y=1.5, size=0.1)
+    
+    # Search for icons
+    icons.search("cell")  # Find all icons with "cell" in the name
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import hashlib
+import warnings
+from pathlib import Path
+from typing import Optional, Union, Dict, Any, List
+from urllib.request import urlopen, Request
+from urllib.error import URLError, HTTPError
+
+import matplotlib.pyplot as plt
+import matplotlib.patches as mpatches
+import matplotlib.image as mpimg
+from matplotlib.offsetbox import OffsetImage, AnnotationBbox
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+import numpy as np
+
+# Try to import optional dependencies
+try:
+    from PIL import Image
+    HAS_PIL = True
+except ImportError:
+    HAS_PIL = False
+
+try:
+    import cairosvg
+    HAS_CAIROSVG = True
+except ImportError:
+    HAS_CAIROSVG = False
+
+
+# Default cache directory for downloaded icons
+DEFAULT_CACHE_DIR = Path.home() / ".cache" / "bsplot" / "bioicons"
+
+# Bioicons.com base URL for icons
+BIOICONS_BASE_URL = "https://bioicons.com/icons"
+BIOICONS_INDEX_URL = "https://bioicons.com/icons/icons.json"
+
+
+class BioIcons:
+    """
+    Interface to fetch and manage bioicons for matplotlib plots.
+    
+    This class provides methods to load, cache, and plot scientific icons
+    from bioicons.com on any matplotlib axis.
+    
+    Parameters
+    ----------
+    cache_dir : str or Path, optional
+        Directory to cache downloaded icons. Defaults to ~/.cache/bsplot/bioicons
+    local_icons_dir : str or Path, optional
+        Directory containing local icon files (SVG or PNG) to use instead of fetching.
+    
+    Examples
+    --------
+    >>> import matplotlib.pyplot as plt
+    >>> from bsplot.bioicons import BioIcons
+    >>> 
+    >>> icons = BioIcons()
+    >>> fig, ax = plt.subplots()
+    >>> ax.plot([0, 1, 2], [1, 2, 1])
+    >>> icons.plot("neuron", ax=ax, x=1, y=2, size=0.15)
+    >>> plt.show()
+    
+    >>> # Search for icons
+    >>> icons.search("cell")
+    >>> 
+    >>> # Get icon by full path
+    >>> icons.plot("cc-0/Genetics/Simon Dürr/neuron", ax=ax, x=0, y=0, size=0.1)
+    """
+
+    def __init__(
+        self,
+        cache_dir: Optional[Union[str, Path]] = None,
+        local_icons_dir: Optional[Union[str, Path]] = None,
+    ):
+        self.cache_dir = Path(cache_dir) if cache_dir else DEFAULT_CACHE_DIR
+        self.local_icons_dir = Path(local_icons_dir) if local_icons_dir else None
+        self._icon_cache: Dict[str, np.ndarray] = {}
+        self._index: Optional[List[Dict[str, str]]] = None
+
+        # Create cache directory if it doesn't exist
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    def _get_cache_path(self, icon_id: str, ext: str = "svg") -> Path:
+        """Get the cache file path for an icon."""
+        # Use hash to handle special characters in icon IDs
+        hash_id = hashlib.md5(icon_id.encode()).hexdigest()[:12]
+        safe_name = icon_id.replace("/", "_").replace(" ", "_")
+        return self.cache_dir / f"{hash_id}_{safe_name}.{ext}"
+
+    def _fetch_index(self) -> List[Dict[str, str]]:
+        """Fetch the icon index from bioicons.com."""
+        if self._index is not None:
+            return self._index
+
+        # Check for cached index
+        index_cache = self.cache_dir / "icons.json"
+        if index_cache.exists():
+            try:
+                with open(index_cache, "r") as f:
+                    self._index = json.load(f)
+                    return self._index
+            except (json.JSONDecodeError, IOError):
+                pass
+
+        # Fetch from remote
+        try:
+            req = Request(
+                BIOICONS_INDEX_URL,
+                headers={"User-Agent": "bsplot/1.0"}
+            )
+            with urlopen(req, timeout=10) as response:
+                data = response.read().decode("utf-8")
+                self._index = json.loads(data)
+
+                # Cache the index
+                with open(index_cache, "w") as f:
+                    f.write(data)
+
+                return self._index
+        except (URLError, HTTPError) as e:
+            warnings.warn(f"Failed to fetch icon index: {e}")
+            return []
+        except Exception as e:
+            warnings.warn(f"Error processing icon index: {e}")
+            return []
+
+    def search(self, query: str, category: Optional[str] = None,
+               license: Optional[str] = None) -> List[Dict[str, str]]:
+        """
+        Search for icons matching the query.
+        
+        Parameters
+        ----------
+        query : str
+            Search query (matches icon name, category, or author)
+        category : str, optional
+            Filter by category
+        license : str, optional
+            Filter by license type (e.g., "cc-0", "cc-by")
+            
+        Returns
+        -------
+        list of dict
+            List of matching icons with keys: name, category, license, author
+        """
+        index = self._fetch_index()
+        query_lower = query.lower()
+
+        results = []
+        for icon in index:
+            # Match query against name, category, or author
+            if (query_lower in icon.get("name", "").lower() or
+                query_lower in icon.get("category", "").lower() or
+                query_lower in icon.get("author", "").lower()):
+
+                # Apply filters
+                if category and icon.get("category", "").lower() != category.lower():
+                    continue
+                if license and license.lower() not in icon.get("license", "").lower():
+                    continue
+
+                results.append(icon)
+
+        return results
+
+    def list_categories(self) -> List[str]:
+        """Get list of all available icon categories."""
+        index = self._fetch_index()
+        categories = set(icon.get("category", "") for icon in index)
+        return sorted(cat for cat in categories if cat)
+
+    def list_licenses(self) -> List[str]:
+        """Get list of all available licenses."""
+        index = self._fetch_index()
+        licenses = set(icon.get("license", "") for icon in index)
+        return sorted(lic for lic in licenses if lic)
+
+    def _build_icon_url(self, icon_info: Dict[str, str]) -> str:
+        """Build the URL for an icon from its info dict."""
+        license_dir = icon_info.get("license", "").replace(" ", "%20")
+        category = icon_info.get("category", "").replace(" ", "%20")
+        author = icon_info.get("author", "").replace(" ", "%20")
+        name = icon_info.get("name", "").replace(" ", "%20")
+
+        return f"{BIOICONS_BASE_URL}/{license_dir}/{category}/{author}/{name}.svg"
+
+    def _find_icon(self, icon_name: str) -> Optional[Dict[str, str]]:
+        """
+        Find an icon by name in the index.
+        
+        If icon_name contains '/', treat it as a full path.
+        Otherwise, search by name and return the first match.
+        """
+        # Check if it's a full path
+        if "/" in icon_name:
+            parts = icon_name.split("/")
+            if len(parts) == 4:
+                return {
+                    "license": parts[0],
+                    "category": parts[1],
+                    "author": parts[2],
+                    "name": parts[3].replace(".svg", ""),
+                }
+
+        # Search by name
+        index = self._fetch_index()
+        for icon in index:
+            if icon.get("name", "").lower() == icon_name.lower():
+                return icon
+            # Also match without extension
+            if icon.get("name", "").lower().replace(".svg", "") == icon_name.lower():
+                return icon
+
+        # Partial match
+        for icon in index:
+            if icon_name.lower() in icon.get("name", "").lower():
+                return icon
+
+        return None
+
+    def _load_from_local(self, icon_name: str) -> Optional[np.ndarray]:
+        """Try to load icon from local icons directory."""
+        if self.local_icons_dir is None:
+            return None
+
+        # Try different file extensions
+        for ext in ["svg", "png", "jpg", "jpeg"]:
+            icon_path = self.local_icons_dir / f"{icon_name}.{ext}"
+            if icon_path.exists():
+                return self._load_image_file(icon_path)
+        return None
+
+    def _load_from_cache(self, icon_id: str) -> Optional[np.ndarray]:
+        """Try to load icon from cache."""
+        for ext in ["png", "svg"]:
+            cache_path = self._get_cache_path(icon_id, ext)
+            if cache_path.exists():
+                return self._load_image_file(cache_path)
+        return None
+
+    def _load_image_file(self, path: Path) -> np.ndarray:
+        """Load an image file and return as numpy array."""
+        if path.suffix.lower() == ".svg":
+            return self._load_svg(path)
+        else:
+            if HAS_PIL:
+                img = Image.open(path).convert("RGBA")
+                return np.array(img)
+            else:
+                return mpimg.imread(str(path))
+
+    def _load_svg(self, path: Path) -> np.ndarray:
+        """Load SVG file and convert to numpy array."""
+        if not HAS_CAIROSVG:
+            raise ImportError(
+                "cairosvg is required to load SVG files. "
+                "Install with: pip install cairosvg"
+            )
+        if not HAS_PIL:
+            raise ImportError(
+                "PIL is required to process images. "
+                "Install with: pip install pillow"
+            )
+
+        # Convert SVG to PNG in memory
+        # unsafe=True allows SVGs with external entities (some bioicons use these)
+        png_data = cairosvg.svg2png(
+            url=str(path), output_width=256, output_height=256, unsafe=True
+        )
+        img = Image.open(io.BytesIO(png_data)).convert("RGBA")
+        return np.array(img)
+
+    def _load_svg_from_bytes(self, svg_data: bytes) -> np.ndarray:
+        """Load SVG from bytes and convert to numpy array."""
+        if not HAS_CAIROSVG:
+            raise ImportError(
+                "cairosvg is required to load SVG files. "
+                "Install with: pip install cairosvg"
+            )
+        if not HAS_PIL:
+            raise ImportError(
+                "PIL is required to process images. "
+                "Install with: pip install pillow"
+            )
+
+        # Convert SVG to PNG in memory
+        # unsafe=True allows SVGs with external entities (some bioicons use these)
+        png_data = cairosvg.svg2png(
+            bytestring=svg_data, output_width=256, output_height=256, unsafe=True
+        )
+        img = Image.open(io.BytesIO(png_data)).convert("RGBA")
+        return np.array(img)
+
+    def _fetch_icon(self, icon_name: str) -> Optional[np.ndarray]:
+        """
+        Fetch icon from bioicons.com.
+        """
+        # Check in-memory cache first
+        if icon_name in self._icon_cache:
+            return self._icon_cache[icon_name]
+
+        # Check local directory
+        img = self._load_from_local(icon_name)
+        if img is not None:
+            self._icon_cache[icon_name] = img
+            return img
+
+        # Check file cache
+        img = self._load_from_cache(icon_name)
+        if img is not None:
+            self._icon_cache[icon_name] = img
+            return img
+
+        # Find icon in index
+        icon_info = self._find_icon(icon_name)
+        if icon_info is None:
+            warnings.warn(
+                f"Icon '{icon_name}' not found. Use search() to find available icons."
+            )
+            return None
+
+        # Build URL and fetch
+        url = self._build_icon_url(icon_info)
+
+        try:
+            req = Request(url, headers={"User-Agent": "bsplot/1.0"})
+            with urlopen(req, timeout=10) as response:
+                if response.status == 200:
+                    svg_data = response.read()
+
+                    # Cache the SVG
+                    cache_path = self._get_cache_path(icon_name, "svg")
+                    with open(cache_path, "wb") as f:
+                        f.write(svg_data)
+
+                    # Convert to numpy array
+                    img = self._load_svg_from_bytes(svg_data)
+                    self._icon_cache[icon_name] = img
+                    return img
+
+        except (URLError, HTTPError) as e:
+            warnings.warn(f"Failed to fetch icon '{icon_name}': {e}")
+        except ImportError as e:
+            warnings.warn(str(e))
+        except Exception as e:
+            warnings.warn(f"Error processing icon '{icon_name}': {e}")
+
+        return None
+
+    def get_icon(self, icon_name: str) -> Optional[np.ndarray]:
+        """
+        Get an icon as a numpy array.
+        
+        Parameters
+        ----------
+        icon_name : str
+            Name of the icon to fetch. Can be:
+            - A simple name like "neuron" (will search and use first match)
+            - A full path like "cc-0/Genetics/Simon Dürr/neuron"
+            
+        Returns
+        -------
+        np.ndarray or None
+            Icon as RGBA numpy array, or None if not found
+        """
+        return self._fetch_icon(icon_name)
+
+    def _create_placeholder(
+        self,
+        icon_name: str,
+        size: int = 64,
+        color: str = "#4a90e2",
+    ) -> np.ndarray:
+        """Create a placeholder icon when the actual icon is not available."""
+        if not HAS_PIL:
+            # Return a simple colored square
+            arr = np.ones((size, size, 4), dtype=np.float32)
+            if color.startswith("#"):
+                r = int(color[1:3], 16) / 255
+                g = int(color[3:5], 16) / 255
+                b = int(color[5:7], 16) / 255
+            else:
+                r, g, b = 0.3, 0.6, 0.9
+            arr[:, :, 0] = r
+            arr[:, :, 1] = g
+            arr[:, :, 2] = b
+            arr[:, :, 3] = 0.8
+            return arr
+
+        from PIL import Image, ImageDraw
+
+        img = Image.new("RGBA", (size, size), (255, 255, 255, 0))
+        draw = ImageDraw.Draw(img)
+
+        # Parse color
+        if color.startswith("#"):
+            r = int(color[1:3], 16)
+            g = int(color[3:5], 16)
+            b = int(color[5:7], 16)
+            fill_color = (r, g, b, 200)
+        else:
+            fill_color = (74, 144, 226, 200)
+
+        # Draw a rounded rectangle
+        margin = size // 8
+        draw.rounded_rectangle(
+            [margin, margin, size - margin, size - margin],
+            radius=size // 6,
+            fill=fill_color,
+        )
+
+        # Add first letter of icon name
+        letter = icon_name[0].upper() if icon_name else "?"
+        bbox = draw.textbbox((0, 0), letter)
+        text_w = bbox[2] - bbox[0]
+        text_h = bbox[3] - bbox[1]
+        text_x = (size - text_w) // 2
+        text_y = (size - text_h) // 2 - 2
+        draw.text((text_x, text_y), letter, fill=(255, 255, 255, 255))
+
+        return np.array(img)
+
+    def plot(
+        self,
+        icon_name: str,
+        ax: Optional[Axes] = None,
+        x: float = 0.5,
+        y: float = 0.5,
+        size: float = 0.1,
+        zoom: float = 1.0,
+        alpha: float = 1.0,
+        zorder: int = 10,
+        frameon: bool = False,
+        box_alignment: tuple = (0.5, 0.5),
+        xycoords: str = "data",
+        **kwargs,
+    ) -> Optional[AnnotationBbox]:
+        """
+        Plot an icon on a matplotlib axis.
+        
+        Parameters
+        ----------
+        icon_name : str
+            Name or path of the icon to plot
+        ax : matplotlib.axes.Axes, optional
+            Axis to plot on. If None, uses current axis.
+        x : float
+            X coordinate for icon placement
+        y : float
+            Y coordinate for icon placement
+        size : float
+            Size of the icon relative to the figure (default 0.1)
+        zoom : float
+            Additional zoom factor (default 1.0)
+        alpha : float
+            Transparency (0-1, default 1.0)
+        zorder : int
+            Z-order for layering (default 10)
+        frameon : bool
+            Whether to show a frame around the icon (default False)
+        box_alignment : tuple
+            Alignment of the icon box (default (0.5, 0.5) for center)
+        xycoords : str
+            Coordinate system for x, y (default "data")
+        **kwargs
+            Additional arguments passed to AnnotationBbox
+            
+        Returns
+        -------
+        AnnotationBbox or None
+            The annotation box artist, or None if icon not found
+        """
+        if ax is None:
+            ax = plt.gca()
+
+        # Get icon image
+        img = self._fetch_icon(icon_name)
+        if img is None:
+            # Use placeholder
+            warnings.warn(f"Using placeholder for '{icon_name}'")
+            img = self._create_placeholder(icon_name)
+
+        # Calculate zoom based on desired size
+        fig = ax.get_figure()
+        fig_width, fig_height = fig.get_size_inches()
+        dpi = fig.dpi
+
+        # Target size in pixels
+        target_size = size * min(fig_width, fig_height) * dpi
+        current_size = max(img.shape[:2])
+        calculated_zoom = (target_size / current_size) * zoom
+
+        # Create offset image
+        imagebox = OffsetImage(img, zoom=calculated_zoom, alpha=alpha)
+
+        # Create annotation box
+        ab = AnnotationBbox(
+            imagebox,
+            (x, y),
+            xycoords=xycoords,
+            frameon=frameon,
+            box_alignment=box_alignment,
+            zorder=zorder,
+            **kwargs,
+        )
+
+        ax.add_artist(ab)
+        return ab
+
+    def plot_grid(
+        self,
+        icon_names: List[str],
+        ncols: int = 4,
+        figsize: Optional[tuple] = None,
+        show_labels: bool = True,
+        title: Optional[str] = None,
+    ) -> Figure:
+        """
+        Plot a grid of icons.
+        
+        Parameters
+        ----------
+        icon_names : list of str
+            Names of icons to plot
+        ncols : int
+            Number of columns in the grid
+        figsize : tuple, optional
+            Figure size (width, height) in inches
+        show_labels : bool
+            Whether to show icon names below each icon
+        title : str, optional
+            Title for the figure
+            
+        Returns
+        -------
+        matplotlib.figure.Figure
+            The figure containing the icon grid
+        """
+        n_icons = len(icon_names)
+        nrows = (n_icons + ncols - 1) // ncols
+
+        if figsize is None:
+            figsize = (ncols * 2, nrows * (2.5 if show_labels else 2))
+
+        fig, axes = plt.subplots(nrows, ncols, figsize=figsize)
+        if nrows == 1 and ncols == 1:
+            axes = np.array([[axes]])
+        elif nrows == 1:
+            axes = axes.reshape(1, -1)
+        elif ncols == 1:
+            axes = axes.reshape(-1, 1)
+
+        for idx, name in enumerate(icon_names):
+            row = idx // ncols
+            col = idx % ncols
+            ax = axes[row, col]
+
+            img = self._fetch_icon(name)
+            if img is None:
+                img = self._create_placeholder(name)
+
+            ax.imshow(img)
+            ax.axis("off")
+
+            if show_labels:
+                ax.set_title(name, fontsize=9, wrap=True)
+
+        # Hide empty subplots
+        for idx in range(n_icons, nrows * ncols):
+            row = idx // ncols
+            col = idx % ncols
+            axes[row, col].axis("off")
+
+        if title:
+            fig.suptitle(title, fontsize=14)
+
+        plt.tight_layout()
+        return fig
+
+
+class IconAnnotation:
+    """
+    Helper class for annotating matplotlib plots with icons.
+    
+    This class provides a simpler interface for adding icons as annotations
+    to existing matplotlib figures.
+    
+    Parameters
+    ----------
+    icons : BioIcons, optional
+        BioIcons instance to use. If None, creates a new one.
+    """
+
+    def __init__(self, icons: Optional[BioIcons] = None):
+        self.icons = icons or BioIcons()
+
+    def annotate(
+        self,
+        ax: Axes,
+        icon_name: str,
+        xy: tuple,
+        size: float = 0.1,
+        **kwargs,
+    ) -> Optional[AnnotationBbox]:
+        """
+        Add an icon annotation to an axis.
+        
+        Parameters
+        ----------
+        ax : matplotlib.axes.Axes
+            Axis to annotate
+        icon_name : str
+            Name of the icon
+        xy : tuple
+            (x, y) position for the icon
+        size : float
+            Size of the icon
+        **kwargs
+            Additional arguments passed to BioIcons.plot()
+        """
+        return self.icons.plot(icon_name, ax=ax, x=xy[0], y=xy[1], size=size, **kwargs)
+
+
+# Module-level convenience functions
+
+_default_icons: Optional[BioIcons] = None
+
+
+def _get_default_icons() -> BioIcons:
+    """Get or create the default BioIcons instance."""
+    global _default_icons
+    if _default_icons is None:
+        _default_icons = BioIcons()
+    return _default_icons
+
+
+def plot_icon(
+    icon_name: str,
+    ax: Optional[Axes] = None,
+    x: float = 0.5,
+    y: float = 0.5,
+    size: float = 0.1,
+    **kwargs,
+) -> Optional[AnnotationBbox]:
+    """
+    Plot an icon on a matplotlib axis.
+    
+    This is a convenience function that uses the default BioIcons instance.
+    
+    Parameters
+    ----------
+    icon_name : str
+        Name or path of the icon to plot
+    ax : matplotlib.axes.Axes, optional
+        Axis to plot on. If None, uses current axis.
+    x : float
+        X coordinate for icon placement
+    y : float
+        Y coordinate for icon placement  
+    size : float
+        Size of the icon relative to the figure (default 0.1)
+    **kwargs
+        Additional arguments passed to BioIcons.plot()
+        
+    Returns
+    -------
+    AnnotationBbox or None
+        The annotation box artist, or None if icon not found
+        
+    Examples
+    --------
+    >>> import matplotlib.pyplot as plt
+    >>> from bsplot.bioicons import plot_icon
+    >>> 
+    >>> fig, ax = plt.subplots()
+    >>> ax.plot([0, 1, 2], [0, 1, 0])
+    >>> plot_icon("neuron", ax=ax, x=1, y=1, size=0.15)
+    >>> plt.show()
+    """
+    icons = _get_default_icons()
+    return icons.plot(icon_name, ax=ax, x=x, y=y, size=size, **kwargs)
+
+
+def plot_icons_grid(
+    icon_names: List[str],
+    ncols: int = 4,
+    **kwargs,
+) -> Figure:
+    """
+    Plot a grid of icons.
+    
+    Parameters
+    ----------
+    icon_names : list of str
+        Names of icons to plot
+    ncols : int
+        Number of columns in the grid
+    **kwargs
+        Additional arguments passed to BioIcons.plot_grid()
+        
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The figure containing the icon grid
+    """
+    icons = _get_default_icons()
+    return icons.plot_grid(icon_names, ncols=ncols, **kwargs)
+
+
+def search_icons(query: str, **kwargs) -> List[Dict[str, str]]:
+    """
+    Search for icons matching the query.
+    
+    Parameters
+    ----------
+    query : str
+        Search query
+    **kwargs
+        Additional arguments passed to BioIcons.search()
+        
+    Returns
+    -------
+    list of dict
+        Matching icons
+    """
+    icons = _get_default_icons()
+    return icons.search(query, **kwargs)
+
+
+def list_categories() -> List[str]:
+    """Get list of all available icon categories."""
+    icons = _get_default_icons()
+    return icons.list_categories()
+
+
+def list_licenses() -> List[str]:
+    """Get list of all available licenses."""
+    icons = _get_default_icons()
+    return icons.list_licenses()