pylocuszoom 0.5.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

{pylocuszoom-0.5.0.dist-info → pylocuszoom-0.8.0.dist-info}/METADATA

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: pylocuszoom
-Version: 0.5.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
@@ -26,13 +26,17 @@ Requires-Dist: loguru>=0.7.0
 Requires-Dist: matplotlib>=3.5.0
 Requires-Dist: numpy>=1.21.0
 Requires-Dist: pandas>=1.4.0
-Requires-Dist: plotly>=5.0.0
+Requires-Dist: plotly>=5.15.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pyliftover>=0.4
+Requires-Dist: requests>=2.25.0
+Requires-Dist: tqdm>=4.60.0
 Provides-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-randomly>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.0.0; extra == 'dev'
 Requires-Dist: pytest>=7.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
 Provides-Extra: spark
@@ -40,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).
 
@@ -64,18 +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. **Multiple charting libraries**: matplotlib (static), plotly (interactive), bokeh (dashboards)
-6. **Pandas and PySpark support**: Works with both Pandas and PySpark DataFrames for large-scale genomics data
-7. **Convenience data file loaders**: Load and validate common GWAS, eQTL and fine-mapping file formats
+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)
 
 ## Installation
 
@@ -175,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.
 
@@ -215,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
 
@@ -238,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
 
