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

pylocuszoom/__init__.py

@@ -34,14 +34,31 @@ Species Support:
     - Custom: User provides all reference data
 """
 
-__version__ = "0.3.0"
+__version__ = "0.6.0"
 
 # Main plotter class
 # Backend types
 from .backends import BackendType, get_backend
 
 # Colors and LD
-from .colors import LEAD_SNP_COLOR, get_ld_bin, get_ld_color, get_ld_color_palette
+from .colors import (
+    LEAD_SNP_COLOR,
+    PHEWAS_CATEGORY_COLORS,
+    get_ld_bin,
+    get_ld_color,
+    get_ld_color_palette,
+    get_phewas_category_color,
+    get_phewas_category_palette,
+)
+
+# Ensembl integration
+from .ensembl import (
+    clear_ensembl_cache,
+    fetch_exons_from_ensembl,
+    fetch_genes_from_ensembl,
+    get_ensembl_species_name,
+    get_genes_for_region,
+)
 
 # eQTL support
 from .eqtl import (
@@ -65,6 +82,9 @@ from .finemapping import (
     validate_finemapping_df,
 )
 
+# Forest plot support
+from .forest import validate_forest_df
+
 # Gene track
 from .gene_track import get_nearest_gene, plot_gene_track
 
@@ -101,6 +121,9 @@ from .loaders import (
 
 # Logging configuration
 from .logging import disable_logging, enable_logging
+
+# PheWAS support
+from .phewas import validate_phewas_df
 from .plotter import LocusZoomPlotter
 
 # Reference data management
@@ -130,7 +153,10 @@ __all__ = [
     "get_ld_color",
     "get_ld_bin",
     "get_ld_color_palette",
+    "get_phewas_category_color",
+    "get_phewas_category_palette",
     "LEAD_SNP_COLOR",
+    "PHEWAS_CATEGORY_COLORS",
     # Gene track
     "get_nearest_gene",
     "plot_gene_track",
@@ -164,6 +190,10 @@ __all__ = [
     # Validation & Utils
     "ValidationError",
     "to_pandas",
+    # PheWAS
+    "validate_phewas_df",
+    # Forest plot
+    "validate_forest_df",
     # GWAS loaders
     "load_gwas",
     "load_plink_assoc",
@@ -187,4 +217,10 @@ __all__ = [
     "load_ensembl_genes",
     # Schema validation
     "LoaderValidationError",
+    # Ensembl integration
+    "get_genes_for_region",
+    "fetch_genes_from_ensembl",
+    "fetch_exons_from_ensembl",
+    "get_ensembl_species_name",
+    "clear_ensembl_cache",
 ]

pylocuszoom/backends/__init__.py

@@ -1,18 +1,77 @@
 """Pluggable plotting backends for pyLocusZoom.
 
 Supports matplotlib (default), plotly, and bokeh backends.
