lazy-visual 0.1.0__py3-none-any.whl

lazy_visual/__init__.py

@@ -0,0 +1,82 @@
+"""lazy-visual: one-line statistical plots with built-in stats."""
+from __future__ import annotations
+
+from ._errors import (
+    LvArgumentError,
+    LvDataError,
+    LvDataWarning,
+    LvDependencyError,
+    LvError,
+    LvExportError,
+    LvPerformanceWarning,
+)
+from ._options import Options, get_options, set_options
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "LvArgumentError",
+    "LvDataError",
+    "LvDataWarning",
+    "LvDependencyError",
+    "LvError",
+    "LvExportError",
+    "LvPerformanceWarning",
+    "LvResult",
+    "Options",
+    "Theme",
+    "__version__",
+    "box",
+    "distribution",
+    "get_options",
+    "heatmap",
+    "load",
+    "raincloud",
+    "roc",
+    "scatterplot",
+    "set_options",
+    "theme",
+    "upset",
+    "violin",
+]
+
+
+def __getattr__(name: str):
+    """Lazy imports so `import lazy_visual` stays fast (NFR-1)."""
+    if name == "load":
+        from .io.loader import load
+        return load
+    if name == "theme":
+        from .core.style import theme
+        return theme
+    if name == "Theme":
+        from .core.style import Theme
+        return Theme
+    if name == "LvResult":
+        from .core.result import LvResult
+        return LvResult
+    if name == "scatterplot":
+        from .plots.scatter import scatterplot
+        return scatterplot
+    if name == "distribution":
+        from .plots.distribution import distribution
+        return distribution
+    if name == "box":
+        from .plots.box import box
+        return box
+    if name == "violin":
+        from .plots.violin import violin
+        return violin
+    if name == "raincloud":
+        from .plots.raincloud import raincloud
+        return raincloud
+    if name == "heatmap":
+        from .plots.heatmap import heatmap
+        return heatmap
+    if name == "upset":
+        from .plots.upset import upset
+        return upset
+    if name == "roc":
+        from .plots.roc import roc
+        return roc
+    raise AttributeError(f"module 'lazy_visual' has no attribute {name!r}")

