pylocuszoom 0.1.0__tar.gz → 0.2.0__tar.gz

pylocuszoom-0.2.0/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-01-26
+
+### Added
+- Fine-mapping/SuSiE visualization with credible set coloring
+- Example plots in `examples/` directory
+- Plot generation script for documentation
+
+### Fixed
+- Ruff linting and formatting errors
+- Bokeh security vulnerability (bumped to >= 3.8.2)
+- `plot()` KeyError when `rs_col` column missing with `ld_reference_file` provided
+- `plot_stacked()` now validates eQTL DataFrame columns before use
+- `plot_stacked()` now validates list lengths for `lead_positions`, `panel_labels`, and `ld_reference_files`
+- `calculate_ld()` docstring now documents `ValidationError` for missing PLINK files
+
+### Changed
+- Minimum Python version bumped to 3.10 (required by bokeh 3.8.2)
+- Renamed species terminology: "dog" → "canine", "cat" → "feline"
+- Clarified interactive backend status in README (coming soon)
+
+## [0.1.0] - 2026-01-26
+
+### Added
+- Initial release of pyLocusZoom
+- Regional association plots with LD coloring
+- Gene and exon track visualization
+- Recombination rate overlay (canine only)
+- Automatic SNP labeling with adjustText
+- Species support: Canine (CanFam3.1/CanFam4), Feline (FelCat9), custom
+- CanFam4 coordinate liftover via pyliftover
+- Stacked plots for multi-GWAS comparison
+- eQTL overlay panel support
+- PySpark DataFrame support
+- Backend infrastructure for matplotlib, plotly, bokeh (matplotlib only active)
+- Logging via loguru
+- Comprehensive test suite
+
+### Dependencies
+- matplotlib >= 3.5.0
+- pandas >= 1.4.0
+- numpy >= 1.21.0
+- loguru >= 0.7.0
+- pyliftover >= 0.4
+- plotly >= 5.0.0
+- bokeh >= 3.8.2
+- kaleido >= 0.2.0
+
+[Unreleased]: https://github.com/michael-denyer/pyLocusZoom/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/michael-denyer/pyLocusZoom/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/michael-denyer/pyLocusZoom/releases/tag/v0.1.0

pylocuszoom-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,114 @@
+# Contributing to pyLocusZoom
+
+Thank you for your interest in contributing to pyLocusZoom!
+
+## Development Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/michael-denyer/pyLocusZoom.git
+   cd pyLocusZoom
+   ```
+
+2. Install dependencies with uv:
+   ```bash
+   uv sync --all-extras
+   ```
+
+3. Run tests:
+   ```bash
+   uv run python -m pytest tests/ -v
+   ```
+
+4. Run linting:
+   ```bash
+   uv run ruff check src/
+   uv run ruff format --check src/ tests/
+   ```
+
+## Code Style
+
+- Follow [PEP 8](https://peps.python.org/pep-0008/) guidelines
+- Use [ruff](https://github.com/astral-sh/ruff) for linting and formatting
+- Maximum line length: 88 characters
+- Use Google-style docstrings
+
+### Docstring Example
+
+```python
+def function_name(param1: str, param2: int = 10) -> bool:
+    """Short one-line description.
+
+    Longer description if needed.
+
+    Args:
+        param1: Description of first parameter.
+        param2: Description of second parameter.
+
+    Returns:
+        Description of return value.
+
+    Raises:
+        ValueError: When param1 is empty.
+    """
+```
+
+## Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/your-feature`
+3. Make your changes
+4. Run tests and linting:
+   ```bash
+   uv run python -m pytest tests/ -v
+   uv run ruff check src/
+   uv run ruff format src/ tests/
+   ```
+5. Commit with a descriptive message
+6. Push and create a pull request
+
+## Testing
+
+- Write tests for new functionality
+- Use pytest fixtures from `tests/conftest.py`
+- Mock external dependencies (PLINK, network calls)
+- Aim for test coverage of new code
+
+### Running Tests
+
+```bash
+# All tests
+uv run python -m pytest tests/ -v
+
+# Specific test file
+uv run python -m pytest tests/test_plotter.py -v
+
+# With coverage
+uv run python -m pytest tests/ --cov=pylocuszoom --cov-report=html
+```
+
+## Architecture
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for project structure.
+
+### Key Modules
+
+| Module | Purpose |
+|--------|---------|
+| `plotter.py` | Main LocusZoomPlotter class |
+| `backends/` | Rendering backends (matplotlib, plotly, bokeh) |
+| `ld.py` | PLINK LD calculation |
+| `gene_track.py` | Gene/exon visualization |
+| `recombination.py` | Recombination map handling |
+| `eqtl.py` | eQTL data support |
+
+## Reporting Issues
+
+- Use GitHub Issues
+- Include Python version, OS, and package versions
+- Provide a minimal reproducible example
+- Include full error traceback
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the GPL-3.0-or-later license.

