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

pylocuszoom/recombination.py

@@ -42,7 +42,7 @@ def _normalize_build(build: Optional[str]) -> Optional[str]:
     if build is None:
         return None
     build_lower = build.lower().replace(".", "").replace("_", "")
-    if "canfam4" in build_lower or "uucfamgsd" in build_lower:
+    if any(x in build_lower for x in ("canfam4", "uucfamgsd")):
         return "canfam4"
     if "canfam3" in build_lower:
         return "canfam3"
@@ -158,9 +158,9 @@ def get_default_data_dir() -> Path:
     """Get default directory for recombination map data.
 
     Returns platform-appropriate cache directory:
-    - macOS: ~/Library/Caches/snp-scope-plot
-    - Linux: ~/.cache/snp-scope-plot
+    - macOS/Linux: ~/.cache/snp-scope-plot (or $XDG_CACHE_HOME if set)
     - Windows: %LOCALAPPDATA%/snp-scope-plot
+    - Databricks: /dbfs/FileStore/reference_data/recombination_maps
     """
     if os.name == "nt":  # Windows
         base = Path(os.environ.get("LOCALAPPDATA", Path.home()))
@@ -207,7 +207,7 @@ def download_canine_recombination_maps(
     # Check if already downloaded
     if output_path.exists() and not force:
         existing_files = list(output_path.glob("chr*_recomb.tsv"))
-        if len(existing_files) >= 38:  # 38 autosomes + X
+        if len(existing_files) >= 39:  # 38 autosomes + X
             return output_path
 
     # Create output directory

pylocuszoom/schemas.py

@@ -0,0 +1,395 @@
+"""Pydantic validation schemas for loaded data.
+
+Provides validation models for GWAS, eQTL, fine-mapping, and gene annotation
+DataFrames to ensure data quality before plotting.
+"""
+
+from pathlib import Path
+from typing import Optional, Union
+
+import pandas as pd
+from pydantic import BaseModel, ConfigDict, field_validator, model_validator
+
+
+class LoaderValidationError(Exception):
+    """Raised when loaded data fails validation."""
+
+    pass
+
+
+# =============================================================================
+# GWAS Validation
+# =============================================================================
+
+
+class GWASRowModel(BaseModel):
+    """Validation model for a single GWAS row."""
+
+    model_config = ConfigDict(extra="allow")
+
+    ps: int
+    p_wald: float
+    rs: Optional[str] = None
+    chr: Optional[Union[str, int]] = None
+
+    @field_validator("ps")
+    @classmethod
+    def position_positive(cls, v: int) -> int:
+        """Position must be positive."""
+        if v <= 0:
+            raise ValueError(f"Position must be positive, got {v}")
+        return v
+
+    @field_validator("p_wald")
+    @classmethod
+    def pvalue_in_range(cls, v: float) -> float:
+        """P-value must be between 0 and 1."""
+        if not (0 < v <= 1):
+            raise ValueError(f"P-value must be in range (0, 1], got {v}")
+        return v
+
+
+def validate_gwas_dataframe(
+    df: pd.DataFrame,
+    pos_col: str = "ps",
+    p_col: str = "p_wald",
+    rs_col: str = "rs",
+    strict: bool = False,
+) -> pd.DataFrame:
+    """Validate a GWAS DataFrame.
+
+    Args:
+        df: DataFrame to validate.
+        pos_col: Column name for position.
+        p_col: Column name for p-value.
+        rs_col: Column name for SNP ID.
+        strict: If True, validate every row. If False (default), validate schema only.
+
+    Returns:
+        Validated DataFrame.
+
+    Raises:
+        LoaderValidationError: If validation fails.
+    """
+    errors = []
+
+    # Check required columns exist
+    if pos_col not in df.columns:
+        errors.append(f"Missing required column: '{pos_col}'")
+    if p_col not in df.columns:
+        errors.append(f"Missing required column: '{p_col}'")
+
+    if errors:
+        raise LoaderValidationError(
+            "GWAS validation failed:\n  - " + "\n  - ".join(errors)
+        )
+
+    # Check data types
+    if not pd.api.types.is_numeric_dtype(df[pos_col]):
+        errors.append(f"Column '{pos_col}' must be numeric, got {df[pos_col].dtype}")
+
+    if not pd.api.types.is_numeric_dtype(df[p_col]):
+        errors.append(f"Column '{p_col}' must be numeric, got {df[p_col].dtype}")
+
+    # Check value ranges
+    if (df[pos_col] <= 0).any():
+        n_invalid = (df[pos_col] <= 0).sum()
+        errors.append(f"Column '{pos_col}' has {n_invalid} non-positive values")
+
+    if ((df[p_col] <= 0) | (df[p_col] > 1)).any():
+        n_invalid = ((df[p_col] <= 0) | (df[p_col] > 1)).sum()
+        errors.append(f"Column '{p_col}' has {n_invalid} values outside range (0, 1]")
+
+    # Check for NaN in required columns
+    if df[pos_col].isna().any():
+        n_na = df[pos_col].isna().sum()
+        errors.append(f"Column '{pos_col}' has {n_na} missing values")
+
+    if df[p_col].isna().any():
+        n_na = df[p_col].isna().sum()
+        errors.append(f"Column '{p_col}' has {n_na} missing values")
+
+    if errors:
+        raise LoaderValidationError(
+            "GWAS validation failed:\n  - " + "\n  - ".join(errors)
+        )
+
+    return df
+
+
+# =============================================================================
+# eQTL Validation
+# =============================================================================
+
+
+class EQTLRowModel(BaseModel):
+    """Validation model for a single eQTL row."""
+
+    model_config = ConfigDict(extra="allow")
+
+    pos: int
+    p_value: float
+    gene: str
+    effect: Optional[float] = None
+
+    @field_validator("pos")
+    @classmethod
+    def position_positive(cls, v: int) -> int:
+        """Position must be positive."""
+        if v <= 0:
+            raise ValueError(f"Position must be positive, got {v}")
+        return v
+
+    @field_validator("p_value")
+    @classmethod
+    def pvalue_in_range(cls, v: float) -> float:
+        """P-value must be between 0 and 1."""
+        if not (0 < v <= 1):
+            raise ValueError(f"P-value must be in range (0, 1], got {v}")
+        return v
+
+
+def validate_eqtl_dataframe(
+    df: pd.DataFrame,
+    strict: bool = False,
+) -> pd.DataFrame:
+    """Validate an eQTL DataFrame.
+
+    Args:
+        df: DataFrame to validate.
+        strict: If True, validate every row.
+
+    Returns:
+        Validated DataFrame.
+
+    Raises:
+        LoaderValidationError: If validation fails.
+    """
+    errors = []
+
+    # Check required columns
+    required = ["pos", "p_value", "gene"]
+    for col in required:
+        if col not in df.columns:
+            errors.append(f"Missing required column: '{col}'")
+
+    if errors:
+        raise LoaderValidationError(
+            "eQTL validation failed:\n  - " + "\n  - ".join(errors)
+        )
+
+    # Check data types and ranges
+    if not pd.api.types.is_numeric_dtype(df["pos"]):
+        errors.append(f"Column 'pos' must be numeric, got {df['pos'].dtype}")
+    elif (df["pos"] <= 0).any():
+        n_invalid = (df["pos"] <= 0).sum()
+        errors.append(f"Column 'pos' has {n_invalid} non-positive values")
+
+    if not pd.api.types.is_numeric_dtype(df["p_value"]):
+        errors.append(f"Column 'p_value' must be numeric, got {df['p_value'].dtype}")
+    elif ((df["p_value"] <= 0) | (df["p_value"] > 1)).any():
+        n_invalid = ((df["p_value"] <= 0) | (df["p_value"] > 1)).sum()
+        errors.append(f"Column 'p_value' has {n_invalid} values outside range (0, 1]")
+
+    if errors:
+        raise LoaderValidationError(
+            "eQTL validation failed:\n  - " + "\n  - ".join(errors)
+        )
+
+    return df
+
+
+# =============================================================================
+# Fine-mapping Validation
+# =============================================================================
+
+
+class FinemappingRowModel(BaseModel):
+    """Validation model for a single fine-mapping row."""
+
+    model_config = ConfigDict(extra="allow")
+
+    pos: int
+    pip: float
+    cs: Optional[int] = None
+
+    @field_validator("pos")
+    @classmethod
+    def position_positive(cls, v: int) -> int:
+        """Position must be positive."""
+        if v <= 0:
+            raise ValueError(f"Position must be positive, got {v}")
+        return v
+
+    @field_validator("pip")
+    @classmethod
+    def pip_in_range(cls, v: float) -> float:
+        """PIP must be between 0 and 1."""
+        if not (0 <= v <= 1):
+            raise ValueError(f"PIP must be in range [0, 1], got {v}")
+        return v
+
+
+def validate_finemapping_dataframe(
+    df: pd.DataFrame,
+    cs_col: str = "cs",
+    strict: bool = False,
+) -> pd.DataFrame:
+    """Validate a fine-mapping DataFrame.
+
+    Args:
+        df: DataFrame to validate.
+        cs_col: Column name for credible set.
+        strict: If True, validate every row.
+
+    Returns:
+        Validated DataFrame.
+
+    Raises:
+        LoaderValidationError: If validation fails.
+    """
+    errors = []
+
+    # Check required columns
+    if "pos" not in df.columns:
+        errors.append("Missing required column: 'pos'")
+    if "pip" not in df.columns:
+        errors.append("Missing required column: 'pip'")
+
+    if errors:
+        raise LoaderValidationError(
+            "Fine-mapping validation failed:\n  - " + "\n  - ".join(errors)
+        )
+
+    # Check data types and ranges
+    if not pd.api.types.is_numeric_dtype(df["pos"]):
+        errors.append(f"Column 'pos' must be numeric, got {df['pos'].dtype}")
+    elif (df["pos"] <= 0).any():
+        n_invalid = (df["pos"] <= 0).sum()
+        errors.append(f"Column 'pos' has {n_invalid} non-positive values")
+
+    if not pd.api.types.is_numeric_dtype(df["pip"]):
+        errors.append(f"Column 'pip' must be numeric, got {df['pip'].dtype}")
+    elif ((df["pip"] < 0) | (df["pip"] > 1)).any():
+        n_invalid = ((df["pip"] < 0) | (df["pip"] > 1)).sum()
+        errors.append(f"Column 'pip' has {n_invalid} values outside range [0, 1]")
+
+    if errors:
+        raise LoaderValidationError(
+            "Fine-mapping validation failed:\n  - " + "\n  - ".join(errors)
+        )
+
+    return df
+
+
+# =============================================================================
+# Gene Annotation Validation
+# =============================================================================
+
+
+class GeneRowModel(BaseModel):
+    """Validation model for a single gene annotation row."""
+
+    model_config = ConfigDict(extra="allow")
+
+    chr: Union[str, int]
+    start: int
+    end: int
+    gene_name: str
+    strand: Optional[str] = None
+
+    @field_validator("start", "end")
+    @classmethod
+    def position_positive(cls, v: int) -> int:
+        """Position must be positive."""
+        if v < 0:
+            raise ValueError(f"Position must be non-negative, got {v}")
+        return v
+
+    @model_validator(mode="after")
+    def start_before_end(self):
+        """Start must be <= end."""
+        if self.start > self.end:
+            raise ValueError(f"Start ({self.start}) must be <= end ({self.end})")
+        return self
+
+
+def validate_genes_dataframe(
+    df: pd.DataFrame,
+    strict: bool = False,
+) -> pd.DataFrame:
+    """Validate a genes DataFrame.
+
+    Args:
+        df: DataFrame to validate.
+        strict: If True, validate every row.
+
+    Returns:
+        Validated DataFrame.
+
+    Raises:
+        LoaderValidationError: If validation fails.
+    """
+    errors = []
+
+    # Check required columns
+    required = ["chr", "start", "end", "gene_name"]
+    for col in required:
+        if col not in df.columns:
+            errors.append(f"Missing required column: '{col}'")
+
+    if errors:
+        raise LoaderValidationError(
+            "Gene annotation validation failed:\n  - " + "\n  - ".join(errors)
+        )
+
+    # Check data types
+    if not pd.api.types.is_numeric_dtype(df["start"]):
+        errors.append(f"Column 'start' must be numeric, got {df['start'].dtype}")
+
+    if not pd.api.types.is_numeric_dtype(df["end"]):
+        errors.append(f"Column 'end' must be numeric, got {df['end'].dtype}")
+
+    # Check ranges
+    if (df["start"] < 0).any():
+        n_invalid = (df["start"] < 0).sum()
+        errors.append(f"Column 'start' has {n_invalid} negative values")
+
+    if (df["end"] < df["start"]).any():
+        n_invalid = (df["end"] < df["start"]).sum()
+        errors.append(f"Found {n_invalid} genes where end < start")
+
+    if errors:
+        raise LoaderValidationError(
+            "Gene annotation validation failed:\n  - " + "\n  - ".join(errors)
+        )
+
+    return df
+
+
+# =============================================================================
+# File Path Validation
+# =============================================================================
+
+
+def validate_file_path(filepath: Union[str, Path]) -> Path:
+    """Validate that a file path exists and is readable.
+
+    Args:
+        filepath: Path to validate.
+
+    Returns:
+        Validated Path object.
+
+    Raises:
+        LoaderValidationError: If file doesn't exist or isn't readable.
+    """
+    path = Path(filepath)
+
+    if not path.exists():
+        raise LoaderValidationError(f"File not found: {path}")
+
+    if not path.is_file():
+        raise LoaderValidationError(f"Not a file: {path}")
+
+    return path

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pylocuszoom
-Version: 0.2.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
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.10
+Requires-Dist: adjusttext>=0.8
 Requires-Dist: bokeh>=3.8.2
 Requires-Dist: kaleido>=0.2.0
 Requires-Dist: loguru>=0.7.0
@@ -26,63 +27,72 @@ 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: adjusttext>=0.8; 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>=7.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
-Provides-Extra: labels
-Requires-Dist: adjusttext>=0.8; extra == 'labels'
 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
+pip install pylocuszoom
+```
+
+Or with uv:
+
 ```bash
 uv add pylocuszoom
 ```
 
-Or with pip:
+Or with conda (Bioconda):
 
 ```bash
-pip install pylocuszoom
+conda install -c bioconda pylocuszoom
 ```
 
 ## Quick Start
@@ -165,20 +175,30 @@ fig = plotter.plot(
 )
 ```
 
-## Interactive Backends (Coming Soon)
+## Backends
 
-> **Note:** Interactive backends (plotly, bokeh) are planned but not yet fully integrated. Currently all plots use matplotlib.
+pyLocusZoom supports multiple rendering backends:
 
 ```python
-# Static publication-quality plot (default, currently only supported backend)
-plotter = LocusZoomPlotter(species="canine", backend="matplotlib")
-fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000)
+# Static publication-quality plot (default)
+fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000, backend="matplotlib")
 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")
+fig.write_html("plot.html")
+
+# Interactive Bokeh (dashboard-ready)
+fig = plotter.plot(gwas_df, chrom=1, start=1000000, end=2000000, backend="bokeh")
 ```
 
-Future releases will support:
-- **Plotly**: Interactive plots with hover tooltips, zoom/pan
-- **Bokeh**: Dashboard-friendly interactive plots
+| 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 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
 
@@ -195,6 +215,8 @@ fig = plotter.plot_stacked(
 )
 ```
 
+![Example stacked plot](examples/stacked_plot.png)
+
 ## eQTL Overlay
 
 Add expression QTL data as a separate panel:
@@ -215,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:
@@ -231,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
@@ -357,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