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

pylocuszoom/backends/plotly_backend.py

@@ -71,8 +71,23 @@ class PlotlyBackend:
             template="plotly_white",
         )
 
-        # Return row indices (1-based for plotly)
-        panel_refs = list(range(1, n_panels + 1))
+        # Style all panels for clean LocusZoom appearance
+        axis_style = dict(
+            showgrid=False,
+            showline=True,
+            linecolor="black",
+            ticks="outside",
+            minor_ticks="",
+            zeroline=False,
+        )
+        for row in range(1, n_panels + 1):
+            xaxis = self._axis_name("xaxis", row)
+            yaxis = self._axis_name("yaxis", row)
+            fig.update_layout(**{xaxis: axis_style, yaxis: axis_style})
+
+        # Return (fig, row) tuples for each panel
+        # This matches the expected ax parameter format for all methods
+        panel_refs = [(fig, row) for row in range(1, n_panels + 1)]
         return fig, panel_refs
 
     def scatter(
@@ -110,10 +125,13 @@ class PlotlyBackend:
             hover_cols = hover_data.columns.tolist()
             hovertemplate = "<b>%{customdata[0]}</b><br>"
             for i, col in enumerate(hover_cols[1:], 1):
-                if "p" in col.lower():
+                col_lower = col.lower()
+                if col_lower in ("p-value", "pval", "p_value"):
                     hovertemplate += f"{col}: %{{customdata[{i}]:.2e}}<br>"
-                elif "r2" in col.lower() or "ld" in col.lower():
+                elif any(x in col_lower for x in ("r2", "r²", "ld")):
                     hovertemplate += f"{col}: %{{customdata[{i}]:.3f}}<br>"
+                elif "pos" in col_lower:
+                    hovertemplate += f"{col}: %{{customdata[{i}]:,.0f}}<br>"
                 else:
                     hovertemplate += f"{col}: %{{customdata[{i}]}}<br>"
             hovertemplate += "<extra></extra>"
@@ -221,6 +239,7 @@ class PlotlyBackend:
         color: str = "grey",
         linestyle: str = "--",
         linewidth: float = 1.0,
+        alpha: float = 1.0,
         zorder: int = 1,
     ) -> Any:
         """Add a horizontal line across the panel."""
@@ -234,6 +253,7 @@ class PlotlyBackend:
             line_dash=dash,
             line_color=color,
             line_width=linewidth,
+            opacity=alpha,
             row=row,
             col=1,
         )
@@ -299,26 +319,55 @@ class PlotlyBackend:
             col=1,
         )
 
+    def add_polygon(
+        self,
+        ax: Tuple[go.Figure, int],
+        points: List[List[float]],
+        facecolor: str = "blue",
+        edgecolor: str = "black",
+        linewidth: float = 0.5,
+        zorder: int = 2,
+    ) -> Any:
+        """Add a polygon (e.g., triangle for strand arrows) to the panel."""
+        fig, row = ax
+
+        # Build SVG path from points
+        path = f"M {points[0][0]} {points[0][1]}"
+        for px, py in points[1:]:
+            path += f" L {px} {py}"
+        path += " Z"
+
+        fig.add_shape(
+            type="path",
+            path=path,
+            fillcolor=facecolor,
+            line=dict(color=edgecolor, width=linewidth),
+            row=row,
+            col=1,
+        )
+
     def set_xlim(self, ax: Tuple[go.Figure, int], left: float, right: float) -> None:
         """Set x-axis limits."""
         fig, row = ax
-        xaxis = f"xaxis{row}" if row > 1 else "xaxis"
-        fig.update_layout(**{xaxis: dict(range=[left, right])})
+        fig.update_layout(**{self._axis_name("xaxis", row): dict(range=[left, right])})
 
     def set_ylim(self, ax: Tuple[go.Figure, int], bottom: float, top: float) -> None:
         """Set y-axis limits."""
         fig, row = ax