+
+Backend Registration:
+    Backends are registered using the @register_backend decorator.
+    This enables extensibility without modifying core code.
+
+    @register_backend("custom")
+    class CustomBackend:
+        ...
+
+Fallback Behavior:
+    When an optional backend (plotly, bokeh) is requested but not installed,
+    get_backend() falls back to matplotlib with a warning. This ensures
+    code works even without optional dependencies.
 """
 
+import warnings
 from typing import Literal
 
 from .base import PlotBackend
-from .matplotlib_backend import MatplotlibBackend
 
 BackendType = Literal["matplotlib", "plotly", "bokeh"]
 
-_BACKENDS: dict[str, type[PlotBackend]] = {
-    "matplotlib": MatplotlibBackend,
-}
+# LaTeX to Unicode conversion table for interactive backends
+_LATEX_TO_UNICODE = [
+    (r"$-\log_{10}$ P", "-log10(P)"),
+    (r"$-\log_{10}$", "-log10"),
+    (r"\log_{10}", "log10"),
+    (r"$r^2$", "r"),
+    (r"$R^2$", "R"),
+]
+
+
+def convert_latex_to_unicode(label: str) -> str:
+    """Convert LaTeX-style labels to Unicode for display in interactive backends.
+
+    Args:
+        label: Label text possibly containing LaTeX notation.
+
+    Returns:
+        Label with LaTeX converted to Unicode characters.
+    """
+    for latex, unicode_str in _LATEX_TO_UNICODE:
+        if latex in label:
+            label = label.replace(latex, unicode_str)
+    return label.replace("$", "")
+
+
+# Backend registry - populated by @register_backend decorator
+_BACKENDS: dict[str, type[PlotBackend]] = {}
+
+
+def register_backend(name: str):
+    """Decorator to register a backend class.
+
+    Args:
+        name: Backend name (e.g., "matplotlib", "plotly", "bokeh").
+
+    Returns:
+        Decorator function that registers the class.
+
+    Example:
+        @register_backend("custom")
+        class CustomBackend:
+            ...
+    """
+
+    def decorator(cls: type[PlotBackend]) -> type[PlotBackend]:
+        _BACKENDS[name] = cls
+        return cls
+
+    return decorator
 
 
 def get_backend(name: BackendType) -> PlotBackend:
@@ -25,24 +84,64 @@ def get_backend(name: BackendType) -> PlotBackend:
         Instantiated backend.
 
     Raises:
-        ValueError: If backend name is invalid.
-        ImportError: If backend dependencies are not installed.
-    """
-    if name == "plotly":
-        from .plotly_backend import PlotlyBackend
+        ValueError: If backend name is completely unknown.
 
-        _BACKENDS["plotly"] = PlotlyBackend
-    elif name == "bokeh":
-        from .bokeh_backend import BokehBackend
+    Note:
+        When optional backends (plotly, bokeh) are unavailable,
+        falls back to matplotlib with a UserWarning.
+    """
+    # Ensure matplotlib is always registered (it's always available)
+    if "matplotlib" not in _BACKENDS:
+        from .matplotlib_backend import MatplotlibBackend  # noqa: F401
 
-        _BACKENDS["bokeh"] = BokehBackend
+    # Try lazy import for optional backends
+    if name not in _BACKENDS:
+        if name == "plotly":
+            try:
+                from .plotly_backend import PlotlyBackend  # noqa: F401
+            except ImportError:
+                warnings.warn(
+                    "Plotly not installed, falling back to matplotlib. "
+                    "Install plotly with: pip install plotly",
+                    UserWarning,
+                    stacklevel=2,
+                )
+                name = "matplotlib"
+        elif name == "bokeh":
+            try:
+                from .bokeh_backend import BokehBackend  # noqa: F401
+            except ImportError:
+                warnings.warn(
+                    "Bokeh not installed, falling back to matplotlib. "
+                    "Install bokeh with: pip install bokeh",
+                    UserWarning,
+                    stacklevel=2,
+                )
+                name = "matplotlib"
 
     if name not in _BACKENDS:
-        raise ValueError(
-            f"Unknown backend: {name}. Available: matplotlib, plotly, bokeh"
-        )
+        available = list(_BACKENDS.keys())
+        raise ValueError(f"Unknown backend: {name}. Available: {available}")
 
     return _BACKENDS[name]()
 
 
-__all__ = ["PlotBackend", "BackendType", "get_backend", "MatplotlibBackend"]
+# Lazy import for backward compatibility - MatplotlibBackend available at module level
+# The actual registration happens when matplotlib_backend is imported
+def __getattr__(name: str):
+    """Lazy attribute access for backward compatibility."""
+    if name == "MatplotlibBackend":
+        from .matplotlib_backend import MatplotlibBackend
+
+        return MatplotlibBackend
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "PlotBackend",
+    "BackendType",
+    "get_backend",
+    "register_backend",
+    "MatplotlibBackend",
+    "convert_latex_to_unicode",
+]