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

pylocuszoom/__init__.py

@@ -34,7 +34,7 @@ Species Support:
     - Custom: User provides all reference data
 """
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 
 # Main plotter class
 # Backend types
@@ -74,6 +74,31 @@ from .labels import add_snp_labels
 # LD calculation
 from .ld import calculate_ld
 
+# File format loaders
+from .loaders import (
+    load_bed,
+    load_bolt_lmm,
+    load_caviar,
+    load_ensembl_genes,
+    load_eqtl_catalogue,
+    load_finemap,
+    load_gemma,
+    # eQTL loaders
+    load_gtex_eqtl,
+    # Gene annotation loaders
+    load_gtf,
+    # GWAS loaders
+    load_gwas,
+    load_gwas_catalog,
+    load_matrixeqtl,
+    load_plink_assoc,
+    load_polyfun,
+    load_regenie,
+    load_saige,
+    # Fine-mapping loaders
+    load_susie,
+)
+
 # Logging configuration
 from .logging import disable_logging, enable_logging
 from .plotter import LocusZoomPlotter
@@ -86,6 +111,9 @@ from .recombination import (
     load_recombination_map,
 )
 
+# Schema validation
+from .schemas import LoaderValidationError
+
 # Validation utilities
 from .utils import ValidationError, to_pandas
 
@@ -136,4 +164,27 @@ __all__ = [
     # Validation & Utils
     "ValidationError",
     "to_pandas",
+    # GWAS loaders
+    "load_gwas",
+    "load_plink_assoc",
+    "load_regenie",
+    "load_bolt_lmm",
+    "load_gemma",
+    "load_saige",
+    "load_gwas_catalog",
+    # eQTL loaders
+    "load_gtex_eqtl",
+    "load_eqtl_catalogue",
+    "load_matrixeqtl",
+    # Fine-mapping loaders
+    "load_susie",
+    "load_finemap",
+    "load_caviar",
+    "load_polyfun",
+    # Gene annotation loaders
+    "load_gtf",
+    "load_bed",
+    "load_ensembl_genes",
+    # Schema validation
+    "LoaderValidationError",
 ]

pylocuszoom/backends/base.py

@@ -132,6 +132,7 @@ class PlotBackend(Protocol):
         color: str = "grey",
         linestyle: str = "--",
         linewidth: float = 1.0,
+        alpha: float = 1.0,
         zorder: int = 1,
     ) -> Any:
         """Add a horizontal line across the axes.
@@ -142,6 +143,7 @@ class PlotBackend(Protocol):
             color: Line color.
             linestyle: Line style.
             linewidth: Line width.
+            alpha: Line transparency (0-1).
             zorder: Drawing order.
 
         Returns:
@@ -339,3 +341,48 @@ class PlotBackend(Protocol):
             fig: Figure object.
         """
         ...
+
+    def add_eqtl_legend(
+        self,
+        ax: Any,
+        eqtl_positive_bins: List[Tuple[float, float, str, str]],
+        eqtl_negative_bins: List[Tuple[float, float, str, str]],
+    ) -> None:
+        """Add eQTL effect size legend to the axes.
+
+        Args:
+            ax: Axes or panel.
+            eqtl_positive_bins: List of (min, max, label, color) for positive effects.
+            eqtl_negative_bins: List of (min, max, label, color) for negative effects.
+        """
+        ...
+
+    def add_finemapping_legend(
+        self,
+        ax: Any,
+        credible_sets: List[int],
+        get_color_func: Any,
+    ) -> None:
+        """Add fine-mapping credible set legend to the axes.
+
+        Args:
+            ax: Axes or panel.
+            credible_sets: List of credible set IDs to show.
+            get_color_func: Function that takes CS ID and returns color.
+        """
+        ...
+
+    def add_simple_legend(
+        self,
+        ax: Any,
+        label: str,
+        loc: str = "upper right",
+    ) -> None:
+        """Add a simple legend entry for labeled data already in the plot.
+
+        Args:
+            ax: Axes or panel.
+            label: Legend label for labeled scatter data.
+            loc: Legend location.
+        """
+        ...

pylocuszoom/backends/bokeh_backend.py

@@ -8,7 +8,7 @@ from typing import Any, List, Optional, Tuple, Union
 import pandas as pd
 from bokeh.io import export_png, export_svgs, output_file, save, show
 from bokeh.layouts import column
-from bokeh.models import ColumnDataSource, HoverTool, Span
+from bokeh.models import ColumnDataSource, DataRange1d, HoverTool, Span
 from bokeh.plotting import figure
 
 
@@ -56,29 +56,29 @@ class BokehBackend:
         heights = [int(total_height * r / total_ratio) for r in height_ratios]
 
         figures = []
-        x_range = None
+        x_range = DataRange1d() if sharex else None
 
         for i, h in enumerate(heights):
             p = figure(
                 width=width_px,
                 height=h,
-                x_range=x_range if sharex and x_range else None,
+                x_range=x_range if sharex else DataRange1d(),
                 tools="pan,wheel_zoom,box_zoom,reset,save",
                 toolbar_location="above" if i == 0 else None,
             )
 
-            # Share x_range for subsequent figures
-            if sharex and x_range is None:
-                x_range = p.x_range
-
-            # Style
-            p.grid.grid_line_alpha = 0.3
+            # Style - no grid lines, black axes for clean LocusZoom appearance
+            p.grid.visible = False
             p.outline_line_color = None
+            p.xaxis.axis_line_color = "black"
+            p.yaxis.axis_line_color = "black"
+            p.xaxis.minor_tick_line_color = None
+            p.yaxis.minor_tick_line_color = None
 
             figures.append(p)
 
-        # Create column layout
-        layout = column(*figures, sizing_mode="fixed")
+        # Create column layout (use default sizing mode to avoid validation warnings)
+        layout = column(*figures)
 
         return layout, figures
 
@@ -118,29 +118,34 @@ class BokehBackend:
         if hover_data is not None:
             for col in hover_data.columns:
                 data[col] = hover_data[col].values
-                if "p" in col.lower():
+                col_lower = col.lower()
+                if col_lower in ("p-value", "pval", "p_value"):
                     tooltips.append((col, "@{" + col + "}{0.2e}"))
-                elif "r2" in col.lower() or "ld" in col.lower():
+                elif any(x in col_lower for x in ("r2", "r²", "ld")):
                     tooltips.append((col, "@{" + col + "}{0.3f}"))
+                elif "pos" in col_lower:
+                    tooltips.append((col, "@{" + col + "}{0,0}"))
                 else:
                     tooltips.append((col, f"@{col}"))
 
         source = ColumnDataSource(data)
 
-        # Get marker type
+        # Get marker type for scatter()
         marker_type = self._marker_map.get(marker, "circle")
 
-        # Create scatter
-        renderer = getattr(ax, marker_type)(
-            "x",
-            "y",
-            source=source,
-            size="size",
-            fill_color="color",
-            line_color=edgecolor,
-            line_width=linewidth,
-            legend_label=label if label else None,
-        )
+        # Create scatter using scatter() method (Bokeh 3.4+ preferred API)
+        scatter_kwargs = {
+            "source": source,
+            "marker": marker_type,
+            "size": "size",
+            "fill_color": "color",
+            "line_color": edgecolor,
+            "line_width": linewidth,
+        }
+        if label:
+            scatter_kwargs["legend_label"] = label
+
+        renderer = ax.scatter("x", "y", **scatter_kwargs)
 
         # Add hover tool if we have hover data
         if tooltips:
@@ -175,15 +180,16 @@ class BokehBackend:
         }
         line_dash = dash_map.get(linestyle, "solid")
 
-        return ax.line(
-            x.values,
-            y.values,
-            line_color=color,
-            line_width=linewidth,
-            line_alpha=alpha,
-            line_dash=line_dash,
-            legend_label=label if label else None,
-        )
+        line_kwargs = {
+            "line_color": color,
+            "line_width": linewidth,
+            "line_alpha": alpha,
+            "line_dash": line_dash,
+        }
+        if label:
+            line_kwargs["legend_label"] = label
+
+        return ax.line(x.values, y.values, **line_kwargs)
 
     def fill_between(
         self,
@@ -223,6 +229,7 @@ class BokehBackend:
         color: str = "grey",
         linestyle: str = "--",
         linewidth: float = 1.0,
+        alpha: float = 1.0,
         zorder: int = 1,
     ) -> Any:
         """Add a horizontal line across the figure."""
@@ -235,6 +242,7 @@ class BokehBackend:
             line_color=color,
             line_dash=line_dash,
             line_width=linewidth,
+            line_alpha=alpha,
         )
         ax.add_layout(span)
         return span
@@ -303,6 +311,28 @@ class BokehBackend:
             line_width=linewidth,
         )
 
+    def add_polygon(
+        self,
+        ax: figure,
+        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 figure."""
+        xs = [p[0] for p in points]
+        ys = [p[1] for p in points]
+
+        # Bokeh patch() uses x/y (singular) for single polygon
+        return ax.patch(
+            x=xs,
+            y=ys,
+            fill_color=facecolor,
+            line_color=edgecolor,
+            line_width=linewidth,
+        )
+
     def set_xlim(self, ax: figure, left: float, right: float) -> None:
         """Set x-axis limits."""
         ax.x_range.start = left