-        yaxis = f"yaxis{row}" if row > 1 else "yaxis"
-        fig.update_layout(**{yaxis: dict(range=[bottom, top])})
+        fig.update_layout(**{self._axis_name("yaxis", row): dict(range=[bottom, top])})
 
     def set_xlabel(
         self, ax: Tuple[go.Figure, int], label: str, fontsize: int = 12
     ) -> None:
         """Set x-axis label."""
         fig, row = ax
-        xaxis = f"xaxis{row}" if row > 1 else "xaxis"
+        label = self._convert_label(label)
         fig.update_layout(
-            **{xaxis: dict(title=dict(text=label, font=dict(size=fontsize)))}
+            **{
+                self._axis_name("xaxis", row): dict(
+                    title=dict(text=label, font=dict(size=fontsize))
+                )
+            }
         )
 
     def set_ylabel(
@@ -326,11 +375,49 @@ class PlotlyBackend:
     ) -> None:
         """Set y-axis label."""
         fig, row = ax
-        yaxis = f"yaxis{row}" if row > 1 else "yaxis"
+        label = self._convert_label(label)
         fig.update_layout(
-            **{yaxis: dict(title=dict(text=label, font=dict(size=fontsize)))}
+            **{
+                self._axis_name("yaxis", row): dict(
+                    title=dict(text=label, font=dict(size=fontsize))
+                )
+            }
         )
 
+    def _axis_name(self, axis: str, row: int) -> str:
+        """Get Plotly axis name for a given row.
+
+        Plotly names axes as 'xaxis', 'yaxis' for row 1, and
+        'xaxis2', 'yaxis2', etc. for subsequent rows.
+        """
+        return f"{axis}{row}" if row > 1 else axis
+
+    def _get_legend_position(self, loc: str) -> dict:
+        """Map matplotlib-style legend location to Plotly position dict."""
+        loc_map = {
+            "upper left": dict(x=0.01, y=0.99, xanchor="left", yanchor="top"),
+            "upper right": dict(x=0.99, y=0.99, xanchor="right", yanchor="top"),
+            "lower left": dict(x=0.01, y=0.01, xanchor="left", yanchor="bottom"),
+            "lower right": dict(x=0.99, y=0.01, xanchor="right", yanchor="bottom"),
+        }
+        return loc_map.get(loc, loc_map["upper left"])
+
+    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
+
     def set_title(
         self, ax: Tuple[go.Figure, int], title: str, fontsize: int = 14
     ) -> None:
@@ -360,6 +447,189 @@ class PlotlyBackend:
 
         return (fig, row, secondary_y)
 
