dnakit 0.1.0.dev0__py3-none-any.whl

dnakit/visualization/export.py

@@ -0,0 +1,349 @@
+"""Atomic persistence for standalone SVG visualization artifacts."""
+
+from __future__ import annotations
+
+import hashlib
+import importlib
+import os
+import tempfile
+from contextlib import suppress
+from datetime import datetime, timezone
+from io import BytesIO
+from pathlib import Path
+from types import TracebackType
+from typing import BinaryIO, Protocol, TypeAlias, cast
+
+from dnakit.core.provenance import ArtifactRef
+from dnakit.exceptions import BackendUnavailableError, ConfigurationError
+
+from .config import ImageExportConfig, SaveConfig
+from .results import HTMLReportArtifact, SVGArtifact, VisualizationSaveResult
+
+PathLike: TypeAlias = str | os.PathLike[str]
+
+
+class _CairoSVGModule(Protocol):
+    def svg2pdf(
+        self,
+        *,
+        bytestring: bytes,
+        dpi: int,
+        output_width: int,
+        output_height: int,
+    ) -> bytes: ...
+
+    def svg2png(
+        self,
+        *,
+        bytestring: bytes,
+        dpi: int,
+        output_width: int,
+        output_height: int,
+    ) -> bytes: ...
+
+
+class _PILImage(Protocol):
+    def __enter__(self) -> _PILImage: ...
+
+    def __exit__(
+        self,
+        exception_type: type[BaseException] | None,
+        exception: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> bool | None: ...
+
+    def save(self, stream: BinaryIO, *, format: str, **parameters: object) -> None: ...
+
+
+class _PILImageModule(Protocol):
+    def open(self, stream: BinaryIO) -> _PILImage: ...
+
+
+def _artifact_ref(
+    path: Path,
+    *,
+    sha256: str,
+    byte_size: int,
+    media_type: str,
+    schema_version: str,
+) -> ArtifactRef:
+    stat = path.stat()
+    return ArtifactRef(
+        relative_path=os.path.relpath(path.resolve(), Path.cwd()),
+        media_type=media_type,
+        schema_version=schema_version,
+        sha256=sha256,
+        byte_size=byte_size,
+        created_at=datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc).isoformat(),
+    )
+
+
+def _atomic_write(path: Path, payload: bytes, *, overwrite: bool, create_parents: bool) -> bool:
+    parent = path.parent
+    if not parent.exists():
+        if create_parents:
+            parent.mkdir(parents=True, exist_ok=True)
+        else:
+            raise FileNotFoundError(f"Output parent directory does not exist: {parent}")
+    if not parent.is_dir():
+        raise NotADirectoryError(f"Output parent is not a directory: {parent}")
+    existed = path.exists()
+    if existed and not overwrite:
+        raise FileExistsError(f"Refusing to overwrite existing output: {path}")
+    descriptor, temporary_name = tempfile.mkstemp(
+        prefix=f".{path.name}.", suffix=".tmp", dir=parent
+    )
+    temporary_path = Path(temporary_name)
+    try:
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(payload)
+            stream.flush()
+            os.fsync(stream.fileno())
+        if overwrite:
+            os.replace(temporary_path, path)
+        else:
+            os.link(temporary_path, path)
+            temporary_path.unlink()
+    except BaseException:
+        with suppress(OSError):
+            os.close(descriptor)
+        temporary_path.unlink(missing_ok=True)
+        raise
+    return existed
+
+
+def save_svg(
+    artifact: SVGArtifact,
+    target: PathLike,
+    *,
+    config: SaveConfig | None = None,
+) -> VisualizationSaveResult:
+    """Atomically save exact SVG bytes, refusing overwrite by default."""
+
+    if not isinstance(artifact, SVGArtifact):
+        raise TypeError("artifact must be SVGArtifact.")
+    if not isinstance(target, (str, os.PathLike)):
+        raise TypeError("target must be a string or path-like object.")
+    resolved = SaveConfig() if config is None else config
+    if not isinstance(resolved, SaveConfig):
+        raise TypeError("config must be SaveConfig or None.")
+    path = Path(target)
+    if path.suffix.lower() != ".svg":
+        raise ConfigurationError(
+            "SVG output path must end with .svg.",
+            code="INVALID_VISUALIZATION_FORMAT",
+            context={"target": str(path)},
+        )
+    payload = artifact.svg.encode("utf-8")
+    existed = _atomic_write(
+        path,
+        payload,
+        overwrite=resolved.overwrite,
+        create_parents=resolved.create_parents,
+    )
+    target_artifact = _artifact_ref(
+        path,
+        sha256=artifact.sha256,
+        byte_size=len(payload),
+        media_type="image/svg+xml",
+        schema_version="dnakit-visualization-v1",
+    )
+    return VisualizationSaveResult(
+        artifact.sha256,
+        target_artifact,
+        overwritten=existed,
+        provenance=artifact.provenance,
+        issues=artifact.issues,
+    )
+
+
+def _target_dimensions(artifact: SVGArtifact, config: ImageExportConfig) -> tuple[int, int]:
+    if config.width is None and config.height is None:
+        scale = config.dpi / 96.0
+        width = max(1, round(artifact.width * scale))
+        height = max(1, round(artifact.height * scale))
+    elif config.width is None:
+        assert config.height is not None
+        height = config.height
+        width = max(1, round(artifact.width * height / artifact.height))
+    elif config.height is None:
+        width = config.width
+        height = max(1, round(artifact.height * width / artifact.width))
+    else:
+        width, height = config.width, config.height
+    if width * height > config.max_output_pixels:
+        raise ConfigurationError(
+            "Rendered image exceeds max_output_pixels.",
+            code="VISUALIZATION_PIXEL_LIMIT",
+            context={
+                "width": width,
+                "height": height,
+                "max_output_pixels": config.max_output_pixels,
+            },
+        )
+    return width, height
+
+
+def _svg_payload(artifact: SVGArtifact, *, transparent: bool) -> bytes:
+    if not transparent:
+        return artifact.svg.encode("utf-8")
+    import xml.etree.ElementTree as ET
+
+    root = ET.fromstring(artifact.svg)
+    for child in tuple(root):
+        if child.tag.endswith("rect") and child.attrib.get("class") == "background":
+            root.remove(child)
+            break
+    return cast(bytes, ET.tostring(root, encoding="utf-8", xml_declaration=False))
+
+
+def _convert_image(
+    artifact: SVGArtifact, output_format: str, config: ImageExportConfig
+) -> tuple[bytes, int, int]:
+    width, height = _target_dimensions(artifact, config)
+    try:
+        cairosvg = cast(_CairoSVGModule, importlib.import_module("cairosvg"))
+    except ImportError as exc:
+        raise BackendUnavailableError(
+            "PNG, TIFF, and PDF export requires the optional visualization backend.",
+            code="VISUALIZATION_BACKEND_UNAVAILABLE",
+            hint="Install DNAKit with the 'viz' extra.",
+        ) from exc
+    source = _svg_payload(artifact, transparent=config.transparent)
+    if output_format == "pdf":
+        payload = cairosvg.svg2pdf(
+            bytestring=source,
+            dpi=config.dpi,
+            output_width=width,
+            output_height=height,
+        )
+        return payload, width, height
+    png = cairosvg.svg2png(
+        bytestring=source,
+        dpi=config.dpi,
+        output_width=width,
+        output_height=height,
+    )
+    try:
+        image_module = cast(_PILImageModule, importlib.import_module("PIL.Image"))
+    except ImportError as exc:
+        raise BackendUnavailableError(
+            "PNG and TIFF export require Pillow from the optional visualization extra.",
+            code="VISUALIZATION_BACKEND_UNAVAILABLE",
+            hint="Install DNAKit with the 'viz' extra.",
+        ) from exc
+    output = BytesIO()
+    with image_module.open(BytesIO(png)) as image:
+        if output_format == "png":
+            image.save(output, format="PNG", dpi=(config.dpi, config.dpi))
+        else:
+            image.save(output, format="TIFF", compression="tiff_lzw", dpi=(config.dpi, config.dpi))
+    return output.getvalue(), width, height
+
+
+def save_image(
+    artifact: SVGArtifact,
+    target: PathLike,
+    *,
+    config: ImageExportConfig | None = None,
+) -> VisualizationSaveResult:
+    """Atomically export an SVG artifact as SVG, PNG, TIFF, or PDF."""
+
+    if not isinstance(artifact, SVGArtifact):
+        raise TypeError("artifact must be SVGArtifact.")
+    if not isinstance(target, (str, os.PathLike)):
+        raise TypeError("target must be a string or path-like object.")
+    resolved = ImageExportConfig() if config is None else config
+    if not isinstance(resolved, ImageExportConfig):
+        raise TypeError("config must be ImageExportConfig or None.")
+    path = Path(target)
+    suffix = path.suffix.lower()
+    format_by_suffix = {
+        ".svg": "svg",
+        ".png": "png",
+        ".tif": "tiff",
+        ".tiff": "tiff",
+        ".pdf": "pdf",
+    }
+    output_format = format_by_suffix.get(suffix)
+    if output_format is None:
+        raise ConfigurationError(
+            "Visualization output must end with .svg, .png, .tif, .tiff, or .pdf.",
+            code="INVALID_VISUALIZATION_FORMAT",
+        )
+    if output_format == "svg":
+        return save_svg(
+            artifact,
+            path,
+            config=SaveConfig(overwrite=resolved.overwrite, create_parents=resolved.create_parents),
+        )
+    payload, _width, _height = _convert_image(artifact, output_format, resolved)
+    existed = _atomic_write(
+        path,
+        payload,
+        overwrite=resolved.overwrite,
+        create_parents=resolved.create_parents,
+    )
+    media_type = {"png": "image/png", "tiff": "image/tiff", "pdf": "application/pdf"}[output_format]
+    digest = hashlib.sha256(payload).hexdigest()
+    target_artifact = _artifact_ref(
+        path,
+        sha256=digest,
+        byte_size=len(payload),
+        media_type=media_type,
+        schema_version="dnakit-visualization-export-v1",
+    )
+    return VisualizationSaveResult(
+        artifact.sha256,
+        target_artifact,
+        format=output_format,
+        overwritten=existed,
+        provenance=artifact.provenance,
+        issues=artifact.issues,
+    )
+
+
+def save_html_report(
+    artifact: HTMLReportArtifact,
+    target: PathLike,
+    *,
+    config: SaveConfig | None = None,
+) -> VisualizationSaveResult:
+    """Atomically persist a self-contained DNAKit HTML report."""
+
+    if not isinstance(artifact, HTMLReportArtifact):
+        raise TypeError("artifact must be HTMLReportArtifact.")
+    resolved = SaveConfig() if config is None else config
+    if not isinstance(resolved, SaveConfig):
+        raise TypeError("config must be SaveConfig or None.")
+    path = Path(target)
+    if path.suffix.lower() not in {".html", ".htm"}:
+        raise ConfigurationError(
+            "HTML report path must end with .html or .htm.",
+            code="INVALID_VISUALIZATION_FORMAT",
+        )
+    payload = artifact.html.encode("utf-8")
+    existed = _atomic_write(
+        path,
+        payload,
+        overwrite=resolved.overwrite,
+        create_parents=resolved.create_parents,
+    )
+    target_artifact = _artifact_ref(
+        path,
+        sha256=artifact.sha256,
+        byte_size=len(payload),
+        media_type="text/html",
+        schema_version="dnakit-html-report-v1",
+    )
+    return VisualizationSaveResult(
+        artifact.sha256,
+        target_artifact,
+        format="html",
+        overwritten=existed,
+        provenance=artifact.provenance,
+        issues=artifact.issues,
+    )
+
+
+__all__ = ["PathLike", "save_html_report", "save_image", "save_svg"]

