pylocuszoom 0.6.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

pylocuszoom/backends/base.py

@@ -3,7 +3,7 @@
 Defines the interface that matplotlib, plotly, and bokeh backends must implement.
 """
 
-from typing import Any, List, Optional, Protocol, Tuple, Union
+from typing import Any, Callable, List, Optional, Protocol, Tuple, Union
 
 import pandas as pd
 
@@ -13,8 +13,48 @@ class PlotBackend(Protocol):
 
     All backends (matplotlib, plotly, bokeh) must implement these methods
     to enable consistent plotting across different rendering engines.
+
+    Capability Properties:
+        supports_snp_labels: Whether backend supports text labels via adjustText.
+        supports_hover: Whether backend supports hover tooltips.
+        supports_secondary_axis: Whether backend supports twin y-axis for overlays.
     """
 
+    # =========================================================================
+    # Capability Properties
+    # =========================================================================
+
+    @property
+    def supports_snp_labels(self) -> bool:
+        """Whether backend supports text labels via adjustText.
+
+        Matplotlib supports SNP labels using adjustText for automatic repositioning.
+        Interactive backends (Plotly, Bokeh) use hover tooltips instead.
+        """
+        ...
+
+    @property
+    def supports_hover(self) -> bool:
+        """Whether backend supports hover tooltips.
+
+        Interactive backends (Plotly, Bokeh) support hover tooltips.
+        Matplotlib does not support hover - use SNP labels instead.
+        """
+        ...
+
+    @property
+    def supports_secondary_axis(self) -> bool:
+        """Whether backend supports twin y-axis for recombination overlay.
+
+        All current backends support secondary axes, but this allows for
+        future backends that may not.
+        """
+        ...
+
+    # =========================================================================
+    # Figure Creation
+    # =========================================================================
+
     def create_figure(
         self,
         n_panels: int,
@@ -35,6 +75,31 @@ class PlotBackend(Protocol):
         """
         ...
 
+    def finalize_layout(
+        self,
+        fig: Any,
+        left: float = 0.08,
+        right: float = 0.95,
+        top: float = 0.95,
+        bottom: float = 0.1,
+        hspace: float = 0.08,
+    ) -> None:
+        """Finalize figure layout with margins and spacing.
+
+        Args:
+            fig: Figure object.
+            left: Left margin fraction.
+            right: Right margin fraction.
+            top: Top margin fraction.
+            bottom: Bottom margin fraction.
+            hspace: Vertical space between subplots.
+        """
+        ...
+
+    # =========================================================================
+    # Basic Plotting
+    # =========================================================================
+
     def scatter(
         self,
         ax: Any,
@@ -151,6 +216,36 @@ class PlotBackend(Protocol):
         """
         ...
 
+    def axvline(
+        self,
+        ax: Any,
+        x: float,
+        color: str = "grey",
+        linestyle: str = "--",
+        linewidth: float = 1.0,
+        alpha: float = 1.0,
+        zorder: int = 1,
+    ) -> Any:
+        """Add a vertical line across the axes.
+
+        Args:
+            ax: Axes or panel.
+            x: X-value for the line.
+            color: Line color.
+            linestyle: Line style.
+            linewidth: Line width.
+            alpha: Line transparency (0-1).
+            zorder: Drawing order.
+
+        Returns:
+            The line object.
+        """
+        ...
+
+    # =========================================================================
+    # Text and Annotations
+    # =========================================================================
+
     def add_text(
         self,
         ax: Any,
@@ -181,6 +276,57 @@ class PlotBackend(Protocol):
         """
         ...
 
+    def add_panel_label(
+        self,
+        ax: Any,
+        label: str,
+        x_frac: float = 0.02,
+        y_frac: float = 0.95,
+    ) -> None:
+        """Add label text at fractional position in panel.
+
+        Used for panel letters (A, B, C) in multi-panel figures.
+
+        Args:
+            ax: Axes or panel.
+            label: Label text (e.g., "A", "B").
+            x_frac: Horizontal position as fraction of axes (0-1).
+            y_frac: Vertical position as fraction of axes (0-1).
+        """
+        ...
+
+    def add_snp_labels(
+        self,
+        ax: Any,
+        df: pd.DataFrame,
+        pos_col: str,
+        neglog10p_col: str,
+        rs_col: str,
+        label_top_n: int,
+        genes_df: Optional[pd.DataFrame],
+        chrom: int,
+    ) -> None:
+        """Add SNP labels to plot.
+
+        No-op if supports_snp_labels=False. Matplotlib uses adjustText
+        for automatic label repositioning to avoid overlaps.
+
+        Args:
+            ax: Axes or panel.
+            df: DataFrame with SNP data.
+            pos_col: Column name for position.
+            neglog10p_col: Column name for -log10(p-value).
+            rs_col: Column name for SNP ID.
+            label_top_n: Number of top SNPs to label.
+            genes_df: Gene annotations (unused, for signature compatibility).
+            chrom: Chromosome number (unused, for signature compatibility).
+        """
+        ...
+
+    # =========================================================================
+    # Shapes and Patches
+    # =========================================================================
+
     def add_rectangle(
         self,
         ax: Any,
@@ -209,6 +355,36 @@ class PlotBackend(Protocol):
         """
         ...
 
+    def add_polygon(
+        self,
+        ax: Any,
+        points: List[List[float]],
+        facecolor: str = "blue",
+        edgecolor: str = "black",
+        linewidth: float = 0.5,
+        zorder: int = 2,
+    ) -> Any:
+        """Add polygon patch to axes.
+
+        Used for gene track directional arrows.
+
+        Args:
+            ax: Axes or panel.
+            points: List of [x, y] coordinate pairs forming the polygon.
+            facecolor: Fill color.
+            edgecolor: Edge color.
+            linewidth: Edge width.
+            zorder: Drawing order.
+
+        Returns:
+            The polygon object.
+        """
+        ...
+
+    # =========================================================================
+    # Axis Configuration
+    # =========================================================================
+
     def set_xlim(self, ax: Any, left: float, right: float) -> None:
         """Set x-axis limits.
 
@@ -249,6 +425,23 @@ class PlotBackend(Protocol):
         """
         ...
 
+    def set_yticks(
+        self,
+        ax: Any,
+        positions: List[float],
+        labels: List[str],
+        fontsize: int = 10,
+    ) -> None:
+        """Set y-axis tick positions and labels.
+
+        Args:
+            ax: Axes or panel.
+            positions: Tick positions.
+            labels: Tick labels.
+            fontsize: Font size.
+        """
+        ...
+
     def set_title(self, ax: Any, title: str, fontsize: int = 14) -> None:
         """Set panel title.
 
@@ -259,6 +452,38 @@ class PlotBackend(Protocol):
         """
         ...
 
+    def hide_spines(self, ax: Any, spines: List[str]) -> None:
+        """Hide specified axis spines.
+
+        Args:
+            ax: Axes or panel.
+            spines: List of spine names ('top', 'right', 'bottom', 'left').
+        """
+        ...
+
+    def hide_yaxis(self, ax: Any) -> None:
+        """Hide y-axis for gene track panels.
+
+        Hides y-axis ticks, labels, and line. Gene tracks don't need
+        a y-axis since the vertical position is just for layout.
+
+        Args:
+            ax: Axes or panel.
+        """
+        ...
+
+    def format_xaxis_mb(self, ax: Any) -> None:
+        """Format x-axis to show megabase values.
+
+        Args:
+            ax: Axes or panel.
+        """
+        ...
+
+    # =========================================================================
+    # Secondary Y-Axis (for recombination overlay)
+    # =========================================================================
+
     def create_twin_axis(self, ax: Any) -> Any:
         """Create a secondary y-axis sharing the same x-axis.
 
@@ -270,75 +495,138 @@ class PlotBackend(Protocol):
         """
         ...
 
-    def add_legend(
+    def line_secondary(
         self,
         ax: Any,
-        handles: List[Any],
-        labels: List[str],
-        loc: str = "upper left",
-        title: Optional[str] = None,
+        x: pd.Series,
+        y: pd.Series,
+        color: str = "blue",
+        linewidth: float = 1.5,
+        alpha: float = 1.0,
+        linestyle: str = "-",
+        label: Optional[str] = None,
+        yaxis_name: Any = None,
     ) -> Any:
-        """Add a legend to the axes.
+        """Create line on secondary y-axis.
 
         Args:
-            ax: Axes or panel.
-            handles: Legend handle objects.
-            labels: Legend labels.
-            loc: Legend location.
-            title: Legend title.
+            ax: Axes or panel (may be tuple for Plotly).
+            x: X-axis values.
+            y: Y-axis values.
+            color: Line color.
+            linewidth: Line width.
+            alpha: Transparency.
+            linestyle: Line style.
+            label: Legend label.
+            yaxis_name: Backend-specific secondary axis identifier.
 
         Returns:
-            The legend object.
+            The line object.
         """
         ...
 
-    def hide_spines(self, ax: Any, spines: List[str]) -> None:
-        """Hide specified axis spines.
+    def fill_between_secondary(
+        self,
+        ax: Any,
+        x: pd.Series,
+        y1: Union[float, pd.Series],
+        y2: Union[float, pd.Series],
+        color: str = "blue",
+        alpha: float = 0.3,
+        yaxis_name: Any = None,
+    ) -> Any:
+        """Fill area on secondary y-axis.
 
         Args:
             ax: Axes or panel.
-            spines: List of spine names ('top', 'right', 'bottom', 'left').
+            x: X-axis values.
+            y1: Lower y boundary.
+            y2: Upper y boundary.
+            color: Fill color.
+            alpha: Transparency.
+            yaxis_name: Backend-specific secondary axis identifier.
+
+        Returns:
+            The fill object.
         """
         ...
 
-    def format_xaxis_mb(self, ax: Any) -> None:
-        """Format x-axis to show megabase values.
+    def set_secondary_ylim(
+        self,
+        ax: Any,
+        bottom: float,
+        top: float,
+        yaxis_name: Any = None,
+    ) -> None:
+        """Set secondary y-axis limits.
 
         Args:
             ax: Axes or panel.
+            bottom: Minimum y value.
+            top: Maximum y value.
+            yaxis_name: Backend-specific secondary axis identifier.
         """
         ...
 
-    def save(
+    def set_secondary_ylabel(
         self,
-        fig: Any,
-        path: str,
-        dpi: int = 150,
-        bbox_inches: str = "tight",
+        ax: Any,
+        label: str,
+        color: str = "black",
+        fontsize: int = 10,
+        yaxis_name: Any = None,
     ) -> None:
-        """Save figure to file.
+        """Set secondary y-axis label.
 
         Args:
-            fig: Figure object.
-            path: Output file path (.png, .pdf, .html).
-            dpi: Resolution for raster formats.
-            bbox_inches: Bounding box adjustment.
+            ax: Axes or panel.
+            label: Label text.
+            color: Label color.
+            fontsize: Font size.
+            yaxis_name: Backend-specific secondary axis identifier.
         """
         ...
 
-    def show(self, fig: Any) -> None:
-        """Display the figure.
+    # =========================================================================
+    # Legends
+    # =========================================================================
+
+    def add_legend(
+        self,
+        ax: Any,
+        handles: List[Any],
+        labels: List[str],
+        loc: str = "upper left",
+        title: Optional[str] = None,
+    ) -> Any:
+        """Add a legend to the axes.
 
         Args:
-            fig: Figure object.
+            ax: Axes or panel.
+            handles: Legend handle objects.
+            labels: Legend labels.
+            loc: Legend location.
+            title: Legend title.
+
+        Returns:
+            The legend object.
         """
         ...
 
-    def close(self, fig: Any) -> None:
-        """Close the figure and free resources.
+    def add_ld_legend(
+        self,
+        ax: Any,
+        ld_bins: List[Tuple[float, str, str]],
+        lead_snp_color: str,
+    ) -> None:
+        """Add LD color legend.
+
+        Shows the linkage disequilibrium (r^2) color scale and lead SNP marker.
 
         Args:
-            fig: Figure object.
+            ax: Axes or panel.
+            ld_bins: List of (threshold, label, color) tuples defining LD bins.
+            lead_snp_color: Color for lead SNP marker in legend.
         """
         ...
 
@@ -361,7 +649,7 @@ class PlotBackend(Protocol):
         self,
         ax: Any,
         credible_sets: List[int],
-        get_color_func: Any,
+        get_color_func: Callable[[int], str],
     ) -> None:
         """Add fine-mapping credible set legend to the axes.
 
@@ -387,31 +675,9 @@ class PlotBackend(Protocol):
         """
         ...
 
-    def axvline(
-        self,
-        ax: Any,
-        x: float,
-        color: str = "grey",
-        linestyle: str = "--",
-        linewidth: float = 1.0,
-        alpha: float = 1.0,
-        zorder: int = 1,
-    ) -> Any:
-        """Add a vertical line across the axes.
-
-        Args:
-            ax: Axes or panel.
-            x: X-value for the line.
-            color: Line color.
-            linestyle: Line style.
-            linewidth: Line width.
-            alpha: Line transparency (0-1).
-            zorder: Drawing order.
-
-        Returns:
-            The line object.
-        """
-        ...
+    # =========================================================================
+    # Specialized Charts
+    # =========================================================================
 
     def hbar(
         self,
@@ -472,3 +738,40 @@ class PlotBackend(Protocol):
             The errorbar object.
         """
         ...
+
+    # =========================================================================
+    # File Operations
+    # =========================================================================
+
+    def save(
+        self,
+        fig: Any,
+        path: str,
+        dpi: int = 150,
+        bbox_inches: str = "tight",
+    ) -> None:
+        """Save figure to file.
+
+        Args:
+            fig: Figure object.
+            path: Output file path (.png, .pdf, .html).
+            dpi: Resolution for raster formats.
+            bbox_inches: Bounding box adjustment.
+        """
+        ...
+
+    def show(self, fig: Any) -> None:
+        """Display the figure.
+
+        Args:
+            fig: Figure object.
+        """
+        ...
+
+    def close(self, fig: Any) -> None:
+        """Close the figure and free resources.
+
+        Args:
+            fig: Figure object.
+        """
+        ...

pylocuszoom/backends/bokeh_backend.py

@@ -11,7 +11,10 @@ from bokeh.layouts import column
 from bokeh.models import ColumnDataSource, DataRange1d, HoverTool, Span
 from bokeh.plotting import figure
 
+from . import convert_latex_to_unicode, register_backend
 
+
+@register_backend("bokeh")
 class BokehBackend:
     """Bokeh backend for interactive plot generation.
 
@@ -34,9 +37,20 @@ class BokehBackend:
         "-.": "dashdot",
     }
 
-    def __init__(self) -> None:
-        """Initialize the bokeh backend."""
-        pass
+    @property
+    def supports_snp_labels(self) -> bool:
+        """Bokeh uses hover tooltips instead of labels."""
+        return False
+
+    @property
+    def supports_hover(self) -> bool:
+        """Bokeh supports hover tooltips."""
+        return True
+
+    @property
+    def supports_secondary_axis(self) -> bool:
+        """Bokeh supports secondary y-axis."""
+        return True
 
     def create_figure(
         self,
@@ -356,6 +370,18 @@ class BokehBackend:
         ax.yaxis.axis_label = label
         ax.yaxis.axis_label_text_font_size = f"{fontsize}pt"
 
+    def set_yticks(
+        self,
+        ax: figure,
+        positions: List[float],
+        labels: List[str],
+        fontsize: int = 10,
+    ) -> None:
+        """Set y-axis tick positions and labels."""
+        ax.yaxis.ticker = positions
+        ax.yaxis.major_label_overrides = dict(zip(positions, labels))
+        ax.yaxis.major_label_text_font_size = f"{fontsize}pt"
+
     def _get_legend_location(self, loc: str, default: str = "top_left") -> str:
         """Map matplotlib-style legend location to Bokeh location."""
         loc_map = {
@@ -368,18 +394,7 @@ class BokehBackend:
 
     def _convert_label(self, label: str) -> str:
         """Convert LaTeX-style labels to Unicode for Bokeh display."""
-        conversions = [
-            (r"$-\log_{10}$ P", "-log₁₀(P)"),
-            (r"$-\log_{10}$", "-log₁₀"),
-            (r"\log_{10}", "log₁₀"),
-            (r"$r^2$", "r²"),
-            (r"$R^2$", "R²"),
-        ]
-        for latex, unicode_str in conversions:
-            if latex in label:
-                label = label.replace(latex, unicode_str)
-        label = label.replace("$", "")
-        return label
+        return convert_latex_to_unicode(label)
 
     def set_title(self, ax: figure, title: str, fontsize: int = 14) -> None:
         """Set figure title."""
@@ -489,6 +504,53 @@ class BokehBackend:
                 renderer.major_label_text_color = color
                 break
 
+    def add_snp_labels(
+        self,
+        ax: figure,
+        df: pd.DataFrame,
+        pos_col: str,
+        neglog10p_col: str,
+        rs_col: str,
+        label_top_n: int,
+        genes_df: Optional[pd.DataFrame],
+        chrom: int,
+    ) -> None:
+        """No-op: Bokeh uses hover tooltips instead of text labels."""
+        pass
+
+    def add_panel_label(
+        self,
+        ax: figure,
+        label: str,
+        x_frac: float = 0.02,
+        y_frac: float = 0.95,
+    ) -> None:
+        """Add label text at fractional position in panel."""
+        from bokeh.models import Label
+
+        # Convert fraction to data coordinates using axis ranges
+        x_range = ax.x_range
+        y_range = ax.y_range
+        x = (
+            x_range.start + x_frac * (x_range.end - x_range.start)
+            if hasattr(x_range, "start") and x_range.start is not None
+            else 0
+        )
+        y = (
+            y_range.start + y_frac * (y_range.end - y_range.start)
+            if hasattr(y_range, "start") and y_range.start is not None
+            else 0
+        )
+
+        label_obj = Label(
+            x=x,
+            y=y,
+            text=label,
+            text_font_size="12px",
+            text_font_style="bold",
+        )
+        ax.add_layout(label_obj)
+
     def _ensure_legend_range(self, ax: figure) -> Any:
         """Ensure legend range exists and return a dummy data source.