pylocuszoom 0.1.0__py3-none-any.whl

pylocuszoom/__init__.py

@@ -0,0 +1,120 @@
+"""pyLocusZoom - Regional association plots for GWAS results.
+
+This package provides LocusZoom-style regional association plots with:
+- LD coloring based on R² with lead variant
+- Gene and exon tracks
+- Recombination rate overlays (dog built-in, or user-provided)
+- Automatic SNP labeling
+- Multiple backends: matplotlib (static), plotly (interactive), bokeh (dashboards)
+- eQTL overlay support
+- PySpark DataFrame support for large-scale data
+
+Example:
+    >>> from pylocuszoom import LocusZoomPlotter
+    >>> plotter = LocusZoomPlotter(species="dog")
+    >>> fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
+    >>> fig.savefig("regional_plot.png", dpi=150)
+
+Interactive example:
+    >>> plotter = LocusZoomPlotter(species="dog", backend="plotly")
+    >>> fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
+    >>> fig.write_html("regional_plot.html")
+
+Stacked plots:
+    >>> fig = plotter.plot_stacked(
+    ...     [gwas_height, gwas_bmi],
+    ...     chrom=1, start=1000000, end=2000000,
+    ...     panel_labels=["Height", "BMI"],
+    ... )
+
+Species Support:
+    - Dog (Canis lupus familiaris): Full features including built-in recombination maps
+    - Cat (Felis catus): LD coloring and gene tracks (user provides recombination data)
+    - Custom: User provides all reference data
+"""
+
+__version__ = "0.1.0"
+
+# Main plotter class
+from .plotter import LocusZoomPlotter
+
+# 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
+
+# Gene track
+from .gene_track import get_nearest_gene, plot_gene_track
+
+# Labels
+from .labels import add_snp_labels
+
+# LD calculation
+from .ld import calculate_ld
+
+# Logging configuration
+from .logging import disable_logging, enable_logging
+
+# Reference data management
+from .recombination import (
+    add_recombination_overlay,
+    download_dog_recombination_maps,
+    get_recombination_rate_for_region,
+    load_recombination_map,
+)
+
+# eQTL support
+from .eqtl import (
+    EQTLValidationError,
+    calculate_colocalization_overlap,
+    filter_eqtl_by_gene,
+    filter_eqtl_by_region,
+    get_eqtl_genes,
+    prepare_eqtl_for_plotting,
+    validate_eqtl_df,
+)
+
+# Validation utilities
+from .utils import ValidationError, to_pandas
+
+__all__ = [
+    # Core
+    "__version__",
+    "LocusZoomPlotter",
+    # Backends
+    "BackendType",
+    "get_backend",
+    # Reference data
+    "download_dog_recombination_maps",
+    # Colors
+    "get_ld_color",
+    "get_ld_bin",
+    "get_ld_color_palette",
+    "LEAD_SNP_COLOR",
+    # Gene track
+    "get_nearest_gene",
+    "plot_gene_track",
+    # LD
+    "calculate_ld",
+    # Labels
+    "add_snp_labels",
+    # Recombination
+    "add_recombination_overlay",
+    "get_recombination_rate_for_region",
+    "load_recombination_map",
+    # eQTL
+    "validate_eqtl_df",
+    "filter_eqtl_by_gene",
+    "filter_eqtl_by_region",
+    "prepare_eqtl_for_plotting",
+    "get_eqtl_genes",
+    "calculate_colocalization_overlap",
+    "EQTLValidationError",
+    # Logging
+    "enable_logging",
+    "disable_logging",
+    # Validation & Utils
+    "ValidationError",
+    "to_pandas",
+]

pylocuszoom/backends/__init__.py

@@ -0,0 +1,52 @@
+"""Pluggable plotting backends for pyLocusZoom.
+
+Supports matplotlib (default), plotly, and bokeh backends.
+"""
+
+from typing import TYPE_CHECKING, Literal
+
+from .base import PlotBackend
+from .matplotlib_backend import MatplotlibBackend
+
+if TYPE_CHECKING:
+    from .bokeh_backend import BokehBackend
+    from .plotly_backend import PlotlyBackend
+
+BackendType = Literal["matplotlib", "plotly", "bokeh"]
+
+_BACKENDS: dict[str, type[PlotBackend]] = {
+    "matplotlib": MatplotlibBackend,
+}
+
+
+def get_backend(name: BackendType) -> PlotBackend:
+    """Get a backend instance by name.
+
+    Args:
+        name: Backend name ('matplotlib', 'plotly', or 'bokeh').
+
+    Returns:
+        Instantiated backend.
+
+    Raises:
+        ValueError: If backend name is invalid.
+        ImportError: If backend dependencies are not installed.
+    """
+    if name == "plotly":
+        from .plotly_backend import PlotlyBackend
+
+        _BACKENDS["plotly"] = PlotlyBackend
+    elif name == "bokeh":
+        from .bokeh_backend import BokehBackend
+
+        _BACKENDS["bokeh"] = BokehBackend
+
+    if name not in _BACKENDS:
+        raise ValueError(
+            f"Unknown backend: {name}. Available: matplotlib, plotly, bokeh"
+        )
+
+    return _BACKENDS[name]()
+
+
+__all__ = ["PlotBackend", "BackendType", "get_backend", "MatplotlibBackend"]

pylocuszoom/backends/base.py

@@ -0,0 +1,341 @@
+"""Base protocol for plotting backends.
+
+Defines the interface that matplotlib, plotly, and bokeh backends must implement.
+"""
+
+from typing import Any, Dict, List, Optional, Protocol, Tuple, Union
+
+import pandas as pd
+
+
+class PlotBackend(Protocol):
+    """Protocol defining the backend interface for LocusZoom plots.
+
+    All backends (matplotlib, plotly, bokeh) must implement these methods
+    to enable consistent plotting across different rendering engines.
+    """
+
+    def create_figure(
+        self,
+        n_panels: int,
+        height_ratios: List[float],
+        figsize: Tuple[float, float],
+        sharex: bool = True,
+    ) -> Tuple[Any, List[Any]]:
+        """Create a figure with multiple panels (subplots).
+
+        Args:
+            n_panels: Number of vertical panels.
+            height_ratios: Relative heights for each panel.
+            figsize: Figure size as (width, height).
+            sharex: Whether panels share the x-axis.
+
+        Returns:
+            Tuple of (figure, list of axes/panels).
+        """
+        ...
+
+    def scatter(
+        self,
+        ax: Any,
+        x: pd.Series,
+        y: pd.Series,
+        colors: Union[str, List[str], pd.Series],
+        sizes: Union[float, List[float], pd.Series] = 60,
+        marker: str = "o",
+        edgecolor: str = "black",
+        linewidth: float = 0.5,
+        zorder: int = 2,
+        hover_data: Optional[pd.DataFrame] = None,
+        label: Optional[str] = None,
+    ) -> Any:
+        """Create a scatter plot on the given axes.
+
+        Args:
+            ax: Axes or panel to plot on.
+            x: X-axis values (positions).
+            y: Y-axis values (-log10 p-values).
+            colors: Point colors (single color or per-point).
+            sizes: Point sizes.
+            marker: Marker style.
+            edgecolor: Marker edge color.
+            linewidth: Marker edge width.
+            zorder: Drawing order.
+            hover_data: DataFrame with columns for hover tooltips.
+            label: Legend label.
+
+        Returns:
+            The scatter plot object.
+        """
+        ...
+
+    def line(
+        self,
+        ax: Any,
+        x: pd.Series,
+        y: pd.Series,
+        color: str = "blue",
+        linewidth: float = 1.5,
+        alpha: float = 1.0,
+        linestyle: str = "-",
+        zorder: int = 1,
+        label: Optional[str] = None,
+    ) -> Any:
+        """Create a line plot on the given axes.
+
+        Args:
+            ax: Axes or panel to plot on.
+            x: X-axis values.
+            y: Y-axis values.
+            color: Line color.
+            linewidth: Line width.
+            alpha: Transparency.
+            linestyle: Line style ('-', '--', ':', '-.').
+            zorder: Drawing order.
+            label: Legend label.
+
+        Returns:
+            The line plot object.
+        """
+        ...
+
+    def fill_between(
+        self,
+        ax: Any,
+        x: pd.Series,
+        y1: Union[float, pd.Series],
+        y2: Union[float, pd.Series],
+        color: str = "blue",
+        alpha: float = 0.3,
+        zorder: int = 0,
+    ) -> Any:
+        """Fill area between two y-values.
+
+        Args:
+            ax: Axes or panel to plot on.
+            x: X-axis values.
+            y1: Lower y boundary.
+            y2: Upper y boundary.
+            color: Fill color.
+            alpha: Transparency.
+            zorder: Drawing order.
+
+        Returns:
+            The fill object.
+        """
+        ...
+
+    def axhline(
+        self,
+        ax: Any,
+        y: float,
+        color: str = "grey",
+        linestyle: str = "--",
+        linewidth: float = 1.0,
+        zorder: int = 1,
+    ) -> Any:
+        """Add a horizontal line across the axes.
+
+        Args:
+            ax: Axes or panel.
+            y: Y-value for the line.
+            color: Line color.
+            linestyle: Line style.
+            linewidth: Line width.
+            zorder: Drawing order.
+
+        Returns:
+            The line object.
+        """
+        ...
+
+    def add_text(
+        self,
+        ax: Any,
+        x: float,
+        y: float,
+        text: str,
+        fontsize: int = 10,
+        ha: str = "center",
+        va: str = "bottom",
+        rotation: float = 0,
+        color: str = "black",
+    ) -> Any:
+        """Add text annotation to axes.
+
+        Args:
+            ax: Axes or panel.
+            x: X position.
+            y: Y position.
+            text: Text content.
+            fontsize: Font size.
+            ha: Horizontal alignment.
+            va: Vertical alignment.
+            rotation: Text rotation in degrees.
+            color: Text color.
+
+        Returns:
+            The text object.
+        """
+        ...
+
+    def add_rectangle(
+        self,
+        ax: Any,
+        xy: Tuple[float, float],
+        width: float,
+        height: float,
+        facecolor: str = "blue",
+        edgecolor: str = "black",
+        linewidth: float = 0.5,
+        zorder: int = 2,
+    ) -> Any:
+        """Add a rectangle patch to axes.
+
+        Args:
+            ax: Axes or panel.
+            xy: Bottom-left corner coordinates.
+            width: Rectangle width.
+            height: Rectangle height.
+            facecolor: Fill color.
+            edgecolor: Edge color.
+            linewidth: Edge width.
+            zorder: Drawing order.
+
+        Returns:
+            The rectangle object.
+        """
+        ...
+
+    def set_xlim(self, ax: Any, left: float, right: float) -> None:
+        """Set x-axis limits.
+
+        Args:
+            ax: Axes or panel.
+            left: Minimum x value.
+            right: Maximum x value.
+        """
+        ...
+
+    def set_ylim(self, ax: Any, bottom: float, top: float) -> None:
+        """Set y-axis limits.
+
+        Args:
+            ax: Axes or panel.
+            bottom: Minimum y value.
+            top: Maximum y value.
+        """
+        ...
+
+    def set_xlabel(self, ax: Any, label: str, fontsize: int = 12) -> None:
+        """Set x-axis label.
+
+        Args:
+            ax: Axes or panel.
+            label: Label text.
+            fontsize: Font size.
+        """
+        ...
+
+    def set_ylabel(self, ax: Any, label: str, fontsize: int = 12) -> None:
+        """Set y-axis label.
+
+        Args:
+            ax: Axes or panel.
+            label: Label text.
+            fontsize: Font size.
+        """
+        ...
+
+    def set_title(self, ax: Any, title: str, fontsize: int = 14) -> None:
+        """Set panel title.
+
+        Args:
+            ax: Axes or panel.
+            title: Title text.
+            fontsize: Font size.
+        """
+        ...
+
+    def create_twin_axis(self, ax: Any) -> Any:
+        """Create a secondary y-axis sharing the same x-axis.
+
+        Args:
+            ax: Primary axes.
+
+        Returns:
+            Secondary axes for overlay (e.g., recombination rate).
+        """
+        ...
+
+    def add_legend(
+        self,
+        ax: Any,
+        handles: List[Any],
+        labels: List[str],
+        loc: str = "upper left",
+        title: Optional[str] = None,
+    ) -> Any:
+        """Add a legend to the axes.
+
+        Args:
+            ax: Axes or panel.
+            handles: Legend handle objects.
+            labels: Legend labels.
+            loc: Legend location.
+            title: Legend title.
+
+        Returns:
+            The legend object.
+        """
+        ...
+
+    def hide_spines(self, ax: Any, spines: List[str]) -> None:
+        """Hide specified axis spines.
+
+        Args:
+            ax: Axes or panel.
+            spines: List of spine names ('top', 'right', 'bottom', 'left').
+        """
+        ...
+
+    def format_xaxis_mb(self, ax: Any) -> None:
+        """Format x-axis to show megabase values.
+
+        Args:
+            ax: Axes or panel.
+        """
+        ...
+
+    def save(
+        self,
+        fig: Any,
+        path: str,
+        dpi: int = 150,
+        bbox_inches: str = "tight",
+    ) -> None:
+        """Save figure to file.
+
+        Args:
+            fig: Figure object.
+            path: Output file path (.png, .pdf, .html).
+            dpi: Resolution for raster formats.
+            bbox_inches: Bounding box adjustment.
+        """
+        ...
+
+    def show(self, fig: Any) -> None:
+        """Display the figure.
+
+        Args:
+            fig: Figure object.
+        """
+        ...
+
+    def close(self, fig: Any) -> None:
+        """Close the figure and free resources.
+
+        Args:
+            fig: Figure object.
+        """
+        ...