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

pylocuszoom/backends/plotly_backend.py

@@ -20,15 +20,24 @@ class PlotlyBackend:
     - Nearest gene
     """
 
+    # Class constants for style mappings
+    _MARKER_SYMBOLS = {
+        "o": "circle",
+        "D": "diamond",
+        "s": "square",
+        "^": "triangle-up",
+        "v": "triangle-down",
+    }
+    _DASH_MAP = {
+        "-": "solid",
+        "--": "dash",
+        ":": "dot",
+        "-.": "dashdot",
+    }
+
     def __init__(self) -> None:
         """Initialize the plotly backend."""
-        self._marker_symbols = {
-            "o": "circle",
-            "D": "diamond",
-            "s": "square",
-            "^": "triangle-up",
-            "v": "triangle-down",
-        }
+        pass
 
     def create_figure(
         self,
@@ -71,6 +80,20 @@ class PlotlyBackend:
             template="plotly_white",
         )
 
+        # 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)]
@@ -97,7 +120,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)):
@@ -112,9 +135,9 @@ class PlotlyBackend:
             hovertemplate = "<b>%{customdata[0]}</b><br>"
             for i, col in enumerate(hover_cols[1:], 1):
                 col_lower = col.lower()
-                if col_lower == "p-value" or col_lower == "pval" or col_lower == "p_value":
+                if col_lower in ("p-value", "pval", "p_value"):
                     hovertemplate += f"{col}: %{{customdata[{i}]:.2e}}<br>"
-                elif "r2" in col_lower or "r²" 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>"
@@ -164,15 +187,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,
@@ -230,9 +245,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,
@@ -335,25 +348,25 @@ class PlotlyBackend:
     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"
-        # Convert LaTeX-style labels to Unicode for Plotly
         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(
@@ -361,16 +374,35 @@ class PlotlyBackend:
     ) -> None:
         """Set y-axis label."""
         fig, row = ax
-        yaxis = f"yaxis{row}" if row > 1 else "yaxis"
-        # Convert LaTeX-style labels to Unicode for Plotly
         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."""
-        # Common conversions for genomics plots
         conversions = [
             (r"$-\log_{10}$ P", "-log₁₀(P)"),
             (r"$-\log_{10}$", "-log₁₀"),
@@ -428,9 +460,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,
@@ -487,7 +517,9 @@ class PlotlyBackend:
     ) -> None:
         """Set secondary y-axis limits."""
         fig, row = ax
