pylocuszoom 0.5.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

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.
 
@@ -19,15 +22,35 @@ class BokehBackend:
     applications and dashboards.
     """
 
-    def __init__(self) -> None:
-        """Initialize the bokeh backend."""
-        self._marker_map = {
-            "o": "circle",
-            "D": "diamond",
-            "s": "square",
-            "^": "triangle",
-            "v": "inverted_triangle",
-        }
+    # Class constants for style mappings
+    _MARKER_MAP = {
+        "o": "circle",
+        "D": "diamond",
+        "s": "square",
+        "^": "triangle",
+        "v": "inverted_triangle",
+    }
+    _DASH_MAP = {
+        "-": "solid",
+        "--": "dashed",
+        ":": "dotted",
+        "-.": "dashdot",
+    }
+
+    @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,
@@ -131,7 +154,7 @@ class BokehBackend:
         source = ColumnDataSource(data)
 
         # Get marker type for scatter()
-        marker_type = self._marker_map.get(marker, "circle")
+        marker_type = self._MARKER_MAP.get(marker, "circle")
 
         # Create scatter using scatter() method (Bokeh 3.4+ preferred API)
         scatter_kwargs = {
@@ -171,14 +194,7 @@ class BokehBackend:
         label: Optional[str] = None,
     ) -> Any:
         """Create a line plot on the given figure."""
-        # Convert linestyle
-        dash_map = {
-            "-": "solid",
-            "--": "dashed",
-            ":": "dotted",
-            "-.": "dashdot",
-        }
-        line_dash = dash_map.get(linestyle, "solid")
+        line_dash = self._DASH_MAP.get(linestyle, "solid")
 
         line_kwargs = {
             "line_color": color,
@@ -233,8 +249,7 @@ class BokehBackend:
         zorder: int = 1,
     ) -> Any:
         """Add a horizontal line across the figure."""
-        dash_map = {"-": "solid", "--": "dashed", ":": "dotted", "-.": "dashdot"}
-        line_dash = dash_map.get(linestyle, "dashed")
+        line_dash = self._DASH_MAP.get(linestyle, "dashed")
 
         span = Span(
             location=y,
@@ -355,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 = {
@@ -367,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."""
@@ -411,8 +427,7 @@ class BokehBackend:
         yaxis_name: str = "secondary",
     ) -> Any:
         """Create a line plot on secondary y-axis."""