{pylocuszoom-0.1.0 → pylocuszoom-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pylocuszoom
-Version: 0.1.0
+Version: 0.2.0
 Summary: Regional association plots for GWAS results with LD coloring, gene tracks, and recombination rate overlays
 Project-URL: Homepage, https://github.com/michael-denyer/pylocuszoom
 Project-URL: Documentation, https://github.com/michael-denyer/pylocuszoom#readme
@@ -71,6 +71,8 @@ Inspired by [LocusZoom](http://locuszoom.org/) and [locuszoomr](https://github.c
 - **eQTL overlay**: Expression QTL data as separate panel
 - **PySpark support**: Handles large-scale genomics DataFrames
 
+![Example regional association plot](examples/regional_plot.png)
+
 ## Installation
 
 ```bash
@@ -88,8 +90,8 @@ pip install pylocuszoom
 ```python
 from pylocuszoom import LocusZoomPlotter
 
-# Initialize plotter (loads reference data for dog)
-plotter = LocusZoomPlotter(species="dog")
+# Initialize plotter (loads reference data for canine)
+plotter = LocusZoomPlotter(species="canine")
 
 # Create regional plot
 fig = plotter.plot(
@@ -109,7 +111,7 @@ fig.savefig("regional_plot.png", dpi=150)
 from pylocuszoom import LocusZoomPlotter
 
 plotter = LocusZoomPlotter(
-    species="dog",                      # or "cat", or None for custom
+    species="canine",                   # or "feline", or None for custom
     plink_path="/path/to/plink",        # Optional, auto-detects if on PATH
 )
 
@@ -134,10 +136,10 @@ fig = plotter.plot(
 
 ## Genome Builds
 
-The default genome build for dog is CanFam3.1. For CanFam4 data:
+The default genome build for canine is CanFam3.1. For CanFam4 data:
 
 ```python
-plotter = LocusZoomPlotter(species="dog", genome_build="canfam4")
+plotter = LocusZoomPlotter(species="canine", genome_build="canfam4")
 ```
 
 Recombination maps are automatically lifted over from CanFam3.1 to CanFam4 coordinates using the UCSC liftOver chain file.
@@ -145,8 +147,8 @@ Recombination maps are automatically lifted over from CanFam3.1 to CanFam4 coord
 ## Using with Other Species
 
 ```python
-# Cat (LD and gene tracks, user provides recombination data)
-plotter = LocusZoomPlotter(species="cat")
+# Feline (LD and gene tracks, user provides recombination data)
+plotter = LocusZoomPlotter(species="feline")
 
 # Custom species (provide all reference data)
 plotter = LocusZoomPlotter(
@@ -163,27 +165,20 @@ fig = plotter.plot(
 )
 ```
 
-## Interactive Backends
+## Interactive Backends (Coming Soon)
 
-Choose between static (matplotlib) and interactive (plotly, bokeh) outputs:
+> **Note:** Interactive backends (plotly, bokeh) are planned but not yet fully integrated. Currently all plots use matplotlib.
 
 ```python
-# Static publication-quality plot (default)
-plotter = LocusZoomPlotter(species="dog", backend="matplotlib")
+# Static publication-quality plot (default, currently only supported backend)
+plotter = LocusZoomPlotter(species="canine", backend="matplotlib")
 fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
 fig.savefig("plot.png", dpi=150)
-
-# Interactive with plotly (hover tooltips, zoom/pan)
-plotter = LocusZoomPlotter(species="dog", backend="plotly")
-fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
-fig.write_html("plot.html")
-
-# Interactive with bokeh (dashboard-friendly)
-plotter = LocusZoomPlotter(species="dog", backend="bokeh")
-fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
 ```
 
-Interactive plots show SNP details (RS ID, p-value, R²) on hover.
+Future releases will support:
+- **Plotly**: Interactive plots with hover tooltips, zoom/pan
+- **Bokeh**: Dashboard-friendly interactive plots
 
 ## Stacked Plots
 
@@ -324,14 +319,14 @@ chr	pos	rate	cM
 
 ## Reference Data
 
-Dog recombination maps are downloaded from [Campbell et al. 2016](https://github.com/cflerin/dog_recombination) on first use.
+Canine recombination maps are downloaded from [Campbell et al. 2016](https://github.com/cflerin/dog_recombination) on first use.
 
 To manually download:
 
 ```python
-from pylocuszoom import download_dog_recombination_maps
+from pylocuszoom import download_canine_recombination_maps
 
-download_dog_recombination_maps()
+download_canine_recombination_maps()
 ```
 
 ## Logging

{pylocuszoom-0.1.0 → pylocuszoom-0.2.0}/README.md

@@ -29,6 +29,8 @@ Inspired by [LocusZoom](http://locuszoom.org/) and [locuszoomr](https://github.c
 - **eQTL overlay**: Expression QTL data as separate panel
 - **PySpark support**: Handles large-scale genomics DataFrames
 
+![Example regional association plot](examples/regional_plot.png)
+
 ## Installation
 
 ```bash
@@ -46,8 +48,8 @@ pip install pylocuszoom
 ```python
 from pylocuszoom import LocusZoomPlotter
 
-# Initialize plotter (loads reference data for dog)
-plotter = LocusZoomPlotter(species="dog")
+# Initialize plotter (loads reference data for canine)
+plotter = LocusZoomPlotter(species="canine")
 
 # Create regional plot
 fig = plotter.plot(
@@ -67,7 +69,7 @@ fig.savefig("regional_plot.png", dpi=150)
 from pylocuszoom import LocusZoomPlotter
 
 plotter = LocusZoomPlotter(
-    species="dog",                      # or "cat", or None for custom
+    species="canine",                   # or "feline", or None for custom
     plink_path="/path/to/plink",        # Optional, auto-detects if on PATH
 )
 
@@ -92,10 +94,10 @@ fig = plotter.plot(
 
 ## Genome Builds
 
-The default genome build for dog is CanFam3.1. For CanFam4 data:
+The default genome build for canine is CanFam3.1. For CanFam4 data:
 
 ```python
-plotter = LocusZoomPlotter(species="dog", genome_build="canfam4")
+plotter = LocusZoomPlotter(species="canine", genome_build="canfam4")
 ```
 
 Recombination maps are automatically lifted over from CanFam3.1 to CanFam4 coordinates using the UCSC liftOver chain file.
@@ -103,8 +105,8 @@ Recombination maps are automatically lifted over from CanFam3.1 to CanFam4 coord
 ## Using with Other Species
 
 ```python
-# Cat (LD and gene tracks, user provides recombination data)
-plotter = LocusZoomPlotter(species="cat")
+# Feline (LD and gene tracks, user provides recombination data)
+plotter = LocusZoomPlotter(species="feline")
 
 # Custom species (provide all reference data)
 plotter = LocusZoomPlotter(
@@ -121,27 +123,20 @@ fig = plotter.plot(
 )
 ```
 
-## Interactive Backends
+## Interactive Backends (Coming Soon)
 
-Choose between static (matplotlib) and interactive (plotly, bokeh) outputs:
+> **Note:** Interactive backends (plotly, bokeh) are planned but not yet fully integrated. Currently all plots use matplotlib.
 
 ```python
-# Static publication-quality plot (default)
-plotter = LocusZoomPlotter(species="dog", backend="matplotlib")
+# Static publication-quality plot (default, currently only supported backend)
+plotter = LocusZoomPlotter(species="canine", backend="matplotlib")
 fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
 fig.savefig("plot.png", dpi=150)
-
-# Interactive with plotly (hover tooltips, zoom/pan)
-plotter = LocusZoomPlotter(species="dog", backend="plotly")
-fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
-fig.write_html("plot.html")
-
-# Interactive with bokeh (dashboard-friendly)
-plotter = LocusZoomPlotter(species="dog", backend="bokeh")
-fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
 ```
 
-Interactive plots show SNP details (RS ID, p-value, R²) on hover.
+Future releases will support:
+- **Plotly**: Interactive plots with hover tooltips, zoom/pan
+- **Bokeh**: Dashboard-friendly interactive plots
 
 ## Stacked Plots
 
@@ -282,14 +277,14 @@ chr	pos	rate	cM
 
 ## Reference Data
 
-Dog recombination maps are downloaded from [Campbell et al. 2016](https://github.com/cflerin/dog_recombination) on first use.
+Canine recombination maps are downloaded from [Campbell et al. 2016](https://github.com/cflerin/dog_recombination) on first use.
 
 To manually download:
 
 ```python
-from pylocuszoom import download_dog_recombination_maps
+from pylocuszoom import download_canine_recombination_maps
 
-download_dog_recombination_maps()
+download_canine_recombination_maps()
 ```
 
 ## Logging

pylocuszoom-0.2.0/examples/generate_readme_plots.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""Generate example plots for README documentation.
+
+Note: Backend integration (plotly/bokeh) is not yet fully implemented in the main
+plot methods. This script generates matplotlib plots only.
+"""
+
+import matplotlib
+
+matplotlib.use("Agg")  # Non-interactive backend
+
+import numpy as np
+import pandas as pd
+
+from pylocuszoom import LocusZoomPlotter
+
+# Generate synthetic GWAS data
+np.random.seed(42)
+n_snps = 500
+positions = np.sort(np.random.randint(1_000_000, 2_000_000, n_snps))
+
+# Ensure lead SNP exists at exact position
+peak_center = 1_500_000
+positions[250] = peak_center  # Place lead SNP in middle of array
+
+# Create a peak around position 1,500,000
+p_values = np.ones(n_snps) * 0.5
+for i, pos in enumerate(positions):
+    dist = abs(pos - peak_center)
+    if dist < 100_000:
+        p_values[i] = 10 ** -(8 * np.exp(-dist / 30_000))
+    else:
+        p_values[i] = np.random.uniform(0.01, 1)
+
+# Generate synthetic LD values (R² with lead SNP at peak_center)
+# LD decays with distance from lead SNP
+ld_values = []
+for pos in positions:
+    dist = abs(pos - peak_center)
+    if dist == 0:
+        r2 = 1.0
+    elif dist < 50_000:
+        # High LD close to lead
+        r2 = max(0, 0.9 * np.exp(-dist / 20_000) + np.random.uniform(-0.1, 0.1))
+    elif dist < 150_000:
+        # Moderate LD at medium distance
+        r2 = max(0, 0.5 * np.exp(-dist / 50_000) + np.random.uniform(-0.1, 0.1))
+    else:
+        # Low/no LD far from lead
+        r2 = max(0, np.random.uniform(0, 0.2))
+    ld_values.append(min(1.0, r2))
+
+gwas_df = pd.DataFrame(
+    {
+        "ps": positions,
+        "p_wald": p_values,
+        "rs": [f"rs{i}" for i in range(n_snps)],
+        "ld_r2": ld_values,  # Pre-computed LD column
+    }
+)
+
+# Create gene annotations
+genes_df = pd.DataFrame(
+    {
+        "chr": ["1", "1", "1", "1"],
+        "start": [1_100_000, 1_400_000, 1_550_000, 1_800_000],
+        "end": [1_200_000, 1_520_000, 1_650_000, 1_900_000],
+        "gene_name": ["GENE1", "GENE2", "GENE3", "GENE4"],
+        "strand": ["+", "-", "+", "-"],
+    }
+)
+
+# Create exon annotations
+exons_df = pd.DataFrame(
+    {
+        "chr": ["1", "1", "1", "1", "1", "1"],
+        "start": [1_100_000, 1_150_000, 1_400_000, 1_450_000, 1_550_000, 1_600_000],
+        "end": [1_120_000, 1_170_000, 1_420_000, 1_470_000, 1_580_000, 1_630_000],
+        "gene_name": ["GENE1", "GENE1", "GENE2", "GENE2", "GENE3", "GENE3"],
+    }
+)
+
+print("Generating example plots...")
+
+# 1. Basic matplotlib plot with LD coloring
+print("1. Basic regional plot with LD coloring...")
+plotter = LocusZoomPlotter(species="canine", log_level=None)
+fig = plotter.plot(
+    gwas_df,
+    chrom=1,
+    start=1_000_000,
+    end=2_000_000,
+    lead_pos=1_500_000,
+    ld_col="ld_r2",  # Use pre-computed LD values for coloring
+    genes_df=genes_df,
+    exons_df=exons_df,
+    show_recombination=False,
+    snp_labels=True,
+    label_top_n=1,
+)
+fig.savefig("examples/regional_plot.png", dpi=150, bbox_inches="tight")
+print("   Saved: examples/regional_plot.png")
+
+# 2. Stacked plot with LD coloring
+print("2. Stacked plot with LD coloring...")
+gwas_df2 = gwas_df.copy()
+gwas_df2["p_wald"] = np.ones(n_snps) * 0.5
+peak_center2 = 1_700_000
+# Ensure lead SNP exists at exact position for second panel
+positions[350] = peak_center2
+gwas_df2.loc[350, "ps"] = peak_center2
+for i, pos in enumerate(positions):
+    dist = abs(pos - peak_center2)
+    if dist < 80_000:
+        gwas_df2.loc[i, "p_wald"] = 10 ** -(6 * np.exp(-dist / 25_000))
+    else:
+        gwas_df2.loc[i, "p_wald"] = np.random.uniform(0.05, 1)
+
+# Generate LD for second GWAS (different lead SNP)
+ld_values2 = []
+for pos in positions:
+    dist = abs(pos - peak_center2)
+    if dist == 0:
+        r2 = 1.0
+    elif dist < 50_000:
+        r2 = max(0, 0.9 * np.exp(-dist / 20_000) + np.random.uniform(-0.1, 0.1))
+    elif dist < 150_000:
+        r2 = max(0, 0.5 * np.exp(-dist / 50_000) + np.random.uniform(-0.1, 0.1))
+    else:
+        r2 = max(0, np.random.uniform(0, 0.2))
+    ld_values2.append(min(1.0, r2))
+gwas_df2["ld_r2"] = ld_values2
+
+fig = plotter.plot_stacked(
+    [gwas_df, gwas_df2],
+    chrom=1,
+    start=1_000_000,
+    end=2_000_000,
+    lead_positions=[1_500_000, 1_700_000],  # Lead SNPs for each panel
+    ld_col="ld_r2",  # Use pre-computed LD values for coloring
+    panel_labels=["Phenotype A", "Phenotype B"],
+    genes_df=genes_df,
+    show_recombination=False,
+    label_top_n=1,
+)
+fig.savefig("examples/stacked_plot.png", dpi=150, bbox_inches="tight")
+print("   Saved: examples/stacked_plot.png")
+
+# 3. eQTL overlay with effect sizes
+print("3. eQTL overlay plot...")
+eqtl_df = pd.DataFrame(
+    {
+        "pos": [1_420_000, 1_450_000, 1_480_000, 1_500_000, 1_520_000, 1_550_000, 1_600_000, 1_650_000],
+        "p_value": [1e-4, 1e-5, 1e-6, 1e-7, 1e-6, 1e-4, 1e-3, 0.01],
+        "gene": ["GENE2", "GENE2", "GENE2", "GENE2", "GENE2", "GENE2", "GENE3", "GENE3"],
+        "effect_size": [0.35, 0.28, 0.22, 0.15, -0.18, -0.25, -0.32, 0.12],
+    }
+)
+
+fig = plotter.plot_stacked(
+    [gwas_df],
+    chrom=1,
+    start=1_000_000,
+    end=2_000_000,
+    lead_positions=[1_500_000],  # Lead SNP for LD coloring
+    ld_col="ld_r2",  # Use pre-computed LD values for coloring
+    eqtl_df=eqtl_df,
+    eqtl_gene="GENE2",
+    genes_df=genes_df,
+    show_recombination=False,
+    label_top_n=1,
+)
+fig.savefig("examples/eqtl_overlay.png", dpi=150, bbox_inches="tight")
+print("   Saved: examples/eqtl_overlay.png")
+
+# 4. Fine-mapping/SuSiE plot
+print("4. Fine-mapping/SuSiE plot with credible sets...")
+
+# Generate synthetic fine-mapping data
+# Create PIP values that peak around the lead SNP
+finemapping_positions = positions.copy()
+pip_values = []
+cs_assignments = []
+
+for i, pos in enumerate(finemapping_positions):
+    dist = abs(pos - peak_center)
+    if dist < 20_000:
+        # High PIP near causal variant
+        pip = max(0, 0.95 * np.exp(-dist / 8_000) + np.random.uniform(-0.05, 0.05))
+        cs = 1 if pip > 0.1 else 0
+    elif dist < 80_000:
+        # Moderate PIP in LD region
+        pip = max(0, 0.3 * np.exp(-dist / 30_000) + np.random.uniform(-0.02, 0.02))
+        cs = 1 if pip > 0.05 else 0
+    else:
+        # Low PIP elsewhere
+        pip = max(0, np.random.uniform(0, 0.02))
+        cs = 0
+    pip_values.append(min(1.0, pip))
+    cs_assignments.append(cs)
+
+# Add a second credible set near a different peak
+for i, pos in enumerate(finemapping_positions):
+    dist = abs(pos - 1_300_000)  # Second signal
+    if dist < 30_000:
+        pip_values[i] = max(pip_values[i], 0.7 * np.exp(-dist / 12_000))
+        if pip_values[i] > 0.05:
+            cs_assignments[i] = 2  # Second credible set
+
+finemapping_df = pd.DataFrame(
+    {
+        "pos": finemapping_positions,
+        "pip": pip_values,
+        "cs": cs_assignments,
+        "rs": [f"rs{i}" for i in range(n_snps)],
+    }
+)
+
+fig = plotter.plot_stacked(
+    [gwas_df],
+    chrom=1,
+    start=1_000_000,
+    end=2_000_000,
+    lead_positions=[1_500_000],
+    ld_col="ld_r2",
+    finemapping_df=finemapping_df,
+    finemapping_cs_col="cs",
+    genes_df=genes_df,
+    show_recombination=False,
+    label_top_n=1,
+)
+fig.savefig("examples/finemapping_plot.png", dpi=150, bbox_inches="tight")
+print("   Saved: examples/finemapping_plot.png")
+
+print("\nAll plots generated successfully!")