lazy_visual/_errors.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import difflib
+from collections.abc import Iterable
+
+
+class LvError(Exception):
+    code: str = "LV-E000"
+
+    def __init__(self, message: str, *, code: str | None = None,
+                 hint: str | None = None) -> None:
+        self.code = code or self.code
+        self.message = message
+        self.hint = hint
+        super().__init__(self._format())
+
+    def _format(self) -> str:
+        base = f"[{self.code}] {self.message}"
+        if self.hint:
+            base += f" Hint: {self.hint}"
+        return base
+
+    def __str__(self) -> str:
+        return self._format()
+
+
+class LvDataError(LvError, ValueError):
+    code = "LV-E100"
+
+
+class LvArgumentError(LvError, ValueError):
+    code = "LV-E200"
+
+
+class LvExportError(LvError, OSError):
+    code = "LV-E300"
+
+
+class LvDependencyError(LvError, ImportError):
+    code = "LV-E401"
+
+
+class LvDataWarning(UserWarning):
+    pass
+
+
+class LvPerformanceWarning(UserWarning):
+    pass
+
+
+def _suggest(name: str, available: Iterable[str]) -> str | None:
+    m = difflib.get_close_matches(name, list(available), n=1, cutoff=0.6)
+    return m[0] if m else None
+
+
+def err_column_not_found(name: str, available: list) -> LvDataError:
+    hint = "column names are case-sensitive"
+    s = _suggest(name, available)
+    if s:
+        hint = f"did you mean '{s}'? {hint}"
+    return LvDataError(
+        f"Column '{name}' not found. Available: {', '.join(available)}.",
+        code="LV-E101", hint=hint)
+
+
+def err_wrong_dtype(name: str, expected: str, found: str) -> LvDataError:
+    return LvDataError(
+        f"Column '{name}' has invalid dtype '{found}', expected {expected}.",
+        code="LV-E102")
+
+
+def err_empty_after_nan(n_before: int, n_dropped: int) -> LvDataError:
+    return LvDataError(
+        f"No rows left after dropping NaNs "
+        f"(had {n_before}, dropped {n_dropped}).", code="LV-E103")
+
+
+def err_duplicate_columns(dupes: list) -> LvDataError:
+    return LvDataError(
+        f"Duplicate column names: {', '.join(dupes)}.",
+        code="LV-E104", hint="rename columns to be unique")
+
+
+def err_y_true_not_binary(classes: list) -> LvDataError:
+    return LvDataError(
+        f"y_true must have exactly 2 classes, found {len(classes)}: "
+        f"{classes}.", code="LV-E106")
+
+
+def err_upset_sets_count(n: int) -> LvDataError:
+    return LvDataError(f"upset requires 2-20 sets, got {n}.",
+                       code="LV-E107")
+
+
+def err_file_not_found(path: str) -> LvDataError:
+    return LvDataError(f"File not found or unreadable: {path}.",
+                       code="LV-E108")
+
+
+def err_unsupported_format(fmt: str) -> LvDataError:
+    return LvDataError(f"Unsupported file format: '{fmt}'.",
+                       code="LV-E109")
+
+
+def err_url_unreachable(url: str, reason: str) -> LvDataError:
+    return LvDataError(
+        f"URL unreachable or timed out: {url} ({reason}).",
+        code="LV-E110")
+
+
+def err_out_of_range(name: str, value: object,
+                     allowed: str) -> LvArgumentError:
+    return LvArgumentError(
+        f"Argument '{name}' = {value!r} is out of range. "
+        f"Allowed: {allowed}.", code="LV-E201")
+
+
+def err_wrong_arg_type(name: str, expected: str,
+                       got: str) -> LvArgumentError:
+    return LvArgumentError(
+        f"Argument '{name}' must be {expected}, got {got}.",
+        code="LV-E202")
+
+
+def err_unknown_theme(name: str, available: list) -> LvArgumentError:
+    return LvArgumentError(
+        f"Unknown theme/palette '{name}'. "
+        f"Available: {', '.join(available)}.", code="LV-E203")
+
+
+def err_incompatible_args(message: str) -> LvArgumentError:
+    return LvArgumentError(message, code="LV-E204")
+
+
+def err_too_many_groups(n: int, limit: int) -> LvDataError:
+    return LvDataError(
+        f"Too many groups on axis ({n} > {limit}).",
+        code="LV-E205", hint="reduce the number of categories")
+
+
+def err_export_format(fmt: str) -> LvExportError:
+    return LvExportError(
+        f"Unsupported export format '{fmt}'. Use png/svg/pdf.",
+        code="LV-E301")
+
+
+def err_no_write_permission(path: str) -> LvExportError:
+    return LvExportError(f"Cannot write to {path}.", code="LV-E302")
+
+
+def err_backend_unavailable(backend: str) -> LvArgumentError:
+    return LvArgumentError(
+        f"Backend '{backend}' is not available in this version.",
+        code="LV-E310", hint="only 'matplotlib' is supported in 0.1.0")
+
+
+def err_missing_dependency(pkg: str, extra: str) -> LvDependencyError:
+    return LvDependencyError(
+        f"Optional dependency '{pkg}' is missing. "
+        f"Install with: pip install lazy-visual[{extra}]",
+        code="LV-E401")