dnakit/visualization/matrix.py

@@ -0,0 +1,279 @@
+"""Deterministic SVG heatmaps for precomputed similarity matrices."""
+
+from __future__ import annotations
+
+import math
+
+from dnakit.core.enums import IssueSeverity
+from dnakit.core.issues import Issue
+from dnakit.exceptions import ConfigurationError
+from dnakit.similarity.results import SimilarityMatrixResult
+
+from ._svg import SVGBuilder, interpolate_color, number, validate_xml_text
+from .config import HeatmapConfig, LimitPolicy
+from .results import SVGArtifact
+
+_MAX_LABEL_LENGTH = 1_024
+_DISPLAY_LABEL_LENGTH = 32
+
+
+def _validate_labels(labels: tuple[str, ...]) -> None:
+    for index, label in enumerate(labels):
+        if len(label) > _MAX_LABEL_LENGTH:
+            raise ConfigurationError(
+                "A matrix label exceeds the visualization safety limit.",
+                code="VISUALIZATION_SIZE_LIMIT",
+                context={"label_index": index, "max_label_length": _MAX_LABEL_LENGTH},
+            )
+        try:
+            validate_xml_text(label, name="matrix label")
+        except ValueError as exc:
+            raise ConfigurationError(
+                "A matrix label contains a character forbidden by XML.",
+                code="INVALID_VISUALIZATION_LABEL",
+                context={"label_index": index},
+            ) from exc
+
+
+def _short_label(value: str) -> str:
+    if len(value) <= _DISPLAY_LABEL_LENGTH:
+        return value
+    return value[: _DISPLAY_LABEL_LENGTH - 1] + "…"
+
+
+def _stride_indices(length: int, maximum: int) -> tuple[int, ...]:
+    if length <= maximum:
+        return tuple(range(length))
+    step = math.ceil(length / maximum)
+    return tuple(range(0, length, step))
+
+
+def _scale(values: tuple[tuple[float, ...], ...], config: HeatmapConfig) -> tuple[float, float]:
+    flat = tuple(value for row in values for value in row)
+    data_min = min(flat, default=0.0)
+    data_max = max(flat, default=1.0)
+    lower = data_min if config.value_min is None else float(config.value_min)
+    upper = data_max if config.value_max is None else float(config.value_max)
+    if lower >= upper:
+        if config.value_min is not None and config.value_max is None:
+            upper = lower + 1.0
+        elif config.value_min is None and config.value_max is not None:
+            lower = upper - 1.0
+        elif lower == 0:
+            upper = 1.0
+        else:
+            padding = max(abs(lower) * 0.05, 0.5)
+            lower -= padding
+            upper += padding
+    return lower, upper
+
+
+def plot_similarity_matrix(
+    result: SimilarityMatrixResult,
+    *,
+    config: HeatmapConfig | None = None,
+) -> SVGArtifact:
+    """Render an existing matrix in its original order without mirroring it."""
+
+    if not isinstance(result, SimilarityMatrixResult):
+        raise TypeError("result must be SimilarityMatrixResult.")
+    resolved = HeatmapConfig() if config is None else config
+    if not isinstance(resolved, HeatmapConfig):
+        raise TypeError("config must be HeatmapConfig or None.")
+    _validate_labels(result.labels)
+
+    size = result.item_count
+    display_limit = min(resolved.max_rows, resolved.max_columns)
+    if size > display_limit and resolved.limit_policy is LimitPolicy.ERROR:
+        raise ConfigurationError(
+            "Similarity heatmap exceeds its configured dimensions.",
+            code="VISUALIZATION_SIZE_LIMIT",
+            context={
+                "item_count": size,
+                "max_columns": resolved.max_columns,
+                "max_rows": resolved.max_rows,
+            },
+            hint="Raise the limits or explicitly choose limit_policy='stride'.",
+        )
+    indices = _stride_indices(size, display_limit)
+    strided = len(indices) < size
+    lower, upper = _scale(result.values, resolved)
+    issues: list[Issue] = []
+    if size == 0:
+        issues.append(
+            Issue(
+                "VIZ_EMPTY_MATRIX",
+                IssueSeverity.INFO,
+                "The similarity result contains an empty matrix.",
+            )
+        )
+    if strided:
+        issues.append(
+            Issue(
+                "VIZ_MATRIX_STRIDED",
+                IssueSeverity.WARNING,
+                "Rows and columns were explicitly display-sampled with the same stride.",
+                details={"input_items": size, "displayed_items": len(indices)},
+            )
+        )
+    clipped_count = sum(value < lower or value > upper for row in result.values for value in row)
+    if clipped_count:
+        issues.append(
+            Issue(
+                "VIZ_MATRIX_VALUES_CLIPPED",
+                IssueSeverity.WARNING,
+                "Values outside the configured color range were clipped.",
+                details={"count": clipped_count},
+            )
+        )
+
+    labels = tuple(result.labels[index] for index in indices)
+    title = resolved.title or f"{result.name} ({result.method})"
+    label_gutter = 170 if resolved.show_labels and labels else 24
+    top_gutter = 190 if resolved.show_labels and labels else 60
+    legend_width = 80
+    matrix_size = max(1, len(indices)) * resolved.cell_size
+    width = label_gutter + matrix_size + legend_width + 28
+    height = top_gutter + matrix_size + 42
+    metadata = {
+        "display_indices": indices,
+        "displayed_items": len(indices),
+        "input_items": size,
+        "matrix_method": result.method,
+        "strided": strided,
+        "symmetric": result.symmetric,
+        "value_kind": result.value_kind,
+        "value_max": upper,
+        "value_min": lower,
+    }
+    builder = SVGBuilder(
+        width,
+        height,
+        title=title,
+        description="Heatmap of a precomputed DNA similarity or distance matrix.",
+        kind="similarity-matrix",
+        theme=resolved.theme,
+        metadata=metadata,
+    )
+    builder.text(
+        width / 2,
+        28,
+        title,
+        fill=resolved.theme.foreground,
+        font_family=resolved.theme.font_family,
+        font_size=16,
+        font_weight="bold",
+        text_anchor="middle",
+        class_="plot-title",
+    )
+
+    if not indices:
+        builder.text(
+            width / 2,
+            height / 2,
+            "Empty matrix",
+            fill=resolved.theme.muted,
+            font_family=resolved.theme.font_family,
+            font_size=14,
+            text_anchor="middle",
+            class_="empty-state",
+        )
+        return builder.artifact(issues=issues)
+
+    for display_row, source_row in enumerate(indices):
+        y = top_gutter + display_row * resolved.cell_size
+        if resolved.show_labels:
+            builder.text(
+                label_gutter - 8,
+                y + resolved.cell_size * 0.72,
+                _short_label(result.labels[source_row]),
+                fill=resolved.theme.foreground,
+                font_family=resolved.theme.font_family,
+                font_size=10,
+                text_anchor="end",
+                class_="row-label",
+                data_label=result.labels[source_row],
+                data_source_index=source_row,
+            )
+        for display_column, source_column in enumerate(indices):
+            value = result.values[source_row][source_column]
+            fraction = (min(upper, max(lower, value)) - lower) / (upper - lower)
+            cell_x = label_gutter + display_column * resolved.cell_size
+            builder.rect(
+                cell_x,
+                y,
+                resolved.cell_size,
+                resolved.cell_size,
+                fill=interpolate_color(resolved.low_color, resolved.high_color, fraction),
+                stroke=resolved.theme.background,
+                stroke_width=0.5,
+                class_="heatmap-cell",
+                data_column=source_column,
+                data_row=source_row,
+                data_value=number(value),
+            )
+            if resolved.show_values and resolved.cell_size >= 18:
+                builder.text(
+                    cell_x + resolved.cell_size / 2,
+                    y + resolved.cell_size * 0.7,
+                    number(value),
+                    fill=resolved.theme.foreground,
+                    font_family=resolved.theme.font_family,
+                    font_size=max(7, min(10, resolved.cell_size - 9)),
+                    text_anchor="middle",
+                    class_="cell-value",
+                )
+    if resolved.show_labels:
+        for display_column, source_column in enumerate(indices):
+            label_x = label_gutter + (display_column + 0.5) * resolved.cell_size
+            label_y = top_gutter - 8
+            builder.text(
+                label_x,
+                label_y,
+                _short_label(result.labels[source_column]),
+                fill=resolved.theme.foreground,
+                font_family=resolved.theme.font_family,
+                font_size=10,
+                text_anchor="start",
+                transform=f"rotate(-45 {number(label_x)} {number(label_y)})",
+                class_="column-label",
+                data_label=result.labels[source_column],
+                data_source_index=source_column,
+            )
+
+    legend_x = label_gutter + matrix_size + 24
+    legend_steps = 20
+    legend_height = min(200, matrix_size)
+    for step in range(legend_steps):
+        fraction = step / (legend_steps - 1)
+        legend_y = top_gutter + (1 - fraction) * legend_height
+        builder.rect(
+            legend_x,
+            legend_y,
+            14,
+            legend_height / legend_steps + 1,
+            fill=interpolate_color(resolved.low_color, resolved.high_color, fraction),
+            class_="legend-step",
+        )
+    builder.text(
+        legend_x + 20,
+        top_gutter + 8,
+        number(upper),
+        fill=resolved.theme.muted,
+        font_family=resolved.theme.font_family,
+        font_size=9,
+        class_="legend-maximum",
+    )
+    builder.text(
+        legend_x + 20,
+        top_gutter + legend_height,
+        number(lower),
+        fill=resolved.theme.muted,
+        font_family=resolved.theme.font_family,
+        font_size=9,
+        class_="legend-minimum",
+    )
+    return builder.artifact(issues=issues)
+
+
+__all__ = ["plot_similarity_matrix"]