pylocuszoom 0.3.0__tar.gz → 0.5.0__tar.gz

pylocuszoom-0.5.0/.gitattributes

@@ -0,0 +1,3 @@
+
+# Use bd merge for beads JSONL files
+.beads/issues.jsonl merge=beads

pylocuszoom-0.5.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,39 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behavior
+title: ''
+labels: bug
+assignees: ''
+---
+
+## Description
+
+A clear description of the bug.
+
+## Minimal Reproducible Example
+
+```python
+from pylocuszoom import LocusZoomPlotter
+import pandas as pd
+
+# Minimal code to reproduce the issue
+```
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened. Include error messages if applicable.
+
+## Environment
+
+- pylocuszoom version:
+- Python version:
+- OS:
+- Installation method: pip / conda / uv
+
+## Additional Context
+
+Any other relevant information (screenshots, data samples, etc.)

pylocuszoom-0.5.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Documentation
+    url: https://github.com/michael-denyer/pyLocusZoom/blob/main/docs/USER_GUIDE.md
+    about: Check the user guide before opening an issue

pylocuszoom-0.5.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature Request
+about: Suggest a new feature or enhancement
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+## Problem
+
+What problem does this feature solve?
+
+## Proposed Solution
+
+Describe the feature you'd like.
+
+## Alternatives Considered
+
+Any alternative solutions or workarounds you've tried.
+
+## Additional Context
+
+Any other relevant information (mockups, examples from other tools, etc.)

{pylocuszoom-0.3.0 → pylocuszoom-0.5.0}/.github/workflows/ci.yml

@@ -29,7 +29,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12"]
 
     steps:
       - uses: actions/checkout@v4

{pylocuszoom-0.3.0 → pylocuszoom-0.5.0}/.gitignore

@@ -21,5 +21,8 @@ htmlcov/
 *.swp
 .claude/
 
+# Issue tracking (local)
+.beads/
+
 # Project instructions (private)
 CLAUDE.md

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

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.1
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

{pylocuszoom-0.3.0 → pylocuszoom-0.5.0}/CHANGELOG.md

@@ -5,6 +5,44 @@ 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.5.0] - 2026-01-27
+
+### Added
+- Hover tooltips for fine-mapping scatter plots (Plotly/Bokeh backends)
+- Hover tooltips for eQTL scatter plots (Plotly/Bokeh backends)
+- Interactive HTML example plots for eQTL and fine-mapping (Plotly/Bokeh)
+- Comprehensive marker and hover data tests for interactive backends
+
+### Changed
+- Plotly/Bokeh backends now hide grid lines for cleaner LocusZoom appearance
+- Plotly/Bokeh backends now show black axis lines (matching matplotlib style)
+- Plotly/Bokeh gene track panels now hide y-axis (ticks, labels, line, grid)
+- Plotly/Bokeh backends now hide minor ticks and zero lines
+
+## [0.4.0] - 2026-01-26
+
+### Added
+- **File format loaders** for common GWAS, eQTL, and fine-mapping formats:
+  - GWAS: `load_gwas`, `load_plink_assoc`, `load_regenie`, `load_bolt_lmm`, `load_gemma`, `load_saige`, `load_gwas_catalog`
+  - eQTL: `load_gtex_eqtl`, `load_eqtl_catalogue`, `load_matrixeqtl`
+  - Fine-mapping: `load_susie`, `load_finemap`, `load_caviar`, `load_polyfun`
+  - Gene annotations: `load_gtf`, `load_bed`, `load_ensembl_genes`
+- Pydantic validation for file loaders with detailed error messages
+- `py.typed` marker for PEP 561 type checking support
+- Pre-commit configuration for automated linting
+- GitHub issue templates for bug reports and feature requests
+- Codecov badge in README
+
+### Changed
+- eQTL and fine-mapping legends now route through backend protocol (works with all backends)
+- Simplified backend code with reduced duplication
+- Backend protocol class diagram added to ARCHITECTURE.md
+
+### Fixed
+- Additional robustness improvements for edge cases
+
 ## [0.3.0] - 2026-01-26
 
 ### Added
@@ -80,7 +118,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.3.0...HEAD
+[Unreleased]: https://github.com/michael-denyer/pyLocusZoom/compare/v0.5.0...HEAD
+[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
 [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 → pylocuszoom-0.5.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pylocuszoom
-Version: 0.3.0
-Summary: Regional association plots for GWAS results with LD coloring, gene tracks, and recombination rate overlays
+Version: 0.5.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
@@ -27,6 +27,7 @@ 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: pydantic>=2.0.0
 Requires-Dist: pyliftover>=0.4
 Provides-Extra: all
 Requires-Dist: pyspark>=3.0.0; extra == 'all'
@@ -38,39 +39,44 @@ Provides-Extra: spark
 Requires-Dist: pyspark>=3.0.0; extra == 'spark'
 Description-Content-Type: text/markdown
 
-# pyLocusZoom
-
 [![CI](https://github.com/michael-denyer/pyLocusZoom/actions/workflows/ci.yml/badge.svg)](https://github.com/michael-denyer/pyLocusZoom/actions/workflows/ci.yml)
-[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![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/)
 [![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
 
-Regional association plots for GWAS results with LD coloring, gene tracks, and recombination rate overlays.
+Publication-ready regional association plots with LD coloring, gene tracks, and recombination overlays.
 
 Inspired by [LocusZoom](http://locuszoom.org/) and [locuszoomr](https://github.com/myles-lewis/locuszoomr).
 
 ## Features
 
-- **LD coloring**: SNPs colored by linkage disequilibrium (R²) with lead variant
-- **Gene track**: Annotated gene/exon positions below the association plot
-- **Recombination rate**: Overlay showing recombination rate across region (*Canis lupus familiaris* only)
-- **SNP labels**: Automatic labeling of top SNPs with RS ID or nearest gene
-- **Species support**: Built-in *Canis lupus familiaris* (CanFam3.1/CanFam4), *Felis catus* (FelCat9), or custom species
-- **CanFam4 support**: Automatic coordinate liftover for recombination maps
-- **Multiple backends**: matplotlib (static), plotly (interactive), bokeh (dashboards)
-- **Stacked plots**: Compare multiple GWAS/phenotypes vertically
-- **eQTL overlay**: Expression QTL data as separate panel
-- **PySpark support**: Handles large-scale genomics DataFrames
+1. **Regional association plot**:
+
+    - **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
 
 ![Example regional association plot](examples/regional_plot.png)
 
+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
+
 ## Installation
 
 ```bash
@@ -186,13 +192,13 @@ fig.write_html("plot.html")
 fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000, backend="bokeh")
 ```
 
-| Backend | Output | Best For |
-|---------|--------|----------|
-| `matplotlib` | Static PNG/PDF/SVG | Publications, presentations |
-| `plotly` | Interactive HTML | Web reports, data exploration |
-| `bokeh` | Interactive HTML | Dashboards, web apps |
+| 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 |
 
-> **Note:** All backends support gene track, recombination overlay, and LD legend. SNP labels (auto-positioned with adjustText) are matplotlib-only.
+> **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.
 
 ## Stacked Plots
 
@@ -209,6 +215,8 @@ fig = plotter.plot_stacked(
 )
 ```
 
+![Example stacked plot](examples/stacked_plot.png)
+
 ## eQTL Overlay
 
 Add expression QTL data as a separate panel:
@@ -229,6 +237,30 @@ fig = plotter.plot_stacked(
 )
 ```
 
+![Example eQTL overlay plot](examples/eqtl_overlay.png)
+
+## Fine-mapping Visualization
+
+Visualize SuSiE or other fine-mapping results with credible set coloring:
+
+```python
+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)
+})
+
+fig = plotter.plot_stacked(
+    [gwas_df],
+    chrom=1, start=1000000, end=2000000,
+    finemapping_df=finemapping_df,
+    finemapping_cs_col="cs",
+    genes_df=genes_df,
+)
+```
+
+![Example fine-mapping plot](examples/finemapping_plot.png)
+
 ## PySpark Support
 
 For large-scale genomics data, pass PySpark DataFrames directly:
@@ -245,6 +277,47 @@ pandas_df = to_pandas(spark_gwas_df, sample_size=100000)
 
 Install PySpark support: `uv add pylocuszoom[spark]`
 
+## Loading Data from Files
+
+pyLocusZoom includes loaders for common GWAS, eQTL, and fine-mapping file formats:
+
+```python
+from pylocuszoom import (
+    # GWAS loaders
+    load_gwas,           # Auto-detect format
+    load_plink_assoc,    # PLINK .assoc, .assoc.linear, .qassoc
+    load_regenie,        # REGENIE .regenie
+    load_bolt_lmm,       # BOLT-LMM .stats
+    load_gemma,          # GEMMA .assoc.txt
+    load_saige,          # SAIGE output
+    # eQTL loaders
+    load_gtex_eqtl,      # GTEx significant pairs
+    load_eqtl_catalogue, # eQTL Catalogue format
+    # Fine-mapping loaders
+    load_susie,          # SuSiE output
+    load_finemap,        # FINEMAP .snp output
+    # Gene annotations
+    load_gtf,            # GTF/GFF3 files
+    load_bed,            # BED files
+)
+
+# Auto-detect GWAS format from filename
+gwas_df = load_gwas("results.assoc.linear")
+
+# Or use specific loader
+gwas_df = load_regenie("ukb_results.regenie")
+
+# Load gene annotations
+genes_df = load_gtf("genes.gtf", feature_type="gene")
+exons_df = load_gtf("genes.gtf", feature_type="exon")
+
+# Load eQTL data
+eqtl_df = load_gtex_eqtl("GTEx.signif_pairs.txt.gz", gene="BRCA1")
+
+# Load fine-mapping results
+fm_df = load_susie("susie_output.tsv")
+```
+
 ## Data Formats
 
 ### GWAS Results DataFrame
@@ -371,6 +444,13 @@ plotter = LocusZoomPlotter(log_level="DEBUG")
 Optional:
 - pyspark >= 3.0.0 (for PySpark DataFrame support) - `uv add pylocuszoom[spark]`
 
+## Documentation
+
+- [User Guide](docs/USER_GUIDE.md) - Comprehensive documentation with API reference
+- [Architecture](docs/ARCHITECTURE.md) - Design decisions and component overview
+- [Example Notebook](examples/getting_started.ipynb) - Interactive tutorial
+- [CHANGELOG](CHANGELOG.md) - Version history
+
 ## License
 
 GPL-3.0-or-later

{pylocuszoom-0.3.0 → pylocuszoom-0.5.0}/README.md

@@ -1,36 +1,41 @@
-# pyLocusZoom
-
 [![CI](https://github.com/michael-denyer/pyLocusZoom/actions/workflows/ci.yml/badge.svg)](https://github.com/michael-denyer/pyLocusZoom/actions/workflows/ci.yml)
-[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![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/)
 [![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
 
-Regional association plots for GWAS results with LD coloring, gene tracks, and recombination rate overlays.
+Publication-ready regional association plots with LD coloring, gene tracks, and recombination overlays.
 
 Inspired by [LocusZoom](http://locuszoom.org/) and [locuszoomr](https://github.com/myles-lewis/locuszoomr).
 
 ## Features
 
-- **LD coloring**: SNPs colored by linkage disequilibrium (R²) with lead variant
-- **Gene track**: Annotated gene/exon positions below the association plot
-- **Recombination rate**: Overlay showing recombination rate across region (*Canis lupus familiaris* only)
-- **SNP labels**: Automatic labeling of top SNPs with RS ID or nearest gene
-- **Species support**: Built-in *Canis lupus familiaris* (CanFam3.1/CanFam4), *Felis catus* (FelCat9), or custom species
-- **CanFam4 support**: Automatic coordinate liftover for recombination maps
-- **Multiple backends**: matplotlib (static), plotly (interactive), bokeh (dashboards)
-- **Stacked plots**: Compare multiple GWAS/phenotypes vertically
-- **eQTL overlay**: Expression QTL data as separate panel
-- **PySpark support**: Handles large-scale genomics DataFrames
+1. **Regional association plot**:
+
+    - **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
 
 ![Example regional association plot](examples/regional_plot.png)
 
+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
+
 ## Installation
 
 ```bash
@@ -146,13 +151,13 @@ fig.write_html("plot.html")
 fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000, backend="bokeh")
 ```
 
-| Backend | Output | Best For |
-|---------|--------|----------|
-| `matplotlib` | Static PNG/PDF/SVG | Publications, presentations |
-| `plotly` | Interactive HTML | Web reports, data exploration |
-| `bokeh` | Interactive HTML | Dashboards, web apps |
+| 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 |
 
-> **Note:** All backends support gene track, recombination overlay, and LD legend. SNP labels (auto-positioned with adjustText) are matplotlib-only.
+> **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.
 
 ## Stacked Plots
 
@@ -169,6 +174,8 @@ fig = plotter.plot_stacked(
 )
 ```
 
+![Example stacked plot](examples/stacked_plot.png)
+
 ## eQTL Overlay
 
 Add expression QTL data as a separate panel:
@@ -189,6 +196,30 @@ fig = plotter.plot_stacked(
 )
 ```
 
+![Example eQTL overlay plot](examples/eqtl_overlay.png)
+
+## Fine-mapping Visualization
+
+Visualize SuSiE or other fine-mapping results with credible set coloring:
+
+```python
+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)
+})
+
+fig = plotter.plot_stacked(
+    [gwas_df],
+    chrom=1, start=1000000, end=2000000,
+    finemapping_df=finemapping_df,
+    finemapping_cs_col="cs",
+    genes_df=genes_df,
+)
+```
+
+![Example fine-mapping plot](examples/finemapping_plot.png)
+
 ## PySpark Support
 
 For large-scale genomics data, pass PySpark DataFrames directly:
@@ -205,6 +236,47 @@ pandas_df = to_pandas(spark_gwas_df, sample_size=100000)
 
 Install PySpark support: `uv add pylocuszoom[spark]`
 
+## Loading Data from Files
+
+pyLocusZoom includes loaders for common GWAS, eQTL, and fine-mapping file formats:
+
+```python
+from pylocuszoom import (
+    # GWAS loaders
+    load_gwas,           # Auto-detect format
+    load_plink_assoc,    # PLINK .assoc, .assoc.linear, .qassoc
+    load_regenie,        # REGENIE .regenie
+    load_bolt_lmm,       # BOLT-LMM .stats
+    load_gemma,          # GEMMA .assoc.txt
+    load_saige,          # SAIGE output
+    # eQTL loaders
+    load_gtex_eqtl,      # GTEx significant pairs
+    load_eqtl_catalogue, # eQTL Catalogue format
+    # Fine-mapping loaders
+    load_susie,          # SuSiE output
+    load_finemap,        # FINEMAP .snp output
+    # Gene annotations
+    load_gtf,            # GTF/GFF3 files
+    load_bed,            # BED files
+)
+
+# Auto-detect GWAS format from filename
+gwas_df = load_gwas("results.assoc.linear")
+
+# Or use specific loader
+gwas_df = load_regenie("ukb_results.regenie")
+
+# Load gene annotations
+genes_df = load_gtf("genes.gtf", feature_type="gene")
+exons_df = load_gtf("genes.gtf", feature_type="exon")
+
+# Load eQTL data
+eqtl_df = load_gtex_eqtl("GTEx.signif_pairs.txt.gz", gene="BRCA1")
+
+# Load fine-mapping results
+fm_df = load_susie("susie_output.tsv")
+```
+
 ## Data Formats
 
 ### GWAS Results DataFrame
@@ -331,6 +403,13 @@ plotter = LocusZoomPlotter(log_level="DEBUG")
 Optional:
 - pyspark >= 3.0.0 (for PySpark DataFrame support) - `uv add pylocuszoom[spark]`
 
+## Documentation
+
+- [User Guide](docs/USER_GUIDE.md) - Comprehensive documentation with API reference
+- [Architecture](docs/ARCHITECTURE.md) - Design decisions and component overview
+- [Example Notebook](examples/getting_started.ipynb) - Interactive tutorial
+- [CHANGELOG](CHANGELOG.md) - Version history
+
 ## License
 
 GPL-3.0-or-later

{pylocuszoom-0.3.0 → pylocuszoom-0.5.0}/docs/ARCHITECTURE.md

@@ -129,14 +129,36 @@ flowchart LR
 
 All backends implement the `PlotBackend` protocol defined in `backends/base.py`:
 
-```python
-class PlotBackend(Protocol):
-    def create_figure(self, n_panels, height_ratios, figsize) -> Any
-    def create_scatter(self, ax, x, y, colors, sizes, hover_data, **kwargs) -> None
-    def create_line(self, ax, x, y, **kwargs) -> None
-    def add_annotation(self, ax, text, xy, **kwargs) -> None
-    def finalize(self, fig, **kwargs) -> Any
-    def save(self, fig, path, **kwargs) -> None
+```mermaid
+classDiagram
+    class PlotBackend {
+        <<Protocol>>
+        +create_figure()
+        +scatter()
+        +line()
+        +fill_between()
+        +axhline()
+        +set_xlabel()
+        +set_ylabel()
+        +add_ld_legend()
+    }
+
+    class MatplotlibBackend {
+        +fig: Figure
+        +ax: Axes
+    }
+
+    class PlotlyBackend {
+        +fig: go.Figure
+    }
+
+    class BokehBackend {
+        +fig: figure
+    }
+
+    PlotBackend <|.. MatplotlibBackend
+    PlotBackend <|.. PlotlyBackend
+    PlotBackend <|.. BokehBackend
 ```
 
 ## Module Responsibilities