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

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

pylocuszoom/backends/matplotlib_backend.py

@@ -12,17 +12,40 @@ from matplotlib.figure import Figure
 from matplotlib.patches import Polygon, Rectangle
 from matplotlib.ticker import FuncFormatter, MaxNLocator
 
+from . import register_backend
 
+
+@register_backend("matplotlib")
 class MatplotlibBackend:
     """Matplotlib backend for static plot generation.
 
     This is the default backend, producing publication-quality static plots
     suitable for papers and presentations.
+
+    Capability Properties:
+        supports_snp_labels: True - uses adjustText for automatic label positioning.
+        supports_hover: False - static plots don't support hover tooltips.
+        supports_secondary_axis: True - supports twin y-axis via twinx().
     """
 
-    def __init__(self) -> None:
-        """Initialize the matplotlib backend."""
-        pass
+    # =========================================================================
+    # Capability Properties
+    # =========================================================================
+
+    @property
+    def supports_snp_labels(self) -> bool:
+        """Matplotlib supports SNP labels via adjustText."""
+        return True
+
+    @property
+    def supports_hover(self) -> bool:
+        """Matplotlib does not support hover tooltips."""
+        return False
+
+    @property
+    def supports_secondary_axis(self) -> bool:
+        """Matplotlib supports twin y-axis."""
+        return True
 
     def create_figure(
         self,
@@ -164,6 +187,67 @@ class MatplotlibBackend:
             x, y, text, fontsize=fontsize, ha=ha, va=va, rotation=rotation, color=color
         )
 