lazy_visual/_options.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from . import defaults
+from ._errors import err_out_of_range
+
+
+@dataclass
+class Options:
+    active_theme: str = "default"
+    random_state: int | None = defaults.RANDOM_STATE
+    max_points: int = defaults.MAX_POINTS
+    n_boot: int = defaults.N_BOOT
+
+_OPTIONS = Options()
+
+def get_options():
+    return _OPTIONS
+
+def set_options(*, random_state=defaults.RANDOM_STATE,
+                max_points=defaults.MAX_POINTS,
+                n_boot=defaults.N_BOOT, active_theme=None):
+    if max_points < 1:
+        raise err_out_of_range("max_points", max_points, ">= 1")
+    if not (defaults.N_BOOT_MIN <= n_boot <= defaults.N_BOOT_MAX):
+        raise err_out_of_range("n_boot", n_boot,
+            f"{defaults.N_BOOT_MIN}-{defaults.N_BOOT_MAX}")
+    _OPTIONS.random_state = random_state
+    _OPTIONS.max_points = int(max_points)
+    _OPTIONS.n_boot = int(n_boot)
+    if active_theme is not None:
+        _OPTIONS.active_theme = active_theme

lazy_visual/core/result.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+from .spec import PlotSpec
+
+
+@dataclass
+class LvResult:
+    fig: Any
+    ax: Any
+    spec: PlotSpec
+    stats: list[Any] = field(default_factory=list)
+    tables: dict[str, pd.DataFrame] = field(default_factory=dict)
+    files: list[Path] = field(default_factory=list)
+
+    def save(self, path: Any, *, fmt: Any = None,
+             dpi: Any = None) -> list[Path]:
+        from ..export import save_result
+        self.files = save_result(self.fig, path, fmt=fmt, dpi=dpi)
+        return self.files
+
+    def show(self) -> None:
+        import matplotlib.pyplot as plt
+        plt.show()
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "kind": self.spec.kind,
+            "stats": [
+                s.to_dict() if hasattr(s, "to_dict") else s.__dict__
+                for s in self.stats
+            ],
+            "files": [str(p) for p in self.files],
+        }
+
+    def __repr__(self) -> str:
+        head = f"<LvResult {self.spec.kind}"
+        if self.stats:
+            s = self.stats[0]
+            p = getattr(s, "p_value", None)
+            if p is not None:
+                ps = "p < 0.001" if p < 0.001 else f"p = {p:.3f}"
+                head += f", {getattr(s, 'method', '')} {ps}"
+        if self.files:
+            head += f", saved: {', '.join(p.name for p in self.files)}"
+        return head + ">"

lazy_visual/core/spec.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Layer:
+    geom: str
+    columns: dict[str, Any] = field(default_factory=dict)
+    style_overrides: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Annotation:
+    kind: str
+    text: str = ""
+    position: tuple[float, float] = (0.0, 0.0)
+    groups: tuple[str, ...] = ()
+    stat_ref: int | None = None
+
+
+@dataclass
+class AxesSpec:
+    xlabel: str | None = None
+    ylabel: str | None = None
+    title: str | None = None
+    xlim: tuple[float, float] | None = None
+    ylim: tuple[float, float] | None = None
+
+
+@dataclass
+class PlotSpec:
+    kind: str
+    panels: list[str] = field(default_factory=list)
+    layers: list[Layer] = field(default_factory=list)
+    annotations: list[Annotation] = field(default_factory=list)
+    axes: AxesSpec = field(default_factory=AxesSpec)
+    legend: bool = True
+    style: dict[str, Any] = field(default_factory=dict)

lazy_visual/core/style.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, replace
+from importlib import resources
+from typing import Any
+
+import matplotlib as mpl
+
+from .. import defaults
+from .._errors import (
+    err_out_of_range,
+    err_unknown_theme,
+    err_wrong_arg_type,
+)
+
+PALETTES: dict[str, list[Any]] = {
+    "okabe": ["#000000", "#E69F00", "#56B4E9", "#009E73",
+              "#F0E442", "#0072B2", "#D55E00", "#CC79A7"],
+    "tab10": [mpl.colormaps["tab10"](i / 10)
+              for i in range(10)],
+    "viridis": [mpl.colormaps["viridis"](x)
+                for x in (0.0, 0.15, 0.3, 0.45, 0.6, 0.75, 0.9)],
+    "gray": ["#111111", "#444444", "#777777", "#999999", "#bbbbbb"],
+}
+KNOWN_THEMES: tuple[str, ...] = ("default", "nature", "apa", "dark")
+
+
+@dataclass(frozen=True)
+class Theme:
+    name: str = "default"
+    font_family: tuple[str, ...] = ("DejaVu Sans",)
+    font_size: float = 10.0
+    palette: str = "tab10"
+    linewidth: float = 1.0
+    alpha: float = 0.85
+    grid: bool = True
+    spines: tuple[str, ...] = ("left", "bottom", "top", "right")
+    background: str = "white"
+    figsize: tuple[float, float] = (6.0, 4.0)
+    dpi: int = defaults.DPI_DEFAULT
+
+    def palette_colors(self) -> list[Any]:
+        p = self.palette
+        if isinstance(p, str) and p in PALETTES:
+            return list(PALETTES[p])
+        if isinstance(p, str):
+            try:
+                cmap = mpl.colormaps[p]
+            except KeyError:
+                return list(PALETTES["tab10"])
+            return [cmap(x) for x in (0.0, 0.2, 0.4, 0.6, 0.8)]
+        return list(PALETTES["tab10"])
+
+
+@dataclass(frozen=True)
+class StyleArgs:
+    color: str | None = None
+    palette: Any | None = None
+    alpha: float | None = None
+    linewidth: float | None = None
+    size: float | None = None
+    title: str | None = None
+    xlabel: str | None = None
+    ylabel: str | None = None
+    show_legend: bool = True
+    show_grid: bool | None = None
+    annotate: bool = True
+    figsize: tuple[float, float] | None = None
+    dpi: int | None = None
+    save: Any | None = None
+    fmt: Any | None = None
+    theme: Any | None = None
+    ax: Any | None = None
+    backend: str = "matplotlib"
+
+    def validate(self) -> None:
+        if self.alpha is not None and not (0.0 <= self.alpha <= 1.0):
+            raise err_out_of_range("alpha", self.alpha, "0-1")
+        if self.linewidth is not None and not (0.0 < self.linewidth <= 10.0):
+            raise err_out_of_range(
+                "linewidth", self.linewidth, "0 < lw <= 10")
+        if self.size is not None and not (self.size > 0):
+            raise err_out_of_range("size", self.size, "> 0")
+        if self.figsize is not None:
+            if len(self.figsize) != 2:
+                raise err_wrong_arg_type(
+                    "figsize", "tuple of 2 floats", str(self.figsize))
+            for v in self.figsize:
+                if not (1 <= v <= 30):
+                    raise err_out_of_range(
+                        "figsize", self.figsize, "1-30 per side")
+        if self.dpi is not None and not (
+            defaults.DPI_MIN <= self.dpi <= defaults.DPI_MAX
+        ):
+            raise err_out_of_range(
+                "dpi", self.dpi,
+                f"{defaults.DPI_MIN}-{defaults.DPI_MAX}")
+        if self.backend != "matplotlib":
+            from .._errors import err_backend_unavailable
+            raise err_backend_unavailable(self.backend)
+
+
+def _theme_from_dict(d: dict[str, Any]) -> Theme:
+    known = set(Theme.__dataclass_fields__)
+    kwargs: dict[str, Any] = {k: v for k, v in d.items() if k in known}
+    if "font_family" in kwargs:
+        kwargs["font_family"] = tuple(kwargs["font_family"])
+    if "spines" in kwargs:
+        kwargs["spines"] = tuple(kwargs["spines"])
+    if "figsize" in kwargs:
+        kwargs["figsize"] = tuple(kwargs["figsize"])
+    return Theme(**kwargs)
+
+
+def _load_builtin(name: str) -> Theme:
+    if name not in KNOWN_THEMES:
+        raise err_unknown_theme(name, list(KNOWN_THEMES))
+    try:
+        data = resources.files("lazy_visual.themes").joinpath(
+            f"{name}.json").read_text("utf-8")
+        return _theme_from_dict(json.loads(data))
+    except (FileNotFoundError, ModuleNotFoundError):
+        return Theme(name=name)
+
+
+_BUILTIN_CACHE: dict[str, Theme] = {}
+
+
+def get_theme(name: str) -> Theme:
+    if name not in _BUILTIN_CACHE:
+        _BUILTIN_CACHE[name] = _load_builtin(name)
+    return _BUILTIN_CACHE[name]
+
+
+def theme(name: str = "default", **overrides: Any) -> Theme:
+    base = get_theme(name)
+    if overrides:
+        base = replace(base, **{
+            k: v for k, v in overrides.items()
+            if k in Theme.__dataclass_fields__
+        })
+    return base
+
+
+def resolve(style: StyleArgs) -> tuple[Theme, StyleArgs]:
+    from .._options import get_options
+    if style.theme is None:
+        t = get_theme(get_options().active_theme)
+    elif isinstance(style.theme, str):
+        t = get_theme(style.theme)
+    elif isinstance(style.theme, dict):
+        base_name = style.theme.get("name", get_options().active_theme)
+        base = get_theme(base_name)
+        merged = {**base.__dict__, **style.theme}
+        t = _theme_from_dict(merged)
+    elif isinstance(style.theme, Theme):
+        t = style.theme
+    else:
+        raise err_wrong_arg_type(
+            "theme", "str, dict or Theme",
+            type(style.theme).__name__)
+    return t, style
+
+
+def apply_mpl_theme(t: Theme) -> None:
+    available = {f.name for f in mpl.font_manager.fontManager.ttflist}
+    fams = [f for f in t.font_family if f in available] or ["DejaVu Sans"]
+    mpl.rcParams["font.family"] = fams
+    mpl.rcParams["font.size"] = t.font_size
+    mpl.rcParams["axes.grid"] = t.grid
+    mpl.rcParams["axes.facecolor"] = t.background
+    mpl.rcParams["figure.facecolor"] = t.background
+    for side in ("left", "bottom", "top", "right"):
+        mpl.rcParams[f"axes.spines.{side}"] = side in t.spines
+    mpl.rcParams["svg.fonttype"] = "none"
+    mpl.rcParams["pdf.fonttype"] = 42

