pylocuszoom 0.6.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

pylocuszoom/__init__.py

@@ -51,9 +51,19 @@ from .colors import (
     get_phewas_category_palette,
 )
 
+# Configuration classes (internal - use kwargs directly on plot()/plot_stacked())
+# from .config import PlotConfig, StackedPlotConfig  # Internal use only
+# 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 (
-    EQTLValidationError,
     calculate_colocalization_overlap,
     filter_eqtl_by_gene,
     filter_eqtl_by_region,
@@ -62,9 +72,19 @@ from .eqtl import (
     validate_eqtl_df,
 )
 
+# Exception hierarchy
+from .exceptions import (
+    BackendError,
+    DataDownloadError,
+    EQTLValidationError,
+    FinemappingValidationError,
+    LoaderValidationError,
+    PyLocusZoomError,
+    ValidationError,
+)
+
 # Fine-mapping/SuSiE support
 from .finemapping import (
-    FinemappingValidationError,
     filter_by_credible_set,
     filter_finemapping_by_region,
     get_credible_sets,
@@ -125,11 +145,8 @@ from .recombination import (
     load_recombination_map,
 )
 
-# Schema validation
-from .schemas import LoaderValidationError
-
 # Validation utilities
-from .utils import ValidationError, to_pandas
+from .utils import to_pandas
 
 __all__ = [
     # Core
@@ -178,8 +195,12 @@ __all__ = [
     # Logging
     "enable_logging",
     "disable_logging",
-    # Validation & Utils
+    # Exceptions
+    "PyLocusZoomError",
     "ValidationError",
+    "BackendError",
+    "DataDownloadError",
+    # Utils
     "to_pandas",
     # PheWAS
     "validate_phewas_df",
@@ -208,4 +229,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",
+]