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

pylocuszoom/qq.py

@@ -0,0 +1,123 @@
+"""QQ plot data preparation and statistics."""
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+
+
+def calculate_lambda_gc(p_values: np.ndarray) -> float:
+    """Calculate genomic inflation factor (lambda GC).
+
+    Lambda is the ratio of the median observed chi-squared statistic
+    to the expected median under the null hypothesis.
+
+    Args:
+        p_values: Array of p-values.
+
+    Returns:
+        Genomic inflation factor (lambda). Returns NaN if no valid p-values.
+    """
+    # Remove NaN and zero/negative values
+    p_clean = p_values[~np.isnan(p_values) & (p_values > 0)]
+    if len(p_clean) == 0:
+        return np.nan
+
+    # Convert to chi-squared statistics (1 df)
+    chi2 = stats.chi2.ppf(1 - p_clean, df=1)
+
+    # Expected median for chi-squared with 1 df
+    expected_median = stats.chi2.ppf(0.5, df=1)
+
+    # Lambda = observed median / expected median
+    return np.median(chi2) / expected_median
+
+
+def calculate_confidence_band(
+    n_points: int, confidence: float = 0.95
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Calculate confidence band for QQ plot.
+
+    Uses order statistics to compute expected distribution of p-values
+    under the null hypothesis.
+
+    Args:
+        n_points: Number of p-values.
+        confidence: Confidence level (default 0.95 for 95% CI).
+
+    Returns:
+        Tuple of (expected, lower_bound, upper_bound) arrays in -log10 scale.
+    """
+    # Expected quantiles
+    expected = -np.log10((np.arange(1, n_points + 1)) / (n_points + 1))
+
+    # Confidence interval using beta distribution
+    alpha = 1 - confidence
+    ranks = np.arange(1, n_points + 1)
+    n_minus_rank = n_points - ranks + 1
+
+    lower_p = stats.beta.ppf(alpha / 2, ranks, n_minus_rank)
+    upper_p = stats.beta.ppf(1 - alpha / 2, ranks, n_minus_rank)
+
+    # Convert to -log10 scale (swap because -log10 reverses order)
+    lower_bound = -np.log10(upper_p)
+    upper_bound = -np.log10(lower_p)
+
+    return expected, lower_bound, upper_bound
+
+
+def prepare_qq_data(
+    df: pd.DataFrame,
+    p_col: str = "p",
+) -> pd.DataFrame:
+    """Prepare DataFrame for QQ plot rendering.
+
+    Args:
+        df: DataFrame with p-values.
+        p_col: Column name for p-value.
+
+    Returns:
+        DataFrame with columns for QQ plotting:
+        - _expected: Expected -log10(p) under null
+        - _observed: Observed -log10(p)
+        - _ci_lower: Lower confidence bound
+        - _ci_upper: Upper confidence bound
+
+        Attributes stored in DataFrame.attrs:
+        - lambda_gc: Genomic inflation factor
+        - n_variants: Number of valid p-values
+    """
+    if p_col not in df.columns:
+        raise ValueError(f"Column '{p_col}' not found in DataFrame")
+
+    # Get p-values and filter invalid
+    p_values = df[p_col].values
+    valid_mask = ~np.isnan(p_values) & (p_values > 0) & (p_values <= 1)
+    p_valid = p_values[valid_mask]
+
+    if len(p_valid) == 0:
+        raise ValueError("No valid p-values found (must be > 0 and <= 1)")
+
+    # Sort p-values (smallest first -> largest -log10 last)
+    p_sorted = np.sort(p_valid)
+
+    # Calculate observed -log10(p)
+    observed = -np.log10(p_sorted)
+
+    # Calculate expected and confidence bands
+    expected, ci_lower, ci_upper = calculate_confidence_band(len(p_sorted))
+
+    # Create result DataFrame
+    result = pd.DataFrame(
+        {
+            "_expected": expected,
+            "_observed": observed,
+            "_ci_lower": ci_lower,
+            "_ci_upper": ci_upper,
+        }
+    )
+
+    # Store statistics in attrs
+    result.attrs["lambda_gc"] = calculate_lambda_gc(p_valid)
+    result.attrs["n_variants"] = len(p_valid)
+
+    return result

pylocuszoom/recombination.py

@@ -432,8 +432,8 @@ def add_recombination_overlay(
         region_recomb["pos"],
         region_recomb["rate"],
         color=RECOMB_COLOR,
-        linewidth=1.5,
-        alpha=0.7,
+        linewidth=2.5,
+        alpha=0.8,
         zorder=0,  # Behind scatter points
     )
 
@@ -447,14 +447,14 @@ def add_recombination_overlay(
         zorder=0,
     )
 
-    # Format secondary axis
-    recomb_ax.set_ylabel("Recombination rate (cM/Mb)", color=RECOMB_COLOR, fontsize=9)
-    recomb_ax.tick_params(axis="y", labelcolor=RECOMB_COLOR, labelsize=8)
+    # Format secondary axis - use black for label text (more readable)
+    recomb_ax.set_ylabel("Recombination rate (cM/Mb)", color="black", fontsize=9)
+    recomb_ax.tick_params(axis="y", labelcolor="black", labelsize=8)
     recomb_ax.set_ylim(bottom=0)
 
-    # Don't let recomb rate overwhelm the plot
+    # Scale to fit data with headroom
     max_rate = region_recomb["rate"].max()
-    recomb_ax.set_ylim(0, max(max_rate * 1.2, 20))
+    recomb_ax.set_ylim(0, max(max_rate * 1.3, 10))
 
     # Remove top spine for cleaner look
     recomb_ax.spines["top"].set_visible(False)

pylocuszoom/stats_plotter.py

@@ -0,0 +1,319 @@
+"""Statistical visualization plotter for PheWAS and forest plots.
+
+Provides variant-centric visualizations:
+- PheWAS plots showing associations across phenotypes
+- Forest plots showing effect sizes with confidence intervals
+"""
+
+from typing import Any, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+from ._plotter_utils import DEFAULT_GENOMEWIDE_THRESHOLD, transform_pvalues
+from .backends import BackendType, get_backend
+from .colors import get_phewas_category_palette
+from .forest import validate_forest_df
+from .phewas import validate_phewas_df
+
+
+class StatsPlotter:
+    """Statistical visualization plotter for PheWAS and forest plots.
+
+    Creates variant-centric visualizations for phenome-wide associations
+    and meta-analysis forest plots.
+
+    Args:
+        backend: Plotting backend ('matplotlib', 'plotly', or 'bokeh').
+        genomewide_threshold: P-value threshold for significance line.
+
+    Example:
+        >>> plotter = StatsPlotter()
+        >>> fig = plotter.plot_phewas(phewas_df, variant_id="rs12345")
+        >>> fig.savefig("phewas.png", dpi=150)
+    """
+
+    def __init__(
+        self,
+        backend: BackendType = "matplotlib",
+        genomewide_threshold: float = DEFAULT_GENOMEWIDE_THRESHOLD,
+    ):
+        """Initialize the stats plotter."""
+        self._backend = get_backend(backend)
+        self.genomewide_threshold = genomewide_threshold
+
+    def plot_phewas(
+        self,
+        phewas_df: pd.DataFrame,
+        variant_id: str,
+        phenotype_col: str = "phenotype",
+        p_col: str = "p_value",
+        category_col: str = "category",
+        effect_col: Optional[str] = None,
+        significance_threshold: float = DEFAULT_GENOMEWIDE_THRESHOLD,
+        figsize: Tuple[float, float] = (10, 8),
+    ) -> Any:
+        """Create a PheWAS (Phenome-Wide Association Study) plot.
+
+        Shows associations of a single variant across multiple phenotypes,
+        with phenotypes grouped by category and colored accordingly.
+
+        Args:
+            phewas_df: DataFrame with phenotype associations.
+            variant_id: Variant identifier (e.g., "rs12345") for plot title.
+            phenotype_col: Column name for phenotype names.
+            p_col: Column name for p-values.
+            category_col: Column name for phenotype categories.
+            effect_col: Optional column name for effect direction (beta/OR).
+            significance_threshold: P-value threshold for significance line.
+            figsize: Figure size as (width, height).
+
+        Returns:
+            Figure object (type depends on backend).
+
+        Example:
+            >>> fig = plotter.plot_phewas(
+            ...     phewas_df,
+            ...     variant_id="rs12345",
+            ...     category_col="category",
+            ... )
+        """
+        validate_phewas_df(phewas_df, phenotype_col, p_col, category_col)
+
+        df = phewas_df.copy()
+        df = transform_pvalues(df, p_col)
+
+        # Sort by category then by p-value for consistent ordering
+        if category_col in df.columns:
+            df = df.sort_values([category_col, p_col])
+            categories = df[category_col].unique().tolist()
+            palette = get_phewas_category_palette(categories)
+        else:
+            df = df.sort_values(p_col)
+            categories = []
+            palette = {}
+
+        # Create figure
+        fig, axes = self._backend.create_figure(
+            n_panels=1,
+            height_ratios=[1.0],
+            figsize=figsize,
+        )
+        ax = axes[0]
+
+        # Assign y-positions (one per phenotype)
+        df["y_pos"] = range(len(df))
+
+        # Plot points by category
+        if categories:
+            for cat in categories:
+                # 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:
+                    # 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,
+                            pos_data["neglog10p"],
+                            pos_data["y_pos"],
+                            colors=palette[cat],
+                            sizes=60,
+                            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,
+                        )
+                else:
+                    self._backend.scatter(
+                        ax,
+                        cat_data["neglog10p"],
+                        cat_data["y_pos"],
+                        colors=palette[cat],
+                        sizes=60,
+                        marker="o",
+                        edgecolor="black",
+                        linewidth=0.5,
+                        zorder=2,
+                    )
+        else:
+            self._backend.scatter(
+                ax,
+                df["neglog10p"],
+                df["y_pos"],
+                colors="#4169E1",
+                sizes=60,
+                edgecolor="black",
+                linewidth=0.5,
+                zorder=2,
+            )
+
+        # Add significance threshold line
+        sig_line = -np.log10(significance_threshold)
+        self._backend.axvline(
+            ax, x=sig_line, color="red", linestyle="--", linewidth=1, alpha=0.7
+        )
+
+        # Set axis labels and limits
+        self._backend.set_xlabel(ax, r"$-\log_{10}$ P")
+        self._backend.set_ylabel(ax, "Phenotype")
+        self._backend.set_ylim(ax, -0.5, len(df) - 0.5)
+
+        # 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"])
+        self._backend.finalize_layout(fig)
+
+        return fig
+
+    def plot_forest(
+        self,
+        forest_df: pd.DataFrame,
+        variant_id: str,
+        study_col: str = "study",
+        effect_col: str = "effect",
+        ci_lower_col: str = "ci_lower",
+        ci_upper_col: str = "ci_upper",
+        weight_col: Optional[str] = None,
+        null_value: float = 0.0,
+        effect_label: str = "Effect Size",
+        figsize: Tuple[float, float] = (8, 6),
+    ) -> Any:
+        """Create a forest plot showing effect sizes with confidence intervals.
+
+        Args:
+            forest_df: DataFrame with effect sizes and confidence intervals.
+            variant_id: Variant identifier for plot title.
+            study_col: Column name for study/phenotype names.
+            effect_col: Column name for effect sizes.
+            ci_lower_col: Column name for lower confidence interval.
+            ci_upper_col: Column name for upper confidence interval.
+            weight_col: Optional column for study weights (affects marker size).
+            null_value: Reference value for null effect (0 for beta, 1 for OR).
+            effect_label: X-axis label.
+            figsize: Figure size as (width, height).
+
+        Returns:
+            Figure object (type depends on backend).
+
+        Example:
+            >>> fig = plotter.plot_forest(
+            ...     forest_df,
+            ...     variant_id="rs12345",
+            ...     effect_label="Odds Ratio",
+            ...     null_value=1.0,
+            ... )
+        """
+        validate_forest_df(forest_df, study_col, effect_col, ci_lower_col, ci_upper_col)
+
+        df = forest_df.copy()
+
+        # Create figure
+        fig, axes = self._backend.create_figure(
+            n_panels=1,
+            height_ratios=[1.0],
+            figsize=figsize,
+        )
+        ax = axes[0]
+
+        # Assign y-positions (reverse so first study is at top)
+        df["y_pos"] = range(len(df) - 1, -1, -1)
+
+        # Calculate marker sizes from weights
+        if weight_col and weight_col in df.columns:
+            # Scale weights to marker sizes (min 40, max 200)
+            weights = df[weight_col]
+            min_size, max_size = 40, 200
+            weight_range = weights.max() - weights.min()
+            if weight_range > 0:
+                sizes = min_size + (weights - weights.min()) / weight_range * (
+                    max_size - min_size
+                )
+            else:
+                sizes = (min_size + max_size) / 2
+        else:
+            sizes = 80
+
+        # Calculate error bar extents
+        xerr_lower = df[effect_col] - df[ci_lower_col]
+        xerr_upper = df[ci_upper_col] - df[effect_col]
+
+        # Plot error bars (confidence intervals)
+        self._backend.errorbar_h(
+            ax,
+            x=df[effect_col],
+            y=df["y_pos"],
+            xerr_lower=xerr_lower,
+            xerr_upper=xerr_upper,
+            color="black",
+            linewidth=1.5,
+            capsize=3,
+            zorder=2,
+        )
+
+        # Plot effect size markers
+        self._backend.scatter(
+            ax,
+            df[effect_col],
+            df["y_pos"],
+            colors="#4169E1",
+            sizes=sizes,
+            marker="s",  # square markers typical for forest plots
+            edgecolor="black",
+            linewidth=0.5,
+            zorder=3,
+        )
+
+        # Add null effect line
+        self._backend.axvline(
+            ax, x=null_value, color="grey", linestyle="--", linewidth=1, alpha=0.7
+        )
+
+        # Set axis labels and limits
+        self._backend.set_xlabel(ax, effect_label)
+        self._backend.set_ylim(ax, -0.5, len(df) - 0.5)
+
+        # 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"])
+        self._backend.finalize_layout(fig)
+
+        return fig

{pylocuszoom-1.0.0.dist-info → pylocuszoom-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pylocuszoom
-Version: 1.0.0
+Version: 1.1.0
 Summary: Publication-ready regional association plots with LD coloring, gene tracks, and recombination overlays
 Project-URL: Homepage, https://github.com/michael-denyer/pylocuszoom
 Project-URL: Documentation, https://github.com/michael-denyer/pylocuszoom#readme
@@ -21,6 +21,7 @@ Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.10
 Requires-Dist: adjusttext>=0.8
 Requires-Dist: bokeh>=3.8.2
+Requires-Dist: colorcet>=3.0.0
 Requires-Dist: kaleido>=0.2.0
 Requires-Dist: loguru>=0.7.0
 Requires-Dist: matplotlib>=3.5.0
@@ -66,22 +67,24 @@ Inspired by [LocusZoom](http://locuszoom.org/) and [locuszoomr](https://github.c
     - **Multi-species support**: Built-in reference data for *Canis lupus familiaris* (CanFam3.1/CanFam4) and *Felis catus* (FelCat9), or optionally provide your own for any species
     - **LD coloring**: SNPs colored by linkage disequilibrium (R²) with lead variant
     - **Gene tracks**: Annotated gene/exon positions below the association plot
-    - **Recombination rate**: Optional overlay across region (*Canis lupus familiaris* built-in, not shown in example image)
+    - **Recombination rate**: Overlay across region (*Canis lupus familiaris* built-in, or user-provided)
     - **SNP labels (matplotlib)**: Automatic labeling of top SNPs by p-value (RS IDs)
     - **Hover tooltips (Plotly and Bokeh)**: Detailed SNP data on hover
 
-![Example regional association plot with LD coloring and gene track](examples/regional_plot.png)
-*Regional association plot with LD coloring, gene/exon track, and top SNP labels (recombination overlay disabled in example).*
+![Example regional association plot with LD coloring, gene track, and recombination overlay](examples/regional_plot_with_recomb.png)
+*Regional association plot with LD coloring, gene/exon track, recombination rate overlay (blue line), and top SNP labels.*
 
 2. **Stacked plots**: Compare multiple GWAS/phenotypes vertically
-3. **eQTL plot**: Expression QTL data aligned with association plots and gene tracks
-4. **Fine-mapping plots**: Visualize SuSiE credible sets with posterior inclusion probabilities
-5. **PheWAS plots**: Phenome-wide association study visualization across multiple phenotypes
-6. **Forest plots**: Meta-analysis effect size visualization with confidence intervals
-7. **Multiple backends**: matplotlib (publication-ready), plotly (interactive), bokeh (dashboard integration)
-8. **Pandas and PySpark support**: Works with both Pandas and PySpark DataFrames for large-scale genomics data
-9. **Convenience data file loaders**: Load and validate common GWAS, eQTL and fine-mapping file formats
-10. **Automatic gene annotations**: Fetch gene/exon data from Ensembl REST API with caching (human, mouse, rat, canine, feline, and any Ensembl species)
+3. **Manhattan plots**: Genome-wide association visualization with chromosome coloring
+4. **QQ plots**: Quantile-quantile plots with confidence bands and genomic inflation factor
+5. **eQTL plot**: Expression QTL data aligned with association plots and gene tracks
+6. **Fine-mapping plots**: Visualize SuSiE credible sets with posterior inclusion probabilities
+7. **PheWAS plots**: Phenome-wide association study visualization across multiple phenotypes
+8. **Forest plots**: Meta-analysis effect size visualization with confidence intervals
+9. **Multiple backends**: matplotlib (publication-ready), plotly (interactive), bokeh (dashboard integration)
+10. **Pandas and PySpark support**: Works with both Pandas and PySpark DataFrames for large-scale genomics data
+11. **Convenience data file loaders**: Load and validate common GWAS, eQTL and fine-mapping file formats
+12. **Automatic gene annotations**: Fetch gene/exon data from Ensembl REST API with caching (human, mouse, rat, canine, feline, and any Ensembl species)
 
 ## Installation
 
@@ -107,15 +110,16 @@ conda install -c bioconda pylocuszoom
 from pylocuszoom import LocusZoomPlotter
 
 # Initialize plotter (loads reference data for canine)
-plotter = LocusZoomPlotter(species="canine")
+plotter = LocusZoomPlotter(species="canine", auto_genes=True)
 
 # Plot with parameters passed directly
 fig = plotter.plot(
-    gwas_df,                        # DataFrame with ps, p_wald, rs columns
+    gwas_df,                        # DataFrame with pos, p_value, rs columns
     chrom=1,
     start=1000000,
     end=2000000,
     lead_pos=1500000,               # Highlight lead SNP
+    show_recombination=True,        # Overlay recombination rate
 )
 fig.savefig("regional_plot.png", dpi=150)
 ```
@@ -355,6 +359,112 @@ fig = plotter.plot_forest(
 ![Example forest plot](examples/forest_plot.png)
 *Forest plot with effect sizes, confidence intervals, and weight-proportional markers.*
 
+## Manhattan Plots
+
+Create genome-wide Manhattan plots showing associations across all chromosomes:
+
+```python
+from pylocuszoom import LocusZoomPlotter
+
+plotter = LocusZoomPlotter(species="human")
+
+fig = plotter.plot_manhattan(
+    gwas_df,
+    chrom_col="chrom",
+    pos_col="pos",
+    p_col="p",
+    significance_threshold=5e-8,  # Genome-wide significance line
+    figsize=(12, 5),
+)
+fig.savefig("manhattan.png", dpi=150)
+```
+
+![Example Manhattan plot](examples/manhattan_plot.png)
+*Manhattan plot showing genome-wide associations with chromosome coloring and significance threshold.*
+
+Categorical Manhattan plots (PheWAS-style) are also supported:
+
+```python
+fig = plotter.plot_manhattan(
+    phewas_df,
+    category_col="phenotype_category",
+    p_col="pvalue",
+)
+```
+
+## QQ Plots
+
+Create quantile-quantile plots to assess p-value distribution:
+
+```python
+from pylocuszoom import LocusZoomPlotter
+
+plotter = LocusZoomPlotter()
+
+fig = plotter.plot_qq(
+    gwas_df,
+    p_col="p",
+    show_confidence_band=True,  # 95% confidence band
+    show_lambda=True,           # Genomic inflation factor in title
+    figsize=(6, 6),
+)
+fig.savefig("qq_plot.png", dpi=150)
+```
+
+![Example QQ plot](examples/qq_plot.png)
+*QQ plot with 95% confidence band and genomic inflation factor (λ).*
+
+## Stacked Manhattan Plots
+
+Compare multiple GWAS results in vertically stacked Manhattan plots:
+
+```python
+from pylocuszoom import LocusZoomPlotter
+
+plotter = LocusZoomPlotter()
+
+fig = plotter.plot_manhattan_stacked(
+    [gwas_study1, gwas_study2, gwas_study3],
+    chrom_col="chrom",
+    pos_col="pos",
+    p_col="p",
+    panel_labels=["Study 1", "Study 2", "Study 3"],
+    significance_threshold=5e-8,
+    figsize=(12, 8),
+    title="Multi-study GWAS Comparison",
+)
+fig.savefig("manhattan_stacked.png", dpi=150)
+```
+
+![Example stacked Manhattan plot](examples/manhattan_stacked.png)
+*Stacked Manhattan plots comparing three GWAS studies with shared chromosome axis.*
+
+## Manhattan and QQ Side-by-Side
+
+Create combined Manhattan and QQ plots in a single figure:
+
+```python
+from pylocuszoom import LocusZoomPlotter
+
+plotter = LocusZoomPlotter()
+
+fig = plotter.plot_manhattan_qq(
+    gwas_df,
+    chrom_col="chrom",
+    pos_col="pos",
+    p_col="p",
+    significance_threshold=5e-8,
+    show_confidence_band=True,
+    show_lambda=True,
+    figsize=(14, 5),
+    title="GWAS Results",
+)
+fig.savefig("manhattan_qq.png", dpi=150)
+```
+
+![Example Manhattan and QQ side-by-side](examples/manhattan_qq_sidebyside.png)
+*Combined Manhattan and QQ plot showing genome-wide associations and p-value distribution.*
+
 ## PySpark Support
 
 For large-scale genomics data, convert PySpark DataFrames with `to_pandas()` before plotting: