pylocuszoom 0.1.0__tar.gz → 0.3.0__tar.gz

pylocuszoom-0.3.0/CHANGELOG.md

@@ -0,0 +1,86 @@
+# 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).
+
+## [0.3.0] - 2026-01-26
+
+### Added
+- Bioconda recipe for conda installation
+- `adjustText` moved to default dependencies (was optional)
+- **Interactive plotly backend** - use `backend="plotly"` for hover tooltips and pan/zoom
+- **Interactive bokeh backend** - use `backend="bokeh"` for dashboard-ready plots
+
+### Changed
+- `plot()` and `plot_stacked()` now use backend protocol for all rendering (scatter, line, axes, layout)
+- **Gene track now works with all backends** (plotly, bokeh, matplotlib)
+- **Recombination overlay now works with all backends** - secondary y-axis with rate line and fill
+- **LD legend now works with all backends** - r² color scale (lead SNP highlighted in plot, not legend)
+- SNP labels remain matplotlib-only (interactive backends use hover tooltips instead)
+- Default `genomewide_threshold` changed from 5e-7 to 5e-8 (standard GWAS significance)
+- Gene track strand colors: forward strand now goldenrod (#DAA520), reverse strand light blue (#6BB3FF)
+- Gene track directional arrows: black for forward, dark grey for reverse
+- Added panel spacing (hspace=0.1) between stacked/fine-mapping panels for visual separation
+- Tightened gene track internal spacing for more compact layout
+
+### Fixed
+- Bokeh backend `x_range=None` error when creating figures with shared x-axis
+- Bokeh backend `legend_label=None` error in scatter plots
+- Bokeh backend LD legend not rendering (empty scatter plots don't create legend glyphs)
+- Bokeh backend deprecated `FuncTickFormatter` replaced with `CustomJSTickFormatter`
+- Bokeh backend deprecated `circle()` method replaced with `scatter(marker=...)`
+- Bokeh backend `FIXED_SIZING_MODE` validation warning in column layouts
+
+## [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.3.0...HEAD
+[0.3.0]: https://github.com/michael-denyer/pyLocusZoom/compare/v0.2.0...v0.3.0
+[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.3.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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pylocuszoom
-Version: 0.1.0
+Version: 0.3.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
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.10
+Requires-Dist: adjusttext>=0.8
 Requires-Dist: bokeh>=3.8.2
 Requires-Dist: kaleido>=0.2.0
 Requires-Dist: loguru>=0.7.0
@@ -28,14 +29,11 @@ Requires-Dist: pandas>=1.4.0
 Requires-Dist: plotly>=5.0.0
 Requires-Dist: pyliftover>=0.4
 Provides-Extra: all
-Requires-Dist: adjusttext>=0.8; extra == 'all'
 Requires-Dist: pyspark>=3.0.0; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
 Requires-Dist: pytest>=7.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
-Provides-Extra: labels
-Requires-Dist: adjusttext>=0.8; extra == 'labels'
 Provides-Extra: spark
 Requires-Dist: pyspark>=3.0.0; extra == 'spark'
 Description-Content-Type: text/markdown
@@ -71,16 +69,24 @@ 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
+pip install pylocuszoom
+```
+
+Or with uv:
+
 ```bash
 uv add pylocuszoom
 ```
 
-Or with pip:
+Or with conda (Bioconda):
 
 ```bash
-pip install pylocuszoom
+conda install -c bioconda pylocuszoom
 ```
 
 ## Quick Start
@@ -88,8 +94,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 +115,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 +140,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 +151,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 +169,30 @@ fig = plotter.plot(
 )
 ```
 
-## Interactive Backends
+## Backends
 
-Choose between static (matplotlib) and interactive (plotly, bokeh) outputs:
+pyLocusZoom supports multiple rendering backends:
 
 ```python
 # Static publication-quality plot (default)
-plotter = LocusZoomPlotter(species="dog", backend="matplotlib")
-fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
+fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000, backend="matplotlib")
 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)
+# Interactive Plotly (hover tooltips, pan/zoom)
+fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000, backend="plotly")
 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 Bokeh (dashboard-ready)
+fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000, backend="bokeh")
 ```
 
-Interactive plots show SNP details (RS ID, p-value, R²) on hover.
+| Backend | Output | Best For |
+|---------|--------|----------|
+| `matplotlib` | Static PNG/PDF/SVG | Publications, presentations |
+| `plotly` | Interactive HTML | Web reports, data exploration |
+| `bokeh` | Interactive HTML | Dashboards, web apps |
+
+> **Note:** All backends support gene track, recombination overlay, and LD legend. SNP labels (auto-positioned with adjustText) are matplotlib-only.
 
 ## Stacked Plots
 
@@ -324,14 +333,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.3.0}/README.md

@@ -29,16 +29,24 @@ 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
+pip install pylocuszoom
+```
+
+Or with uv:
+
 ```bash
 uv add pylocuszoom
 ```
 
-Or with pip:
+Or with conda (Bioconda):
 
 ```bash
-pip install pylocuszoom
+conda install -c bioconda pylocuszoom
 ```
 
 ## Quick Start
@@ -46,8 +54,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 +75,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 +100,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 +111,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 +129,30 @@ fig = plotter.plot(
 )
 ```
 
-## Interactive Backends
+## Backends
 
-Choose between static (matplotlib) and interactive (plotly, bokeh) outputs:
+pyLocusZoom supports multiple rendering backends:
 
 ```python
 # Static publication-quality plot (default)
-plotter = LocusZoomPlotter(species="dog", backend="matplotlib")
-fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
+fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000, backend="matplotlib")
 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)
+# Interactive Plotly (hover tooltips, pan/zoom)
+fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000, backend="plotly")
 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 Bokeh (dashboard-ready)
+fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000, backend="bokeh")
 ```
 
-Interactive plots show SNP details (RS ID, p-value, R²) on hover.
+| Backend | Output | Best For |
+|---------|--------|----------|
+| `matplotlib` | Static PNG/PDF/SVG | Publications, presentations |
+| `plotly` | Interactive HTML | Web reports, data exploration |
+| `bokeh` | Interactive HTML | Dashboards, web apps |
+
+> **Note:** All backends support gene track, recombination overlay, and LD legend. SNP labels (auto-positioned with adjustText) are matplotlib-only.
 
 ## Stacked Plots
 
@@ -282,14 +293,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.3.0/bioconda/meta.yaml

@@ -0,0 +1,54 @@
+{% set name = "pylocuszoom" %}
+{% set version = "0.3.0" %}
+
+package:
+  name: {{ name|lower }}
+  version: {{ version }}
+
+source:
+  url: https://pypi.io/packages/source/{{ name[0] }}/{{ name }}/{{ name }}-{{ version }}.tar.gz
+  sha256: REPLACE_WITH_SHA256_AFTER_PYPI_PUBLISH
+
+build:
+  noarch: python
+  number: 0
+  script: {{ PYTHON }} -m pip install . -vv --no-deps --no-build-isolation
+
+requirements:
+  host:
+    - python >=3.10
+    - pip
+    - hatchling
+  run:
+    - python >=3.10
+    - matplotlib-base >=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
+    - python-kaleido >=0.2.0
+    - adjusttext >=0.8
+
+test:
+  imports:
+    - pylocuszoom
+  commands:
+    - python -c "from pylocuszoom import LocusZoomPlotter"
+
+about:
+  home: https://github.com/michael-denyer/pylocuszoom
+  license: GPL-3.0-or-later
+  license_family: GPL3
+  license_file: LICENSE
+  summary: Regional association plots for GWAS results with LD coloring
+  description: |
+    pyLocusZoom creates publication-quality regional association plots
+    for GWAS results with LD coloring, gene tracks, and recombination
+    rate overlays. Supports canine, feline, and custom species.
+  dev_url: https://github.com/michael-denyer/pylocuszoom
+
+extra:
+  recipe-maintainers:
+    - michael-denyer