@@ -260,19 +286,62 @@ 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
+
+Visualize associations of a single variant across multiple phenotypes:
+
+```python
+phewas_df = pd.DataFrame({
+    "phenotype": ["Height", "BMI", "T2D", "CAD", "HDL"],
+    "p_value": [1e-15, 0.05, 1e-8, 1e-3, 1e-10],
+    "category": ["Anthropometric", "Anthropometric", "Metabolic", "Cardiovascular", "Lipids"],
+})
+
+fig = plotter.plot_phewas(
+    phewas_df,
+    variant_id="rs12345",
+    category_col="category",
+)
+```
+
+![Example PheWAS plot](examples/phewas_plot.png)
+*PheWAS plot showing associations across phenotype categories with significance threshold.*
+
+## Forest Plots
+
+Create forest plots for meta-analysis visualization:
+
+```python
+forest_df = pd.DataFrame({
+    "study": ["Study A", "Study B", "Study C", "Meta-analysis"],
+    "effect": [0.45, 0.52, 0.38, 0.46],
+    "ci_lower": [0.30, 0.35, 0.20, 0.40],
+    "ci_upper": [0.60, 0.69, 0.56, 0.52],
+    "weight": [25, 35, 20, 100],
+})
+
+fig = plotter.plot_forest(
+    forest_df,
+    variant_id="rs12345",
+    weight_col="weight",
+)
+```
+
+![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.dist-info/RECORD

@@ -0,0 +1,29 @@
+pylocuszoom/__init__.py,sha256=UtrNrjV0b0frxv3Zl4jw5D8aTMbNSE55j-PPkd8rz28,5585
+pylocuszoom/colors.py,sha256=B28rfhWwGZ-e6Q-F43iXxC6NZpjUo0yWk4S_-vp9ZvU,7686
+pylocuszoom/ensembl.py,sha256=q767o86FdcKn4V9aK48ESFwNI7ATlaX5tnwjZReYMEw,14436
+pylocuszoom/eqtl.py,sha256=OrpWbFMR1wKMCmfQiC-2sqYx-99TT2i1cStIrPWIUOs,5948
+pylocuszoom/finemapping.py,sha256=ZPcnc9E6N41Su8222wCqBkB3bhhyfASvj9u9Ot4td4o,5898
+pylocuszoom/forest.py,sha256=302gULz9I0UiwqgcB18R756OOl1aa54OsPYHc6TnxGY,1092
+pylocuszoom/gene_track.py,sha256=PkBwfqByVxhXlAPco9-d4P5X7cTg2rrOnw7BJVx48ow,17818
+pylocuszoom/labels.py,sha256=Ams5WVZFNVT692BRiQ5wZcdbdNEAm5xtgRwmF5u0s_A,3492
+pylocuszoom/ld.py,sha256=64xIulpDVvbMSryWUPoCQ99Odcjwf1wejpwVr_30MLU,6412
+pylocuszoom/loaders.py,sha256=KpWPBO0BCb2yrGTtgdiOqOuhx2YLmjK_ywmpr3onnx8,25156
+pylocuszoom/logging.py,sha256=nZHEkbnjp8zoyWj_S-Hy9UQvUYLoMoxyiOWRozBT2dg,4987
+pylocuszoom/phewas.py,sha256=6g2LmwA5kmxYlHgPxJvuXIMerEqfqgsrth110Y3CgVU,968
+pylocuszoom/plotter.py,sha256=gFywhaHPuXlbKPxWaWfw7Wrw8kqPMUPzKMgDcRB6wu8,50709
+pylocuszoom/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pylocuszoom/recombination.py,sha256=97GGBLDLTlQSRMp5sLOna3mCeRxeJiiWPHrw4dBRjQs,14546
+pylocuszoom/schemas.py,sha256=vABBBlAR1vUP6BIewZ8E-TYpacccrcxavrdIDVCrQB4,11916
+pylocuszoom/utils.py,sha256=_rI6ov0MbsWlZGJ7ni-V4387cirmJCX6IF2JAYhBx6A,6929
+pylocuszoom/validation.py,sha256=UInqlhOWhWaCT_mrO7O7SfB1DNIYkjvEMudy4YjtUBg,5698
+pylocuszoom/backends/__init__.py,sha256=xefVj3jVxmYwVLLY5AZtFqTPMehQxZ2qGd-Pk7_V_Bk,4267
+pylocuszoom/backends/base.py,sha256=PBdm9t4f_qFDMkYR5z3edW4DvpuQSCAXuaxs2qjAeH0,21034
+pylocuszoom/backends/bokeh_backend.py,sha256=11zRhXH2guUHiaYXyd7l2IDAv6uawdRAv6dyGPkHmJc,25512
+pylocuszoom/backends/hover.py,sha256=Hjm_jcxJL8dDxO_Ye7jeWAUcHKlbH6oO8ZfGJ2MzIFM,6564
+pylocuszoom/backends/matplotlib_backend.py,sha256=098ITnvNrBTaEztqez_7D0sZ_rKAYIxS6EDR5Yxt8is,20924
+pylocuszoom/backends/plotly_backend.py,sha256=A6ZuHw0wVZaIIA6FgYJ4SH-Sz59tHOtnGUl-e-2VzZM,30574
+pylocuszoom/reference_data/__init__.py,sha256=qqHqAUt1jebGlCN3CjqW3Z-_coHVNo5K3a3bb9o83hA,109
+pylocuszoom-0.8.0.dist-info/METADATA,sha256=VqHRvFL1Wq5OJO3B727Rl0H8UfbBPaxVIJUOSA22s5A,17866
+pylocuszoom-0.8.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+pylocuszoom-0.8.0.dist-info/licenses/LICENSE.md,sha256=U2y_hv8RcN5lECA3uK88irU3ODUE1TDAPictcmnP0Q4,698
+pylocuszoom-0.8.0.dist-info/RECORD,,

pylocuszoom-0.5.0.dist-info/RECORD

@@ -1,24 +0,0 @@
-pylocuszoom/__init__.py,sha256=kEfcTSdVSQgP85IdHDqCQ-oEdq_-8n_Rg-xWWtHzKYk,4806
-pylocuszoom/colors.py,sha256=IyzB6x5Q3kkulv-AnYoFVgvibgGgQYE27XjPx99BI5E,6624
-pylocuszoom/eqtl.py,sha256=9lZJ8jT1WEj3won6D9B54xdqUvbRvxpOitf97NCUR28,6167
-pylocuszoom/finemapping.py,sha256=PJ4HJYeCaHZecUmADCEGQxKd9HhhjrdIA1H5LQsUmLI,6332
-pylocuszoom/gene_track.py,sha256=VWvPY0SrVFGJprTdttJ72r3JD-r3bdRDr0HDBai0oJw,18692
-pylocuszoom/labels.py,sha256=Ams5WVZFNVT692BRiQ5wZcdbdNEAm5xtgRwmF5u0s_A,3492
-pylocuszoom/ld.py,sha256=64xIulpDVvbMSryWUPoCQ99Odcjwf1wejpwVr_30MLU,6412
-pylocuszoom/loaders.py,sha256=MK0jUpb09CLMuQYzIY2P1FF3hhtTwemLSiWv4RvLVf8,24350
-pylocuszoom/logging.py,sha256=nZHEkbnjp8zoyWj_S-Hy9UQvUYLoMoxyiOWRozBT2dg,4987
-pylocuszoom/plotter.py,sha256=A7phON4VYrzFZM0CjSlWwMPLYJmjGV1JF1uKHD8Ml2A,44205
-pylocuszoom/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pylocuszoom/recombination.py,sha256=_W6YVO8a8G8UmGGVda8J_MRI9dOJnffKj8491ILQf3Y,13807
-pylocuszoom/schemas.py,sha256=LRUrtgSYH8CZ7G14VSvSL_Z-p4EQBSv2r5WzyKnROh8,11454
-pylocuszoom/utils.py,sha256=fKNX9WSTbfHR1EpPYijt6ycNjXEjwzunQMHXAvHaK3s,5211
-pylocuszoom/backends/__init__.py,sha256=7dlGvDoqMVK3fCtoMcI9zOP9qO0odQGPwfXhxnLfXfI,1196
-pylocuszoom/backends/base.py,sha256=yLZkr5FRlYHs8L9ViNbTwu8hrBaHoVv_QbMujad2aTc,9793
-pylocuszoom/backends/bokeh_backend.py,sha256=OFx_FISiDFG-A6NXcR8V-2MgkTRq2dXEcpqaWxf0YUg,21528
-pylocuszoom/backends/matplotlib_backend.py,sha256=dUgH3ouQCkh55aufvjNIvkEqMG9oamKKvQYp2AEm4DY,11479
-pylocuszoom/backends/plotly_backend.py,sha256=U3odXYLVCwTC6Xb-NeOs456tlr_qJQxgix7QIjJX-3Q,26922
-pylocuszoom/reference_data/__init__.py,sha256=qqHqAUt1jebGlCN3CjqW3Z-_coHVNo5K3a3bb9o83hA,109
-pylocuszoom-0.5.0.dist-info/METADATA,sha256=_0mgXIY3m1x5ATnQpLfAdRvBjh8iwW_FnX4i-aX4ne8,15228
-pylocuszoom-0.5.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-pylocuszoom-0.5.0.dist-info/licenses/LICENSE.md,sha256=U2y_hv8RcN5lECA3uK88irU3ODUE1TDAPictcmnP0Q4,698
-pylocuszoom-0.5.0.dist-info/RECORD,,