lazy_visual/defaults.py

@@ -0,0 +1,14 @@
+RANDOM_STATE = 0
+MAX_POINTS = 5000
+N_BOOT = 1000
+MAX_GROUPS = 30
+UPSET_TOP_N = 30
+MAX_SETS = 20
+MAX_MODELS = 8
+HEATMAP_ANNOT_LIMIT = 30
+URL_TIMEOUT_S = 30
+PERF_WARN_ROWS = 1_000_000
+DPI_DEFAULT = 150
+DPI_SAVE = 300
+DPI_MIN, DPI_MAX = 72, 1200
+N_BOOT_MIN, N_BOOT_MAX = 100, 10_000

lazy_visual/export.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+from ._errors import err_export_format, err_no_write_permission
+
+VALID_FMTS = {"png", "svg", "pdf"}
+
+def _resolve_targets(path, fmt):
+    items = list(path) if isinstance(path, (list, tuple)) else [path]
+    out = []
+    for p in items:
+        p = Path(p)
+        f = (fmt or p.suffix.lstrip(".") or "png").lower()
+        if f not in VALID_FMTS:
+            raise err_export_format(f)
+        if p.suffix.lower() != f".{f}":
+            p = p.with_suffix(f".{f}")
+        out.append((p, f))
+    return out
+
+def _atomic_save(fig, target, fmt, dpi):
+    target.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(suffix=f".{fmt}", dir=str(target.parent))
+    os.close(fd)
+    try:
+        extra = [a.get_legend() for a in fig.axes if a.get_legend()]
+        if extra:
+            fig.savefig(tmp, format=fmt, dpi=dpi,
+                        bbox_inches="tight",
+                        bbox_extra_artists=extra)
+        else:
+            fig.savefig(tmp, format=fmt, dpi=dpi, bbox_inches="tight")
+        os.replace(tmp, target)
+    except PermissionError as e:
+        try: os.unlink(tmp)
+        except OSError: pass
+        raise err_no_write_permission(str(target)) from e
+    except Exception:
+        try: os.unlink(tmp)
+        except OSError: pass
+        raise
+
+def save_result(fig, path, *, fmt=None, dpi=None):
+    targets = _resolve_targets(path, fmt)
+    files = []
+    for target, f in targets:
+        _atomic_save(fig, target, f, dpi)
+        files.append(target)
+    return files