-        dash_map = {"-": "solid", "--": "dashed", ":": "dotted", "-.": "dashdot"}
-        line_dash = dash_map.get(linestyle, "solid")
+        line_dash = self._DASH_MAP.get(linestyle, "solid")
 
         return ax.line(
             x.values,
@@ -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.
 
@@ -683,6 +745,102 @@ class BokehBackend:
         ax.legend.background_fill_alpha = 0.9
         ax.legend.border_line_color = "black"
 
+    def axvline(
+        self,
+        ax: figure,
+        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 figure."""
+        line_dash = self._DASH_MAP.get(linestyle, "dashed")
+
+        span = Span(
+            location=x,
+            dimension="height",
+            line_color=color,
+            line_dash=line_dash,
+            line_width=linewidth,
+            line_alpha=alpha,
+        )
+        ax.add_layout(span)
+        return span
+
+    def hbar(
+        self,
+        ax: figure,
+        y: pd.Series,
+        width: pd.Series,
+        height: float = 0.8,
+        left: Union[float, pd.Series] = 0,
+        color: Union[str, List[str]] = "blue",
+        edgecolor: str = "black",
+        linewidth: float = 0.5,
+        zorder: int = 2,
+    ) -> Any:
+        """Create horizontal bar chart."""
+        # Convert left to array if scalar
+        if isinstance(left, (int, float)):
+            left_arr = [left] * len(y)
+        else:
+            left_arr = list(left) if hasattr(left, "tolist") else left
+
+        # Calculate right edge
+        right_arr = [left_val + w for left_val, w in zip(left_arr, width)]
+
+        return ax.hbar(
+            y=y.values,
+            right=right_arr,
+            left=left_arr,
+            height=height,
+            fill_color=color,
+            line_color=edgecolor,
+            line_width=linewidth,
+        )
+
+    def errorbar_h(
+        self,
+        ax: figure,
+        x: pd.Series,
+        y: pd.Series,
+        xerr_lower: pd.Series,
+        xerr_upper: pd.Series,
+        color: str = "black",
+        linewidth: float = 1.5,
+        capsize: float = 3,
+        zorder: int = 3,
+    ) -> Any:
+        """Add horizontal error bars."""
+        from bokeh.models import Whisker
+
+        # Calculate bounds
+        lower = x - xerr_lower
+        upper = x + xerr_upper
+
+        source = ColumnDataSource(
+            data={
+                "y": y.values,
+                "lower": lower.values,
+                "upper": upper.values,
+            }
+        )
+
+        # Add horizontal whisker
+        whisker = Whisker(
+            source=source,
+            base="y",
+            lower="lower",
+            upper="upper",
+            dimension="width",
+            line_color=color,
+            line_width=linewidth,
+        )
+        ax.add_layout(whisker)
+        return whisker
+
     def finalize_layout(
         self,
         fig: Any,

pylocuszoom/backends/hover.py

@@ -0,0 +1,198 @@
+"""Hover data builder for consistent hover tooltip generation.
+
+Provides a unified interface for building hover data across Plotly and Bokeh backends.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+import pandas as pd
+
+
+@dataclass
+class HoverConfig:
+    """Configuration for hover data column mapping.
+
+    Maps source DataFrame column names to standardized display names for tooltips.
+
+    Attributes:
+        snp_col: Column name for SNP identifiers (displayed as "SNP").
+        pos_col: Column name for genomic position (displayed as "Position").
+        p_col: Column name for p-value (displayed as "P-value").
+        ld_col: Column name for LD/R-squared (displayed as "R²").
+        extra_cols: Additional columns to include, mapping source name to display name.
+    """
+
+    snp_col: Optional[str] = None
+    pos_col: Optional[str] = None
+    p_col: Optional[str] = None
+    ld_col: Optional[str] = None
+    extra_cols: dict[str, str] = field(default_factory=dict)
+
+
+class HoverDataBuilder:
+    """Builder for constructing hover data and templates across backends.
+
+    Provides consistent hover tooltip generation for Plotly and Bokeh backends
+    with automatic format detection for common column types.
+
+    Attributes:
+        FORMAT_SPECS: Format specifiers for different data types.
+    """
+
+    FORMAT_SPECS = {
+        "p_value": ".2e",
+        "r2": ".3f",
+        "position": ",.0f",
+    }
+
+    # Standard column mappings (source config attr -> display name)
+    _COLUMN_MAPPING = {
+        "snp_col": "SNP",
+        "pos_col": "Position",
+        "p_col": "P-value",
+        "ld_col": "R²",
+    }
+
+    def __init__(self, config: HoverConfig) -> None:
+        """Initialize builder with column configuration.
+
+        Args:
+            config: HoverConfig with column name mappings.
+        """
+        self.config = config
+
+    def build_dataframe(self, df: pd.DataFrame) -> Optional[pd.DataFrame]:
+        """Build standardized hover DataFrame with renamed columns.
+
+        Extracts configured columns from the input DataFrame, renames them to
+        standardized display names, and returns a new DataFrame. Columns that
+        don't exist in the input are skipped gracefully.
+
+        Args:
+            df: Input DataFrame containing hover data columns.
+
+        Returns:
+            DataFrame with renamed columns, or None if no configured columns exist.
+        """
+        result_data = {}
+
+        # Process standard columns in order
+        for config_attr, display_name in self._COLUMN_MAPPING.items():
+            source_col = getattr(self.config, config_attr)
+            if source_col is not None and source_col in df.columns:
+                result_data[display_name] = df[source_col].values
+
+        # Process extra columns
+        for source_col, display_name in self.config.extra_cols.items():
+            if source_col in df.columns:
+                result_data[display_name] = df[source_col].values
+
+        if not result_data:
+            return None
+
+        return pd.DataFrame(result_data)
+
+    def build_plotly_template(self, hover_df: pd.DataFrame) -> str:
+        """Generate Plotly hovertemplate string.
+
+        Creates a template string with appropriate format specifiers for each
+        column type. SNP appears first in bold, followed by other columns with
+        their values.
+
+        Args:
+            hover_df: DataFrame returned by build_dataframe().
+
+        Returns:
+            Plotly hovertemplate string with customdata references.
+        """
+        columns = hover_df.columns.tolist()
+        parts = []
+
+        for i, col in enumerate(columns):
+            if i == 0:
+                # First column (SNP) in bold
+                parts.append(f"<b>%{{customdata[{i}]}}</b>")
+            else:
+                fmt = self._detect_plotly_format(col)
+                if fmt:
+                    parts.append(f"{col}: %{{customdata[{i}]:{fmt}}}")
+                else:
+                    parts.append(f"{col}: %{{customdata[{i}]}}")
+
+        parts.append("<extra></extra>")
+        return "<br>".join(parts)
+
+    def build_bokeh_tooltips(self, hover_df: pd.DataFrame) -> list[tuple[str, str]]:
+        """Generate Bokeh tooltips list.
+
+        Creates a list of (name, format) tuples for Bokeh HoverTool configuration.
+        Each tuple contains the display name and the Bokeh format string with
+        appropriate specifiers.
+
+        Args:
+            hover_df: DataFrame returned by build_dataframe().
+
+        Returns:
+            List of (name, format_string) tuples for Bokeh tooltips.
+        """
+        tooltips = []
+
+        for col in hover_df.columns:
+            fmt = self._detect_bokeh_format(col)
+            if fmt:
+                tooltips.append((col, f"@{{{col}}}{{{fmt}}}"))
+            else:
+                tooltips.append((col, f"@{col}"))
+
+        return tooltips
+
+    def _detect_plotly_format(self, col_name: str) -> Optional[str]:
+        """Detect appropriate Plotly format specifier for column.
+
+        Uses heuristics based on column name to determine formatting:
+        - P-value columns: scientific notation (.2e)
+        - R²/LD columns: 3 decimal places (.3f)
+        - Position columns: comma-separated (.0f)
+
+        Args:
+            col_name: Display name of the column.
+
+        Returns:
+            Plotly format specifier string, or None for default format.
+        """
+        col_lower = col_name.lower()
+
+        if col_lower in ("p-value", "pval", "p_value"):
+            return self.FORMAT_SPECS["p_value"]
+        elif any(x in col_lower for x in ("r2", "r²", "ld")):
+            return self.FORMAT_SPECS["r2"]
+        elif "pos" in col_lower:
+            return self.FORMAT_SPECS["position"]
+
+        return None
+
+    def _detect_bokeh_format(self, col_name: str) -> Optional[str]:
+        """Detect appropriate Bokeh format code for column.
+
+        Uses heuristics based on column name to determine formatting:
+        - P-value columns: scientific notation (0.2e)
+        - R²/LD columns: 3 decimal places (0.3f)
+        - Position columns: comma-separated (0,0)
+
+        Args:
+            col_name: Display name of the column.
+
+        Returns:
+            Bokeh format code string, or None for default format.
+        """
+        col_lower = col_name.lower()
+
+        if col_lower in ("p-value", "pval", "p_value"):
+            return "0.2e"
+        elif any(x in col_lower for x in ("r2", "r²", "ld")):
+            return "0.3f"
+        elif "pos" in col_lower:
+            return "0,0"
+
+        return None