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

pylocuszoom/plotter.py

@@ -15,12 +15,10 @@ from typing import Any, List, Optional, Tuple
 import matplotlib.pyplot as plt
 import numpy as np
 import pandas as pd
-from matplotlib.axes import Axes
-from matplotlib.figure import Figure
-from matplotlib.lines import Line2D
-from matplotlib.patches import Patch
+import requests
 
 from .backends import BackendType, get_backend
+from .backends.hover import HoverConfig, HoverDataBuilder
 from .colors import (
     EQTL_NEGATIVE_BINS,
     EQTL_POSITIVE_BINS,
@@ -33,6 +31,8 @@ from .colors import (
     get_ld_color_palette,
     get_phewas_category_palette,
 )
+from .config import PlotConfig, StackedPlotConfig
+from .ensembl import get_genes_for_region
 from .eqtl import validate_eqtl_df
 from .finemapping import (
     get_credible_sets,
@@ -41,16 +41,13 @@ from .finemapping import (
 from .forest import validate_forest_df
 from .gene_track import (
     assign_gene_positions,
-    plot_gene_track,
     plot_gene_track_generic,
 )
-from .labels import add_snp_labels
 from .ld import calculate_ld, find_plink
 from .logging import enable_logging, logger
 from .phewas import validate_phewas_df
 from .recombination import (
     RECOMB_COLOR,
-    add_recombination_overlay,
     download_canine_recombination_maps,
     get_default_data_dir,
     get_recombination_rate_for_region,
@@ -119,8 +116,21 @@ class LocusZoomPlotter:
         recomb_data_dir: Optional[str] = None,
         genomewide_threshold: float = DEFAULT_GENOMEWIDE_THRESHOLD,
         log_level: Optional[str] = "INFO",
+        auto_genes: bool = False,
     ):
-        """Initialize the plotter."""
+        """Initialize the plotter.
+
+        Args:
+            species: Species name ('canine', 'feline', or None for custom).
+            genome_build: Genome build for coordinate system.
+            backend: Plotting backend ('matplotlib', 'plotly', or 'bokeh').
+            plink_path: Path to PLINK executable for LD calculation.
+            recomb_data_dir: Directory containing recombination maps.
+            genomewide_threshold: P-value threshold for significance line.
+            log_level: Logging level.
+            auto_genes: If True, automatically fetch genes from Ensembl when
+                genes_df is not provided. Default False for backward compatibility.
+        """
         # Configure logging
         if log_level is not None:
             enable_logging(log_level)
@@ -129,12 +139,12 @@ class LocusZoomPlotter:
         self.genome_build = (
             genome_build if genome_build else self._default_build(species)
         )
-        self.backend_name = backend
         self._backend = get_backend(backend)
         self.plink_path = plink_path or find_plink()
         self.recomb_data_dir = recomb_data_dir
         self.genomewide_threshold = genomewide_threshold
         self._genomewide_line = -np.log10(genomewide_threshold)
+        self._auto_genes = auto_genes
 
         # Cache for loaded data
         self._recomb_cache = {}
@@ -163,9 +173,17 @@ class LocusZoomPlotter:
             # Download
             try:
                 return download_canine_recombination_maps()
-            except Exception as e:
+            except (requests.RequestException, OSError, IOError) as e:
+                # Expected network/file errors - graceful fallback
                 logger.warning(f"Could not download recombination maps: {e}")
                 return None
+            except Exception as e:
+                # JUSTIFICATION: Download failure should not prevent plotting.
+                # We catch broadly here because graceful degradation is acceptable
+                # for optional recombination map downloads. Error-level logging
+                # ensures the issue is visible.
+                logger.error(f"Unexpected error downloading recombination maps: {e}")
+                return None
         elif self.recomb_data_dir:
             return Path(self.recomb_data_dir)
         return None
@@ -199,55 +217,94 @@ class LocusZoomPlotter:
     def plot(
         self,
         gwas_df: pd.DataFrame,
+        *,
         chrom: int,
         start: int,
         end: int,
+        pos_col: str = "ps",
+        p_col: str = "p_wald",
+        rs_col: str = "rs",
+        snp_labels: bool = True,
+        label_top_n: int = 5,
+        show_recombination: bool = True,
+        figsize: Tuple[float, float] = (12.0, 8.0),
         lead_pos: Optional[int] = None,
         ld_reference_file: Optional[str] = None,
         ld_col: Optional[str] = None,
         genes_df: Optional[pd.DataFrame] = None,
         exons_df: Optional[pd.DataFrame] = None,
         recomb_df: Optional[pd.DataFrame] = None,
-        show_recombination: bool = True,
-        snp_labels: bool = True,
-        label_top_n: int = 5,
-        pos_col: str = "ps",
-        p_col: str = "p_wald",
-        rs_col: str = "rs",
-        figsize: Tuple[int, int] = (12, 8),
     ) -> Any:
         """Create a regional association plot.
 
         Args:
             gwas_df: GWAS results DataFrame.
             chrom: Chromosome number.
-            start: Start position of the region.
-            end: End position of the region.
-            lead_pos: Position of the lead/index SNP to highlight.
-            ld_reference_file: PLINK binary fileset for LD calculation.
-                If provided with lead_pos, calculates LD on the fly.
-            ld_col: Column name for pre-computed LD (R²) values.
-                Use this if LD was calculated externally.
+            start: Start position in base pairs.
+            end: End position in base pairs.
+            pos_col: Column name for genomic position.
+            p_col: Column name for p-value.
+            rs_col: Column name for SNP identifier.
+            snp_labels: Whether to show SNP labels on plot.
+            label_top_n: Number of top SNPs to label.
+            show_recombination: Whether to show recombination rate overlay.
+            figsize: Figure size as (width, height) in inches.
+            lead_pos: Position of lead/index SNP to highlight.
+            ld_reference_file: Path to PLINK binary fileset for LD calculation.
+            ld_col: Column name for pre-computed LD (R^2) values.
             genes_df: Gene annotations with chr, start, end, gene_name.
             exons_df: Exon annotations with chr, start, end, gene_name.
             recomb_df: Pre-loaded recombination rate data.
                 If None and show_recombination=True, loads from species default.
-            show_recombination: Whether to show recombination rate overlay.
-            snp_labels: Whether to label top SNPs.
-            label_top_n: Number of top SNPs to label.
-            pos_col: Column name for position.
-            p_col: Column name for p-value.
-            rs_col: Column name for SNP ID.
-            figsize: Figure size.
 
         Returns:
-            Matplotlib Figure object.
+            Figure object (type depends on backend).
 
         Raises:
-            ValidationError: If required DataFrame columns are missing.
+            ValidationError: If parameters or DataFrame columns are invalid.
+
+        Example:
+            >>> fig = plotter.plot(
+            ...     gwas_df,
+            ...     chrom=1, start=1000000, end=2000000,
+            ...     lead_pos=1500000, snp_labels=True,
+            ... )
         """
+        # Validate parameters via Pydantic
+        PlotConfig.from_kwargs(
+            chrom=chrom,
+            start=start,
+            end=end,
+            pos_col=pos_col,
+            p_col=p_col,
+            rs_col=rs_col,
+            snp_labels=snp_labels,
+            label_top_n=label_top_n,
+            show_recombination=show_recombination,
+            figsize=figsize,
+            lead_pos=lead_pos,
+            ld_reference_file=ld_reference_file,
+            ld_col=ld_col,
+        )
+
         # Validate inputs
         validate_gwas_df(gwas_df, pos_col=pos_col, p_col=p_col)
+
+        # Auto-fetch genes if enabled and not provided
+        if genes_df is None and self._auto_genes:
+            logger.debug(
+                f"auto_genes enabled, fetching genes for chr{chrom}:{start}-{end}"
+            )
+            genes_df = get_genes_for_region(
+                species=self.species,
+                chrom=chrom,
+                start=start,
+                end=end,
+            )
+            if genes_df.empty:
+                logger.debug("No genes found in region from Ensembl")
+                genes_df = None
+
         if genes_df is not None:
             validate_genes_df(genes_df)
 
@@ -258,6 +315,23 @@ class LocusZoomPlotter:
 
         # Prepare data
         df = gwas_df.copy()
+
+        # Validate p-values and warn about issues
+        p_values = df[p_col]
+        nan_count = p_values.isna().sum()
+        if nan_count > 0:
+            logger.warning(
+                f"GWAS data contains {nan_count} NaN p-values which will be excluded"
+            )
+        invalid_count = ((p_values < 0) | (p_values > 1)).sum()
+        if invalid_count > 0:
+            logger.warning(
+                f"GWAS data contains {invalid_count} p-values outside [0, 1] range"
+            )
+        clipped_count = (p_values < 1e-300).sum()
+        if clipped_count > 0:
+            logger.debug(f"Clipping {clipped_count} p-values below 1e-300 to 1e-300")
+
         df["neglog10p"] = -np.log10(df[p_col].clip(lower=1e-300))
 
         # Calculate LD if reference file provided
@@ -305,10 +379,10 @@ class LocusZoomPlotter:
             zorder=1,
         )
 
-        # Add SNP labels (matplotlib only - interactive backends use hover tooltips)
+        # Add SNP labels (capability check - interactive backends use hover tooltips)
         if snp_labels and rs_col in df.columns and label_top_n > 0 and not df.empty:
-            if self.backend_name == "matplotlib":
-                add_snp_labels(
+            if self._backend.supports_snp_labels:
+                self._backend.add_snp_labels(
                     ax,
                     df,
                     pos_col=pos_col,
@@ -319,12 +393,10 @@ class LocusZoomPlotter:
                     chrom=chrom,
                 )
 
-        # Add recombination overlay (all backends)
+        # Add recombination overlay (all backends with secondary axis support)
         if recomb_df is not None and not recomb_df.empty:
-            if self.backend_name == "matplotlib":
-                add_recombination_overlay(ax, recomb_df, start, end)
-            else:
-                self._add_recombination_overlay_generic(ax, recomb_df, start, end)
+            if self._backend.supports_secondary_axis:
+                self._add_recombination_overlay(ax, recomb_df, start, end)
 
         # Format axes
         self._backend.set_ylabel(ax, r"$-\log_{10}$ P")
@@ -333,25 +405,21 @@ class LocusZoomPlotter:
 
         # Add LD legend (all backends)
         if ld_col is not None and ld_col in df.columns:
-            if self.backend_name == "matplotlib":
-                self._add_ld_legend(ax)
-            else:
-                self._backend.add_ld_legend(ax, LD_BINS, LEAD_SNP_COLOR)
+            self._backend.add_ld_legend(ax, LD_BINS, LEAD_SNP_COLOR)
 
-        # Plot gene track (all backends)
+        # Plot gene track (all backends use generic function)
         if genes_df is not None and gene_ax is not None:
-            if self.backend_name == "matplotlib":
-                plot_gene_track(gene_ax, genes_df, chrom, start, end, exons_df)
-            else:
-                plot_gene_track_generic(
-                    gene_ax, self._backend, genes_df, chrom, start, end, exons_df
-                )
+            plot_gene_track_generic(
+                gene_ax, self._backend, genes_df, chrom, start, end, exons_df
+            )
             self._backend.set_xlabel(gene_ax, f"Chromosome {chrom} (Mb)")
             self._backend.hide_spines(gene_ax, ["top", "right", "left"])
+            # Format both axes for interactive backends (they don't share x-axis)
+            self._backend.format_xaxis_mb(gene_ax)
         else:
             self._backend.set_xlabel(ax, f"Chromosome {chrom} (Mb)")
 
-        # Format x-axis with Mb labels
+        # Format x-axis with Mb labels (association axis always needs formatting)
         self._backend.format_xaxis_mb(ax)
 
         # Adjust layout
@@ -366,7 +434,7 @@ class LocusZoomPlotter:
         start: int,
         end: int,
         figsize: Tuple[int, int],
-    ) -> Tuple[Figure, Axes, Optional[Axes]]:
+    ) -> Tuple[Any, Any, Optional[Any]]:
         """Create figure with optional gene track."""
         if genes_df is not None:
             # Calculate dynamic height based on gene rows
@@ -410,7 +478,7 @@ class LocusZoomPlotter:
 
     def _plot_association(
         self,
-        ax: Axes,
+        ax: Any,
         df: pd.DataFrame,
         pos_col: str,
         ld_col: Optional[str],
@@ -419,23 +487,14 @@ class LocusZoomPlotter:
         p_col: Optional[str] = None,
     ) -> None:
         """Plot association scatter with LD coloring."""
-
-        def _build_hover_data(subset_df: pd.DataFrame) -> Optional[pd.DataFrame]:
-            """Build hover data for interactive backends."""
-            hover_cols = {}
-            # RS ID first (will be bold in hover)
-            if rs_col and rs_col in subset_df.columns:
-                hover_cols["SNP"] = subset_df[rs_col].values
-            # Position
-            if pos_col in subset_df.columns:
-                hover_cols["Position"] = subset_df[pos_col].values
-            # P-value
-            if p_col and p_col in subset_df.columns:
-                hover_cols["P-value"] = subset_df[p_col].values
-            # LD
-            if ld_col and ld_col in subset_df.columns:
-                hover_cols["R²"] = subset_df[ld_col].values
-            return pd.DataFrame(hover_cols) if hover_cols else None
+        # Build hover data using HoverDataBuilder
+        hover_config = HoverConfig(
+            snp_col=rs_col if rs_col and rs_col in df.columns else None,
+            pos_col=pos_col if pos_col in df.columns else None,
+            p_col=p_col if p_col and p_col in df.columns else None,
+            ld_col=ld_col if ld_col and ld_col in df.columns else None,
+        )
+        hover_builder = HoverDataBuilder(hover_config)
 
         # LD-based coloring
         if ld_col is not None and ld_col in df.columns:
@@ -454,7 +513,7 @@ class LocusZoomPlotter:
                     edgecolor="black",
                     linewidth=0.5,
                     zorder=2,
-                    hover_data=_build_hover_data(bin_data),
+                    hover_data=hover_builder.build_dataframe(bin_data),
                 )
         else:
             # Default: grey points