@@ -315,14 +345,41 @@ class BokehBackend:
 
     def set_xlabel(self, ax: figure, label: str, fontsize: int = 12) -> None:
         """Set x-axis label."""
+        label = self._convert_label(label)
         ax.xaxis.axis_label = label
         ax.xaxis.axis_label_text_font_size = f"{fontsize}pt"
 
     def set_ylabel(self, ax: figure, label: str, fontsize: int = 12) -> None:
         """Set y-axis label."""
+        label = self._convert_label(label)
         ax.yaxis.axis_label = label
         ax.yaxis.axis_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 = {
+            "upper left": "top_left",
+            "upper right": "top_right",
+            "lower left": "bottom_left",
+            "lower right": "bottom_right",
+        }
+        return loc_map.get(loc, default)
+
+    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
+
     def set_title(self, ax: figure, title: str, fontsize: int = 14) -> None:
         """Set figure title."""
         ax.title.text = title
@@ -341,6 +398,171 @@ class BokehBackend:
 
         return "secondary"
 
+    def line_secondary(
+        self,
+        ax: figure,
+        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 = "secondary",
+    ) -> Any:
+        """Create a line plot on secondary y-axis."""
+        dash_map = {"-": "solid", "--": "dashed", ":": "dotted", "-.": "dashdot"}
+        line_dash = dash_map.get(linestyle, "solid")
+
+        return ax.line(
+            x.values,
+            y.values,
+            line_color=color,
+            line_width=linewidth,
+            line_alpha=alpha,
+            line_dash=line_dash,
+            y_range_name=yaxis_name,
+        )
+
+    def fill_between_secondary(
+        self,
+        ax: figure,
+        x: pd.Series,
+        y1: Union[float, pd.Series],
+        y2: Union[float, pd.Series],
+        color: str = "blue",
+        alpha: float = 0.3,
+        yaxis_name: str = "secondary",
+    ) -> Any:
+        """Fill area between two y-values on secondary y-axis."""
+        x_arr = x.values
+        if isinstance(y1, (int, float)):
+            y1_arr = [y1] * len(x_arr)
+        else:
+            y1_arr = y1.values if hasattr(y1, "values") else list(y1)
+
+        if isinstance(y2, (int, float)):
+            y2_arr = [y2] * len(x_arr)
+        else:
+            y2_arr = y2.values if hasattr(y2, "values") else list(y2)
+
+        return ax.varea(
+            x=x_arr,
+            y1=y1_arr,
+            y2=y2_arr,
+            fill_color=color,
+            fill_alpha=alpha,
+            y_range_name=yaxis_name,
+        )
+
+    def set_secondary_ylim(
+        self,
+        ax: figure,
+        bottom: float,
+        top: float,
+        yaxis_name: str = "secondary",
+    ) -> None:
+        """Set secondary y-axis limits."""
+        if yaxis_name in ax.extra_y_ranges:
+            ax.extra_y_ranges[yaxis_name].start = bottom
+            ax.extra_y_ranges[yaxis_name].end = top
+
+    def set_secondary_ylabel(
+        self,
+        ax: figure,
+        label: str,
+        color: str = "black",
+        fontsize: int = 10,
+        yaxis_name: str = "secondary",
+    ) -> None:
+        """Set secondary y-axis label."""
+        label = self._convert_label(label)
+        # Find the secondary axis and update its label
+        for renderer in ax.right:
+            if (
+                hasattr(renderer, "y_range_name")
+                and renderer.y_range_name == yaxis_name
+            ):
+                renderer.axis_label = label
+                renderer.axis_label_text_font_size = f"{fontsize}pt"
+                renderer.axis_label_text_color = color
+                renderer.major_label_text_color = color
+                break
+
+    def _ensure_legend_range(self, ax: figure) -> Any:
+        """Ensure legend range exists and return a dummy data source.
+
+        Creates a separate y-range for legend glyphs so they don't affect
+        the main plot's axis scaling.
+        """
+        from bokeh.models import ColumnDataSource, Range1d
+
+        if "legend_range" not in ax.extra_y_ranges:
+            ax.extra_y_ranges["legend_range"] = Range1d(start=0, end=1)
+        return ColumnDataSource(data={"x": [0], "y": [0]})
+
+    def _add_legend_item(
+        self,
+        ax: figure,
+        source: Any,
+        label: str,
+        color: str,
+        marker: str,
+        size: int = 10,
+    ) -> Any:
+        """Create an invisible scatter renderer for a legend entry."""
+        from bokeh.models import LegendItem
+
+        renderer = ax.scatter(
+            x="x",
+            y="y",
+            source=source,
+            marker=marker,
+            size=size,
+            fill_color=color,
+            line_color="black",
+            line_width=0.5,
+            y_range_name="legend_range",
+            visible=False,
+        )
+        return LegendItem(label=label, renderers=[renderer])
+
+    def _create_legend(self, ax: figure, items: List[Any], title: str) -> None:
+        """Create and add a styled legend to the figure."""
+        from bokeh.models import Legend
+
+        legend = Legend(
+            items=items,
+            location="top_right",
+            title=title,
+            background_fill_alpha=0.9,
+            border_line_color="black",
+            spacing=0,
+            padding=4,
+            label_height=12,
+            glyph_height=12,
+        )
+        ax.add_layout(legend)
+
+    def add_ld_legend(
+        self,
+        ax: figure,
+        ld_bins: List[Tuple[float, str, str]],
+        lead_snp_color: str,
+    ) -> None:
+        """Add LD color legend using invisible dummy glyphs.
+
+        Creates legend entries with dummy renderers that are excluded from
+        the data range calculation to avoid affecting axis scaling.
+        """
+        source = self._ensure_legend_range(ax)
+        items = [
+            self._add_legend_item(ax, source, "Lead SNP", lead_snp_color, "diamond", 12)
+        ]
+        for _, label, color in ld_bins:
+            items.append(self._add_legend_item(ax, source, label, color, "square"))
+        self._create_legend(ax, items, "r²")
+
     def add_legend(
         self,
         ax: figure,
@@ -350,17 +572,7 @@ class BokehBackend:
         title: Optional[str] = None,
     ) -> Any:
         """Configure legend on the figure."""
