lazy-visual 0.1.0__tar.gz

lazy_visual-0.1.0/.github/workflows/baseline.yml

@@ -0,0 +1,29 @@
+name: Generate golden baselines
+on:
+  workflow_dispatch:
+permissions:
+  contents: write
+jobs:
+  gen:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install numpy scipy pandas matplotlib pytest pytest-mpl .
+      - name: Generate baselines
+        run: python -m pytest tests/test_golden.py --mpl --mpl-generate-path=tests/baseline -q
+      - name: Commit and push
+        run: |
+          git config user.name  'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
+          git add tests/baseline/
+          git diff --cached --quiet && echo 'no changes' || \
+            git commit -m 'ci: regenerate golden baselines (Linux + latest mpl)'
+          git push

lazy_visual-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.10", "3.12", "3.13"]
+        deps: ["min", "last"]
+        exclude:
+          # 3.12 and 3.13 have no wheels for numpy 1.24 / pandas 1.5 / mpl 3.7
+          - python: "3.12"
+            deps: "min"
+          - python: "3.13"
+            deps: "min"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install min deps
+        if: matrix.deps == 'min'
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install "numpy==1.24.*" "scipy==1.10.*" "pandas==1.5.*" "matplotlib==3.7.*" pytest
+      - name: Install latest deps
+        if: matrix.deps == 'last'
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install numpy scipy pandas matplotlib pytest pytest-mpl
+      - name: Install package
+        shell: bash
+        run: python -m pip install -e .
+      - name: Run tests (golden on ubuntu + py3.12 + latest deps)
+        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.12' && matrix.deps == 'last'
+        shell: bash
+        run: python -m pytest -q --mpl --mpl-baseline-path=tests/baseline
+      - name: Run tests (skip golden)
+        if: matrix.os != 'ubuntu-latest' || matrix.python != '3.12' || matrix.deps != 'last'
+        shell: bash
+        run: python -m pytest -q --deselect tests/test_golden.py

lazy_visual-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,23 @@
+name: Docs
+on:
+  push:
+    branches: [main]
+    paths: ["docs/**", "mkdocs.yml", "lazy_visual/**", ".github/workflows/docs.yml"]
+  workflow_dispatch:
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: |
+          python -m pip install --upgrade pip
+          python -m pip install mkdocs-material 'mkdocstrings[python]' .
+      - run: mkdocs build --strict
+      - uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site