lazy_visual/io/loader.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import io as _io
+import urllib.request
+from pathlib import Path
+
+import pandas as pd
+
+from .. import defaults
+from .._errors import (
+    LvPerformanceWarning,
+    err_file_not_found,
+    err_missing_dependency,
+    err_unsupported_format,
+    err_url_unreachable,
+)
+
+
+def _ext(path):
+    return Path(path).suffix.lower().lstrip(".")
+
+def _read_bytes(payload, fmt, read_kwargs):
+    buf = _io.BytesIO(payload)
+    if fmt == "csv":
+        return pd.read_csv(buf, **read_kwargs)
+    if fmt in ("tsv", "tab"):
+        return pd.read_csv(buf, sep="\t", **read_kwargs)
+    if fmt in ("parquet", "pq"):
+        try:
+            return pd.read_parquet(buf, **read_kwargs)
+        except ImportError as e:
+            raise err_missing_dependency("pyarrow", "parquet") from e
+    if fmt in ("xlsx", "xls"):
+        try:
+            return pd.read_excel(buf, **read_kwargs)
+        except ImportError as e:
+            raise err_missing_dependency("openpyxl", "excel") from e
+    if fmt == "json":
+        return pd.read_json(buf, **read_kwargs)
+    raise err_unsupported_format(fmt)
+
+def load(source, *, fmt=None, **read_kwargs):
+    if isinstance(source, pd.DataFrame):
+        return source
+    s = str(source)
+    if s.startswith(("http://", "https://")):
+        if fmt is None:
+            fmt = _ext(s.split("?")[0]) or "csv"
+        try:
+            with urllib.request.urlopen(s, timeout=defaults.URL_TIMEOUT_S) as r:
+                payload = r.read()
+        except Exception as e:
+            raise err_url_unreachable(s, str(e)) from e
+        return _read_bytes(payload, fmt, read_kwargs)
+    path = Path(s)
+    if not path.exists() or not path.is_file():
+        raise err_file_not_found(s)
+    size_mb = path.stat().st_size / (1024 * 1024)
+    if size_mb > 500:
+        import warnings
+        warnings.warn(f"[LV-W503] File is {size_mb:.0f} MB.",
+            LvPerformanceWarning, stacklevel=2)
+    fmt = fmt or _ext(s)
+    if fmt == "csv":
+        return pd.read_csv(path, **read_kwargs)
+    if fmt in ("tsv", "tab"):
+        return pd.read_csv(path, sep="\t", **read_kwargs)
+    if fmt in ("parquet", "pq"):
+        try:
+            return pd.read_parquet(path, **read_kwargs)
+        except ImportError as e:
+            raise err_missing_dependency("pyarrow", "parquet") from e
+    if fmt in ("xlsx", "xls"):
+        try:
+            return pd.read_excel(path, **read_kwargs)
+        except ImportError as e:
+            raise err_missing_dependency("openpyxl", "excel") from e
+    if fmt == "json":
+        return pd.read_json(path, **read_kwargs)
+    raise err_unsupported_format(fmt)