-        # Bokeh handles legend automatically from legend_label
-        # Just configure position
-
-        loc_map = {
-            "upper left": "top_left",
-            "upper right": "top_right",
-            "lower left": "bottom_left",
-            "lower right": "bottom_right",
-        }
-
-        ax.legend.location = loc_map.get(loc, "top_left")
+        ax.legend.location = self._get_legend_location(loc, "top_left")
         if title:
             ax.legend.title = title
         ax.legend.background_fill_alpha = 0.9
@@ -369,26 +581,25 @@ class BokehBackend:
         return ax.legend
 
     def hide_spines(self, ax: figure, spines: List[str]) -> None:
-        """Hide specified axis spines."""
-        # Bokeh doesn't have spines in the same way
-        # We can hide axis lines
-        if "top" in spines:
-            ax.xaxis.visible = ax.xaxis.visible  # Keep visible but could customize
-        if "right" in spines:
-            ax.yaxis.visible = ax.yaxis.visible
+        """Hide specified axis spines (no-op for Bokeh).
 
-    def format_xaxis_mb(self, ax: figure) -> None:
-        """Format x-axis to show megabase values."""
-        from bokeh.models import NumeralTickFormatter
+        Bokeh doesn't have matplotlib-style spines. This method exists
+        for interface compatibility but has no visual effect.
+        """
+        pass
 
