pylocuszoom 0.3.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

@@ -341,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

@@ -67,9 +67,13 @@ class BokehBackend:
                 toolbar_location="above" if i == 0 else None,
             )
 
-            # 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)
 
@@ -115,9 +119,9 @@ class BokehBackend:
             for col in hover_data.columns:
                 data[col] = hover_data[col].values
                 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"):
                     tooltips.append((col, "@{" + col + "}{0.2e}"))
-                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")):
                     tooltips.append((col, "@{" + col + "}{0.3f}"))
                 elif "pos" in col_lower:
                     tooltips.append((col, "@{" + col + "}{0,0}"))
@@ -351,6 +355,16 @@ class BokehBackend:
         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 = [
@@ -465,60 +479,90 @@ class BokehBackend:
         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:
+            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 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.
+    def _ensure_legend_range(self, ax: figure) -> Any:
+        """Ensure legend range exists and return a dummy data source.
 
-        Creates legend entries with dummy renderers that are excluded from
-        the data range calculation to avoid affecting axis scaling.
+        Creates a separate y-range for legend glyphs so they don't affect
+        the main plot's axis scaling.
         """
-        from bokeh.models import ColumnDataSource, Legend, LegendItem, Range1d, Scatter
-
-        legend_items = []
+        from bokeh.models import ColumnDataSource, Range1d
 
-        # Create a separate range for legend glyphs that won't affect the main plot
         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]})
 
-        # Use coordinates within the legend range
-        dummy_source = 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])
 
-        # Add LD bin markers (no lead SNP - it's shown in the actual plot)
-        for _, label, color in ld_bins:
-            glyph = Scatter(
-                x="x",
-                y="y",
-                marker="square",
-                size=10,
-                fill_color=color,
-                line_color="black",
-                line_width=0.5,
-            )
-            renderer = ax.add_glyph(dummy_source, glyph)
-            renderer.y_range_name = "legend_range"
-            renderer.visible = False
-            legend_items.append(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=legend_items,
+            items=items,
             location="top_right",
-            title="r²",
+            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,
@@ -528,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
@@ -554,6 +588,11 @@ class BokehBackend:
         """
         pass
 
+    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
+
     def format_xaxis_mb(self, ax: figure) -> None:
         """Format x-axis to show megabase values."""
         from bokeh.models import CustomJSTickFormatter
@@ -593,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,

pylocuszoom/backends/matplotlib_backend.py

@@ -290,6 +290,110 @@ class MatplotlibBackend:
         """Close the figure and free resources."""
         plt.close(fig)
 
+    def add_eqtl_legend(
+        self,
+        ax: Axes,
+        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 matplotlib Line2D markers."""
+        from matplotlib.lines import Line2D
+
+        legend_elements = []
+
+        # Positive effects (upward triangles)
+        for _, _, label, color in eqtl_positive_bins:
+            legend_elements.append(
+                Line2D(
+                    [0],
+                    [0],
+                    marker="^",
+                    color="w",
+                    markerfacecolor=color,
+                    markeredgecolor="black",
+                    markersize=7,
+                    label=label,
+                )
+            )
+
+        # Negative effects (downward triangles)
+        for _, _, label, color in eqtl_negative_bins:
+            legend_elements.append(
+                Line2D(
+                    [0],
+                    [0],
+                    marker="v",
+                    color="w",
+                    markerfacecolor=color,
+                    markeredgecolor="black",
+                    markersize=7,
+                    label=label,
+                )
+            )
+
+        ax.legend(
+            handles=legend_elements,
+            loc="upper right",
+            fontsize=8,
+            frameon=True,
+            framealpha=0.9,
+            title="eQTL effect",
+            title_fontsize=9,
+            handlelength=1.2,
+            handleheight=1.0,
+            labelspacing=0.3,
+        )
+
+    def add_finemapping_legend(
+        self,
+        ax: Axes,
+        credible_sets: List[int],
+        get_color_func: Any,
+    ) -> None:
+        """Add fine-mapping credible set legend using matplotlib Line2D markers."""
+        from matplotlib.lines import Line2D
+
+        if not credible_sets:
+            return
+
+        legend_elements = []
+        for cs_id in credible_sets:
+            color = get_color_func(cs_id)
+            legend_elements.append(
+                Line2D(
+                    [0],
+                    [0],
+                    marker="o",
+                    color="w",
+                    markerfacecolor=color,
+                    markeredgecolor="black",
+                    markersize=7,
+                    label=f"CS{cs_id}",
+                )
+            )
+
+        ax.legend(
+            handles=legend_elements,
+            loc="upper right",
+            fontsize=8,
+            frameon=True,
+            framealpha=0.9,
+            title="Credible sets",
+            title_fontsize=9,
+            handlelength=1.2,
+            handleheight=1.0,
+            labelspacing=0.3,
+        )
+
+    def add_simple_legend(
+        self,
+        ax: Axes,
+        label: str,
+        loc: str = "upper right",
+    ) -> None:
+        """Add simple legend for labeled scatter data."""
+        ax.legend(loc=loc, fontsize=9)
+
     def finalize_layout(
         self,
         fig: Figure,