@@ -467,7 +526,7 @@ class LocusZoomPlotter:
                 edgecolor="black",
                 linewidth=0.5,
                 zorder=2,
-                hover_data=_build_hover_data(df),
+                hover_data=hover_builder.build_dataframe(df),
             )
 
         # Highlight lead SNP with larger, more prominent marker
@@ -484,57 +543,21 @@ class LocusZoomPlotter:
                     edgecolor="black",
                     linewidth=1.5,
                     zorder=10,
-                    hover_data=_build_hover_data(lead_snp),
+                    hover_data=hover_builder.build_dataframe(lead_snp),
                 )
 
-    def _add_ld_legend(self, ax: Axes) -> None:
-        """Add LD color legend to plot."""
-        palette = get_ld_color_palette()
-        legend_elements = [
-            Line2D(
-                [0],
-                [0],
-                marker="D",
-                color="w",
-                markerfacecolor=LEAD_SNP_COLOR,
-                markeredgecolor="black",
-                markersize=6,
-                label="Lead SNP",
-            ),
-        ]
-
-        for threshold, label, _ in LD_BINS:
-            legend_elements.append(
-                Patch(
-                    facecolor=palette[label],
-                    edgecolor="black",
-                    label=label,
-                )
-            )
-
-        ax.legend(
-            handles=legend_elements,
-            loc="upper right",
-            fontsize=9,
-            frameon=True,
-            framealpha=0.9,
-            title=r"$r^2$",
-            title_fontsize=10,
-            handlelength=1.5,
-            handleheight=1.0,
-            labelspacing=0.4,
-        )
-
-    def _add_recombination_overlay_generic(
+    def _add_recombination_overlay(
         self,
         ax: Any,
         recomb_df: pd.DataFrame,
         start: int,
         end: int,
     ) -> None:
-        """Add recombination overlay for interactive backends (plotly/bokeh).
+        """Add recombination overlay for all backends.
 
         Creates a secondary y-axis with recombination rate line and fill.
+        Uses backend-agnostic secondary axis methods that work across
+        matplotlib, plotly, and bokeh.
         """
         # Filter to region
         region_recomb = recomb_df[
@@ -545,18 +568,29 @@ class LocusZoomPlotter:
             return
 
         # Create secondary y-axis
-        yaxis_name = self._backend.create_twin_axis(ax)
-
-        # For plotly, yaxis_name is a tuple (fig, row, secondary_y)
-        # For bokeh, yaxis_name is just a string
-        if isinstance(yaxis_name, tuple):
-            _, _, secondary_y = yaxis_name
+        twin_result = self._backend.create_twin_axis(ax)
+
+        # Matplotlib returns the twin Axes object itself - use it for drawing
+        # Plotly returns tuple (fig, row, secondary_y_name)
+        # Bokeh returns string "secondary"
+        from matplotlib.axes import Axes
+
+        if isinstance(twin_result, Axes):
+            # Matplotlib: use the twin axis for all secondary axis operations
+            secondary_ax = twin_result
+            secondary_y = None  # Not used for matplotlib
+        elif isinstance(twin_result, tuple):
+            # Plotly: use original ax, specify y-axis via yaxis_name
+            secondary_ax = ax
+            _, _, secondary_y = twin_result
         else:
-            secondary_y = yaxis_name
+            # Bokeh: use original ax, specify y-axis via yaxis_name
+            secondary_ax = ax
+            secondary_y = twin_result
 
         # Plot fill under curve
         self._backend.fill_between_secondary(
-            ax,
+            secondary_ax,
             region_recomb["pos"],
             0,
             region_recomb["rate"],
@@ -567,7 +601,7 @@ class LocusZoomPlotter:
 
         # Plot recombination rate line
         self._backend.line_secondary(
-            ax,
+            secondary_ax,
             region_recomb["pos"],
             region_recomb["rate"],
             color=RECOMB_COLOR,
@@ -579,10 +613,10 @@ class LocusZoomPlotter:
         # Set y-axis limits and label
         max_rate = region_recomb["rate"].max()
         self._backend.set_secondary_ylim(
-            ax, 0, max(max_rate * 1.2, 20), yaxis_name=secondary_y
+            secondary_ax, 0, max(max_rate * 1.2, 20), yaxis_name=secondary_y
         )
         self._backend.set_secondary_ylabel(
-            ax,
+            secondary_ax,
             "Recombination rate (cM/Mb)",
             color=RECOMB_COLOR,
             fontsize=9,
@@ -591,7 +625,7 @@ class LocusZoomPlotter:
 
     def _plot_finemapping(
         self,
-        ax: Axes,
+        ax: Any,
         df: pd.DataFrame,
         pos_col: str = "pos",
         pip_col: str = "pip",
@@ -610,22 +644,15 @@ class LocusZoomPlotter:
             show_credible_sets: Whether to color points by credible set.
             pip_threshold: Minimum PIP to display as scatter point.
         """
-
-        def _build_finemapping_hover_data(
-            subset_df: pd.DataFrame,
-        ) -> Optional[pd.DataFrame]:
-            """Build hover data for interactive backends."""
-            hover_cols = {}
-            # Position
-            if pos_col in subset_df.columns:
-                hover_cols["Position"] = subset_df[pos_col].values
-            # PIP
-            if pip_col in subset_df.columns:
-                hover_cols["PIP"] = subset_df[pip_col].values
-            # Credible set
-            if cs_col and cs_col in subset_df.columns:
-                hover_cols["Credible Set"] = subset_df[cs_col].values
-            return pd.DataFrame(hover_cols) if hover_cols else None
+        # Build hover data using HoverDataBuilder
+        extra_cols = {pip_col: "PIP"}
+        if cs_col and cs_col in df.columns:
+            extra_cols[cs_col] = "Credible Set"
+        hover_config = HoverConfig(
+            pos_col=pos_col if pos_col in df.columns else None,
+            extra_cols=extra_cols,
+        )
+        hover_builder = HoverDataBuilder(hover_config)
 
         # Sort by position for line plotting
         df = df.sort_values(pos_col)
@@ -660,7 +687,7 @@ class LocusZoomPlotter:
                     edgecolor="black",
                     linewidth=0.5,
                     zorder=3,
-                    hover_data=_build_finemapping_hover_data(cs_data),
+                    hover_data=hover_builder.build_dataframe(cs_data),
                 )
             # Plot variants not in any credible set
             non_cs_data = df[(df[cs_col].isna()) | (df[cs_col] == 0)]