+    def line_secondary(
+        self,
+        ax: Tuple[go.Figure, int],
+        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: str = "y2",
+    ) -> Any:
+        """Create a line plot on secondary y-axis."""
+        fig, row = ax
+
+        dash_map = {"-": "solid", "--": "dash", ":": "dot", "-.": "dashdot"}
+        dash = dash_map.get(linestyle, "solid")
+
+        trace = go.Scatter(
+            x=x,
+            y=y,
+            mode="lines",
+            line=dict(color=color, width=linewidth, dash=dash),
+            opacity=alpha,
+            name=label or "",
+            showlegend=label is not None,
+            yaxis=yaxis_name,
+            hoverinfo="skip",
+        )
+
+        fig.add_trace(trace, row=row, col=1)
+        return trace
+
+    def fill_between_secondary(
+        self,
+        ax: Tuple[go.Figure, int],
+        x: pd.Series,
+        y1: Union[float, pd.Series],
+        y2: Union[float, pd.Series],
+        color: str = "blue",
+        alpha: float = 0.3,
+        yaxis_name: str = "y2",
+    ) -> Any:
+        """Fill area between two y-values on secondary y-axis."""
+        fig, row = ax
+
+        if isinstance(y1, (int, float)):
+            y1 = pd.Series([y1] * len(x))
+
+        trace = go.Scatter(
+            x=pd.concat([x, x[::-1]]),
+            y=pd.concat([y2, y1[::-1]]),
+            fill="toself",
+            fillcolor=color,
+            opacity=alpha,
+            line=dict(width=0),
+            showlegend=False,
+            hoverinfo="skip",
+            yaxis=yaxis_name,
+        )
+
+        fig.add_trace(trace, row=row, col=1)
+        return trace
+
+    def set_secondary_ylim(
+        self,
+        ax: Tuple[go.Figure, int],
+        bottom: float,
+        top: float,
+        yaxis_name: str = "y2",
+    ) -> None:
+        """Set secondary y-axis limits."""
+        fig, row = ax
+        yaxis_key = (
+            "yaxis" + yaxis_name[1:] if yaxis_name.startswith("y") else yaxis_name
+        )
+        fig.update_layout(**{yaxis_key: dict(range=[bottom, top])})
+
+    def set_secondary_ylabel(
+        self,
+        ax: Tuple[go.Figure, int],
+        label: str,
+        color: str = "black",
+        fontsize: int = 10,
+        yaxis_name: str = "y2",
+    ) -> None:
+        """Set secondary y-axis label."""
+        fig, row = ax
+        label = self._convert_label(label)
+        yaxis_key = (
+            "yaxis" + yaxis_name[1:] if yaxis_name.startswith("y") else yaxis_name
+        )
+        fig.update_layout(
+            **{
+                yaxis_key: dict(
+                    title=dict(text=label, font=dict(size=fontsize, color=color)),
+                    tickfont=dict(color=color),
+                )
+            }
+        )
+
+    def _get_panel_y_top(self, fig: go.Figure, row: int) -> float:
+        """Get the top y-coordinate (in paper coords) for a subplot row.
+
+        Plotly subplots have y-axis domains that define their vertical position.
+        This returns the top of the domain for positioning legends.
+        """
+        yaxis = getattr(fig.layout, self._axis_name("yaxis", row), None)
+        if yaxis and yaxis.domain:
+            return yaxis.domain[1]
+        return 0.99
+
+    def _add_legend_item(
+        self,
+        fig: go.Figure,
+        row: int,
+        name: str,
+        color: str,
+        symbol: str,
+        size: int,
+        legend_group: str,
+    ) -> None:
+        """Add an invisible scatter trace for a legend entry."""
+        fig.add_trace(
+            go.Scatter(
+                x=[None],
+                y=[None],
+                mode="markers",
+                marker=dict(
+                    symbol=symbol,
+                    size=size,
+                    color=color,
+                    line=dict(color="black", width=0.5),
+                ),
+                name=name,
+                showlegend=True,
+                legend=legend_group,
+            ),
+            row=row,
+            col=1,
+        )
+
+    def _configure_legend(
+        self, fig: go.Figure, row: int, legend_key: str, title: str
+    ) -> None:
+        """Configure legend position and styling."""
+        y_pos = self._get_panel_y_top(fig, row)
+        fig.update_layout(
+            **{
+                legend_key: dict(
+                    title=dict(text=title),
+                    x=0.99,
+                    y=y_pos,
+                    xanchor="right",
+                    yanchor="top",
+                    bgcolor="rgba(255,255,255,0.9)",
+                    bordercolor="black",
+                    borderwidth=1,
+                )
+            }
+        )
+
+    def add_ld_legend(
+        self,
+        ax: Tuple[go.Figure, int],
+        ld_bins: List[Tuple[float, str, str]],
+        lead_snp_color: str,
+    ) -> None:
+        """Add LD color legend using invisible scatter traces.
+
+        Uses Plotly's separate legend feature (legend="legend") so LD legend
+        can be positioned independently from eQTL and fine-mapping legends.
+        """
+        fig, row = ax
+
+        self._add_legend_item(
+            fig, row, "Lead SNP", lead_snp_color, "diamond", 12, "legend"
+        )
+        for _, label, color in ld_bins:
+            self._add_legend_item(fig, row, label, color, "square", 10, "legend")
+
+        self._configure_legend(fig, row, "legend", "r²")
+
     def add_legend(
         self,
         ax: Tuple[go.Figure, int],
@@ -374,16 +644,7 @@ class PlotlyBackend:
         This method updates legend positioning.
         """
         fig, _ = ax
-
-        # Map matplotlib locations to plotly
-        loc_map = {
-            "upper left": dict(x=0.01, y=0.99, xanchor="left", yanchor="top"),
-            "upper right": dict(x=0.99, y=0.99, xanchor="right", yanchor="top"),
-            "lower left": dict(x=0.01, y=0.01, xanchor="left", yanchor="bottom"),
-            "lower right": dict(x=0.99, y=0.01, xanchor="right", yanchor="bottom"),
-        }
-
-        legend_pos = loc_map.get(loc, loc_map["upper left"])
+        legend_pos = self._get_legend_position(loc)
         fig.update_layout(
             legend=dict(
                 **legend_pos,
@@ -403,23 +664,30 @@ class PlotlyBackend:
         # No action needed - method exists for API compatibility
         pass
 
-    def format_xaxis_mb(self, ax: Tuple[go.Figure, int]) -> None:
-        """Format x-axis to show megabase values."""
+    def hide_yaxis(self, ax: Tuple[go.Figure, int]) -> None:
+        """Hide y-axis ticks, labels, line, and grid for gene track panels."""
         fig, row = ax
-        xaxis = f"xaxis{row}" if row > 1 else "xaxis"
-
         fig.update_layout(
             **{
-                xaxis: dict(
-                    tickformat=".2f",
-                    ticksuffix=" Mb",
-                    tickvals=None,  # Auto
+                self._axis_name("yaxis", row): dict(
+                    showticklabels=False,
+                    showline=False,
+                    showgrid=False,
+                    ticks="",
                 )
             }
         )
 
-        # Apply custom tick formatting via ticktext/tickvals if needed
-        # For now, let plotly auto-format
+    def format_xaxis_mb(self, ax: Tuple[go.Figure, int]) -> None:
+        """Format x-axis to show megabase values.
+
+        Stores the row for later tick formatting in finalize_layout.
+        """
+        fig, row = ax
+        # Store that this axis needs Mb formatting
+        if not hasattr(fig, "_mb_format_rows"):
+            fig._mb_format_rows = []
+        fig._mb_format_rows.append(row)
 
     def save(
         self,
@@ -447,6 +715,73 @@ class PlotlyBackend:
         """Close the figure (no-op for plotly)."""
         pass
 
+    def add_eqtl_legend(
+        self,
+        ax: Tuple[go.Figure, int],
+        eqtl_positive_bins: List[Tuple[float, float, str, str]],
+        eqtl_negative_bins: List[Tuple[float, float, str, str]],
+    ) -> None:
+        """Add eQTL effect size legend using invisible scatter traces.
+
+        Uses Plotly's separate legend feature (legend="legend2") so eQTL legend
+        is positioned independently below the LD legend.
+        """
+        fig, row = ax
+
+        for _, _, label, color in eqtl_positive_bins:
+            self._add_legend_item(fig, row, label, color, "triangle-up", 10, "legend2")
+        for _, _, label, color in eqtl_negative_bins:
+            self._add_legend_item(
+                fig, row, label, color, "triangle-down", 10, "legend2"
+            )
+
+        self._configure_legend(fig, row, "legend2", "eQTL effect")
+
+    def add_finemapping_legend(
+        self,
+        ax: Tuple[go.Figure, int],
+        credible_sets: List[int],
+        get_color_func: Any,
+    ) -> None:
+        """Add fine-mapping credible set legend using invisible scatter traces.
+
+        Uses Plotly's separate legend feature (legend="legend2") so fine-mapping
+        legend is positioned independently below the LD legend.
+        """
+        if not credible_sets:
+            return
+
+        fig, row = ax
+
+        for cs_id in credible_sets:
+            self._add_legend_item(
+                fig, row, f"CS{cs_id}", get_color_func(cs_id), "circle", 10, "legend2"
+            )
+
+        self._configure_legend(fig, row, "legend2", "Credible sets")
+
+    def add_simple_legend(
+        self,
+        ax: Tuple[go.Figure, int],
+        label: str,
+        loc: str = "upper right",
+    ) -> None:
+        """Add simple legend positioning.
+
+        Plotly handles legends automatically from trace names.
+        This just positions the legend.
+        """
+        fig, _ = ax
+        legend_pos = self._get_legend_position(loc)
+        fig.update_layout(
+            legend=dict(
+                **legend_pos,
+                bgcolor="rgba(255,255,255,0.9)",
+                bordercolor="black",
+                borderwidth=1,
+            )
+        )
+
     def finalize_layout(
         self,
         fig: go.Figure,
@@ -456,7 +791,7 @@ class PlotlyBackend:
         bottom: float = 0.1,
         hspace: float = 0.08,
     ) -> None:
-        """Adjust layout margins.
+        """Adjust layout margins and apply Mb tick formatting.
 
         Args:
             fig: Figure object.
@@ -471,3 +806,58 @@ class PlotlyBackend:
                 b=int(bottom * fig.layout.height) if fig.layout.height else 80,
             )
         )
+
+        # Apply Mb tick formatting to marked axes
+        if hasattr(fig, "_mb_format_rows"):
+            import numpy as np
+
+            for row in fig._mb_format_rows:
+                xaxis_name = self._axis_name("xaxis", row)
+                xaxis = getattr(fig.layout, xaxis_name, None)
+
+                # Get x-range from the axis or compute from data
+                x_range = None
+                if xaxis and xaxis.range:
+                    x_range = xaxis.range
+                else:
+                    # Compute from trace data (filter out None values from legend traces)
+                    x_vals = []
+                    for trace in fig.data:
+                        if hasattr(trace, "x") and trace.x is not None:
+                            x_vals.extend([v for v in trace.x if v is not None])
+                    if x_vals:
+                        x_range = [min(x_vals), max(x_vals)]
+
+                if x_range:
+                    x_min_mb, x_max_mb = x_range[0] / 1e6, x_range[1] / 1e6
+                    span_mb = x_max_mb - x_min_mb
+
+                    # Choose tick spacing based on range
+                    if span_mb <= 0.5:
+                        tick_step = 0.1
+                    elif span_mb <= 2:
+                        tick_step = 0.25
+                    elif span_mb <= 5:
+                        tick_step = 0.5
+                    elif span_mb <= 20:
+                        tick_step = 2
+                    else:
+                        tick_step = 5
+
+                    # Generate ticks
+                    first_tick = np.ceil(x_min_mb / tick_step) * tick_step
+                    tickvals_mb = np.arange(
+                        first_tick, x_max_mb + tick_step / 2, tick_step
+                    )
+                    tickvals_bp = [v * 1e6 for v in tickvals_mb]
+                    ticktext = [f"{v:.2f}" for v in tickvals_mb]
+
+                    fig.update_layout(
+                        **{
+                            xaxis_name: dict(
+                                tickvals=tickvals_bp,
+                                ticktext=ticktext,
+                                ticksuffix=" Mb",
+                            )
+                        }
+                    )

pylocuszoom/colors.py

@@ -236,4 +236,6 @@ def get_credible_set_color_palette(n_sets: int = 10) -> dict[int, str]:
         >>> palette[1]
         '#FF7F00'
     """
-    return {i + 1: CREDIBLE_SET_COLORS[i % len(CREDIBLE_SET_COLORS)] for i in range(n_sets)}
+    return {
+        i + 1: CREDIBLE_SET_COLORS[i % len(CREDIBLE_SET_COLORS)] for i in range(n_sets)
+    }

pylocuszoom/finemapping.py

@@ -6,7 +6,6 @@ fine-mapping results (SuSiE, FINEMAP, etc.) for visualization.
 
 from typing import List, Optional
 
-import numpy as np
 import pandas as pd
 
 from .logging import logger