+    def add_panel_label(
+        self,
+        ax: Axes,
+        label: str,
+        x_frac: float = 0.02,
+        y_frac: float = 0.95,
+    ) -> None:
+        """Add label text at fractional position in panel.
+
+        Args:
+            ax: Matplotlib axes.
+            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).
+        """
+        ax.annotate(
+            label,
+            xy=(x_frac, y_frac),
+            xycoords="axes fraction",
+            fontsize=10,
+            fontweight="bold",
+            ha="left",
+            va="top",
+        )
+
+    def add_snp_labels(
+        self,
+        ax: Axes,
+        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 using adjustText.
+
+        Args:
+            ax: Matplotlib axes.
+            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).
+        """
+        from ..labels import add_snp_labels as _add_snp_labels
+
+        _add_snp_labels(
+            ax,
+            df,
+            pos_col=pos_col,
+            neglog10p_col=neglog10p_col,
+            rs_col=rs_col,
+            label_top_n=label_top_n,
+            genes_df=genes_df,
+            chrom=chrom,
+        )
+
     def add_rectangle(
         self,
         ax: Axes,
@@ -225,6 +309,17 @@ class MatplotlibBackend:
         """Set y-axis label."""
         ax.set_ylabel(label, fontsize=fontsize)
 
+    def set_yticks(
+        self,
+        ax: Axes,
+        positions: List[float],
+        labels: List[str],
+        fontsize: int = 10,
+    ) -> None:
+        """Set y-axis tick positions and labels."""
+        ax.set_yticks(positions)
+        ax.set_yticklabels(labels, fontsize=fontsize)
+
     def set_title(self, ax: Axes, title: str, fontsize: int = 14) -> None:
         """Set panel title."""
         ax.set_title(
@@ -238,6 +333,119 @@ class MatplotlibBackend:
         """Create a secondary y-axis sharing the same x-axis."""
         return ax.twinx()
 
+    def line_secondary(
+        self,
+        ax: Axes,
+        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:
+        """Create line on secondary y-axis.
+
+        For matplotlib, the ax should already be a twin axis from create_twin_axis().
+        The yaxis_name parameter is ignored (provided for interface compatibility).
+
+        Args:
+            ax: Secondary axes from create_twin_axis().
+            x: X-axis values.
+            y: Y-axis values.
+            color: Line color.
+            linewidth: Line width.
+            alpha: Transparency.
+            linestyle: Line style.
+            label: Legend label.
+            yaxis_name: Ignored for matplotlib.
+
+        Returns:
+            The line object.
+        """
+        return self.line(
+            ax,
+            x,
+            y,
+            color=color,
+            linewidth=linewidth,
+            alpha=alpha,
+            linestyle=linestyle,
+            label=label,
+        )
+
+    def fill_between_secondary(
+        self,
+        ax: Axes,
+        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.
+
+        For matplotlib, the ax should already be a twin axis from create_twin_axis().
+        The yaxis_name parameter is ignored (provided for interface compatibility).
+
+        Args:
+            ax: Secondary axes from create_twin_axis().
+            x: X-axis values.
+            y1: Lower y boundary.
+            y2: Upper y boundary.
+            color: Fill color.
+            alpha: Transparency.
+            yaxis_name: Ignored for matplotlib.
+
+        Returns:
+            The fill object.
+        """
+        return self.fill_between(ax, x, y1, y2, color=color, alpha=alpha)
+
+    def set_secondary_ylim(
+        self,
+        ax: Axes,
+        bottom: float,
+        top: float,
+        yaxis_name: Any = None,
+    ) -> None:
+        """Set secondary y-axis limits.
+
+        For matplotlib, the ax should already be a twin axis from create_twin_axis().
+        The yaxis_name parameter is ignored (provided for interface compatibility).
+
+        Args:
+            ax: Secondary axes from create_twin_axis().
+            bottom: Minimum y value.
+            top: Maximum y value.
+            yaxis_name: Ignored for matplotlib.
+        """
+        self.set_ylim(ax, bottom, top)
+
+    def set_secondary_ylabel(
+        self,
+        ax: Axes,
+        label: str,
+        color: str = "black",
+        fontsize: int = 10,
+        yaxis_name: Any = None,
+    ) -> None:
+        """Set secondary y-axis label.
+
+        For matplotlib, the ax should already be a twin axis from create_twin_axis().
+        The yaxis_name parameter is ignored (provided for interface compatibility).
+
+        Args:
+            ax: Secondary axes from create_twin_axis().
+            label: Label text.
+            color: Label color.
+            fontsize: Font size.
+            yaxis_name: Ignored for matplotlib.
+        """
+        ax.set_ylabel(label, fontsize=fontsize, color=color)
+
     def add_legend(
         self,
         ax: Axes,
@@ -266,6 +474,10 @@ class MatplotlibBackend:
         for spine in spines:
             ax.spines[spine].set_visible(False)
 
+    def hide_yaxis(self, ax: Axes) -> None:
+        """Hide y-axis ticks, labels, and line."""
+        ax.yaxis.set_visible(False)
+
     def format_xaxis_mb(self, ax: Axes) -> None:
         """Format x-axis to show megabase values."""
         ax.xaxis.set_major_formatter(FuncFormatter(lambda x, _: f"{x / 1e6:.2f}"))
@@ -394,6 +606,54 @@ class MatplotlibBackend:
         """Add simple legend for labeled scatter data."""
         ax.legend(loc=loc, fontsize=9)
 
+    def add_ld_legend(
+        self,
+        ax: Axes,
+        ld_bins: List[Tuple[float, str, str]],
+        lead_snp_color: str,
+    ) -> None:
+        """Add LD color legend using matplotlib patches.
+
+        Args:
+            ax: Matplotlib axes.
+            ld_bins: List of (threshold, label, color) tuples defining LD bins.
+            lead_snp_color: Color for lead SNP marker in legend.
+        """
+        from matplotlib.lines import Line2D
+        from matplotlib.patches import Patch
+
+        from ..colors import get_ld_color_palette
+
+        palette = get_ld_color_palette()
+        legend_elements = [
+            Line2D(
+                [0],
+                [0],
+                marker="D",
+                color="w",
+                markerfacecolor=lead_snp_color,
+                markeredgecolor="black",
+                markersize=6,
+                label="Lead SNP",
+            ),
+        ]
+        for _threshold, label, _color in ld_bins:
+            legend_elements.append(
+                Patch(facecolor=palette[label], edgecolor="black", label=label)
+            )
+        ax.legend(
+            handles=legend_elements,
+            loc="upper right",
+            fontsize=9,
+            frameon=True,
+            framealpha=0.9,
+            title=r"$r^2$",
+            title_fontsize=10,
+            handlelength=1.5,
+            handleheight=1.0,
+            labelspacing=0.4,
+        )
+
     def axvline(
         self,
         ax: Axes,

pylocuszoom/backends/plotly_backend.py

@@ -9,7 +9,10 @@ import pandas as pd
 import plotly.graph_objects as go
 from plotly.subplots import make_subplots
 
+from . import convert_latex_to_unicode, register_backend
 
+
+@register_backend("plotly")
 class PlotlyBackend:
     """Plotly backend for interactive plot generation.
 
@@ -35,9 +38,20 @@ class PlotlyBackend:
         "-.": "dashdot",
     }
 
-    def __init__(self) -> None:
-        """Initialize the plotly backend."""
-        pass
+    @property
+    def supports_snp_labels(self) -> bool:
+        """Plotly uses hover tooltips instead of labels."""
+        return False
+
+    @property
+    def supports_hover(self) -> bool:
+        """Plotly supports hover tooltips."""
+        return True
+
+    @property
+    def supports_secondary_axis(self) -> bool:
+        """Plotly supports secondary y-axis."""
+        return True
 
     def create_figure(
         self,
@@ -383,6 +397,26 @@ class PlotlyBackend:
             }
         )
 
+    def set_yticks(
+        self,
+        ax: Tuple[go.Figure, int],
+        positions: List[float],
+        labels: List[str],
+        fontsize: int = 10,
+    ) -> None:
+        """Set y-axis tick positions and labels."""
+        fig, row = ax
+        fig.update_layout(
+            **{
+                self._axis_name("yaxis", row): dict(
+                    tickmode="array",
+                    tickvals=positions,
+                    ticktext=labels,
+                    tickfont=dict(size=fontsize),
+                )
+            }
+        )
+
     def _axis_name(self, axis: str, row: int) -> str:
         """Get Plotly axis name for a given row.
 
@@ -403,19 +437,7 @@ class PlotlyBackend:
 
     def _convert_label(self, label: str) -> str:
         """Convert LaTeX-style labels to Unicode for Plotly 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)
-        # Remove any remaining $ markers
-        label = label.replace("$", "")
-        return label
+        return convert_latex_to_unicode(label)
 
     def set_title(
         self, ax: Tuple[go.Figure, int], title: str, fontsize: int = 14
@@ -606,6 +628,41 @@ class PlotlyBackend:
             }
         )
 
+    def add_snp_labels(
+        self,
+        ax: Tuple[go.Figure, int],
+        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: Plotly uses hover tooltips instead of text labels."""
+        pass
+
+    def add_panel_label(
+        self,
+        ax: Tuple[go.Figure, int],
+        label: str,
+        x_frac: float = 0.02,
+        y_frac: float = 0.95,
+    ) -> None:
+        """Add label text at fractional position in panel."""
+        fig, row = ax
+        fig.add_annotation(
+            text=f"<b>{label}</b>",
+            xref="x domain",
+            yref="y domain",
+            x=x_frac,
+            y=y_frac,
+            showarrow=False,
+            font=dict(size=12),
+            row=row,
+            col=1,
+        )
+
     def add_ld_legend(
         self,
         ax: Tuple[go.Figure, int],