@@ -677,7 +704,7 @@ class LocusZoomPlotter:
                         edgecolor="black",
                         linewidth=0.3,
                         zorder=2,
-                        hover_data=_build_finemapping_hover_data(non_cs_data),
+                        hover_data=hover_builder.build_dataframe(non_cs_data),
                     )
         else:
             # No credible sets - show all points above threshold
@@ -694,20 +721,28 @@ class LocusZoomPlotter:
                         edgecolor="black",
                         linewidth=0.5,
                         zorder=3,
-                        hover_data=_build_finemapping_hover_data(high_pip),
+                        hover_data=hover_builder.build_dataframe(high_pip),
                     )
 
     def plot_stacked(
         self,
         gwas_dfs: List[pd.DataFrame],
+        *,
         chrom: int,
         start: int,
         end: int,
+        pos_col: str = "ps",
+        p_col: str = "p_wald",
+        rs_col: str = "rs",
+        snp_labels: bool = True,
+        label_top_n: int = 3,
+        show_recombination: bool = True,
+        figsize: Tuple[float, float] = (12.0, 8.0),
+        ld_reference_file: Optional[str] = None,
+        ld_col: Optional[str] = None,
         lead_positions: Optional[List[int]] = None,
         panel_labels: Optional[List[str]] = None,
-        ld_reference_file: Optional[str] = None,
         ld_reference_files: Optional[List[str]] = None,
-        ld_col: Optional[str] = None,
         genes_df: Optional[pd.DataFrame] = None,
         exons_df: Optional[pd.DataFrame] = None,
         eqtl_df: Optional[pd.DataFrame] = None,
@@ -715,13 +750,6 @@ class LocusZoomPlotter:
         finemapping_df: Optional[pd.DataFrame] = None,
         finemapping_cs_col: Optional[str] = "cs",
         recomb_df: Optional[pd.DataFrame] = None,
-        show_recombination: bool = True,
-        snp_labels: bool = True,
-        label_top_n: int = 3,
-        pos_col: str = "ps",
-        p_col: str = "p_wald",
-        rs_col: str = "rs",
-        figsize: Tuple[float, Optional[float]] = (12, None),
     ) -> Any:
         """Create stacked regional association plots for multiple GWAS.
 
@@ -731,30 +759,28 @@ class LocusZoomPlotter:
         Args:
             gwas_dfs: List of GWAS results DataFrames to stack.
             chrom: Chromosome number.
-            start: Start position of the region.
-            end: End position of the region.
-            lead_positions: List of lead SNP positions (one per GWAS).
-                If None, auto-detects from lowest p-value.
-            panel_labels: Labels for each panel (e.g., phenotype names).
-            ld_reference_file: Single PLINK fileset for all panels.
+            start: Start position in base pairs.
+            end: End position in base pairs.
+            pos_col: Column name for genomic position.
+            p_col: Column name for p-value.
+            rs_col: Column name for SNP identifier.
+            snp_labels: Whether to show SNP labels on plot.
+            label_top_n: Number of top SNPs to label (default 3 for stacked).
+            show_recombination: Whether to show recombination rate overlay.
+            figsize: Figure size as (width, height) in inches.
+            ld_reference_file: Single PLINK fileset (broadcast to all panels).
+            ld_col: Column name for pre-computed LD (R^2) values.
+            lead_positions: List of lead SNP positions (one per panel).
+            panel_labels: List of panel labels (one per panel).
             ld_reference_files: List of PLINK filesets (one per panel).
-            ld_col: Column name for pre-computed LD (R²) values in each DataFrame.
-                Use this if LD was calculated externally.
             genes_df: Gene annotations for bottom track.
             exons_df: Exon annotations for gene track.
             eqtl_df: eQTL data to display as additional panel.
             eqtl_gene: Filter eQTL data to this target gene.
             finemapping_df: Fine-mapping/SuSiE results with pos and pip columns.
                 Displayed as PIP line with optional credible set coloring.
-            finemapping_cs_col: Column name for credible set assignment in finemapping_df.
+            finemapping_cs_col: Column name for credible set assignment.
             recomb_df: Pre-loaded recombination rate data.
-            show_recombination: Whether to show recombination overlay.
-            snp_labels: Whether to label top SNPs.
-            label_top_n: Number of top SNPs to label per panel.
-            pos_col: Column name for position.
-            p_col: Column name for p-value.
-            rs_col: Column name for SNP ID.
-            figsize: Figure size (width, height). If height is None, auto-calculates.
 
         Returns:
             Figure object (type depends on backend).
@@ -764,9 +790,27 @@ class LocusZoomPlotter:
             ...     [gwas_height, gwas_bmi, gwas_whr],
             ...     chrom=1, start=1000000, end=2000000,
             ...     panel_labels=["Height", "BMI", "WHR"],
-            ...     genes_df=genes_df,
             ... )
         """
