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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pylocuszoom
-Version: 0.8.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,17 +110,17 @@ 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)
 
-# Create regional plot
+# 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
+    lead_pos=1500000,               # Highlight lead SNP
+    show_recombination=True,        # Overlay recombination rate
 )
-
 fig.savefig("regional_plot.png", dpi=150)
 ```
 
@@ -137,9 +140,7 @@ fig = plotter.plot(
     start=1000000,
     end=2000000,
     lead_pos=1500000,
-    ld_reference_file="genotypes.bed",  # For LD calculation
-    genes_df=genes_df,                  # Gene annotations
-    exons_df=exons_df,                  # Exon annotations
+    ld_reference_file="genotypes",      # PLINK fileset (without extension)
     show_recombination=True,            # Overlay recombination rate
     snp_labels=True,                    # Label top SNPs
     label_top_n=5,                      # How many to label
@@ -147,6 +148,8 @@ fig = plotter.plot(
     p_col="p_wald",                     # Column name for p-value
     rs_col="rs",                        # Column name for SNP ID
     figsize=(12, 8),
+    genes_df=genes_df,                  # Gene annotations
+    exons_df=exons_df,                  # Exon annotations
 )
 ```
 
@@ -163,6 +166,8 @@ Recombination maps are automatically lifted over from CanFam3.1 to CanFam4 coord
 ## Using with Other Species
 
 ```python
+from pylocuszoom import LocusZoomPlotter
+
 # Feline (LD and gene tracks, user provides recombination data)
 plotter = LocusZoomPlotter(species="feline")
 
@@ -172,10 +177,12 @@ plotter = LocusZoomPlotter(
     recomb_data_dir="/path/to/recomb_maps/",
 )
 
-# Or provide data per-plot
+# Provide data per-plot
 fig = plotter.plot(
     gwas_df,
-    chrom=1, start=1000000, end=2000000,
+    chrom=1,
+    start=1000000,
+    end=2000000,
     recomb_df=my_recomb_dataframe,
     genes_df=my_genes_df,
 )
@@ -186,6 +193,8 @@ fig = plotter.plot(
 pyLocusZoom can automatically fetch gene annotations from Ensembl for any species:
 
 ```python
+from pylocuszoom import LocusZoomPlotter
+
 # Enable automatic gene fetching
 plotter = LocusZoomPlotter(species="human", auto_genes=True)
 
