dataeval-plots 0.0.1__tar.gz

dataeval_plots-0.0.1/.gitignore

@@ -0,0 +1,21 @@
+*venv*/
+__pycache__/
+dist/
+
+docs/build/
+docs/source/reference/autoapi
+docs/source/tutorials/notebooks/checkpoints/
+
+output/
+.coverage*
+
+.nox/
+.python-version
+
+# Used to store user customizable settings
+.settings
+
+# debug profiles
+.vscode/launch.json
+
+src/dataeval_plots/_version.py

dataeval_plots-0.0.1/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: dataeval-plots
+Version: 0.0.1
+Summary: DataEval companion package for plotting utilities
+Project-URL: Homepage, https://dataeval.ai/
+Project-URL: Repository, https://github.com/aria-ml/dataeval/
+Project-URL: Documentation, https://dataeval.readthedocs.io/
+Author-email: Andrew Weng <andrew.weng@ariacoustics.com>, Ryan Wood <ryan.wood@ariacoustics.com>, Shaun Jullens <shaun.jullens@ariacoustics.com>
+Maintainer-email: ARiA <dataeval@ariacoustics.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: <3.14,>=3.10
+Requires-Dist: numpy<2.3,>=1.24.2; python_version < '3.12'
+Requires-Dist: numpy<2.3,>=1.26.2; python_version >= '3.12'
+Provides-Extra: all
+Requires-Dist: altair>=5.0; extra == 'all'
+Requires-Dist: matplotlib>=3.7.1; extra == 'all'
+Requires-Dist: plotly>=5.0; extra == 'all'
+Requires-Dist: seaborn>=0.12; extra == 'all'
+Provides-Extra: altair
+Requires-Dist: altair>=5.0; extra == 'altair'
+Provides-Extra: matplotlib
+Requires-Dist: matplotlib>=3.7.1; extra == 'matplotlib'
+Provides-Extra: plotly
+Requires-Dist: plotly>=5.0; extra == 'plotly'
+Provides-Extra: seaborn
+Requires-Dist: matplotlib>=3.7.1; extra == 'seaborn'
+Requires-Dist: seaborn>=0.12; extra == 'seaborn'
+Description-Content-Type: text/markdown
+
+# DataEval Plots
+
+Multi-backend plotting utilities for DataEval outputs.
+
+## Installation
+
+```bash
+# Minimal - no plotting backend included
+pip install dataeval-plots
+
+# With matplotlib plotting (recommended)
+pip install dataeval-plots[matplotlib]
+
+# With multiple backends
+pip install dataeval-plots[matplotlib,plotly]
+
+# Everything
+pip install dataeval-plots[all]
+```
+
+For development:
+```bash
+pip install -e dataeval-plots[all]
+```
+
+## Available Backends
+
+| Backend | Status | Install With | Description |
+|---------|--------|--------------|-------------|
+| matplotlib | ✅ Default | `[matplotlib]` | Standard publication-quality plots |
+| seaborn | ✅ Available | `[seaborn]` | Statistical data visualization |
+| plotly | ✅ Available | `[plotly]` | Interactive web-based plots |
+| altair | ✅ Available | `[altair]` | Declarative visualization grammar |
+
+## Usage
+
+### Option 1: Import from dataeval-plots directly
+
+```python
+from dataeval_plots import plot
+from dataeval.metrics.bias import coverage
+
+result = coverage(embeddings)
+fig = plot(result, images=dataset, top_k=6)
+fig.savefig("coverage.png")
+```
+
+### Option 2: Import from dataeval core (convenience)
+
+```python
+from dataeval import plotting
+from dataeval.metrics.bias import coverage
+
+result = coverage(embeddings)
+fig = plotting.plot(result, images=dataset)
+```
+
+### Option 3: Set default backend
+
+```python
+from dataeval_plots import plot, set_default_backend
+
+# Set seaborn as default
+set_default_backend("seaborn")
+fig = plot(result, images=dataset)  # Uses seaborn
+
+# Override for a specific plot
+fig = plot(result, backend="matplotlib", images=dataset)
+```
+
+## Features
+
+- **Multi-backend architecture**: Support for matplotlib (default), seaborn, plotly, and altair
+- **Optional dependencies**: Install only the backends you need
+- **Clean separation**: Core dataeval has zero plotting dependencies
+- **Protocol-based design**: Loose coupling via structural typing (`Plottable` protocol)
+- **Extensible**: Easy to add new backends via `BasePlottingBackend` or custom outputs via `Plottable`
+- **Lazy loading**: Backends are only imported when first used
+- **Type safe**: Static type checking with mypy/pyright via `@runtime_checkable` protocols
+- **DRY architecture**: Centralized routing logic in `BasePlottingBackend`
+
+## Architecture
+
+The package uses a **protocol-based architecture** for loose coupling between dataeval and dataeval-plots:
+
+```
+dataeval/                           # Core package
+    outputs/
+        _bias.py                    # CoverageOutput, BalanceOutput, DiversityOutput
+        _stats.py                   # BaseStatsOutput
+        _workflows.py               # SufficiencyOutput
+        _drift.py                   # DriftMVDCOutput
+    plotting.py                     # Convenience hook to dataeval-plots
+
+dataeval-plots/                     # Separate plotting package
+    src/dataeval_plots/
+        __init__.py                 # Main plot() function
+        _registry.py                # Backend registry with lazy loading
+        protocols.py                # Protocol definitions (Plottable hierarchy)
+        backends/
+            _base.py                # BasePlottingBackend (abstract routing)
+            _matplotlib.py          # MatplotlibBackend (default)
+            _seaborn.py             # SeabornBackend
+            _plotly.py              # PlotlyBackend
+            _altair.py              # AltairBackend
+```
+
+### Protocol-Based Design
+
+All DataEval output classes implement the `Plottable` protocol, which requires:
+
+- `plot_type()`: Returns a string identifying the plot type (e.g., "coverage", "balance")
+- `meta()`: Returns execution metadata
+
+This enables:
+
+- **Loose coupling**: dataeval-plots doesn't import concrete classes from dataeval
+- **Type safety**: Static and runtime type checking via `@runtime_checkable` protocols
+- **Extensibility**: Anyone can create custom outputs implementing `Plottable`
+- **Zero dependencies**: Core dataeval has no plotting dependencies
+
+## Supported Output Types
+
+| Output Type | Plot Type | Description | Source |
+|-------------|-----------|-------------|--------|
+| `CoverageOutput` | "coverage" | Image grid showing uncovered samples | [dataeval/_bias.py](../dataeval/src/dataeval/outputs/_bias.py) |
+| `BalanceOutput` | "balance" | Heatmap of class balance metrics | [dataeval/_bias.py](../dataeval/src/dataeval/outputs/_bias.py) |
+| `DiversityOutput` | "diversity" | Visualization of diversity indices | [dataeval/_bias.py](../dataeval/src/dataeval/outputs/_bias.py) |
+| `SufficiencyOutput` | "sufficiency" | Learning curves with extrapolation | [dataeval/_workflows.py](../dataeval/src/dataeval/outputs/_workflows.py) |
+| `BaseStatsOutput` | "base_stats" | Statistical histograms and distributions | [dataeval/_stats.py](../dataeval/src/dataeval/outputs/_stats.py) |
+| `DriftMVDCOutput` | "drift_mvdc" | Drift detection plots (MVDC analysis) | [dataeval/_drift.py](../dataeval/src/dataeval/outputs/_drift.py) |
+
+Each output type implements the `Plottable` protocol and can be plotted using any registered backend.
+
+## Extending the Package
+
+### Creating Custom Outputs
+
+You can create custom output classes that work with the plotting system by implementing the `Plottable` protocol:
+
+```python
+from dataclasses import dataclass
+from numpy.typing import NDArray
+from dataeval_plots.protocols import Plottable, ExecutionMetadata
+
+@dataclass
+class MyCustomOutput:
+    """Custom output that reuses existing plot type."""
+    uncovered_indices: NDArray
+
+    def plot_type(self) -> str:
+        return "coverage"  # Reuse existing coverage plotting
+
+    def meta(self) -> ExecutionMetadata:
+        return ExecutionMetadata.empty()
+
+# Works seamlessly with existing backends
+result = MyCustomOutput(uncovered_indices=my_data)
+fig = plot(result, images=my_images)
+```
+
+### Creating Custom Backends
+
+Extend `BasePlottingBackend` to create a new plotting backend:
+
+```python
+from dataeval_plots.backends._base import BasePlottingBackend
+from dataeval_plots.protocols import PlottableCoverage, PlottableBalance
+from dataeval_plots import register_backend
+
+class CustomBackend(BasePlottingBackend):
+    """Custom plotting backend using your preferred library."""
+
+    def _plot_coverage(self, output: PlottableCoverage, **kwargs):
+        # Implement coverage plotting
+        # Access output.uncovered_indices, etc.
+        return my_figure
+
+    def _plot_balance(self, output: PlottableBalance, **kwargs):
+        # Implement balance plotting
+        return my_figure
+
+    # Implement other _plot_* methods...
+
+# Register and use
+register_backend("custom", CustomBackend())
+fig = plot(result, backend="custom")
+```
+
+The `BasePlottingBackend` class handles all routing logic automatically - you just implement the plot-type-specific methods (`_plot_coverage`, `_plot_balance`, etc.).

dataeval_plots-0.0.1/README.md

@@ -0,0 +1,190 @@
+# DataEval Plots
+
+Multi-backend plotting utilities for DataEval outputs.
+
+## Installation
+
+```bash
+# Minimal - no plotting backend included
+pip install dataeval-plots
+
+# With matplotlib plotting (recommended)
+pip install dataeval-plots[matplotlib]
+
+# With multiple backends
+pip install dataeval-plots[matplotlib,plotly]
+
+# Everything
+pip install dataeval-plots[all]
+```
+
+For development:
+```bash
+pip install -e dataeval-plots[all]
+```
+
+## Available Backends
+
+| Backend | Status | Install With | Description |
+|---------|--------|--------------|-------------|
+| matplotlib | ✅ Default | `[matplotlib]` | Standard publication-quality plots |
+| seaborn | ✅ Available | `[seaborn]` | Statistical data visualization |
+| plotly | ✅ Available | `[plotly]` | Interactive web-based plots |
+| altair | ✅ Available | `[altair]` | Declarative visualization grammar |
+
+## Usage
+
+### Option 1: Import from dataeval-plots directly
+
+```python
+from dataeval_plots import plot
+from dataeval.metrics.bias import coverage
+
+result = coverage(embeddings)
+fig = plot(result, images=dataset, top_k=6)
+fig.savefig("coverage.png")
+```
+
+### Option 2: Import from dataeval core (convenience)
+
+```python
+from dataeval import plotting
+from dataeval.metrics.bias import coverage
+
+result = coverage(embeddings)
+fig = plotting.plot(result, images=dataset)
+```
+
+### Option 3: Set default backend
+
+```python
+from dataeval_plots import plot, set_default_backend
+
+# Set seaborn as default
+set_default_backend("seaborn")
+fig = plot(result, images=dataset)  # Uses seaborn
+
+# Override for a specific plot
+fig = plot(result, backend="matplotlib", images=dataset)
+```
+
+## Features
+
+- **Multi-backend architecture**: Support for matplotlib (default), seaborn, plotly, and altair
+- **Optional dependencies**: Install only the backends you need
+- **Clean separation**: Core dataeval has zero plotting dependencies
+- **Protocol-based design**: Loose coupling via structural typing (`Plottable` protocol)
+- **Extensible**: Easy to add new backends via `BasePlottingBackend` or custom outputs via `Plottable`
+- **Lazy loading**: Backends are only imported when first used
+- **Type safe**: Static type checking with mypy/pyright via `@runtime_checkable` protocols
+- **DRY architecture**: Centralized routing logic in `BasePlottingBackend`
+
+## Architecture
+
+The package uses a **protocol-based architecture** for loose coupling between dataeval and dataeval-plots:
+
+```
+dataeval/                           # Core package
+    outputs/
+        _bias.py                    # CoverageOutput, BalanceOutput, DiversityOutput
+        _stats.py                   # BaseStatsOutput
+        _workflows.py               # SufficiencyOutput
+        _drift.py                   # DriftMVDCOutput
+    plotting.py                     # Convenience hook to dataeval-plots
+
+dataeval-plots/                     # Separate plotting package
+    src/dataeval_plots/
+        __init__.py                 # Main plot() function
+        _registry.py                # Backend registry with lazy loading
+        protocols.py                # Protocol definitions (Plottable hierarchy)
+        backends/
+            _base.py                # BasePlottingBackend (abstract routing)
+            _matplotlib.py          # MatplotlibBackend (default)
+            _seaborn.py             # SeabornBackend
+            _plotly.py              # PlotlyBackend
+            _altair.py              # AltairBackend
+```
+
+### Protocol-Based Design
+
+All DataEval output classes implement the `Plottable` protocol, which requires:
+
+- `plot_type()`: Returns a string identifying the plot type (e.g., "coverage", "balance")
+- `meta()`: Returns execution metadata
+
+This enables:
+
+- **Loose coupling**: dataeval-plots doesn't import concrete classes from dataeval
+- **Type safety**: Static and runtime type checking via `@runtime_checkable` protocols
+- **Extensibility**: Anyone can create custom outputs implementing `Plottable`
+- **Zero dependencies**: Core dataeval has no plotting dependencies
+
+## Supported Output Types
+
+| Output Type | Plot Type | Description | Source |
+|-------------|-----------|-------------|--------|
+| `CoverageOutput` | "coverage" | Image grid showing uncovered samples | [dataeval/_bias.py](../dataeval/src/dataeval/outputs/_bias.py) |
+| `BalanceOutput` | "balance" | Heatmap of class balance metrics | [dataeval/_bias.py](../dataeval/src/dataeval/outputs/_bias.py) |
+| `DiversityOutput` | "diversity" | Visualization of diversity indices | [dataeval/_bias.py](../dataeval/src/dataeval/outputs/_bias.py) |
+| `SufficiencyOutput` | "sufficiency" | Learning curves with extrapolation | [dataeval/_workflows.py](../dataeval/src/dataeval/outputs/_workflows.py) |
+| `BaseStatsOutput` | "base_stats" | Statistical histograms and distributions | [dataeval/_stats.py](../dataeval/src/dataeval/outputs/_stats.py) |
+| `DriftMVDCOutput` | "drift_mvdc" | Drift detection plots (MVDC analysis) | [dataeval/_drift.py](../dataeval/src/dataeval/outputs/_drift.py) |
+
+Each output type implements the `Plottable` protocol and can be plotted using any registered backend.
+
+## Extending the Package
+
+### Creating Custom Outputs
+
+You can create custom output classes that work with the plotting system by implementing the `Plottable` protocol:
+
+```python
+from dataclasses import dataclass
+from numpy.typing import NDArray
+from dataeval_plots.protocols import Plottable, ExecutionMetadata
+
+@dataclass
+class MyCustomOutput:
+    """Custom output that reuses existing plot type."""
+    uncovered_indices: NDArray
+
+    def plot_type(self) -> str:
+        return "coverage"  # Reuse existing coverage plotting
+
+    def meta(self) -> ExecutionMetadata:
+        return ExecutionMetadata.empty()
+
+# Works seamlessly with existing backends
+result = MyCustomOutput(uncovered_indices=my_data)
+fig = plot(result, images=my_images)
+```
+
+### Creating Custom Backends
+
+Extend `BasePlottingBackend` to create a new plotting backend:
+
+```python
+from dataeval_plots.backends._base import BasePlottingBackend
+from dataeval_plots.protocols import PlottableCoverage, PlottableBalance
+from dataeval_plots import register_backend
+
+class CustomBackend(BasePlottingBackend):
+    """Custom plotting backend using your preferred library."""
+
+    def _plot_coverage(self, output: PlottableCoverage, **kwargs):
+        # Implement coverage plotting
+        # Access output.uncovered_indices, etc.
+        return my_figure
+
+    def _plot_balance(self, output: PlottableBalance, **kwargs):
+        # Implement balance plotting
+        return my_figure
+
+    # Implement other _plot_* methods...
+
+# Register and use
+register_backend("custom", CustomBackend())
+fig = plot(result, backend="custom")
+```
+
+The `BasePlottingBackend` class handles all routing logic automatically - you just implement the plot-type-specific methods (`_plot_coverage`, `_plot_balance`, etc.).

dataeval_plots-0.0.1/pyproject.toml

@@ -0,0 +1,146 @@
+[project]
+name = "dataeval-plots"
+dynamic = ["version"]
+description = "DataEval companion package for plotting utilities"
+authors = [
+  { name = "Andrew Weng", email = "andrew.weng@ariacoustics.com" },
+  { name = "Ryan Wood", email = "ryan.wood@ariacoustics.com" },
+  { name = "Shaun Jullens", email = "shaun.jullens@ariacoustics.com" },
+]
+requires-python = ">=3.10,<3.14"
+readme = "README.md"
+license = "MIT"
+maintainers = [
+  { name = "ARiA", email = "dataeval@ariacoustics.com" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering",
+]
+dependencies = [
+  "numpy>=1.24.2,<2.3; python_version<'3.12'",
+  "numpy>=1.26.2,<2.3; python_version>='3.12'",
+]
+
+[project.optional-dependencies]
+matplotlib = ["matplotlib>=3.7.1"]
+seaborn = ["matplotlib>=3.7.1", "seaborn>=0.12"]
+plotly = ["plotly>=5.0"]
+altair = ["altair>=5.0"]
+all = [
+  "matplotlib>=3.7.1",
+  "seaborn>=0.12",
+  "plotly>=5.0",
+  "altair>=5.0",
+]
+
+[dependency-groups]
+base = [
+  "nox>=2025.5.1",
+  "nox-uv>=0.6.2",
+  "uv>=0.8.0",
+]
+lint = [
+  { include-group = "base" },
+  "ruff>=0.11",
+  "codespell[toml]>=2.3",
+]
+test = [
+  { include-group = "base" },
+  "pytest>=8.3",
+  "pytest-cov>=6.1",
+  "coverage[toml]>=7.6",
+]
+type = [
+  { include-group = "base" },
+  "pyright[nodejs]>=1.1.400",
+]
+dev = [
+  { include-group = "base" },
+  { include-group = "lint" },
+  { include-group = "test" },
+  { include-group = "type" },
+]
+
+[project.urls]
+Homepage = "https://dataeval.ai/"
+Repository = "https://github.com/aria-ml/dataeval/"
+Documentation = "https://dataeval.readthedocs.io/"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/dataeval_plots"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dataeval_plots"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src/dataeval_plots" = "dataeval_plots"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/dataeval_plots/_version.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = [
+  "--pythonwarnings=ignore::DeprecationWarning",
+  "--verbose",
+]
+
+[tool.coverage.run]
+source = ["src/dataeval_plots"]
+branch = true
+
+[tool.coverage.report]
+exclude_also = [
+  "raise NotImplementedError",
+  ": \\.\\.\\.",
+  "_version.py",
+]
+include = ["*/src/dataeval_plots/*"]
+fail_under = 70
+
+[tool.codespell]
+skip = './*env*,./output,uv.lock'
+
+[tool.ruff]
+exclude = [
+  ".github",
+  ".vscode",
+  "*env*",
+  ".nox",
+]
+line-length = 120
+indent-width = 4
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["A", "ANN", "C4", "C90", "E", "F", "I", "NPY", "S", "SIM", "RET", "RUF100", "UP"]
+ignore = ["ANN401", "C901", "NPY002"]
+fixable = ["ALL"]
+unfixable = []
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+per-file-ignores = { "!src/*" = ["ANN", "S", "RET"]}
+
+[tool.ruff.lint.isort]
+known-first-party = ["dataeval_plots"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"

dataeval_plots-0.0.1/src/dataeval_plots/__init__.py

@@ -0,0 +1,56 @@
+"""Plotting backends for DataEval outputs."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from dataeval_plots._registry import get_backend, register_backend, set_default_backend
+from dataeval_plots.protocols import Plottable
+
+__all__ = ["plot", "register_backend", "set_default_backend", "get_backend"]
+
+
+def plot(output: Plottable, /, backend: str | None = None, **kwargs: Any) -> Any:
+    """
+    Plot any DataEval output object.
+
+    Parameters
+    ----------
+    output : Plottable
+        DataEval output object to visualize (must implement Plottable protocol)
+    backend : str or None, default None
+        Plotting backend ('matplotlib', 'seaborn', 'plotly', 'altair').
+        If None, uses default backend.
+    **kwargs
+        Backend-specific plotting parameters
+
+    Returns
+    -------
+    Figure
+        Backend-specific figure object
+
+    Raises
+    ------
+    ImportError
+        If backend dependencies are not installed
+    NotImplementedError
+        If plotting is not implemented for the given output type
+
+    Examples
+    --------
+    >>> from dataeval_plots import plot
+    >>> from dataeval.metrics.bias import coverage
+    >>> result = coverage(embeddings)
+    >>> fig = plot(result, images=dataset, top_k=6)
+    >>> fig.savefig("coverage.png")
+
+    >>> # Use a different backend
+    >>> plot(result, backend="seaborn", images=dataset)
+
+    >>> # Set default backend
+    >>> from dataeval_plots import set_default_backend
+    >>> set_default_backend("seaborn")
+    >>> plot(result, images=dataset)  # Uses seaborn
+    """
+    plotting_backend = get_backend(backend)
+    return plotting_backend.plot(output, **kwargs)