+        # Validate parameters via Pydantic
+        StackedPlotConfig.from_kwargs(
+            chrom=chrom,
+            start=start,
+            end=end,
+            pos_col=pos_col,
+            p_col=p_col,
+            rs_col=rs_col,
+            snp_labels=snp_labels,
+            label_top_n=label_top_n,
+            show_recombination=show_recombination,
+            figsize=figsize,
+            ld_reference_file=ld_reference_file,
+            ld_col=ld_col,
+            lead_positions=lead_positions,
+            panel_labels=panel_labels,
+            ld_reference_files=ld_reference_files,
+        )
+
         n_gwas = len(gwas_dfs)
         if n_gwas == 0:
             raise ValueError("At least one GWAS DataFrame required")
@@ -802,8 +846,16 @@ class LocusZoomPlotter:
             for df in gwas_dfs:
                 region_df = df[(df[pos_col] >= start) & (df[pos_col] <= end)]
                 if not region_df.empty:
-                    lead_idx = region_df[p_col].idxmin()
-                    lead_positions.append(int(region_df.loc[lead_idx, pos_col]))
+                    # Filter out NaN p-values for lead SNP detection
+                    valid_p = region_df[p_col].dropna()
+                    if valid_p.empty:
+                        logger.warning(
+                            "All p-values in region are NaN, cannot determine lead SNP"
+                        )
+                        lead_positions.append(None)
+                    else:
+                        lead_idx = valid_p.idxmin()
+                        lead_positions.append(int(region_df.loc[lead_idx, pos_col]))
                 else:
                     lead_positions.append(None)
 
@@ -912,10 +964,10 @@ class LocusZoomPlotter:
                 zorder=1,
             )
 
-            # Add SNP labels (matplotlib only - interactive backends use hover tooltips)
+            # Add SNP labels (capability check - interactive backends use hover tooltips)
             if snp_labels and rs_col in df.columns and label_top_n > 0 and not df.empty:
-                if self.backend_name == "matplotlib":
-                    add_snp_labels(
+                if self._backend.supports_snp_labels:
+                    self._backend.add_snp_labels(
                         ax,
                         df,
                         pos_col=pos_col,
@@ -928,10 +980,8 @@ class LocusZoomPlotter:
 
             # Add recombination overlay (only on first panel, all backends)
             if i == 0 and recomb_df is not None and not recomb_df.empty:
-                if self.backend_name == "matplotlib":
-                    add_recombination_overlay(ax, recomb_df, start, end)
-                else:
-                    self._add_recombination_overlay_generic(ax, recomb_df, start, end)
+                if self._backend.supports_secondary_axis:
+                    self._add_recombination_overlay(ax, recomb_df, start, end)
 
             # Format axes
             self._backend.set_ylabel(ax, r"$-\log_{10}$ P")
@@ -940,50 +990,11 @@ class LocusZoomPlotter:
 
             # Add panel label
             if panel_labels and i < len(panel_labels):
-                if self.backend_name == "matplotlib":
-                    ax.annotate(
-                        panel_labels[i],
-                        xy=(0.02, 0.95),
-                        xycoords="axes fraction",
-                        fontsize=11,
-                        fontweight="bold",
-                        va="top",
-                        ha="left",
-                    )
-                elif self.backend_name == "plotly":
-                    fig, row = ax
-                    fig.add_annotation(
-                        text=f"<b>{panel_labels[i]}</b>",
-                        xref=f"x{row} domain" if row > 1 else "x domain",
-                        yref=f"y{row} domain" if row > 1 else "y domain",
-                        x=0.02,
-                        y=0.95,
-                        showarrow=False,
-                        font=dict(size=11),
-                        xanchor="left",
-                        yanchor="top",
-                    )
-                elif self.backend_name == "bokeh":
-                    from bokeh.models import Label
-
-                    # Get y-axis range for positioning
-                    y_max = ax.y_range.end if ax.y_range.end else 10
-                    x_min = ax.x_range.start if ax.x_range.start else start
-                    label = Label(
-                        x=x_min + (end - start) * 0.02,
-                        y=y_max * 0.95,
-                        text=panel_labels[i],
-                        text_font_size="11pt",
-                        text_font_style="bold",
-                    )
-                    ax.add_layout(label)
+                self._backend.add_panel_label(ax, panel_labels[i])
 
             # Add LD legend (only on first panel, all backends)
             if i == 0 and panel_ld_col is not None and panel_ld_col in df.columns:
-                if self.backend_name == "matplotlib":
-                    self._add_ld_legend(ax)
-                else:
-                    self._backend.add_ld_legend(ax, LD_BINS, LEAD_SNP_COLOR)
+                self._backend.add_ld_legend(ax, LD_BINS, LEAD_SNP_COLOR)
 
         # Track current panel index
         panel_idx = n_gwas
@@ -1050,63 +1061,58 @@ class LocusZoomPlotter:
                     eqtl_data["p_value"].clip(lower=1e-300)
                 )
 
-                def _build_eqtl_hover_data(
-                    subset_df: pd.DataFrame,
-                ) -> Optional[pd.DataFrame]:
-                    """Build hover data for eQTL interactive backends."""
-                    hover_cols = {}
-                    # Position
-                    if "pos" in subset_df.columns:
-                        hover_cols["Position"] = subset_df["pos"].values
-                    # P-value
-                    if "p_value" in subset_df.columns:
-                        hover_cols["P-value"] = subset_df["p_value"].values
-                    # Effect size
-                    if "effect_size" in subset_df.columns:
-                        hover_cols["Effect"] = subset_df["effect_size"].values
-                    # Gene
-                    if "gene" in subset_df.columns:
-                        hover_cols["Gene"] = subset_df["gene"].values
-                    return pd.DataFrame(hover_cols) if hover_cols else None
+                # Build hover data using HoverDataBuilder
+                eqtl_extra_cols = {}
+                if "effect_size" in eqtl_data.columns:
+                    eqtl_extra_cols["effect_size"] = "Effect"
+                if "gene" in eqtl_data.columns:
+                    eqtl_extra_cols["gene"] = "Gene"
+                eqtl_hover_config = HoverConfig(
+                    pos_col="pos" if "pos" in eqtl_data.columns else None,
+                    p_col="p_value" if "p_value" in eqtl_data.columns else None,
+                    extra_cols=eqtl_extra_cols,
+                )
+                eqtl_hover_builder = HoverDataBuilder(eqtl_hover_config)
 
                 # Check if effect_size column exists for directional coloring
                 has_effect = "effect_size" in eqtl_data.columns
 
                 if has_effect:
-                    # Plot triangles by effect direction (batch by sign for efficiency)
+                    # Vectorized plotting: split by sign, assign colors in bulk
                     pos_effects = eqtl_data[eqtl_data["effect_size"] >= 0]
                     neg_effects = eqtl_data[eqtl_data["effect_size"] < 0]
 
-                    # Plot positive effects (up triangles)
-                    for _, row in pos_effects.iterrows():
-                        row_df = pd.DataFrame([row])
+                    # Vectorized color assignment using apply
+                    if not pos_effects.empty:
+                        pos_colors = pos_effects["effect_size"].apply(get_eqtl_color)
                         self._backend.scatter(
                             ax,
-                            pd.Series([row["pos"]]),
-                            pd.Series([row["neglog10p"]]),
-                            colors=get_eqtl_color(row["effect_size"]),
+                            pos_effects["pos"],
+                            pos_effects["neglog10p"],
+                            colors=pos_colors.tolist(),
                             sizes=50,
                             marker="^",
                             edgecolor="black",
                             linewidth=0.5,
                             zorder=2,
-                            hover_data=_build_eqtl_hover_data(row_df),
+                            hover_data=eqtl_hover_builder.build_dataframe(pos_effects),
                         )
-                    # Plot negative effects (down triangles)
-                    for _, row in neg_effects.iterrows():
-                        row_df = pd.DataFrame([row])
+
+                    if not neg_effects.empty:
+                        neg_colors = neg_effects["effect_size"].apply(get_eqtl_color)
                         self._backend.scatter(
                             ax,
-                            pd.Series([row["pos"]]),
-                            pd.Series([row["neglog10p"]]),
-                            colors=get_eqtl_color(row["effect_size"]),
+                            neg_effects["pos"],
+                            neg_effects["neglog10p"],
+                            colors=neg_colors.tolist(),
                             sizes=50,
                             marker="v",
                             edgecolor="black",
                             linewidth=0.5,
                             zorder=2,
-                            hover_data=_build_eqtl_hover_data(row_df),
+                            hover_data=eqtl_hover_builder.build_dataframe(neg_effects),
                         )
+
                     # Add eQTL effect legend (all backends)
                     self._backend.add_eqtl_legend(
                         ax, EQTL_POSITIVE_BINS, EQTL_NEGATIVE_BINS
@@ -1125,7 +1131,7 @@ class LocusZoomPlotter:
                         linewidth=0.5,
                         zorder=2,
                         label=label,
-                        hover_data=_build_eqtl_hover_data(eqtl_data),
+                        hover_data=eqtl_hover_builder.build_dataframe(eqtl_data),
                     )
                     self._backend.add_simple_legend(ax, label, loc="upper right")
 
@@ -1141,15 +1147,12 @@ class LocusZoomPlotter:
             self._backend.hide_spines(ax, ["top", "right"])
             panel_idx += 1
 
-        # Plot gene track (all backends)
+        # Plot gene track (all backends use generic function)
         if genes_df is not None:
             gene_ax = axes[panel_idx]
-            if self.backend_name == "matplotlib":
-                plot_gene_track(gene_ax, genes_df, chrom, start, end, exons_df)
-            else:
-                plot_gene_track_generic(
-                    gene_ax, self._backend, genes_df, chrom, start, end, exons_df
-                )
+            plot_gene_track_generic(
+                gene_ax, self._backend, genes_df, chrom, start, end, exons_df
+            )
             self._backend.set_xlabel(gene_ax, f"Chromosome {chrom} (Mb)")
             self._backend.hide_spines(gene_ax, ["top", "right", "left"])
         else:
@@ -1230,18 +1233,37 @@ class LocusZoomPlotter:
         # Plot points by category
         if categories:
             for cat in categories:
-                cat_data = df[df[category_col] == cat]
+                # Handle NaN category: NaN == NaN is False in pandas
+                if pd.isna(cat):
+                    cat_data = df[df[category_col].isna()]
+                else:
+                    cat_data = df[df[category_col] == cat]
                 # Use upward triangles for positive effects, circles otherwise
                 if effect_col and effect_col in cat_data.columns:
-                    for _, row in cat_data.iterrows():
-                        marker = "^" if row[effect_col] >= 0 else "v"
+                    # Vectorized: split by effect sign, 2 scatter calls per category
+                    pos_data = cat_data[cat_data[effect_col] >= 0]
+                    neg_data = cat_data[cat_data[effect_col] < 0]
+
+                    if not pos_data.empty:
                         self._backend.scatter(
                             ax,
-                            pd.Series([row["neglog10p"]]),
-                            pd.Series([row["y_pos"]]),
+                            pos_data["neglog10p"],
+                            pos_data["y_pos"],
                             colors=palette[cat],
                             sizes=60,
-                            marker=marker,
+                            marker="^",
+                            edgecolor="black",
+                            linewidth=0.5,
+                            zorder=2,
+                        )
+                    if not neg_data.empty:
+                        self._backend.scatter(
+                            ax,
+                            neg_data["neglog10p"],
+                            neg_data["y_pos"],
+                            colors=palette[cat],
+                            sizes=60,
+                            marker="v",
                             edgecolor="black",
                             linewidth=0.5,
                             zorder=2,
@@ -1281,10 +1303,13 @@ class LocusZoomPlotter:
         self._backend.set_ylabel(ax, "Phenotype")
         self._backend.set_ylim(ax, -0.5, len(df) - 0.5)
 
-        # Set y-tick labels to phenotype names (matplotlib only)
-        if self.backend_name == "matplotlib":
-            ax.set_yticks(df["y_pos"])
-            ax.set_yticklabels(df[phenotype_col], fontsize=8)
+        # Set y-tick labels to phenotype names
+        self._backend.set_yticks(
+            ax,
+            positions=df["y_pos"].tolist(),
+            labels=df[phenotype_col].tolist(),
+            fontsize=8,
+        )
 
         self._backend.set_title(ax, f"PheWAS: {variant_id}")
         self._backend.hide_spines(ax, ["top", "right"])
@@ -1399,10 +1424,19 @@ class LocusZoomPlotter:
         self._backend.set_xlabel(ax, effect_label)
         self._backend.set_ylim(ax, -0.5, len(df) - 0.5)
 
-        # Set y-tick labels to study names (matplotlib only)
-        if self.backend_name == "matplotlib":
-            ax.set_yticks(df["y_pos"])
-            ax.set_yticklabels(df[study_col], fontsize=10)
+        # Ensure x-axis includes the null value with some padding
+        x_min = min(df[ci_lower_col].min(), null_value)
+        x_max = max(df[ci_upper_col].max(), null_value)
+        x_padding = (x_max - x_min) * 0.1
+        self._backend.set_xlim(ax, x_min - x_padding, x_max + x_padding)
+
+        # Set y-tick labels to study names
+        self._backend.set_yticks(
+            ax,
+            positions=df["y_pos"].tolist(),
+            labels=df[study_col].tolist(),
+            fontsize=10,
+        )
 
         self._backend.set_title(ax, f"Forest Plot: {variant_id}")
         self._backend.hide_spines(ax, ["top", "right"])