lazy_visual-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+.venv/
+venv/
+*.png
+*.csv
+.DS_Store
+
+!tests/baseline/*.png

lazy_visual-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+First public release.
+
+### Added
+
+- `scatterplot`, `distribution`, `box`, `violin`, `raincloud`, `heatmap`, `upset`, `roc`
+- `lv.load` (csv/tsv/parquet/excel/json + URL)
+- 4 themes: default, nature, apa, dark
+- Built-in stats: Mann-Whitney U, Welch t-test, Kruskal-Wallis, Holm correction, Cohen's d, KDE, DeLong & bootstrap AUC CI
+- Error codes LV-E101..E310, LV-W501..W504

lazy_visual-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,8 @@
+# Contributing
+
+1. `pip install -e .[dev]`
+2. `pytest -q`
+3. `ruff check lazy_visual/`
+4. `mypy --config-file mypy.ini lazy_visual/`
+
+Keep `lazy_visual/plots/` and `lazy_visual/stats/` free of matplotlib imports; `stats/` must not know about plots.

lazy_visual-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 lazy-visual contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

lazy_visual-0.1.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.5
+Name: lazy-visual
+Version: 0.1.0
+Summary: One-line statistical plots with built-in stats.
+Author: lazy-visual contributors
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=1.10
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-benchmark; extra == 'dev'
+Requires-Dist: pytest-mpl; extra == 'dev'
+Requires-Dist: pytest-socket; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: scikit-learn; extra == 'dev'
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.1; extra == 'excel'
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=10; extra == 'parquet'
+Description-Content-Type: text/markdown
+
+# lazy-visual
+
+One-line statistical plots.

lazy_visual-0.1.0/README.md

@@ -0,0 +1,3 @@
+# lazy-visual
+
+One-line statistical plots.

lazy_visual-0.1.0/docs/api.md

@@ -0,0 +1,3 @@
+# API reference
+
+::: lazy_visual

lazy_visual-0.1.0/docs/changelog.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+First public release.
+
+### Added
+
+- `scatterplot`, `distribution`, `box`, `violin`, `raincloud`, `heatmap`, `upset`, `roc`
+- `lv.load` (csv/tsv/parquet/excel/json + URL)
+- 4 themes: default, nature, apa, dark
+- Built-in stats: Mann-Whitney U, Welch t-test, Kruskal-Wallis, Holm correction, Cohen's d, KDE, DeLong & bootstrap AUC CI
+- Error codes LV-E101..E310, LV-W501..W504

lazy_visual-0.1.0/docs/errors.md

@@ -0,0 +1,28 @@
+# Error codes
+
+Format: `[LV-E101] message. Hint: ...`
+
+| Code | Class | Situation |
+|---|---|---|
+| LV-E101 | LvDataError | column not found |
+| LV-E102 | LvDataError | wrong dtype |
+| LV-E103 | LvDataError | empty after NaN drop |
+| LV-E104 | LvDataError | duplicate columns |
+| LV-E106 | LvDataError | y_true not binary |
+| LV-E107 | LvDataError | upset sets 2-20 |
+| LV-E108 | LvDataError | file not found |
+| LV-E109 | LvDataError | unsupported format |
+| LV-E110 | LvDataError | URL unreachable |
+| LV-E201 | LvArgumentError | out of range |
+| LV-E202 | LvArgumentError | wrong type |
+| LV-E203 | LvArgumentError | unknown theme |
+| LV-E204 | LvArgumentError | incompatible args |
+| LV-E205 | LvDataError | >30 groups |
+| LV-E301 | LvExportError | unsupported export |
+| LV-E302 | LvExportError | no write permission |
+| LV-E310 | LvArgumentError | backend unavailable |
+| LV-E401 | LvDependencyError | missing optional dep |
+| LV-W501 | LvDataWarning | NaN rows dropped |
+| LV-W502 | LvDataWarning | subsampled points |
+| LV-W503 | LvPerformanceWarning | large data |
+| LV-W504 | LvDataWarning | stats skipped |

lazy_visual-0.1.0/docs/gallery.md

@@ -0,0 +1,14 @@
+# Gallery
+
+Same df as Quickstart.
+
+```python
+lv.scatterplot(df, x="x", y="y", hue="group", fit="linear", save="scatter.png")
+lv.distribution(df, x="score", hue="group", kind="both", save="dist.png")
+lv.box(df, y="score", x="group", pairs=[("a","b"),("a","c")], save="box.png")
+lv.violin(df, y="score", x="group", save="violin.png")
+lv.raincloud(df, y="score", x="group", save="raincloud.png")
+lv.heatmap(df, corr="pearson", save="heatmap.png")
+lv.upset({"A":{1,2,3,4,5},"B":{3,4,5,6},"C":{4,5,6,7}}, save="upset.png")
+lv.roc(df, y_true="class", y_score=["s1","s2"], save="roc.png")
+```

lazy_visual-0.1.0/docs/index.md

@@ -0,0 +1,15 @@
+# lazy-visual
+
+One-line statistical plots with built-in stats.
+
+```python
+import lazy_visual as lv
+lv.raincloud(df, x="group", y="score", save="fig.svg")
+```
+
+- 8 plots: scatterplot, distribution, box, violin, raincloud, heatmap, upset, roc
+- Built-in stats: Mann-Whitney U, Welch, Kruskal-Wallis, Holm, Cohen's d, DeLong/bootstrap AUC CI
+- 4 themes: default, nature, apa, dark
+- Export PNG/SVG/PDF (atomic)
+
+MIT. Deps: numpy, scipy, pandas, matplotlib.

lazy_visual-0.1.0/docs/install.md

@@ -0,0 +1,7 @@
+# Install
+
+```bash
+pip install lazy-visual
+```
+
+Extras: `[parquet]`, `[excel]`. Python 3.10-3.13.

lazy_visual-0.1.0/docs/quickstart.md

@@ -0,0 +1,17 @@
+# Quickstart
+
+```python
+import numpy as np, pandas as pd, lazy_visual as lv
+rng = np.random.default_rng(0); n = 300
+df = pd.DataFrame({
+    "group": rng.choice(["a","b","c"], n),
+    "score": rng.normal(0,1,n) + rng.choice([0,1,2], n),
+    "x": rng.normal(0,1,n), "y": rng.normal(0,1,n),
+    "class": rng.choice([0,1], n),
+    "s1": rng.uniform(0,1,n), "s2": rng.uniform(0,1,n),
+})
+r = lv.raincloud(df, x="group", y="score", save="fig.svg")
+print(r)
+lv.set_options(random_state=42)
+lv.theme("nature")
+```

lazy_visual-0.1.0/docs/themes.md

@@ -0,0 +1,11 @@
+# Themes
+
+`default`, `nature`, `apa`, `dark`.
+
+```python
+lv.theme("nature")
+lv.raincloud(df, x="group", y="score")
+lv.raincloud(df, x="group", y="score", theme="dark")
+lv.raincloud(df, x="group", y="score",
+             theme={"name":"nature","font_size":8,"palette":"okabe"})
+```

lazy_visual-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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 + ">"