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

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,123 @@ 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,
+        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."""
+        return ax.axvline(
+            x=x,
+            color=color,
+            linestyle=linestyle,
+            linewidth=linewidth,
+            alpha=alpha,
+            zorder=zorder,
+        )
+
+    def hbar(
+        self,
+        ax: Axes,
+        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."""
+        return ax.barh(
+            y=y,
+            width=width,
+            height=height,
+            left=left,
+            color=color,
+            edgecolor=edgecolor,
+            linewidth=linewidth,
+            zorder=zorder,
+        )
+
+    def errorbar_h(
+        self,
+        ax: Axes,
+        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."""
+        xerr = [xerr_lower.values, xerr_upper.values]
+        return ax.errorbar(
+            x=x,
+            y=y,
+            xerr=xerr,
+            fmt="none",
+            ecolor=color,
+            elinewidth=linewidth,
+            capsize=capsize,
+            zorder=zorder,
+        )
+
     def finalize_layout(
         self,
         fig: Figure,

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.
 
@@ -20,15 +23,35 @@ class PlotlyBackend:
     - Nearest gene
     """
 
-    def __init__(self) -> None:
-        """Initialize the plotly backend."""
-        self._marker_symbols = {
-            "o": "circle",
-            "D": "diamond",
-            "s": "square",
-            "^": "triangle-up",
-            "v": "triangle-down",
-        }
+    # Class constants for style mappings
+    _MARKER_SYMBOLS = {
+        "o": "circle",
+        "D": "diamond",
+        "s": "square",
+        "^": "triangle-up",
+        "v": "triangle-down",
+    }
+    _DASH_MAP = {
+        "-": "solid",
+        "--": "dash",
+        ":": "dot",
+        "-.": "dashdot",
+    }
+
+    @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,
@@ -111,7 +134,7 @@ class PlotlyBackend:
         fig, row = ax
 
         # Convert matplotlib marker to plotly symbol
-        symbol = self._marker_symbols.get(marker, "circle")
+        symbol = self._MARKER_SYMBOLS.get(marker, "circle")
 
         # Convert size (matplotlib uses area, plotly uses diameter)
         if isinstance(sizes, (int, float)):
@@ -178,15 +201,7 @@ class PlotlyBackend:
     ) -> Any:
         """Create a line plot on the given panel."""
         fig, row = ax
-
-        # Convert linestyle
-        dash_map = {
-            "-": "solid",
-            "--": "dash",
-            ":": "dot",
-            "-.": "dashdot",
-        }
-        dash = dash_map.get(linestyle, "solid")
+        dash = self._DASH_MAP.get(linestyle, "solid")
 
         trace = go.Scatter(
             x=x,
@@ -244,9 +259,7 @@ class PlotlyBackend:
     ) -> Any:
         """Add a horizontal line across the panel."""
         fig, row = ax
-
-        dash_map = {"-": "solid", "--": "dash", ":": "dot", "-.": "dashdot"}
-        dash = dash_map.get(linestyle, "dash")
+        dash = self._DASH_MAP.get(linestyle, "dash")
 
         fig.add_hline(
             y=y,
@@ -384,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.
 
@@ -404,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
@@ -461,9 +482,7 @@ class PlotlyBackend:
     ) -> Any:
         """Create a line plot on secondary y-axis."""
         fig, row = ax
-
-        dash_map = {"-": "solid", "--": "dash", ":": "dot", "-.": "dashdot"}
-        dash = dash_map.get(linestyle, "solid")
+        dash = self._DASH_MAP.get(linestyle, "solid")
 
         trace = go.Scatter(
             x=x,
@@ -609,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],
@@ -782,6 +836,101 @@ class PlotlyBackend:
             )
         )
 
+    def axvline(
+        self,
+        ax: Tuple[go.Figure, int],
+        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 panel."""
+        fig, row = ax
+        dash = self._DASH_MAP.get(linestyle, "dash")
+
+        fig.add_vline(
+            x=x,
+            line_dash=dash,
+            line_color=color,
+            line_width=linewidth,
+            opacity=alpha,
+            row=row,
+            col=1,
+        )
+
+    def hbar(
+        self,
+        ax: Tuple[go.Figure, int],
+        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."""
+        fig, row = ax
+
+        # 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
+
+        trace = go.Bar(
+            y=y,
+            x=width,
+            orientation="h",
+            base=left_arr,
+            marker=dict(
+                color=color,
+                line=dict(color=edgecolor, width=linewidth),
+            ),
+            showlegend=False,
+        )
+
+        fig.add_trace(trace, row=row, col=1)
+        return trace
+
+    def errorbar_h(
+        self,
+        ax: Tuple[go.Figure, int],
+        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."""
+        fig, row = ax
+
+        trace = go.Scatter(
+            x=x,
+            y=y,
+            mode="markers",
+            marker=dict(size=0),
+            error_x=dict(
+                type="data",
+                symmetric=False,
+                array=xerr_upper,
+                arrayminus=xerr_lower,
+                color=color,
+                thickness=linewidth,
+                width=capsize,
+            ),
+            showlegend=False,
+        )
+
+        fig.add_trace(trace, row=row, col=1)
+        return trace
+
     def finalize_layout(
         self,
         fig: go.Figure,