@@ -201,6 +210,8 @@ Data is cached locally for fast subsequent plots. Maximum region size is 5Mb (En
 pyLocusZoom supports multiple rendering backends (set at initialization):
 
 ```python
+from pylocuszoom import LocusZoomPlotter
+
 # Static publication-quality plot (default)
 plotter = LocusZoomPlotter(species="canine", backend="matplotlib")
 fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
@@ -229,6 +240,10 @@ fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
 Compare multiple GWAS results vertically with shared x-axis:
 
 ```python
+from pylocuszoom import LocusZoomPlotter
+
+plotter = LocusZoomPlotter(species="canine")
+
 fig = plotter.plot_stacked(
     [gwas_height, gwas_bmi, gwas_whr],
     chrom=1,
@@ -247,15 +262,21 @@ fig = plotter.plot_stacked(
 Add expression QTL data as a separate panel:
 
 ```python
+from pylocuszoom import LocusZoomPlotter
+
 eqtl_df = pd.DataFrame({
     "pos": [1000500, 1001200, 1002000],
     "p_value": [1e-6, 1e-4, 0.01],
     "gene": ["BRCA1", "BRCA1", "BRCA1"],
 })
 
+plotter = LocusZoomPlotter(species="canine")
+
 fig = plotter.plot_stacked(
     [gwas_df],
-    chrom=1, start=1000000, end=2000000,
+    chrom=1,
+    start=1000000,
+    end=2000000,
     eqtl_df=eqtl_df,
     eqtl_gene="BRCA1",
     genes_df=genes_df,
@@ -270,15 +291,21 @@ fig = plotter.plot_stacked(
 Visualize SuSiE or other fine-mapping results with credible set coloring:
 
 ```python
+from pylocuszoom import LocusZoomPlotter
+
 finemapping_df = pd.DataFrame({
     "pos": [1000500, 1001200, 1002000, 1003500],
     "pip": [0.85, 0.12, 0.02, 0.45],  # Posterior inclusion probability
     "cs": [1, 1, 0, 2],               # Credible set assignment (0 = not in CS)
 })
 
+plotter = LocusZoomPlotter(species="canine")
+
 fig = plotter.plot_stacked(
     [gwas_df],
-    chrom=1, start=1000000, end=2000000,
+    chrom=1,
+    start=1000000,
+    end=2000000,
     finemapping_df=finemapping_df,
     finemapping_cs_col="cs",
     genes_df=genes_df,
@@ -332,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:
@@ -414,7 +547,7 @@ gwas_df = pd.DataFrame({
 |--------|------|----------|-------------|
 | `chr` | str or int | Yes | Chromosome identifier. Accepts "1", "chr1", or 1. The "chr" prefix is stripped for matching. |
 | `start` | int | Yes | Gene start position (bp, 1-based). Transcript start for strand-aware genes. |
-| `end` | int | Yes | Gene end position (bp, 1-based). Must be ≥ start. |
+| `end` | int | Yes | Gene end position (bp, 1-based). Must be >= start. |
 | `gene_name` | str | Yes | Gene symbol displayed in track (e.g., "BRCA1", "TP53"). Keep short for readability. |
 
 Example:
@@ -516,6 +649,7 @@ Optional:
 ## Documentation
 
 - [User Guide](docs/USER_GUIDE.md) - Comprehensive documentation with API reference
+- [Code Map](docs/CODEMAP.md) - Architecture diagram with source code links
 - [Architecture](docs/ARCHITECTURE.md) - Design decisions and component overview
 - [Example Notebook](examples/getting_started.ipynb) - Interactive tutorial
 - [CHANGELOG](CHANGELOG.md) - Version history

pylocuszoom-1.1.0.dist-info/RECORD

@@ -0,0 +1,36 @@
+pylocuszoom/__init__.py,sha256=F-LIZ4jSH9JC09MqQymwYDyEJQ1DWpGDutreJ1qI7NE,6108
+pylocuszoom/_plotter_utils.py,sha256=ELdSOcKk2KvOo_AxEWHeutmmUS4zZMaDMmQfpQUWaF0,1541
+pylocuszoom/colors.py,sha256=B28rfhWwGZ-e6Q-F43iXxC6NZpjUo0yWk4S_-vp9ZvU,7686
+pylocuszoom/config.py,sha256=qjIEodI-RY71RVyQ5QmE6WXcPXU4Re_xEWiDlkEww3g,13266
+pylocuszoom/ensembl.py,sha256=w2msgBoIrY79iHI3hURSbevvdFHxHyWF9Z78hXtAaBc,14296
+pylocuszoom/eqtl.py,sha256=9hGcFARABQRCMN3rco0pVlFJdmlh4SLBBKSgOvdIH_U,5924
+pylocuszoom/exceptions.py,sha256=nd-rWMUodW62WVV4TfcYVPQcb66xV6v9FA-_4xHb5VY,926
+pylocuszoom/finemapping.py,sha256=VYQs4o4dVREXicueT1anzuENiFZk6YXb6HpbwyF0FD0,5828
+pylocuszoom/forest.py,sha256=K-wBinxBOqIzsNMtZJ587e_oMhUXIXEqmEzVTUbmHSY,1161
+pylocuszoom/gene_track.py,sha256=Sh0JCSdLNAAH0NQEiDVMvyXjm63PiCMq3gLvewcagvo,17277
+pylocuszoom/labels.py,sha256=l4PHAR_err75Z9kTmb3a2h0eunkFj6UjzhKBUgmZTDc,3623
+pylocuszoom/ld.py,sha256=64xIulpDVvbMSryWUPoCQ99Odcjwf1wejpwVr_30MLU,6412
+pylocuszoom/loaders.py,sha256=KpWPBO0BCb2yrGTtgdiOqOuhx2YLmjK_ywmpr3onnx8,25156
+pylocuszoom/logging.py,sha256=nZHEkbnjp8zoyWj_S-Hy9UQvUYLoMoxyiOWRozBT2dg,4987
+pylocuszoom/manhattan.py,sha256=sNhPnsfsIqe1ls74D-kKMFyF_ZmaYB9Ul8qf4UMWnF0,8022
+pylocuszoom/manhattan_plotter.py,sha256=1QQxaXEh5YG4x6ZIxpdhdfQPI2KuO_525qYKI7c32n4,27584
+pylocuszoom/phewas.py,sha256=6g2LmwA5kmxYlHgPxJvuXIMerEqfqgsrth110Y3CgVU,968
+pylocuszoom/plotter.py,sha256=mMOQxyLU3d1XJGpDJUuy71fAFm6IAnQfMZQXHgN6Mzk,54689
+pylocuszoom/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pylocuszoom/qq.py,sha256=GPIFHXYCLvhP4IUgjcU3QELLREH8r1AEYXMord8gtEo,3650
+pylocuszoom/recombination.py,sha256=e11IlFRXKILEAP-vgMcbFK28zbAQ5jY-fESsisogq0o,14570
+pylocuszoom/schemas.py,sha256=XxeivyRm5LGDwJw4GToxzOSdyx1yXvFYk3xgeFJ6VW0,11858
+pylocuszoom/stats_plotter.py,sha256=67bgU-TXGnmVTxfTRWT3-PFemVVy6lTu4-ZlxUnwHS4,11171
+pylocuszoom/utils.py,sha256=Z2P__Eau3ilF2ftuAZBm11EZ1NqCFQzfr4br9jCiJmg,6887
+pylocuszoom/validation.py,sha256=3D9axjUvNXWW3Mk7dwRG38-di2P0zDpVVGF5WNSfZbk,7403
+pylocuszoom/backends/__init__.py,sha256=xefVj3jVxmYwVLLY5AZtFqTPMehQxZ2qGd-Pk7_V_Bk,4267
+pylocuszoom/backends/base.py,sha256=d_IqH2yGWIfQHeUCcavV4eL6V68hpNtOyGfTyb2ke0I,22628
+pylocuszoom/backends/bokeh_backend.py,sha256=cubjEzNq5vHov-CeBMLgmf3SAtEET-fUUB8d_oYFgiw,29151
+pylocuszoom/backends/hover.py,sha256=Hjm_jcxJL8dDxO_Ye7jeWAUcHKlbH6oO8ZfGJ2MzIFM,6564
+pylocuszoom/backends/matplotlib_backend.py,sha256=9WAFLWcclj2-4WKi6bE6IPJfQ_HNoIekOE45ibBGPa0,22824
+pylocuszoom/backends/plotly_backend.py,sha256=VDEZMdP7nOeFYLli-YOc_2DG00ZA6VVRNUcvT5PU0HM,39084
+pylocuszoom/reference_data/__init__.py,sha256=qqHqAUt1jebGlCN3CjqW3Z-_coHVNo5K3a3bb9o83hA,109
+pylocuszoom-1.1.0.dist-info/METADATA,sha256=9m2MMDhv12XxZD93IskPFDYGluazggOSErn_1ieTFjM,21283
+pylocuszoom-1.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+pylocuszoom-1.1.0.dist-info/licenses/LICENSE.md,sha256=U2y_hv8RcN5lECA3uK88irU3ODUE1TDAPictcmnP0Q4,698
+pylocuszoom-1.1.0.dist-info/RECORD,,

pylocuszoom-0.8.0.dist-info/RECORD

@@ -1,29 +0,0 @@
-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,,