pylocuszoom 1.0.0__py3-none-any.whl → 1.1.1__py3-none-any.whl

pylocuszoom/__init__.py

@@ -34,7 +34,7 @@ Species Support:
     - Custom: User provides all reference data
 """
 
-__version__ = "0.6.0"
+__version__ = "1.1.1"
 
 # Main plotter class
 # Backend types
@@ -133,6 +133,9 @@ from .loaders import (
 # Logging configuration
 from .logging import disable_logging, enable_logging
 
+# Manhattan and QQ plotting
+from .manhattan_plotter import ManhattanPlotter
+
 # PheWAS support
 from .phewas import validate_phewas_df
 from .plotter import LocusZoomPlotter
@@ -145,6 +148,9 @@ from .recombination import (
     load_recombination_map,
 )
 
+# Statistical visualizations (PheWAS, forest plots)
+from .stats_plotter import StatsPlotter
+
 # Validation utilities
 from .utils import to_pandas
 
@@ -152,6 +158,8 @@ __all__ = [
     # Core
     "__version__",
     "LocusZoomPlotter",
+    "ManhattanPlotter",
+    "StatsPlotter",
     # Backends
     "BackendType",
     "get_backend",

pylocuszoom/_plotter_utils.py

@@ -0,0 +1,66 @@
+"""Shared utilities for plotter classes.
+
+Internal module - not part of public API.
+"""
+
+from typing import Any, Optional
+
+import numpy as np
+import pandas as pd
+
+# Significance thresholds
+DEFAULT_GENOMEWIDE_THRESHOLD = 5e-8
+
+# Manhattan/QQ plot styling constants
+MANHATTAN_POINT_SIZE = 10
+MANHATTAN_CATEGORICAL_POINT_SIZE = 30
+QQ_POINT_SIZE = 10
+POINT_EDGE_COLOR = "black"
+MANHATTAN_EDGE_WIDTH = 0.1
+QQ_EDGE_WIDTH = 0.02
+QQ_POINT_COLOR = "#1f77b4"
+QQ_CI_COLOR = "#CCCCCC"
+QQ_CI_ALPHA = 0.5
+SIGNIFICANCE_LINE_COLOR = "red"
+
+
+def transform_pvalues(df: pd.DataFrame, p_col: str) -> pd.DataFrame:
+    """Add neglog10p column with -log10 transformed p-values.
+
+    Clips extremely small p-values to 1e-300 to avoid -inf.
+
+    Args:
+        df: DataFrame with p-value column.
+        p_col: Name of p-value column.
+
+    Returns:
+        DataFrame with neglog10p column added.
+    """
+    df = df.copy()
+    df["neglog10p"] = -np.log10(df[p_col].clip(lower=1e-300))
+    return df
+
+
+def add_significance_line(
+    backend: Any,
+    ax: Any,
+    threshold: Optional[float],
+) -> None:
+    """Add genome-wide significance threshold line.
+
+    Args:
+        backend: Plot backend instance.
+        ax: Axes object from backend.
+        threshold: P-value threshold (e.g., 5e-8). None to skip.
+    """
+    if threshold is None:
+        return
+    threshold_line = -np.log10(threshold)
+    backend.axhline(
+        ax,
+        y=threshold_line,
+        color=SIGNIFICANCE_LINE_COLOR,
+        linestyle="--",
+        linewidth=1,
+        zorder=1,
+    )

pylocuszoom/backends/base.py

@@ -96,6 +96,31 @@ class PlotBackend(Protocol):
         """
         ...
 
+    def create_figure_grid(
+        self,
+        n_rows: int,
+        n_cols: int,
+        width_ratios: Optional[List[float]] = None,
+        height_ratios: Optional[List[float]] = None,
+        figsize: Tuple[float, float] = (12.0, 8.0),
+    ) -> Tuple[Any, List[Any]]:
+        """Create a figure with a grid of subplots.
+
+        Unlike create_figure which creates vertically stacked panels,
+        this creates a 2D grid of subplots.
+
+        Args:
+            n_rows: Number of rows.
+            n_cols: Number of columns.
+            width_ratios: Relative widths for columns.
+            height_ratios: Relative heights for rows.
+            figsize: Figure size as (width, height).
+
+        Returns:
+            Tuple of (figure, flattened list of axes).
+        """
+        ...
+
     # =========================================================================
     # Basic Plotting
     # =========================================================================
@@ -442,6 +467,27 @@ class PlotBackend(Protocol):
         """
         ...
 
+    def set_xticks(
+        self,
+        ax: Any,
+        positions: List[float],
+        labels: List[str],
+        fontsize: int = 10,
+        rotation: int = 0,
+        ha: str = "center",
+    ) -> None:
+        """Set x-axis tick positions and labels.
+
+        Args:
+            ax: Axes or panel.
+            positions: Tick positions.
+            labels: Tick labels.
+            fontsize: Font size.
+            rotation: Label rotation in degrees.
+            ha: Horizontal alignment for rotated labels.
+        """
+        ...
+
     def set_title(self, ax: Any, title: str, fontsize: int = 14) -> None:
         """Set panel title.
 
@@ -452,6 +498,16 @@ class PlotBackend(Protocol):
         """
         ...
 
+    def set_suptitle(self, fig: Any, title: str, fontsize: int = 14) -> None:
+        """Set overall figure title (super title).
+
+        Args:
+            fig: Figure object.
+            title: Title text.
+            fontsize: Font size.
+        """
+        ...
+
     def hide_spines(self, ax: Any, spines: List[str]) -> None:
         """Hide specified axis spines.
 

pylocuszoom/backends/bokeh_backend.py

@@ -6,13 +6,27 @@ Interactive backend with hover tooltips, well-suited for dashboards.
 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.layouts import column, row
 from bokeh.models import ColumnDataSource, DataRange1d, HoverTool, Span
 from bokeh.plotting import figure
 
 from . import convert_latex_to_unicode, register_backend
 
+# Style mappings (matplotlib -> Bokeh)
+_MARKER_MAP = {
+    "o": "circle",
+    "D": "diamond",
+    "s": "square",
+    "^": "triangle",
+    "v": "inverted_triangle",
+}
+_DASH_MAP = {
+    "-": "solid",
+    "--": "dashed",
+    ":": "dotted",
+    "-.": "dashdot",
+}
+
 
 @register_backend("bokeh")
 class BokehBackend:
@@ -22,21 +36,6 @@ 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",
-    }
-
     @property
     def supports_snp_labels(self) -> bool:
         """Bokeh uses hover tooltips instead of labels."""
@@ -105,6 +104,73 @@ class BokehBackend:
 
         return layout, figures
 