-        ax.xaxis.formatter = NumeralTickFormatter(format="0.00")
-        ax.xaxis.axis_label = ax.xaxis.axis_label or "Position (Mb)"
+    def hide_yaxis(self, ax: figure) -> None:
+        """Hide y-axis ticks, labels, line, and grid for gene track panels."""
+        ax.yaxis.visible = False
+        ax.ygrid.visible = False
 
-        # We need to scale values or use a custom formatter
-        # For now, assume values are already in bp and need /1e6
-        from bokeh.models import FuncTickFormatter
+    def format_xaxis_mb(self, ax: figure) -> None:
+        """Format x-axis to show megabase values."""
+        from bokeh.models import CustomJSTickFormatter
 
-        ax.xaxis.formatter = FuncTickFormatter(code="return (tick / 1e6).toFixed(2);")
+        ax.xaxis.formatter = CustomJSTickFormatter(
+            code="return (tick / 1e6).toFixed(2);"
+        )
 
     def save(
         self,
@@ -421,6 +632,57 @@ class BokehBackend:
         """Close the figure (no-op for bokeh)."""
         pass
 
+    def add_eqtl_legend(
+        self,
+        ax: figure,
+        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 dummy glyphs."""
+        source = self._ensure_legend_range(ax)
+        items = []
+        for _, _, label, color in eqtl_positive_bins:
+            items.append(self._add_legend_item(ax, source, label, color, "triangle"))
+        for _, _, label, color in eqtl_negative_bins:
+            items.append(
+                self._add_legend_item(ax, source, label, color, "inverted_triangle")
+            )
+        self._create_legend(ax, items, "eQTL effect")
+
+    def add_finemapping_legend(
+        self,
+        ax: figure,
+        credible_sets: List[int],
+        get_color_func: Any,
+    ) -> None:
+        """Add fine-mapping credible set legend using invisible dummy glyphs."""
+        if not credible_sets:
+            return
+
+        source = self._ensure_legend_range(ax)
+        items = [
+            self._add_legend_item(
+                ax, source, f"CS{cs_id}", get_color_func(cs_id), "circle"
+            )
+            for cs_id in credible_sets
+        ]
+        self._create_legend(ax, items, "Credible sets")
+
+    def add_simple_legend(
+        self,
+        ax: figure,
+        label: str,
+        loc: str = "upper right",
+    ) -> None:
+        """Configure legend position.
+
+        Bokeh handles legends automatically from legend_label.
+        This just positions the legend.
+        """
+        ax.legend.location = self._get_legend_location(loc, "top_right")
+        ax.legend.background_fill_alpha = 0.9
+        ax.legend.border_line_color = "black"
+
     def finalize_layout(
         self,
         fig: Any,