pylocuszoom 0.8.0__tar.gz → 1.0.0__tar.gz

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

@@ -44,7 +44,9 @@ jobs:
         run: uv sync --extra dev --extra all
 
       - name: Run tests
-        run: uv run pytest --cov=pylocuszoom --cov-report=term-missing
+        # Verbose shows pytest-randomly seed for reproduction
+        # To reproduce: pytest --randomly-seed=<seed>
+        run: uv run pytest -v
 
   build:
     runs-on: ubuntu-latest

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

@@ -58,6 +58,9 @@ jobs:
   update-bioconda:
     needs: publish
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
     steps:
       - uses: actions/checkout@v4
         with:
@@ -90,21 +93,71 @@ jobs:
 
           cat bioconda/meta.yaml
 
-      - name: Create Pull Request
+      - name: Create local PR for bioconda/meta.yaml
         uses: peter-evans/create-pull-request@v6
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
-          commit-message: "chore: update bioconda recipe for new release"
+          commit-message: "chore: update bioconda recipe for v${{ needs.publish.outputs.version }}"
           branch: bioconda-update
-          title: "Update bioconda recipe"
+          title: "Update bioconda recipe for v${{ needs.publish.outputs.version }}"
           body: |
             Automated update of bioconda/meta.yaml after PyPI release.
 
-            **Next steps:**
-            1. Review this PR
-            2. Merge to main
-            3. Copy `bioconda/meta.yaml` to your fork of bioconda-recipes
-            4. Submit PR to bioconda-recipes
+            This PR updates the local recipe. The bioconda-recipes PR is created automatically below.
           labels: |
             bioconda
             automated
+
+  submit-bioconda-pr:
+    needs: [publish, update-bioconda]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout bioconda-recipes fork
+        uses: actions/checkout@v4
+        with:
+          repository: michael-denyer/bioconda-recipes
+          token: ${{ secrets.BIOCONDA_PAT }}
+          path: bioconda-recipes
+
+      - name: Checkout pyLocusZoom
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          path: pylocuszoom
+
+      - name: Update recipe and create PR
+        env:
+          GH_TOKEN: ${{ secrets.BIOCONDA_PAT }}
+          PKG_VERSION: ${{ needs.publish.outputs.version }}
+        run: |
+          cd bioconda-recipes
+
+          # Sync fork with upstream
+          git remote add upstream https://github.com/bioconda/bioconda-recipes.git
+          git fetch upstream
+          git checkout master
+          git reset --hard upstream/master
+          git push origin master --force
+
+          # Create branch for this version
+          BRANCH="pylocuszoom-$PKG_VERSION"
+          git checkout -b "$BRANCH"
+
+          # Copy updated recipe
+          mkdir -p recipes/pylocuszoom
+          cp ../pylocuszoom/bioconda/meta.yaml recipes/pylocuszoom/meta.yaml
+
+          # Commit and push
+          git add recipes/pylocuszoom/meta.yaml
+          git commit -m "Update pylocuszoom to $PKG_VERSION"
+          git push -u origin "$BRANCH" --force
+
+          # Create PR to bioconda/bioconda-recipes
+          gh pr create \
+            --repo bioconda/bioconda-recipes \
+            --title "Update pylocuszoom to $PKG_VERSION" \
+            --body "Automated update of pylocuszoom to version $PKG_VERSION.
+
+          Changes: https://github.com/michael-denyer/pyLocusZoom/releases/tag/v$PKG_VERSION" \
+            --head "michael-denyer:$BRANCH" \
+            --base master || echo "PR may already exist"

{pylocuszoom-0.8.0 → pylocuszoom-1.0.0}/.pre-commit-config.yaml

@@ -10,7 +10,7 @@ repos:
     hooks:
       - id: pytest-cov
         name: pytest with coverage
