pylocuszoom 0.6.0__tar.gz → 0.8.0__tar.gz

{pylocuszoom-0.6.0 → pylocuszoom-0.8.0}/.github/workflows/ci.yml

@@ -44,14 +44,7 @@ jobs:
         run: uv sync --extra dev --extra all
 
       - name: Run tests
-        run: uv run pytest --cov=pylocuszoom --cov-report=xml
-
-      - name: Upload coverage
-        uses: codecov/codecov-action@v4
-        if: matrix.python-version == '3.11'
-        with:
-          files: ./coverage.xml
-          fail_ci_if_error: false
+        run: uv run pytest --cov=pylocuszoom --cov-report=term-missing
 
   build:
     runs-on: ubuntu-latest

{pylocuszoom-0.6.0 → pylocuszoom-0.8.0}/.github/workflows/publish.yml

@@ -60,6 +60,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: main
 
       - name: Update bioconda/meta.yaml
         env:

{pylocuszoom-0.6.0 → pylocuszoom-0.8.0}/.gitignore

@@ -26,3 +26,5 @@ htmlcov/
 
 # Project instructions (private)
 CLAUDE.md
+docs/plans/
+.planning/

pylocuszoom-0.8.0/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.1
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: pytest-cov
+        name: pytest with coverage
+        entry: uv run python -m pytest -q
+        language: system
+        types: [python]
+        pass_filenames: false
+        always_run: true

{pylocuszoom-0.6.0 → pylocuszoom-0.8.0}/CHANGELOG.md

@@ -5,6 +5,47 @@ 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.8.0] - 2026-01-28
+
+### Added
+- `set_yticks()` backend method for consistent y-axis labels across all backends
+- Shared `convert_latex_to_unicode()` utility for interactive backends
+- Automatic gene annotation fetching from Ensembl REST API (`auto_genes=True`)
+- `get_genes_for_region()` function to fetch genes from Ensembl with disk caching
+- `fetch_genes_from_ensembl()` and `fetch_exons_from_ensembl()` low-level API functions
+- `clear_ensembl_cache()` utility to clear cached Ensembl data
+- Support for human, mouse, rat, and any Ensembl species
+- Retry logic with exponential backoff for Ensembl API resilience
+- 5Mb region size validation (Ensembl API limit)
+- `DataFrameValidator` builder class for consistent validation across modules
+- `filter_by_region()` shared utility for chromosome/position filtering
+- `HoverDataBuilder` for constructing hover tooltips across backends
+- Backend capability system with `supports_*` properties for feature detection
+- Backend registration system with `get_backend()` and automatic fallback
+- Pre-commit hook for pytest with coverage enforcement (70% minimum)
+
+### Changed
+- Forest plot example now uses odds ratios with `null_value=1.0` (more representative)
+- PheWAS and forest plot y-axis labels now work correctly in Plotly and Bokeh backends
+- Gene track styling: arrows now 75% height and 10% wider for better proportions
+- Gene track labels increased from 5.5pt to 7pt for improved readability
+- Migrated eQTL, finemapping, phewas, and forest validation to `DataFrameValidator`
+- Plotter now uses capability-based dispatch instead of backend name checks
+- Removed empty `__init__` methods from backend classes
+- Removed unused matplotlib imports from plotter (now backend-agnostic)
+
+### Fixed
+- `load_gwas()` now forwards `**kwargs` to format-specific loaders
+- Forest plot validator now checks that effect and CI columns are numeric
+- PheWAS validator now checks that p-values are numeric and within (0, 1] range
+
+### Security
+- Tar extraction now includes path traversal protection for recombination map downloads
+
+## [0.7.0] - 2026-01-27
+
 ## [0.6.0] - 2026-01-27
 
 ### Added
@@ -140,7 +181,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - bokeh >= 3.8.2
 - kaleido >= 0.2.0
 
-[Unreleased]: https://github.com/michael-denyer/pyLocusZoom/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/michael-denyer/pyLocusZoom/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/michael-denyer/pyLocusZoom/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/michael-denyer/pyLocusZoom/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/michael-denyer/pyLocusZoom/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/michael-denyer/pyLocusZoom/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/michael-denyer/pyLocusZoom/compare/v0.3.0...v0.4.0

{pylocuszoom-0.6.0 → pylocuszoom-0.8.0}/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: pylocuszoom
-Version: 0.6.0
+Version: 0.8.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
 Project-URL: Repository, https://github.com/michael-denyer/pylocuszoom
-Author: Michael Denyer
+Author-email: Michael Denyer <code.denyer@gmail.com>
 License-Expression: GPL-3.0-or-later
 License-File: LICENSE.md
 Keywords: genetics,gwas,locus-zoom,locuszoom,regional-plot,visualization
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
 Classifier: Programming Language :: Python :: 3
@@ -44,20 +44,18 @@ Requires-Dist: pyspark>=3.0.0; extra == 'spark'
 Description-Content-Type: text/markdown
 
 [![CI](https://github.com/michael-denyer/pyLocusZoom/actions/workflows/ci.yml/badge.svg)](https://github.com/michael-denyer/pyLocusZoom/actions/workflows/ci.yml)
-[![codecov](https://codecov.io/gh/michael-denyer/pyLocusZoom/graph/badge.svg)](https://codecov.io/gh/michael-denyer/pyLocusZoom)
 [![PyPI](https://img.shields.io/pypi/v/pylocuszoom)](https://pypi.org/project/pylocuszoom/)
-[![Bioconda](https://img.shields.io/conda/vn/bioconda/pylocuszoom)](https://anaconda.org/bioconda/pylocuszoom)
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-red.svg)](https://www.gnu.org/licenses/gpl-3.0)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Matplotlib](https://img.shields.io/badge/Matplotlib-3.5+-11557c.svg)](https://matplotlib.org/)
-[![Plotly](https://img.shields.io/badge/Plotly-5.0+-3F4F75.svg)](https://plotly.com/python/)
+[![Plotly](https://img.shields.io/badge/Plotly-5.15+-3F4F75.svg)](https://plotly.com/python/)
 [![Bokeh](https://img.shields.io/badge/Bokeh-3.8+-E6526F.svg)](https://bokeh.org/)
 [![Pandas](https://img.shields.io/badge/Pandas-1.4+-150458.svg)](https://pandas.pydata.org/)
 <img src="logo.svg" alt="pyLocusZoom logo" width="120" align="right">
 # pyLocusZoom
 
-Publication-ready regional association plots with LD coloring, gene tracks, and recombination overlays.
+Designed for publication-ready GWAS visualization with regional association plots, gene tracks, eQTL, PheWAS, fine-mapping, and forest plots.
 
 Inspired by [LocusZoom](http://locuszoom.org/) and [locuszoomr](https://github.com/myles-lewis/locuszoomr).
 
@@ -68,20 +66,22 @@ 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**: Overlay showing recombination rate across region (*Canis lupus familiaris* only)
-    - **SNP labels (matplotlib)**: Automatic labeling of lead SNPs with RS ID
-    - **Tooltips (Bokeh and Plotly)**: Mouseover for detailed SNP data
+    - **Recombination rate**: Optional overlay across region (*Canis lupus familiaris* built-in, not shown in example image)
+    - **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](examples/regional_plot.png)
+![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).*
 
 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 charting libraries**: matplotlib (static), plotly (interactive), bokeh (dashboards)
+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)
 
 ## Installation
 
@@ -181,28 +181,46 @@ fig = plotter.plot(
 )
 ```
 
+## Automatic Gene Annotations
+
+pyLocusZoom can automatically fetch gene annotations from Ensembl for any species:
+
+```python
+# Enable automatic gene fetching
+plotter = LocusZoomPlotter(species="human", auto_genes=True)
+
+# No need to provide genes_df - fetched automatically
+fig = plotter.plot(gwas_df, chrom=13, start=32000000, end=33000000)
+```
+
+Supported species aliases: `human`, `mouse`, `rat`, `canine`/`dog`, `feline`/`cat`, or any Ensembl species name.
+Data is cached locally for fast subsequent plots. Maximum region size is 5Mb (Ensembl API limit).
+
 ## Backends
 
-pyLocusZoom supports multiple rendering backends:
+pyLocusZoom supports multiple rendering backends (set at initialization):
 
 ```python
 # Static publication-quality plot (default)
-fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000, backend="matplotlib")
+plotter = LocusZoomPlotter(species="canine", backend="matplotlib")
+fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
 fig.savefig("plot.png", dpi=150)
 
 # Interactive Plotly (hover tooltips, pan/zoom)
-fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000, backend="plotly")
+plotter = LocusZoomPlotter(species="canine", backend="plotly")
+fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
 fig.write_html("plot.html")
 
 # Interactive Bokeh (dashboard-ready)
-fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000, backend="bokeh")
+plotter = LocusZoomPlotter(species="canine", backend="bokeh")
+fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
 ```
 
 | Backend | Output | Best For | Features |
 |---------|--------|----------|----------|
-| `matplotlib` | Static PNG/PDF/SVG | Publications, presentations | Full feature set with SNP labels |
-| `plotly` | Interactive HTML | Web reports, data exploration | Hover tooltips, pan/zoom |
-| `bokeh` | Interactive HTML | Dashboards, web apps | Hover tooltips, pan/zoom |
+| `matplotlib` | Static PNG/PDF/SVG | Publication-ready figures | Full feature set with SNP labels |
+| `plotly` | Interactive HTML | Web reports, exploration | Hover tooltips, pan/zoom |
+| `bokeh` | Interactive HTML | Dashboard integration | Hover tooltips, pan/zoom |
 
 > **Note:** All backends support scatter plots, gene tracks, recombination overlay, and LD legend. SNP labels (auto-positioned with adjustText) are matplotlib-only; interactive backends use hover tooltips instead.
 
@@ -221,7 +239,8 @@ fig = plotter.plot_stacked(
 )
 ```
 
-![Example stacked plot](examples/stacked_plot.png)
+![Example stacked plot comparing two phenotypes](examples/stacked_plot.png)
+*Stacked plot comparing two phenotypes with LD coloring and shared gene track.*
 
 ## eQTL Overlay
 
@@ -244,6 +263,7 @@ fig = plotter.plot_stacked(
 ```
 
 ![Example eQTL overlay plot](examples/eqtl_overlay.png)
+*eQTL overlay with effect direction (up/down triangles) and magnitude binning.*
 
 ## Fine-mapping Visualization
 
@@ -266,6 +286,7 @@ fig = plotter.plot_stacked(
 ```
 
 ![Example fine-mapping plot](examples/finemapping_plot.png)
+*Fine-mapping visualization with PIP line and credible set coloring (CS1/CS2).*
 
 ## PheWAS Plots
 
@@ -286,6 +307,7 @@ fig = plotter.plot_phewas(
 ```
 
 ![Example PheWAS plot](examples/phewas_plot.png)
+*PheWAS plot showing associations across phenotype categories with significance threshold.*
 
 ## Forest Plots
 
@@ -308,19 +330,18 @@ fig = plotter.plot_forest(
 ```
 
 ![Example forest plot](examples/forest_plot.png)
+*Forest plot with effect sizes, confidence intervals, and weight-proportional markers.*
 
 ## PySpark Support
 
-For large-scale genomics data, pass PySpark DataFrames directly:
+For large-scale genomics data, convert PySpark DataFrames with `to_pandas()` before plotting:
 
 ```python
 from pylocuszoom import LocusZoomPlotter, to_pandas
 
-# PySpark DataFrame (automatically converted)
-fig = plotter.plot(spark_gwas_df, chrom=1, start=1000000, end=2000000)
-
-# Or convert manually with sampling for very large data
+# Convert PySpark DataFrame (optionally sampled for very large data)
 pandas_df = to_pandas(spark_gwas_df, sample_size=100000)
+fig = plotter.plot(pandas_df, chrom=1, start=1000000, end=2000000)
 ```
 
 Install PySpark support: `uv add pylocuszoom[spark]`

{pylocuszoom-0.6.0 → pylocuszoom-0.8.0}/README.md

@@ -1,18 +1,16 @@
 [![CI](https://github.com/michael-denyer/pyLocusZoom/actions/workflows/ci.yml/badge.svg)](https://github.com/michael-denyer/pyLocusZoom/actions/workflows/ci.yml)
-[![codecov](https://codecov.io/gh/michael-denyer/pyLocusZoom/graph/badge.svg)](https://codecov.io/gh/michael-denyer/pyLocusZoom)
 [![PyPI](https://img.shields.io/pypi/v/pylocuszoom)](https://pypi.org/project/pylocuszoom/)
-[![Bioconda](https://img.shields.io/conda/vn/bioconda/pylocuszoom)](https://anaconda.org/bioconda/pylocuszoom)
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-red.svg)](https://www.gnu.org/licenses/gpl-3.0)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Matplotlib](https://img.shields.io/badge/Matplotlib-3.5+-11557c.svg)](https://matplotlib.org/)
-[![Plotly](https://img.shields.io/badge/Plotly-5.0+-3F4F75.svg)](https://plotly.com/python/)
+[![Plotly](https://img.shields.io/badge/Plotly-5.15+-3F4F75.svg)](https://plotly.com/python/)
 [![Bokeh](https://img.shields.io/badge/Bokeh-3.8+-E6526F.svg)](https://bokeh.org/)
 [![Pandas](https://img.shields.io/badge/Pandas-1.4+-150458.svg)](https://pandas.pydata.org/)
 <img src="logo.svg" alt="pyLocusZoom logo" width="120" align="right">
 # pyLocusZoom
 
-Publication-ready regional association plots with LD coloring, gene tracks, and recombination overlays.
+Designed for publication-ready GWAS visualization with regional association plots, gene tracks, eQTL, PheWAS, fine-mapping, and forest plots.
 
 Inspired by [LocusZoom](http://locuszoom.org/) and [locuszoomr](https://github.com/myles-lewis/locuszoomr).
 
@@ -23,20 +21,22 @@ 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**: Overlay showing recombination rate across region (*Canis lupus familiaris* only)
-    - **SNP labels (matplotlib)**: Automatic labeling of lead SNPs with RS ID
-    - **Tooltips (Bokeh and Plotly)**: Mouseover for detailed SNP data
+    - **Recombination rate**: Optional overlay across region (*Canis lupus familiaris* built-in, not shown in example image)
+    - **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](examples/regional_plot.png)
+![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).*
 
 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 charting libraries**: matplotlib (static), plotly (interactive), bokeh (dashboards)
+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)
 
 ## Installation
 
@@ -136,28 +136,46 @@ fig = plotter.plot(
 )
 ```
 
+## Automatic Gene Annotations
+
+pyLocusZoom can automatically fetch gene annotations from Ensembl for any species:
+
+```python
+# Enable automatic gene fetching
+plotter = LocusZoomPlotter(species="human", auto_genes=True)
+
+# No need to provide genes_df - fetched automatically
+fig = plotter.plot(gwas_df, chrom=13, start=32000000, end=33000000)
+```
+
+Supported species aliases: `human`, `mouse`, `rat`, `canine`/`dog`, `feline`/`cat`, or any Ensembl species name.
+Data is cached locally for fast subsequent plots. Maximum region size is 5Mb (Ensembl API limit).
+
 ## Backends
 
-pyLocusZoom supports multiple rendering backends:
+pyLocusZoom supports multiple rendering backends (set at initialization):
 
 ```python
 # Static publication-quality plot (default)
-fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000, backend="matplotlib")
+plotter = LocusZoomPlotter(species="canine", backend="matplotlib")
+fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
 fig.savefig("plot.png", dpi=150)
 
 # Interactive Plotly (hover tooltips, pan/zoom)
-fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000, backend="plotly")
+plotter = LocusZoomPlotter(species="canine", backend="plotly")
+fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
 fig.write_html("plot.html")
 
 # Interactive Bokeh (dashboard-ready)
-fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000, backend="bokeh")
+plotter = LocusZoomPlotter(species="canine", backend="bokeh")
+fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
 ```
 
 | Backend | Output | Best For | Features |
 |---------|--------|----------|----------|
-| `matplotlib` | Static PNG/PDF/SVG | Publications, presentations | Full feature set with SNP labels |
-| `plotly` | Interactive HTML | Web reports, data exploration | Hover tooltips, pan/zoom |
-| `bokeh` | Interactive HTML | Dashboards, web apps | Hover tooltips, pan/zoom |
+| `matplotlib` | Static PNG/PDF/SVG | Publication-ready figures | Full feature set with SNP labels |
+| `plotly` | Interactive HTML | Web reports, exploration | Hover tooltips, pan/zoom |
+| `bokeh` | Interactive HTML | Dashboard integration | Hover tooltips, pan/zoom |
 
 > **Note:** All backends support scatter plots, gene tracks, recombination overlay, and LD legend. SNP labels (auto-positioned with adjustText) are matplotlib-only; interactive backends use hover tooltips instead.
 
@@ -176,7 +194,8 @@ fig = plotter.plot_stacked(
 )
 ```
 
-![Example stacked plot](examples/stacked_plot.png)
+![Example stacked plot comparing two phenotypes](examples/stacked_plot.png)
+*Stacked plot comparing two phenotypes with LD coloring and shared gene track.*
 
 ## eQTL Overlay
 
@@ -199,6 +218,7 @@ fig = plotter.plot_stacked(
 ```
 
 ![Example eQTL overlay plot](examples/eqtl_overlay.png)
+*eQTL overlay with effect direction (up/down triangles) and magnitude binning.*
 
 ## Fine-mapping Visualization
 
@@ -221,6 +241,7 @@ fig = plotter.plot_stacked(
 ```
 
 ![Example fine-mapping plot](examples/finemapping_plot.png)
+*Fine-mapping visualization with PIP line and credible set coloring (CS1/CS2).*
 
 ## PheWAS Plots
 
@@ -241,6 +262,7 @@ fig = plotter.plot_phewas(
 ```
 
 ![Example PheWAS plot](examples/phewas_plot.png)
+*PheWAS plot showing associations across phenotype categories with significance threshold.*
 
 ## Forest Plots
 
@@ -263,19 +285,18 @@ fig = plotter.plot_forest(
 ```
 
 ![Example forest plot](examples/forest_plot.png)
+*Forest plot with effect sizes, confidence intervals, and weight-proportional markers.*
 
 ## PySpark Support
 
-For large-scale genomics data, pass PySpark DataFrames directly:
+For large-scale genomics data, convert PySpark DataFrames with `to_pandas()` before plotting:
 
 ```python
 from pylocuszoom import LocusZoomPlotter, to_pandas
 
-# PySpark DataFrame (automatically converted)
-fig = plotter.plot(spark_gwas_df, chrom=1, start=1000000, end=2000000)
-
-# Or convert manually with sampling for very large data
+# Convert PySpark DataFrame (optionally sampled for very large data)
 pandas_df = to_pandas(spark_gwas_df, sample_size=100000)
+fig = plotter.plot(pandas_df, chrom=1, start=1000000, end=2000000)
 ```
 
 Install PySpark support: `uv add pylocuszoom[spark]`

pylocuszoom-0.8.0/bioconda/meta.yaml

@@ -0,0 +1,63 @@
+{% set name = "pylocuszoom" %}
+{% set version = "0.6.0" %}
+
+package:
+  name: {{ name|lower }}
+  version: {{ version }}
+
+source:
+  url: https://pypi.io/packages/source/{{ name[0] }}/{{ name }}/{{ name }}-{{ version }}.tar.gz
+  sha256: 1597c2080e2e32019293aab67836d1b944c1cc0b2fe3e7cd94e82d9119175742
+
+build:
+  noarch: python
+  number: 0
+  script: {{ PYTHON }} -m pip install . -vv --no-deps --no-build-isolation
+  run_exports:
+    - {{ pin_subpackage('pylocuszoom', max_pin="x") }}
+
+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.15.0
+    - bokeh >=3.8.2
+    - python-kaleido >=0.2.0
+    - adjusttext >=0.8
+    - pydantic >=2.0.0
+    - requests >=2.25.0
+    - tqdm >=4.60.0
+
+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: Publication-ready GWAS visualization library with regional association plots, gene tracks, eQTL, PheWAS, fine-mapping, and forest plots
+  description: |
+    pyLocusZoom creates publication-quality genetic association visualizations:
+    regional association plots with LD coloring and recombination overlays,
+    stacked multi-GWAS comparisons, eQTL overlays, fine-mapping/SuSiE credible sets,
+    PheWAS (phenome-wide association) plots, and forest plots for meta-analysis.
+    Includes gene track visualization, file loaders for common formats (REGENIE, BOLT-LMM,
+    SAIGE, GEMMA, GTEx, SuSiE, FINEMAP), and three backends: matplotlib (static/publication),
+    plotly (interactive), and bokeh (dashboards).
+  dev_url: https://github.com/michael-denyer/pylocuszoom
+
+extra:
+  recipe-maintainers:
+    - michael-denyer

{pylocuszoom-0.6.0 → pylocuszoom-0.8.0}/docs/USER_GUIDE.md

@@ -773,6 +773,44 @@ plotter = LocusZoomPlotter(
 
 Recombination maps must be named `chr{N}_recomb.tsv`.
 
+### Automatic Gene Annotations from Ensembl
+
+Instead of providing your own `genes_df`, enable automatic fetching from Ensembl:
+
+```python
+plotter = LocusZoomPlotter(species="human", auto_genes=True)
+fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
+# Gene track populated automatically from Ensembl
+```
+
+**Supported Species:**
+| Alias | Ensembl Name |
+|-------|--------------|
+| human | homo_sapiens |
+| mouse | mus_musculus |
+| rat | rattus_norvegicus |
+| canine, dog | canis_lupus_familiaris |
+| feline, cat | felis_catus |
+
+Any valid Ensembl species name also works (e.g., `sus_scrofa` for pig).
+
+**Region Limit:** Maximum 5Mb per request (Ensembl API limitation). For larger regions, provide `genes_df` directly.
+
+**Error Handling:** By default, API errors result in warnings and an empty gene track. Use `raise_on_error=True` in low-level functions to get exceptions instead.
+
+**Cache Location:**
+- Linux/macOS: `~/.cache/snp-scope-plot/ensembl/{species}/`
+- Windows: `%LOCALAPPDATA%/snp-scope-plot/ensembl/{species}/`
+
+```python
+# Clear cache when needed
+from pylocuszoom import clear_ensembl_cache
+clear_ensembl_cache()  # Clear all
+clear_ensembl_cache(species="human")  # Clear specific species
+```
+
+**Note:** Recombination rates are NOT available from Ensembl for most species. Continue to provide recombination maps separately.
+
 ---
 
 ## Recipes & Examples