pylocuszoom 0.5.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.3.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
 
@@ -101,6 +112,9 @@ from .loaders import (
 
 # Logging configuration
 from .logging import disable_logging, enable_logging
+
+# PheWAS support
+from .phewas import validate_phewas_df
 from .plotter import LocusZoomPlotter
 
 # Reference data management
@@ -130,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",
@@ -164,6 +181,10 @@ __all__ = [
     # Validation & Utils
     "ValidationError",
     "to_pandas",
+    # PheWAS
+    "validate_phewas_df",
+    # Forest plot
+    "validate_forest_df",
     # GWAS loaders
     "load_gwas",
     "load_plink_assoc",

pylocuszoom/backends/base.py

@@ -386,3 +386,89 @@ class PlotBackend(Protocol):
             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,
@@ -131,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 = {
@@ -171,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,
@@ -233,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,
@@ -411,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,
@@ -683,6 +683,102 @@ class BokehBackend:
         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,

pylocuszoom/backends/matplotlib_backend.py

@@ -394,6 +394,75 @@ class MatplotlibBackend:
         """Add simple legend for labeled scatter data."""
         ax.legend(loc=loc, fontsize=9)
 
+    def axvline(
+        self,
+        ax: Axes,
+        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."""
+        return ax.axvline(
+            x=x,
+            color=color,
+            linestyle=linestyle,
+            linewidth=linewidth,
+            alpha=alpha,
+            zorder=zorder,
+        )
+
+    def hbar(
+        self,
+        ax: Axes,
+        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."""
+        return ax.barh(
+            y=y,
+            width=width,
+            height=height,
+            left=left,
+            color=color,
+            edgecolor=edgecolor,
+            linewidth=linewidth,
+            zorder=zorder,
+        )
+
+    def errorbar_h(
+        self,
+        ax: Axes,
+        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."""
+        xerr = [xerr_lower.values, xerr_upper.values]
+        return ax.errorbar(
+            x=x,
+            y=y,
+            xerr=xerr,
+            fmt="none",
+            ecolor=color,
+            elinewidth=linewidth,
+            capsize=capsize,
+            zorder=zorder,
+        )
+
     def finalize_layout(
         self,
         fig: Figure,

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,
@@ -111,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)):
@@ -178,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,
@@ -244,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,
@@ -461,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,
@@ -782,6 +779,101 @@ class PlotlyBackend:
             )
         )
 
+    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,

pylocuszoom/colors.py

@@ -239,3 +239,44 @@ def get_credible_set_color_palette(n_sets: int = 10) -> dict[int, str]:
     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)}"
+        )