+    def create_figure_grid(
+        self,
+        n_rows: int,
+        n_cols: int,
+        width_ratios: Optional[List[float]] = None,
+        height_ratios: Optional[List[float]] = None,
+        figsize: Tuple[float, float] = (12.0, 8.0),
+    ) -> Tuple[Any, List[figure]]:
+        """Create a layout with a grid of subplots.
+
+        Args:
+            n_rows: Number of rows.
+            n_cols: Number of columns.
+            width_ratios: Relative widths for columns.
+            height_ratios: Relative heights for rows.
+            figsize: Figure size as (width, height).
+
+        Returns:
+            Tuple of (layout, flattened list of figure objects).
+        """
+        width_px = int(figsize[0] * 100)
+        height_px = int(figsize[1] * 100)
+
+        # Calculate widths
+        if width_ratios is not None:
+            total_w = sum(width_ratios)
+            widths = [int(width_px * w / total_w) for w in width_ratios]
+        else:
+            widths = [width_px // n_cols] * n_cols
+
+        # Calculate heights
+        if height_ratios is not None:
+            total_h = sum(height_ratios)
+            heights = [int(height_px * h / total_h) for h in height_ratios]
+        else:
+            heights = [height_px // n_rows] * n_rows
+
+        figures = []
+        rows = []
+
+        for i in range(n_rows):
+            row_figures = []
+            for j in range(n_cols):
+                p = figure(
+                    width=widths[j],
+                    height=heights[i],
+                    tools="pan,wheel_zoom,box_zoom,reset,save",
+                    toolbar_location="above" if i == 0 and j == 0 else None,
+                )
+
+                # Style
+                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
+
+                row_figures.append(p)
+                figures.append(p)
+
+            rows.append(row(*row_figures))
+
+        layout = column(*rows)
+
+        return layout, figures
+
     def scatter(
         self,
         ax: figure,
@@ -153,8 +219,7 @@ class BokehBackend:
 
         source = ColumnDataSource(data)
 
-        # Get marker type for scatter()
-        marker_type = self._MARKER_MAP.get(marker, "circle")
+        marker_type = _MARKER_MAP.get(marker, "circle")
 
         # Create scatter using scatter() method (Bokeh 3.4+ preferred API)
         scatter_kwargs = {
@@ -194,7 +259,7 @@ class BokehBackend:
         label: Optional[str] = None,
     ) -> Any:
         """Create a line plot on the given figure."""
-        line_dash = self._DASH_MAP.get(linestyle, "solid")
+        line_dash = _DASH_MAP.get(linestyle, "solid")
 
         line_kwargs = {
             "line_color": color,
@@ -249,7 +314,7 @@ class BokehBackend:
         zorder: int = 1,
     ) -> Any:
         """Add a horizontal line across the figure."""
-        line_dash = self._DASH_MAP.get(linestyle, "dashed")
+        line_dash = _DASH_MAP.get(linestyle, "dashed")
 
         span = Span(
             location=y,
@@ -379,9 +444,31 @@ class BokehBackend:
     ) -> None:
         """Set y-axis tick positions and labels."""
         ax.yaxis.ticker = positions
-        ax.yaxis.major_label_overrides = dict(zip(positions, labels))
+        ax.yaxis.major_label_overrides = {
+            pos: label for pos, label in zip(positions, labels)
+        }
         ax.yaxis.major_label_text_font_size = f"{fontsize}pt"
 
+    def set_xticks(
+        self,
+        ax: figure,
+        positions: List[float],
+        labels: List[str],
+        fontsize: int = 10,
+        rotation: int = 0,
+        ha: str = "center",
+    ) -> None:
+        """Set x-axis tick positions and labels."""
+        ax.xaxis.ticker = positions
+        ax.xaxis.major_label_overrides = {
+            pos: label for pos, label in zip(positions, labels)
+        }
+        ax.xaxis.major_label_text_font_size = f"{fontsize}pt"
+        if rotation:
+            ax.xaxis.major_label_orientation = (
+                rotation * 3.14159 / 180
+            )  # Convert to radians
+
     def _get_legend_location(self, loc: str, default: str = "top_left") -> str:
         """Map matplotlib-style legend location to Bokeh location."""
         loc_map = {
@@ -401,6 +488,22 @@ class BokehBackend:
         ax.title.text = title
         ax.title.text_font_size = f"{fontsize}pt"
 
+    def set_suptitle(self, fig: Any, title: str, fontsize: int = 14) -> None:
+        """Set overall figure title.
+
+        For Bokeh layouts, add title to the first figure in the layout.
+        """
+        from bokeh.models.layouts import Column
+
+        if isinstance(fig, Column) and len(fig.children) > 0:
+            first_child = fig.children[0]
+            if hasattr(first_child, "title"):
+                first_child.title.text = title
+                first_child.title.text_font_size = f"{fontsize}pt"
+        elif hasattr(fig, "title"):
+            fig.title.text = title
+            fig.title.text_font_size = f"{fontsize}pt"
+
     def create_twin_axis(self, ax: figure) -> Any:
         """Create a secondary y-axis.
 
@@ -408,9 +511,15 @@ class BokehBackend:
         """
         from bokeh.models import LinearAxis, Range1d
 
-        # Add a second y-axis
+        # Add a second y-axis without tick marks (cleaner look)
         ax.extra_y_ranges = {"secondary": Range1d(start=0, end=100)}
-        ax.add_layout(LinearAxis(y_range_name="secondary"), "right")
+        secondary_axis = LinearAxis(
+            y_range_name="secondary",
+            major_tick_line_color=None,  # Hide major ticks
+            minor_tick_line_color=None,  # Hide minor ticks
+            major_label_text_font_size="0pt",  # Hide tick labels
+        )
+        ax.add_layout(secondary_axis, "right")
 
         return "secondary"
 
@@ -427,7 +536,7 @@ class BokehBackend:
         yaxis_name: str = "secondary",
     ) -> Any:
         """Create a line plot on secondary y-axis."""
-        line_dash = self._DASH_MAP.get(linestyle, "solid")
+        line_dash = _DASH_MAP.get(linestyle, "solid")
 
         return ax.line(
             x.values,
@@ -570,7 +679,7 @@ class BokehBackend:
         label: str,
         color: str,
         marker: str,
-        size: int = 10,
+        size: int = 14,
     ) -> Any:
         """Create an invisible scatter renderer for a legend entry."""
         from bokeh.models import LegendItem
@@ -619,7 +728,7 @@ class BokehBackend:
         """
         source = self._ensure_legend_range(ax)
         items = [
-            self._add_legend_item(ax, source, "Lead SNP", lead_snp_color, "diamond", 12)
+            self._add_legend_item(ax, source, "Lead SNP", lead_snp_color, "diamond", 16)
         ]
         for _, label, color in ld_bins:
             items.append(self._add_legend_item(ax, source, label, color, "square"))
@@ -674,6 +783,8 @@ class BokehBackend:
 
         Supports .html for interactive and .png for static.
         """
+        from bokeh.io import export_png, export_svgs, output_file, save
+
         if path.endswith(".html"):
             output_file(path)
             save(fig)
@@ -682,12 +793,13 @@ class BokehBackend:
         elif path.endswith(".svg"):
             export_svgs(fig, filename=path)
         else:
-            # Default to HTML
             output_file(path)
             save(fig)
 
     def show(self, fig: Any) -> None:
         """Display the figure."""
+        from bokeh.io import show
+
         show(fig)
 
     def close(self, fig: Any) -> None:
@@ -756,7 +868,7 @@ class BokehBackend:
         zorder: int = 1,
     ) -> Any:
         """Add a vertical line across the figure."""
-        line_dash = self._DASH_MAP.get(linestyle, "dashed")
+        line_dash = _DASH_MAP.get(linestyle, "dashed")
 
         span = Span(
             location=x,

pylocuszoom/backends/matplotlib_backend.py

@@ -82,6 +82,48 @@ class MatplotlibBackend:
 
         return fig, list(axes)
 
+    def create_figure_grid(
+        self,
+        n_rows: int,
+        n_cols: int,
+        width_ratios: Optional[List[float]] = None,
+        height_ratios: Optional[List[float]] = None,
+        figsize: Tuple[float, float] = (12.0, 8.0),
+    ) -> Tuple[Figure, List[Axes]]:
+        """Create a figure with a grid of subplots.
+
+        Args:
+            n_rows: Number of rows.
+            n_cols: Number of columns.
+            width_ratios: Relative widths for columns.
+            height_ratios: Relative heights for rows.
+            figsize: Figure size as (width, height).
+
+        Returns:
+            Tuple of (figure, flattened list of axes).
+        """
+        plt.ioff()
+
+        gridspec_kw = {}
+        if width_ratios is not None:
+            gridspec_kw["width_ratios"] = width_ratios
+        if height_ratios is not None:
+            gridspec_kw["height_ratios"] = height_ratios
+
+        fig, axes = plt.subplots(
+            n_rows,
+            n_cols,
+            figsize=figsize,
+            gridspec_kw=gridspec_kw if gridspec_kw else None,
+        )
+
+        # Flatten axes to list
+        import numpy as np
+
+        if isinstance(axes, np.ndarray):
+            return fig, list(axes.flatten())
+        return fig, [axes]
+
     def scatter(
         self,
         ax: Axes,
@@ -320,6 +362,19 @@ class MatplotlibBackend:
         ax.set_yticks(positions)
         ax.set_yticklabels(labels, fontsize=fontsize)
 
+    def set_xticks(
+        self,
+        ax: Axes,
+        positions: List[float],
+        labels: List[str],
+        fontsize: int = 10,
+        rotation: int = 0,
+        ha: str = "center",
+    ) -> None:
+        """Set x-axis tick positions and labels."""
+        ax.set_xticks(positions)
+        ax.set_xticklabels(labels, fontsize=fontsize, rotation=rotation, ha=ha)
+
     def set_title(self, ax: Axes, title: str, fontsize: int = 14) -> None:
         """Set panel title."""
         ax.set_title(
@@ -329,6 +384,10 @@ class MatplotlibBackend:
             fontfamily="sans-serif",
         )
 
+    def set_suptitle(self, fig: Figure, title: str, fontsize: int = 14) -> None:
+        """Set overall figure title (super title)."""
+        fig.suptitle(title, fontsize=fontsize, fontweight="bold")
+
     def create_twin_axis(self, ax: Axes) -> Axes:
         """Create a secondary y-axis sharing the same x-axis."""
         return ax.twinx()
@@ -445,6 +504,7 @@ class MatplotlibBackend:
             yaxis_name: Ignored for matplotlib.
         """
         ax.set_ylabel(label, fontsize=fontsize, color=color)
+        ax.tick_params(axis="y", labelcolor=color, labelsize=fontsize - 1)
 
     def add_legend(
         self,