-        entry: uv run python -m pytest -q
+        entry: uv run python -m pytest -n auto -q
         language: system
         types: [python]
         pass_filenames: false

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

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-01-28
+
+### Added
+- Unified exception hierarchy with `PyLocusZoomError` base class
+- Custom exceptions: `ValidationError`, `DownloadError`, `LiftoverError`, `DataError`, `PLINKError`, `ConfigurationError`
+- Internal Pydantic validation for plot parameters (validates kwargs at call time)
+- Error path tests for download failures and validation edge cases
+- CI ordering validation for forest plots (`ci_lower <= effect <= ci_upper`)
+- P-value validation warnings for NaN and out-of-range values
+- Vectorized eQTL/PheWAS scatter calls for better performance
+
+### Changed
+- All validation errors now raise `ValidationError` (also a `ValueError` for backward compatibility)
+- Test randomization enabled via pytest-randomly (visible in CI output)
+- Config classes (`PlotConfig`, `StackedPlotConfig`) are now internal implementation details, not part of public API
+- Capped pytest-xdist workers at 8 to prevent terminal issues
+
+### Fixed
+- Recombination overlay now uses correct twin axis for matplotlib (no longer distorts GWAS y-limits)
+- Mb formatting now applied to gene track axis for interactive backends (Plotly/Bokeh)
+- Gene track row assignment algorithm now correctly prevents overlapping genes in same row
+- Handle all-NaN p-values in stacked plot lead SNP detection
+- Replaced broad `except Exception` blocks with specific exception types (only 1 justified fallback remains)
+- Download error handling now catches specific HTTP/network errors
+
 ## [0.8.0] - 2026-01-28
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pylocuszoom
-Version: 0.8.0
+Version: 1.0.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
@@ -109,15 +109,14 @@ from pylocuszoom import LocusZoomPlotter
 # Initialize plotter (loads reference data for canine)
 plotter = LocusZoomPlotter(species="canine")
 
-# Create regional plot
+# Plot with parameters passed directly
 fig = plotter.plot(
-    gwas_df,                    # DataFrame with ps, p_wald, rs columns
+    gwas_df,                        # DataFrame with ps, p_wald, rs columns
     chrom=1,
     start=1000000,
     end=2000000,
-    lead_pos=1500000,           # Highlight lead SNP
+    lead_pos=1500000,               # Highlight lead SNP
 )
-
 fig.savefig("regional_plot.png", dpi=150)
 ```
 
@@ -137,9 +136,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 +144,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 +162,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 +173,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 +189,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 +206,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 +236,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 +258,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 +287,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,
@@ -414,7 +437,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 +539,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-0.8.0 → pylocuszoom-1.0.0}/README.md

@@ -64,15 +64,14 @@ from pylocuszoom import LocusZoomPlotter
 # Initialize plotter (loads reference data for canine)
 plotter = LocusZoomPlotter(species="canine")
 
-# Create regional plot
+# Plot with parameters passed directly
 fig = plotter.plot(
-    gwas_df,                    # DataFrame with ps, p_wald, rs columns
+    gwas_df,                        # DataFrame with ps, p_wald, rs columns
     chrom=1,
     start=1000000,
     end=2000000,
-    lead_pos=1500000,           # Highlight lead SNP
+    lead_pos=1500000,               # Highlight lead SNP
 )
-
 fig.savefig("regional_plot.png", dpi=150)
 ```
 
@@ -92,9 +91,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
@@ -102,6 +99,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
 )
 ```
 
@@ -118,6 +117,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")
 
@@ -127,10 +128,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,
 )
@@ -141,6 +144,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)
 
@@ -156,6 +161,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)
@@ -184,6 +191,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,
@@ -202,15 +213,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,
@@ -225,15 +242,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,
@@ -369,7 +392,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:
@@ -471,6 +494,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-0.8.0 → pylocuszoom-1.0.0}/bioconda/meta.yaml

@@ -1,5 +1,5 @@
 {% set name = "pylocuszoom" %}
-{% set version = "0.6.0" %}
+{% set version = "0.8.0" %}
 
 package:
   name: {{ name|lower }}
@@ -7,7 +7,7 @@ package:
 
 source:
   url: https://pypi.io/packages/source/{{ name[0] }}/{{ name }}/{{ name }}-{{ version }}.tar.gz
-  sha256: 1597c2080e2e32019293aab67836d1b944c1cc0b2fe3e7cd94e82d9119175742
+  sha256: cfca452d1dd34c0f6f8c837ef6b45a274bdd9d7e9ab248d67220b4aa830fed06
 
 build:
   noarch: python
@@ -46,7 +46,7 @@ about:
   home: https://github.com/michael-denyer/pylocuszoom
   license: GPL-3.0-or-later
   license_family: GPL3
-  license_file: LICENSE
+  license_file: LICENSE.md
   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: