plotaviz 0.1.0__py3-none-any.whl

plotaviz/core/codegen.py

@@ -0,0 +1,482 @@
+"""Generate a standalone Python script that reproduces a chart.
+
+This is a headline feature, so the bar is specific: the emitted script must run on a machine that
+has never heard of PlotaViz. No ``import plotaviz`` anywhere, no helper module, no hidden state —
+just pandas plus one plotting library, the exact preprocessing steps that were applied, and the
+chart. Paste it into a notebook or a report pipeline and it works.
+
+The preprocessing steps write their own source (``Step.to_code``), so generated code cannot drift
+away from what the app actually did to the data.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from pathlib import Path
+
+from .errors import ExportError
+from .loader import read_code_for
+from .plotter import effective_spec, group_keys
+from .preprocess import Pipeline
+from .spec import MATRIX_CHARTS, ChartSpec
+
+#: Flavours the generator can emit.
+FLAVOURS: tuple[str, ...] = ("matplotlib", "plotly")
+
+_HEADER = '''"""{title}
+
+Generated by PlotaViz {version} on {timestamp}.
+
+This script is standalone — it does not import plotaviz. Run it with:
+
+    python {filename}
+
+Requirements: {requirements}
+"""
+
+from __future__ import annotations
+
+import argparse
+'''
+
+
+def generate(
+    spec: ChartSpec,
+    pipeline: Pipeline,
+    source_path: str | Path,
+    *,
+    flavour: str = "matplotlib",
+    version: str = "0.1.0",
+    output_image: str | None = None,
+) -> str:
+    """Emit a runnable script reproducing ``spec``.
+
+    Args:
+        spec: The chart to reproduce.
+        pipeline: The preprocessing steps that were applied, in order.
+        source_path: Path to the dataset the script should read.
+        flavour: ``"matplotlib"`` for static output or ``"plotly"`` for an interactive figure.
+        version: PlotaViz version, recorded in the header.
+        output_image: Default ``--save`` path baked into the script.
+
+    Returns:
+        The complete script as a string.
+
+    Raises:
+        ExportError: If ``flavour`` is not one of :data:`FLAVOURS`.
+    """
+    if flavour not in FLAVOURS:
+        raise ExportError(
+            f"Unknown code flavour {flavour!r}.", hint=f"Choose one of: {', '.join(FLAVOURS)}."
+        )
+    spec.validate()
+
+    source_path = Path(source_path)
+    filename = f"plot_{spec.chart}.py"
+    requirements = "pandas, matplotlib" if flavour == "matplotlib" else "pandas, plotly"
+
+    lines: list[str] = [
+        _HEADER.format(
+            title=spec.display_title(),
+            version=version,
+            timestamp=datetime.now(UTC).strftime("%Y-%m-%d %H:%M UTC"),
+            filename=filename,
+            requirements=requirements,
+        )
+    ]
+
+    lines.append("import pandas as pd")
+    if flavour == "matplotlib":
+        lines.append("import matplotlib.pyplot as plt")
+        if spec.chart in {"scatter", "kde"} or spec.chart in MATRIX_CHARTS:
+            lines.append("import numpy as np")
+    else:
+        lines.append("import plotly.express as px")
+        if spec.chart == "kde":
+            lines.append("import numpy as np")
+            lines.append("import plotly.graph_objects as go")
+
+    lines += [
+        "",
+        "",
+        "def load():",
+        '    """Read the source dataset."""',
+        f"    return {read_code_for(source_path)}",
+        "",
+        "",
+        "def preprocess(df):",
+        '    """Replay the exact cleaning steps PlotaViz applied."""',
+    ]
+
+    step_code = pipeline.to_code()
+    if step_code:
+        lines += [f"    {line}" if line else "" for line in step_code]
+    else:
+        lines.append("    # No cleaning steps were applied.")
+    lines += ["    return df", "", ""]
+
+    lines += _chart_function(spec, flavour)
+
+    lines += [
+        "",
+        "",
+        'if __name__ == "__main__":',
+        "    parser = argparse.ArgumentParser(description=__doc__)",
+        f"    parser.add_argument('--save', default={output_image!r}, "
+        "help='write the figure to this path instead of (only) showing it')",
+        "    parser.add_argument('--no-show', action='store_true', help='do not open a window')",
+        "    args = parser.parse_args()",
+        "",
+        "    df = preprocess(load())",
+        "    fig = build_chart(df)",
+        "",
+    ]
+    if flavour == "matplotlib":
+        lines += [
+            "    if args.save:",
+            "        fig.savefig(args.save, dpi=300, bbox_inches='tight')",
+            "        print(f'Saved {args.save}')",
+            "    if not args.no_show:",
+            "        plt.show()",
+        ]
+    else:
+        lines += [
+            "    if args.save:",
+            "        if args.save.endswith('.html'):",
+            "            fig.write_html(args.save)",
+            "        else:",
+            "            fig.write_image(args.save, scale=3)  # needs kaleido",
+            "        print(f'Saved {args.save}')",
+            "    if not args.no_show:",
+            "        fig.show()",
+        ]
+
+    return "\n".join(lines) + "\n"
+
+
+def _chart_function(spec: ChartSpec, flavour: str) -> list[str]:
+    """Emit the ``build_chart`` function body for one spec and flavour.
+
+    The chart body is written against the *effective* spec — the same one the live renderer uses
+    — so a counted bar chart plots the ``count`` column the aggregation just created rather than
+    a column that never existed.
+    """
+    eff = effective_spec(spec)
+    lines = [
+        "def build_chart(df):",
+        f'    """Build the {spec.chart} chart."""',
+    ]
+    lines += [f"    {line}" for line in _prepare_lines(spec, eff)]
+    lines.append("")
+    body = _plotly_body(eff) if flavour == "plotly" else _matplotlib_body(eff)
+    lines += [f"    {line}" if line else "" for line in body]
+    return lines
+
+
+def _prepare_lines(spec: ChartSpec, eff: ChartSpec) -> list[str]:
+    """Emit the aggregation/sorting the plotter would have done, so the script matches the app."""
+    lines: list[str] = []
+    if spec.chart in MATRIX_CHARTS:
+        lines.append("plot_df = df.select_dtypes('number')")
+        lines.append(
+            "plot_df = plot_df[[c for c in plot_df.columns if not str(c).endswith('__outlier')]]"
+        )
+        return lines
+
+    used = list(spec.columns_used)
+    lines.append(f"plot_df = df[{used!r}].dropna()")
+
+    if spec.agg:
+        keys = group_keys(spec.x, spec.color)
+        measure = eff.y
+        source_measure = spec.y
+        if spec.chart == "heatmap":
+            keys = group_keys(spec.x, spec.y)
+            measure = eff.color
+            source_measure = spec.color
+
+        if spec.agg == "count" or not source_measure:
+            lines.append(
+                f"plot_df = plot_df.groupby({keys!r}, observed=True).size()"
+                f".reset_index(name={measure!r})"
+            )
+        else:
+            lines.append(
+                f"plot_df = plot_df.groupby({keys!r}, observed=True)[{source_measure!r}]"
+                f".agg({spec.agg!r}).reset_index()"
+            )
+
+    if spec.chart in {"line", "area"} and eff.x:
+        lines.append(f"plot_df = plot_df.sort_values({eff.x!r})")
+    elif spec.chart in {"bar", "treemap", "pie"} and eff.y:
+        lines.append(f"plot_df = plot_df.sort_values({eff.y!r}, ascending=False)")
+
+    top_n = spec.options.get("top_n")
+    if top_n and spec.chart in {"bar", "treemap", "pie"}:
+        lines.append(f"plot_df = plot_df.head({int(top_n)})")
+
+    return lines
+
+
+def _plotly_body(spec: ChartSpec) -> list[str]:
+    """The Plotly call for one spec."""
+    title = spec.display_title()
+    x, y, color = spec.x, spec.y, spec.color
+    chart = spec.chart
+    lines: list[str] = []
+
+    if chart == "histogram":
+        lines.append(f"fig = px.histogram(plot_df, x={x!r}, color={color!r}, title={title!r})")
+    elif chart == "kde":
+        lines += [
+            f"values = pd.to_numeric(plot_df[{x!r}], errors='coerce').dropna().to_numpy()",
+            "bw = 0.9 * values.std(ddof=1) * len(values) ** (-1 / 5)",
+            "grid = np.linspace(values.min() - 3 * bw, values.max() + 3 * bw, 200)",
+            "z = (grid[:, None] - values[None, :]) / bw",
+            "density = np.exp(-0.5 * z ** 2).sum(axis=1) / (len(values) * bw * np.sqrt(2 * np.pi))",
+            "fig = go.Figure(go.Scatter(x=grid, y=density, fill='tozeroy', mode='lines'))",
+            f"fig.update_layout(title={title!r}, xaxis_title={x!r}, yaxis_title='density')",
+        ]
+    elif chart in {"bar", "grouped_bar", "stacked_bar"}:
+        barmode = "stack" if chart == "stacked_bar" or spec.options.get("stacked") else "group"
+        lines.append(
+            f"fig = px.bar(plot_df, x={x!r}, y={y!r}, color={color!r}, "
+            f"barmode={barmode!r}, title={title!r})"
+        )
+    elif chart == "pie":
+        lines.append(f"fig = px.pie(plot_df, names={x!r}, values={y!r}, title={title!r})")
+    elif chart == "treemap":
+        path = [color, x] if color else [x]
+        lines.append(f"fig = px.treemap(plot_df, path={path!r}, values={y!r}, title={title!r})")
+    elif chart == "scatter":
+        lines.append(
+            f"fig = px.scatter(plot_df, x={x!r}, y={y!r}, color={color!r}, "
+            f"opacity=0.75, title={title!r})"
+        )
+    elif chart == "line":
+        lines.append(f"fig = px.line(plot_df, x={x!r}, y={y!r}, color={color!r}, title={title!r})")
+    elif chart == "area":
+        lines.append(f"fig = px.area(plot_df, x={x!r}, y={y!r}, color={color!r}, title={title!r})")
+    elif chart == "box":
+        lines.append(
+            f"fig = px.box(plot_df, x={x!r}, y={y!r}, color={color!r}, "
+            f"points='outliers', title={title!r})"
+        )
+    elif chart == "violin":
+        lines.append(
+            f"fig = px.violin(plot_df, x={x!r}, y={y!r}, color={color!r}, "
+            f"box=True, title={title!r})"
+        )
+    elif chart == "heatmap":
+        value = color or y
+        lines += [
+            f"matrix = plot_df.pivot_table(index={y!r}, columns={x!r}, values={value!r})",
+            f"fig = px.imshow(matrix, aspect='auto', title={title!r})",
+        ]
+    elif chart == "correlation_heatmap":
+        lines += [
+            "corr = plot_df.corr(numeric_only=True)",
+            "fig = px.imshow(corr, zmin=-1, zmax=1, color_continuous_scale='RdBu_r', "
+            f"text_auto='.2f', aspect='auto', title={title!r})",
+        ]
+    elif chart == "pair_plot":
+        lines += [
+            "fig = px.scatter_matrix(plot_df, "
+            f"dimensions=list(plot_df.columns)[:6], title={title!r})",
+            "fig.update_traces(diagonal_visible=False, showupperhalf=False)",
+        ]
+
+    if spec.options.get("log_y"):
+        lines.append("fig.update_yaxes(type='log')")
+    if spec.options.get("log_x"):
+        lines.append("fig.update_xaxes(type='log')")
+
+    lines.append("fig.update_layout(template='plotly_white')")
+    lines.append("return fig")
+    return lines
+
+
+def _matplotlib_body(spec: ChartSpec) -> list[str]:
+    """The matplotlib calls for one spec."""
+    title = spec.display_title()
+    x, y, color = spec.x, spec.y, spec.color
+    chart = spec.chart
+    lines: list[str] = []
+
+    if chart == "pair_plot":
+        return [
+            "cols = list(plot_df.columns)[:5]",
+            "fig, axes = plt.subplots(len(cols), len(cols), figsize=(10, 8), squeeze=False)",
+            "for i, row_col in enumerate(cols):",
+            "    for j, col_col in enumerate(cols):",
+            "        ax = axes[i][j]",
+            "        if i == j:",
+            "            ax.hist(plot_df[row_col].dropna(), bins=20, color='#4C78A8')",
+            "        else:",
+            "            ax.scatter(plot_df[col_col], plot_df[row_col], s=6, alpha=0.5)",
+            "        if i == len(cols) - 1:",
+            "            ax.set_xlabel(col_col, fontsize=8)",
+            "        if j == 0:",
+            "            ax.set_ylabel(row_col, fontsize=8)",
+            f"fig.suptitle({title!r})",
+            "fig.tight_layout()",
+            "return fig",
+        ]
+
+    lines.append("fig, ax = plt.subplots(figsize=(10, 6))")
+
+    if chart == "histogram":
+        lines += [
+            f"ax.hist(pd.to_numeric(plot_df[{x!r}], errors='coerce').dropna(), "
+            "bins='auto', color='#4C78A8', edgecolor='white')",
+            "ax.set_ylabel('count')",
+        ]
+    elif chart == "kde":
+        lines += [
+            f"values = pd.to_numeric(plot_df[{x!r}], errors='coerce').dropna().to_numpy()",
+            "bw = 0.9 * values.std(ddof=1) * len(values) ** (-1 / 5)",
+            "grid = np.linspace(values.min() - 3 * bw, values.max() + 3 * bw, 200)",
+            "z = (grid[:, None] - values[None, :]) / bw",
+            "density = np.exp(-0.5 * z ** 2).sum(axis=1) / (len(values) * bw * np.sqrt(2 * np.pi))",
+            "ax.plot(grid, density, color='#4C78A8')",
+            "ax.fill_between(grid, density, alpha=0.3, color='#4C78A8')",
+            "ax.set_ylabel('density')",
+        ]
+    elif chart in {"bar", "grouped_bar", "stacked_bar"}:
+        stacked = chart == "stacked_bar" or bool(spec.options.get("stacked"))
+        if color:
+            lines += [
+                f"pivot = plot_df.pivot_table(index={x!r}, columns={color!r}, values={y!r})",
+                f"pivot.plot(kind='bar', stacked={stacked!r}, ax=ax, width=0.8)",
+                f"ax.legend(title={color!r}, fontsize=8)",
+            ]
+        elif y:
+            lines.append(f"ax.bar(plot_df[{x!r}].astype(str), plot_df[{y!r}], color='#4C78A8')")
+        else:
+            lines += [
+                f"counts = plot_df[{x!r}].value_counts()",
+                "ax.bar(counts.index.astype(str), counts.to_numpy(), color='#4C78A8')",
+                "ax.set_ylabel('count')",
+            ]
+        lines.append("ax.tick_params(axis='x', rotation=45)")
+    elif chart == "pie":
+        values = f"plot_df[{y!r}]" if y else f"plot_df[{x!r}].value_counts()"
+        lines.append(f"ax.pie({values}, labels=plot_df[{x!r}].astype(str), autopct='%1.1f%%')")
+    elif chart == "treemap":
+        lines += [
+            "# A simple slice-and-dice treemap; swap in the `squarify` package for nicer layout.",
+            "from matplotlib.patches import Rectangle",
+            f"pairs = list(zip(plot_df[{x!r}].astype(str), plot_df[{y!r}]))[:40]",
+            "total = sum(size for _, size in pairs) or 1",
+            "left, horizontal = 0.0, True",
+            "cmap = plt.get_cmap('tab20')",
+            "for i, (label, size) in enumerate(pairs):",
+            "    width = size / total",
+            "    ax.add_patch(Rectangle((left, 0), width, 1, facecolor=cmap(i % 20), "
+            "edgecolor='white'))",
+            "    if width > 0.06:",
+            "        ax.text(left + width / 2, 0.5, label, ha='center', va='center', fontsize=8)",
+            "    left += width",
+            "ax.set_xlim(0, 1); ax.set_ylim(0, 1); ax.axis('off')",
+        ]
+    elif chart == "scatter":
+        if color:
+            lines += [
+                f"for name, group in plot_df.groupby({color!r}, observed=True):",
+                f"    ax.scatter(group[{x!r}], group[{y!r}], s=14, alpha=0.7, label=str(name))",
+                f"ax.legend(title={color!r}, fontsize=8)",
+            ]
+        else:
+            lines.append(
+                f"ax.scatter(plot_df[{x!r}], plot_df[{y!r}], s=14, alpha=0.7, color='#4C78A8')"
+            )
+        if spec.options.get("trendline"):
+            lines += [
+                f"slope, intercept = np.polyfit(plot_df[{x!r}], plot_df[{y!r}], 1)",
+                f"line = np.linspace(plot_df[{x!r}].min(), plot_df[{x!r}].max(), 100)",
+                "ax.plot(line, slope * line + intercept, color='#E45756', linewidth=1.5)",
+            ]
+    elif chart in {"line", "area"}:
+        if color:
+            lines += [
+                f"for name, group in plot_df.groupby({color!r}, observed=True):",
+                f"    ax.plot(group[{x!r}], group[{y!r}], label=str(name), linewidth=1.6)",
+                f"ax.legend(title={color!r}, fontsize=8)",
+            ]
+        else:
+            lines.append(f"ax.plot(plot_df[{x!r}], plot_df[{y!r}], color='#4C78A8', linewidth=1.6)")
+            if chart == "area":
+                lines.append(
+                    f"ax.fill_between(plot_df[{x!r}], plot_df[{y!r}], alpha=0.3, color='#4C78A8')"
+                )
+        lines.append("fig.autofmt_xdate()")
+    elif chart in {"box", "violin"}:
+        lines += [
+            f"groups = [(str(k), g[{y!r}].dropna().to_numpy()) "
+            f"for k, g in plot_df.groupby({x!r}, observed=True)]"
+            if x
+            else f"groups = [({y!r}, plot_df[{y!r}].dropna().to_numpy())]",
+            "labels = [name for name, _ in groups]",
+            "values = [vals for _, vals in groups]",
+        ]
+        if chart == "violin":
+            lines += [
+                "ax.violinplot(values, showmedians=True)",
+                "ax.set_xticks(range(1, len(labels) + 1), labels)",
+            ]
+        else:
+            lines.append("ax.boxplot(values, tick_labels=labels)")
+        lines.append("ax.tick_params(axis='x', rotation=45)")
+    elif chart == "heatmap":
+        value = color or y
+        lines += [
+            f"matrix = plot_df.pivot_table(index={y!r}, columns={x!r}, values={value!r})",
+            "image = ax.imshow(matrix.to_numpy(dtype=float), aspect='auto', cmap='viridis')",
+            "ax.set_xticks(range(len(matrix.columns)), [str(c) for c in matrix.columns], "
+            "rotation=45, ha='right')",
+            "ax.set_yticks(range(len(matrix.index)), [str(i) for i in matrix.index])",
+            f"fig.colorbar(image, ax=ax, label={str(value)!r})",
+        ]
+    elif chart == "correlation_heatmap":
+        lines += [
+            "corr = plot_df.corr(numeric_only=True)",
+            "image = ax.imshow(corr.to_numpy(dtype=float), vmin=-1, vmax=1, cmap='RdBu_r')",
+            "ax.set_xticks(range(len(corr.columns)), list(corr.columns), rotation=45, ha='right')",
+            "ax.set_yticks(range(len(corr.index)), list(corr.index))",
+            "for i in range(len(corr.index)):",
+            "    for j in range(len(corr.columns)):",
+            "        ax.text(j, i, f'{corr.iat[i, j]:.2f}', ha='center', va='center', fontsize=8)",
+            "fig.colorbar(image, ax=ax, label='Pearson r')",
+        ]
+
+    if spec.options.get("log_y"):
+        lines.append("ax.set_yscale('log')")
+    if spec.options.get("log_x"):
+        lines.append("ax.set_xscale('log')")
+
+    lines.append(f"ax.set_title({title!r})")
+    if chart not in {"pie", "treemap", "heatmap", "correlation_heatmap"}:
+        if x:
+            lines.append(f"ax.set_xlabel({x!r})")
+        if y and chart not in {"histogram", "kde"}:
+            lines.append(f"ax.set_ylabel({y!r})")
+        lines.append("ax.grid(True, alpha=0.25, linestyle='--')")
+        lines.append("ax.set_axisbelow(True)")
+
+    lines += ["fig.tight_layout()", "return fig"]
+    return lines
+
+
+def write(path: str | Path, code: str) -> Path:
+    """Write generated code to disk.
+
+    Raises:
+        ExportError: If the file cannot be written.
+    """
+    target = Path(path).expanduser()
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(code, encoding="utf-8")
+    except OSError as exc:
+        raise ExportError(f"Could not write {target}.", hint=str(exc)) from exc
+    return target

plotaviz/core/errors.py

@@ -0,0 +1,65 @@
+"""Exception hierarchy for PlotaViz.
+
+Every error the user can plausibly trigger is one of these, and every one carries a message
+written for a human rather than a stack trace. The UI catches :class:`PlotaVizError` at the
+boundary and shows ``str(exc)`` in a dialog; nothing else should reach the user.
+"""
+
+from __future__ import annotations
+
+
+class PlotaVizError(Exception):
+    """Base class for all PlotaViz errors intended to be shown to the user.
+
+    Args:
+        message: Human-readable description of what went wrong.
+        hint: Optional suggestion for how to fix it, shown as secondary text.
+    """
+
+    def __init__(self, message: str, hint: str | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.hint = hint
+
+    def __str__(self) -> str:
+        return f"{self.message}\n\n{self.hint}" if self.hint else self.message
+
+
+class LoadError(PlotaVizError):
+    """A dataset could not be read — unsupported format, corrupt file, bad encoding."""
+
+
+class PreprocessError(PlotaVizError):
+    """A cleaning step could not be applied to the dataframe."""
+
+
+class ProfileError(PlotaVizError):
+    """The dataset could not be profiled (empty, or no usable columns)."""
+
+
+class SelectionError(PlotaVizError):
+    """No chart could be recommended for the given data shape."""
+
+
+class SpecError(PlotaVizError):
+    """A chart spec is malformed or references columns that do not exist."""
+
+
+class PlotError(PlotaVizError):
+    """A figure could not be built from a chart spec."""
+
+
+class ExportError(PlotaVizError):
+    """Writing an image, script, or session file failed."""
+
+
+class SessionError(PlotaVizError):
+    """A ``.pviz`` session file could not be read or is from an incompatible version."""
+
+
+class LLMError(PlotaVizError):
+    """An LLM provider failed. Always recoverable — the caller falls back to the local engine."""
+
+
+class ProviderNotConfigured(LLMError):
+    """No provider selected, or the selected provider has no API key in the keyring."""

plotaviz/core/exporter.py

@@ -0,0 +1,145 @@
+"""Static image export — PNG, SVG, PDF.
+
+Export always goes through matplotlib rather than the Plotly figure on screen. Plotly's static
+export needs the kaleido binary, which is another large dependency and another packaging problem;
+matplotlib is already present, renders headless, and produces better print output. The two
+renderers share :func:`~plotaviz.core.plotter.prepare`, so what gets saved matches what was seen.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+from .errors import ExportError
+from .plotter import build_matplotlib, prepare
+from .spec import ChartSpec
+
+#: Formats :func:`export_image` can write.
+IMAGE_FORMATS: tuple[str, ...] = ("png", "svg", "pdf", "jpg", "jpeg", "webp", "tiff")
+
+#: Export DPI. 300 is print quality.
+DEFAULT_DPI = 300
+
+#: Default figure size in inches.
+DEFAULT_SIZE = (10.0, 6.0)
+
+
+@dataclass
+class ExportOptions:
+    """Settings from the export dialog.
+
+    Attributes:
+        dpi: Dots per inch for raster formats. Ignored by SVG and PDF, which are vector.
+        width: Figure width in inches.
+        height: Figure height in inches.
+        transparent: Whether to leave the background transparent.
+        include_notice: Whether to stamp the "showing a sample of N" note onto the image. On by
+            default — an exported chart that hides its own sampling is a chart that misleads.
+    """
+
+    dpi: int = DEFAULT_DPI
+    width: float = DEFAULT_SIZE[0]
+    height: float = DEFAULT_SIZE[1]
+    transparent: bool = False
+    include_notice: bool = True
+
+    @property
+    def figsize(self) -> tuple[float, float]:
+        """Size as the ``(width, height)`` tuple matplotlib wants."""
+        return (float(self.width), float(self.height))
+
+
+def export_image(
+    df: pd.DataFrame,
+    spec: ChartSpec,
+    path: str | Path,
+    *,
+    options: ExportOptions | None = None,
+) -> Path:
+    """Render a spec and write it to an image file.
+
+    The format comes from the file extension.
+
+    Args:
+        df: Cleaned, filtered data.
+        spec: What to draw.
+        path: Destination file.
+        options: Size, DPI, and background settings.
+
+    Returns:
+        The path written.
+
+    Raises:
+        ExportError: If the extension is unsupported or the file cannot be written.
+    """
+    options = options or ExportOptions()
+    target = Path(path).expanduser()
+    fmt = target.suffix.lower().lstrip(".")
+
+    if not fmt:
+        target = target.with_suffix(".png")
+        fmt = "png"
+    if fmt not in IMAGE_FORMATS:
+        raise ExportError(
+            f"PlotaViz cannot export {fmt!r} images.",
+            hint=f"Supported formats: {', '.join(IMAGE_FORMATS)}.",
+        )
+
+    prepared = prepare(df, spec)
+    if not options.include_notice:
+        prepared.sampled = False
+
+    figure = build_matplotlib(df, spec, prepared=prepared, figsize=options.figsize, dpi=options.dpi)
+
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        figure.savefig(
+            target,
+            dpi=options.dpi,
+            bbox_inches="tight",
+            transparent=options.transparent,
+            format=fmt if fmt not in {"jpg"} else "jpeg",
+        )
+    except OSError as exc:
+        raise ExportError(f"Could not write {target}.", hint=str(exc)) from exc
+    except ValueError as exc:
+        raise ExportError(f"Could not render the chart as {fmt}.", hint=str(exc)) from exc
+    finally:
+        _close(figure)
+
+    return target
+
+
+def export_html(df: pd.DataFrame, spec: ChartSpec, path: str | Path) -> Path:
+    """Write the interactive Plotly figure as a self-contained HTML file.
+
+    Useful for sharing a chart someone can actually zoom and hover, without them installing
+    anything.
+
+    Raises:
+        ExportError: If Plotly is missing or the file cannot be written.
+    """
+    from .plotter import build_plotly
+
+    target = Path(path).expanduser().with_suffix(".html")
+    figure = build_plotly(df, spec)
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        figure.write_html(str(target), include_plotlyjs="cdn", full_html=True)
+    except OSError as exc:
+        raise ExportError(f"Could not write {target}.", hint=str(exc)) from exc
+    return target
+
+
+def _close(figure: Any) -> None:
+    """Close a matplotlib figure so long sessions do not leak them."""
+    try:
+        import matplotlib.pyplot as plt
+
+        plt.close(figure)
+    except Exception:
+        pass