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

pylocuszoom/__init__.py

@@ -34,14 +34,22 @@ Species Support:
     - Custom: User provides all reference data
 """
 
-__version__ = "0.1.0"
+__version__ = "0.6.0"
 
 # Main plotter class
 # Backend types
 from .backends import BackendType, get_backend
 
 # Colors and LD
-from .colors import LEAD_SNP_COLOR, get_ld_bin, get_ld_color, get_ld_color_palette
+from .colors import (
+    LEAD_SNP_COLOR,
+    PHEWAS_CATEGORY_COLORS,
+    get_ld_bin,
+    get_ld_color,
+    get_ld_color_palette,
+    get_phewas_category_color,
+    get_phewas_category_palette,
+)
 
 # eQTL support
 from .eqtl import (
@@ -65,6 +73,9 @@ from .finemapping import (
     validate_finemapping_df,
 )
 
+# Forest plot support
+from .forest import validate_forest_df
+
 # Gene track
 from .gene_track import get_nearest_gene, plot_gene_track
 
@@ -74,8 +85,36 @@ 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
+
+# PheWAS support
+from .phewas import validate_phewas_df
 from .plotter import LocusZoomPlotter
 
 # Reference data management
@@ -86,6 +125,9 @@ from .recombination import (
     load_recombination_map,
 )
 
+# Schema validation
+from .schemas import LoaderValidationError
+
 # Validation utilities
 from .utils import ValidationError, to_pandas
 
@@ -102,7 +144,10 @@ __all__ = [
     "get_ld_color",
     "get_ld_bin",
     "get_ld_color_palette",
+    "get_phewas_category_color",
+    "get_phewas_category_palette",
     "LEAD_SNP_COLOR",
+    "PHEWAS_CATEGORY_COLORS",
     # Gene track
     "get_nearest_gene",
     "plot_gene_track",
@@ -136,4 +181,31 @@ __all__ = [
     # Validation & Utils
     "ValidationError",
     "to_pandas",
+    # PheWAS
+    "validate_phewas_df",
+    # Forest plot
+    "validate_forest_df",
+    # 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,134 @@ 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.
+        """
+        ...
+
+    def axvline(
+        self,
+        ax: Any,
+        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.
+
+        Args:
+            ax: Axes or panel.
+            x: X-value for the line.
+            color: Line color.
+            linestyle: Line style.
+            linewidth: Line width.
+            alpha: Line transparency (0-1).
+            zorder: Drawing order.
+
+        Returns:
+            The line object.
+        """
+        ...
+
+    def hbar(
+        self,
+        ax: Any,
+        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.
+
+        Args:
+            ax: Axes or panel.
+            y: Y positions for bars.
+            width: Bar widths (x-extent).
+            height: Bar height.
+            left: Left edge positions.
+            color: Bar colors.
+            edgecolor: Edge color.
+            linewidth: Edge width.
+            zorder: Drawing order.
+
+        Returns:
+            The bar collection object.
+        """
+        ...
+
+    def errorbar_h(
+        self,
+        ax: Any,
+        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 (for forest plots).
+
+        Args:
+            ax: Axes or panel.
+            x: X positions (effect sizes).
+            y: Y positions.
+            xerr_lower: Lower error (distance from x).
+            xerr_upper: Upper error (distance from x).
+            color: Line color.
+            linewidth: Line width.
+            capsize: Cap size in points.
+            zorder: Drawing order.
+
+        Returns:
+            The errorbar object.
+        """
+        ...

pylocuszoom/backends/bokeh_backend.py

@@ -19,15 +19,24 @@ class BokehBackend:
     applications and dashboards.
     """
 
+    # Class constants for style mappings
+    _MARKER_MAP = {
+        "o": "circle",
+        "D": "diamond",
+        "s": "square",
+        "^": "triangle",
+        "v": "inverted_triangle",
+    }
+    _DASH_MAP = {
+        "-": "solid",
+        "--": "dashed",
+        ":": "dotted",
+        "-.": "dashdot",
+    }
+
     def __init__(self) -> None:
         """Initialize the bokeh backend."""
-        self._marker_map = {
-            "o": "circle",
-            "D": "diamond",
-            "s": "square",
-            "^": "triangle",
-            "v": "inverted_triangle",
-        }
+        pass
 
     def create_figure(
         self,
@@ -67,9 +76,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 +128,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}"))
@@ -127,7 +140,7 @@ class BokehBackend:
         source = ColumnDataSource(data)
 
         # Get marker type for scatter()
-        marker_type = self._marker_map.get(marker, "circle")
+        marker_type = self._MARKER_MAP.get(marker, "circle")
 
         # Create scatter using scatter() method (Bokeh 3.4+ preferred API)
         scatter_kwargs = {
@@ -167,14 +180,7 @@ class BokehBackend:
         label: Optional[str] = None,
     ) -> Any:
         """Create a line plot on the given figure."""
-        # Convert linestyle
-        dash_map = {
-            "-": "solid",
-            "--": "dashed",
-            ":": "dotted",
-            "-.": "dashdot",
-        }
-        line_dash = dash_map.get(linestyle, "solid")
+        line_dash = self._DASH_MAP.get(linestyle, "solid")
 
         line_kwargs = {
             "line_color": color,
@@ -229,8 +235,7 @@ class BokehBackend:
         zorder: int = 1,
     ) -> Any:
         """Add a horizontal line across the figure."""
-        dash_map = {"-": "solid", "--": "dashed", ":": "dotted", "-.": "dashdot"}
-        line_dash = dash_map.get(linestyle, "dashed")
+        line_dash = self._DASH_MAP.get(linestyle, "dashed")
 
         span = Span(
             location=y,
@@ -351,6 +356,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 = [
@@ -397,8 +412,7 @@ class BokehBackend:
         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")
+        line_dash = self._DASH_MAP.get(linestyle, "solid")
 
         return ax.line(
             x.values,
@@ -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,153 @@ 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 axvline(
+        self,
+        ax: figure,
+        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 figure."""
+        line_dash = self._DASH_MAP.get(linestyle, "dashed")
+
+        span = Span(
+            location=x,
+            dimension="height",
+            line_color=color,
+            line_dash=line_dash,
+            line_width=linewidth,
+            line_alpha=alpha,
+        )
+        ax.add_layout(span)
+        return span
+
+    def hbar(
+        self,
+        ax: figure,
+        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."""
+        # 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
+
+        # Calculate right edge
+        right_arr = [left_val + w for left_val, w in zip(left_arr, width)]
+
+        return ax.hbar(
+            y=y.values,
+            right=right_arr,
+            left=left_arr,
+            height=height,
+            fill_color=color,
+            line_color=edgecolor,
+            line_width=linewidth,
+        )
+
+    def errorbar_h(
+        self,
+        ax: figure,
+        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."""
+        from bokeh.models import Whisker
+
+        # Calculate bounds
+        lower = x - xerr_lower
+        upper = x + xerr_upper
+
+        source = ColumnDataSource(
+            data={
+                "y": y.values,
+                "lower": lower.values,
+                "upper": upper.values,
+            }
+        )
+
+        # Add horizontal whisker
+        whisker = Whisker(
+            source=source,
+            base="y",
+            lower="lower",
+            upper="upper",
+            dimension="width",
+            line_color=color,
+            line_width=linewidth,
+        )
+        ax.add_layout(whisker)
+        return whisker
+
     def finalize_layout(
         self,
         fig: Any,