-        yaxis_key = "yaxis" + yaxis_name[1:] if yaxis_name.startswith("y") else yaxis_name
+        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(
@@ -501,7 +533,9 @@ class PlotlyBackend:
         """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
+        yaxis_key = (
+            "yaxis" + yaxis_name[1:] if yaxis_name.startswith("y") else yaxis_name
+        )
         fig.update_layout(
             **{
                 yaxis_key: dict(
@@ -511,48 +545,87 @@ class PlotlyBackend:
             }
         )
 
+    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."""
+        """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
 
-        # Add LD bin markers (no lead SNP - it's shown in the actual plot)
+        self._add_legend_item(
+            fig, row, "Lead SNP", lead_snp_color, "diamond", 12, "legend"
+        )
         for _, label, color in ld_bins:
-            fig.add_trace(
-                go.Scatter(
-                    x=[None],
-                    y=[None],
-                    mode="markers",
-                    marker=dict(
-                        symbol="square",
-                        size=10,
-                        color=color,
-                        line=dict(color="black", width=0.5),
-                    ),
-                    name=label,
-                    showlegend=True,
-                ),
-                row=row,
-                col=1,
-            )
+            self._add_legend_item(fig, row, label, color, "square", 10, "legend")
 
-        # Position legend
-        fig.update_layout(
-            legend=dict(
-                x=0.99,
-                y=0.99,
-                xanchor="right",
-                yanchor="top",
-                title=dict(text="r²"),
-                bgcolor="rgba(255,255,255,0.9)",
-                bordercolor="black",
-                borderwidth=1,
-            )
-        )
+        self._configure_legend(fig, row, "legend", "r²")
 
     def add_legend(
         self,
@@ -568,16 +641,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,
@@ -597,6 +661,20 @@ class PlotlyBackend:
         # No action needed - method exists for API compatibility
         pass
 
+    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
+        fig.update_layout(
+            **{
+                self._axis_name("yaxis", row): dict(
+                    showticklabels=False,
+                    showline=False,
+                    showgrid=False,
+                    ticks="",
+                )
+            }
+        )
+
     def format_xaxis_mb(self, ax: Tuple[go.Figure, int]) -> None:
         """Format x-axis to show megabase values.
 
@@ -634,6 +712,168 @@ 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 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,
@@ -664,7 +904,7 @@ class PlotlyBackend:
             import numpy as np
 
             for row in fig._mb_format_rows:
-                xaxis_name = f"xaxis{row}" if row > 1 else "xaxis"
+                xaxis_name = self._axis_name("xaxis", row)
                 xaxis = getattr(fig.layout, xaxis_name, None)
 
                 # Get x-range from the axis or compute from data
@@ -672,18 +912,16 @@ class PlotlyBackend:
                 if xaxis and xaxis.range:
                     x_range = xaxis.range
                 else:
-                    # Compute from trace data
+                    # 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(list(trace.x))
+                            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:
-                    # Create nice tick values in Mb
-                    x_min_mb = x_range[0] / 1e6
-                    x_max_mb = x_range[1] / 1e6
+                    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
@@ -700,7 +938,9 @@ class PlotlyBackend:
 
                     # 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_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]
 

pylocuszoom/colors.py

@@ -236,4 +236,47 @@ 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)
+    }
+
+
+# PheWAS category colors - distinct colors for phenotype categories
+PHEWAS_CATEGORY_COLORS: List[str] = [
+    "#E41A1C",  # red
+    "#377EB8",  # blue
+    "#4DAF4A",  # green
+    "#984EA3",  # purple
+    "#FF7F00",  # orange
+    "#FFFF33",  # yellow
+    "#A65628",  # brown
+    "#F781BF",  # pink
+    "#999999",  # grey
+    "#66C2A5",  # teal
+    "#FC8D62",  # salmon
+    "#8DA0CB",  # periwinkle
+]
+
+
+def get_phewas_category_color(category_idx: int) -> str:
+    """Get color for a PheWAS category by index.
+
+    Args:
+        category_idx: Zero-indexed category number.
+
+    Returns:
+        Hex color code string.
+    """
+    return PHEWAS_CATEGORY_COLORS[category_idx % len(PHEWAS_CATEGORY_COLORS)]
+
+
+def get_phewas_category_palette(categories: List[str]) -> dict[str, str]:
+    """Get color palette mapping category names to colors.
+
+    Args:
+        categories: List of unique category names.
+
+    Returns:
+        Dictionary mapping category names to hex colors.
+    """
+    return {cat: get_phewas_category_color(i) for i, cat in enumerate(categories)}

pylocuszoom/forest.py

@@ -0,0 +1,37 @@
+"""Forest plot data validation and preparation.
+
+Validates and prepares meta-analysis/forest plot data for visualization.
+"""
+
+import pandas as pd
+
+from .utils import ValidationError
+
+
+def validate_forest_df(
+    df: pd.DataFrame,
+    study_col: str = "study",
+    effect_col: str = "effect",
+    ci_lower_col: str = "ci_lower",
+    ci_upper_col: str = "ci_upper",
+) -> None:
+    """Validate forest plot DataFrame has required columns.
+
+    Args:
+        df: Forest plot data DataFrame.
+        study_col: Column name for study/phenotype names.
+        effect_col: Column name for effect sizes (beta, OR, HR).
+        ci_lower_col: Column name for lower confidence interval.
+        ci_upper_col: Column name for upper confidence interval.
+
+    Raises:
+        ValidationError: If required columns are missing.
+    """
+    required = [study_col, effect_col, ci_lower_col, ci_upper_col]
+    missing = [col for col in required if col not in df.columns]
+
+    if missing:
+        raise ValidationError(
+            f"Forest plot DataFrame missing required columns: {missing}. "
+            f"Required: {required}. Found: {list(df.columns)}"
+        )

pylocuszoom/gene_track.py

@@ -362,6 +362,7 @@ def plot_gene_track_generic(
 
     backend.set_xlim(ax, start, end)
     backend.set_ylabel(ax, "", fontsize=10)
+    backend.hide_yaxis(ax)
 
     if region_genes.empty:
         backend.set_ylim(ax, 0, 1)