cpdatakit 0.1.1__py3-none-any.whl

cpdatakit/__init__.py

@@ -0,0 +1,16 @@
+"""CPDataKit public API."""
+
+from ._version import __version__
+from .io import load_dataset
+from .normalization import FieldMapping, normalize_dataset
+from .statistics import summarize_dataset
+from .validation import validate_dataset
+
+__all__ = [
+    "FieldMapping",
+    "__version__",
+    "load_dataset",
+    "normalize_dataset",
+    "summarize_dataset",
+    "validate_dataset",
+]

cpdatakit/_version.py

@@ -0,0 +1,3 @@
+"""Package version kept in one import-safe location."""
+
+__version__ = "0.1.1"

cpdatakit/adapters/__init__.py

@@ -0,0 +1,16 @@
+"""Extension interfaces; no solver-specific adapter is bundled in v0.1.x."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from ..model import Dataset
+
+
+class DatasetAdapter(ABC):
+    """Contract for optional, independently licensed source adapters."""
+
+    @abstractmethod
+    def load(self, path: Path) -> Dataset:
+        """Translate an explicit external representation into a Dataset."""

cpdatakit/cli.py

@@ -0,0 +1,145 @@
+"""Command-line interface for CPDataKit."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import matplotlib.pyplot as plt
+
+from . import __version__
+from .exceptions import CPDataKitError
+from .io import load_dataset, write_hdf5
+from .plotting import (
+    plot_counts,
+    plot_field2d,
+    plot_histogram,
+    plot_stress_strain,
+    save_figure,
+)
+from .schema import load_schema
+from .statistics import summarize_dataset
+from .validation import validate_dataset
+
+
+def _common(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("data", type=Path, help="Input CSV, JSON records, or CPDataKit HDF5")
+    parser.add_argument("--schema", required=True, help="Built-in profile or JSON schema path")
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cpdatakit",
+        description="Validate and process declared crystal-plasticity data structures.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument(
+        "--debug", action="store_true", help="Show tracebacks for unexpected failures"
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+    validate = commands.add_parser("validate", help="Validate schema conformance")
+    _common(validate)
+    validate.add_argument("--json-output", type=Path, help="Write the validation report as JSON")
+    validate.add_argument("--force", action="store_true", help="Replace an existing report")
+    summary = commands.add_parser("summary", help="Print a descriptive JSON summary")
+    _common(summary)
+    summary.add_argument("--json-output", type=Path, help="Write the summary as JSON")
+    summary.add_argument("--force", action="store_true", help="Replace an existing report")
+    convert = commands.add_parser("convert", help="Convert to CPDataKit HDF5")
+    _common(convert)
+    convert.add_argument("--output", required=True, type=Path)
+    convert.add_argument("--source-description")
+    convert.add_argument("--force", action="store_true")
+    plot = commands.add_parser("plot", help="Create a PNG or SVG plot")
+    _common(plot)
+    plot.add_argument(
+        "--kind",
+        required=True,
+        choices=["stress-strain", "histogram", "grain-count", "phase-count", "field2d"],
+    )
+    plot.add_argument("--field", help="Declared numeric field for histogram")
+    plot.add_argument("--output", required=True, type=Path)
+    plot.add_argument("--force", action="store_true")
+    return parser
+
+
+def _write_json(payload: dict[str, Any], target: Path | None, force: bool) -> None:
+    rendered = json.dumps(payload, indent=2, sort_keys=True, allow_nan=False)
+    if target is None:
+        print(rendered)
+        return
+    if target.exists() and not force:
+        raise CPDataKitError(f"Output already exists: {target}; pass --force to replace it")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(rendered + "\n", encoding="utf-8")
+
+
+def _run(args: argparse.Namespace) -> int:
+    schema = load_schema(args.schema)
+    dataset = load_dataset(args.data)
+    result = validate_dataset(dataset, schema)
+    if args.command == "validate":
+        _write_json(result.to_dict(), args.json_output, args.force)
+        return 0 if result.valid else 1
+    if args.command == "summary":
+        _write_json(
+            summarize_dataset(dataset, schema, validation=result), args.json_output, args.force
+        )
+        return 0 if result.valid else 1
+    if args.command == "convert":
+        if not result.valid:
+            print(json.dumps(result.to_dict(), indent=2), file=sys.stderr)
+            return 1
+        write_hdf5(
+            dataset,
+            args.output,
+            schema,
+            result,
+            source_description=args.source_description,
+            operation_log=["load", "validate", "convert"],
+            force=args.force,
+        )
+        print(args.output)
+        return 0
+    if not result.valid:
+        print(json.dumps(result.to_dict(), indent=2), file=sys.stderr)
+        return 1
+    if args.kind == "stress-strain":
+        fig, _ = plot_stress_strain(dataset, schema)
+    elif args.kind == "histogram":
+        if not args.field:
+            raise CPDataKitError("--field is required for histogram")
+        fig, _ = plot_histogram(dataset, schema, args.field)
+    elif args.kind == "grain-count":
+        fig, _ = plot_counts(dataset, schema, "grain_id")
+    elif args.kind == "phase-count":
+        fig, _ = plot_counts(dataset, schema, "phase_id")
+    else:
+        fig, _ = plot_field2d(dataset, schema)
+    try:
+        save_figure(fig, args.output, force=args.force)
+    finally:
+        plt.close(fig)
+    print(args.output)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the CLI and return a process exit status."""
+    parser = _parser()
+    args = parser.parse_args(argv)
+    try:
+        return _run(args)
+    except CPDataKitError as exc:
+        if args.debug:
+            raise
+        parser.print_usage(sys.stderr)
+        print(f"{parser.prog}: error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cpdatakit/exceptions.py

@@ -0,0 +1,21 @@
+"""Public exception hierarchy for CPDataKit."""
+
+
+class CPDataKitError(Exception):
+    """Base class for expected CPDataKit failures."""
+
+
+class DataReadError(CPDataKitError):
+    """Raised when an input cannot be read as a supported dataset."""
+
+
+class SchemaError(CPDataKitError):
+    """Raised when a schema is missing, malformed, or unsupported."""
+
+
+class NormalizationError(CPDataKitError):
+    """Raised when an explicit mapping cannot be applied safely."""
+
+
+class OutputExistsError(CPDataKitError):
+    """Raised when an operation would overwrite a file without consent."""

cpdatakit/io/__init__.py

@@ -0,0 +1,166 @@
+"""CSV, JSON records, and CPDataKit HDF5 I/O."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import h5py
+import numpy as np
+import pandas as pd
+
+from ..exceptions import DataReadError, OutputExistsError
+from ..model import Dataset, ValidationResult
+from ..provenance import build_provenance
+from ..schema import ProfileSchema
+
+_SUPPORTED = {".csv", ".json", ".h5", ".hdf5"}
+
+
+def _ensure_readable(path: Path) -> None:
+    if not path.exists():
+        raise DataReadError(f"Input path does not exist: {path}")
+    if not path.is_file():
+        raise DataReadError(f"Input path is not a file: {path}")
+    if path.stat().st_size == 0:
+        raise DataReadError(f"Input file is empty: {path}")
+    if path.suffix.lower() not in _SUPPORTED:
+        raise DataReadError(
+            f"Unsupported extension {path.suffix!r}; supported: {', '.join(sorted(_SUPPORTED))}"
+        )
+
+
+def _read_hdf5(path: Path) -> Dataset:
+    try:
+        with h5py.File(path, "r") as handle:
+            if handle.attrs.get("format") != "CPDataKit":
+                raise DataReadError("HDF5 is not a CPDataKit file (missing format marker)")
+            if "data" not in handle or not isinstance(handle["data"], h5py.Group):
+                raise DataReadError("CPDataKit HDF5 is missing the /data group")
+            columns: dict[str, Any] = {}
+            record_count: int | None = None
+            for name, item in handle["data"].items():
+                if not isinstance(item, h5py.Dataset):
+                    continue
+                values = item[()]
+                if values.ndim == 0:
+                    raise DataReadError(f"CPDataKit HDF5 field {name!r} must contain records")
+                if values.dtype.kind in {"S", "O"}:
+                    values = np.asarray(
+                        [v.decode("utf-8") if isinstance(v, bytes) else v for v in values]
+                    )
+                if record_count is None:
+                    record_count = len(values)
+                elif len(values) != record_count:
+                    raise DataReadError("CPDataKit HDF5 fields have inconsistent record counts")
+                columns[name] = list(values) if values.ndim > 1 else values
+            if not columns:
+                raise DataReadError("CPDataKit HDF5 /data group contains no fields")
+            if record_count == 0:
+                raise DataReadError("CPDataKit HDF5 contains no records")
+            metadata = {
+                "profile": str(handle.attrs.get("profile", "")),
+                "schema_version": str(handle.attrs.get("schema_version", "")),
+                "units": json.loads(str(handle.attrs.get("units_json", "{}"))),
+                "field_mapping": json.loads(str(handle.attrs.get("field_mapping_json", "{}"))),
+                "provenance": json.loads(str(handle.attrs.get("provenance_json", "{}"))),
+                "validation_summary": json.loads(
+                    str(handle.attrs.get("validation_summary_json", "{}"))
+                ),
+            }
+            frame = pd.DataFrame(columns)
+    except DataReadError:
+        raise
+    except (OSError, ValueError, KeyError, TypeError, UnicodeError) as exc:
+        raise DataReadError(f"Cannot read CPDataKit HDF5 {path}: {exc}") from exc
+    return Dataset(frame, metadata, path)
+
+
+def load_dataset(path: str | Path) -> Dataset:
+    """Load CSV, JSON records, or CPDataKit HDF5 from a filesystem path."""
+    input_path = Path(path)
+    _ensure_readable(input_path)
+    suffix = input_path.suffix.lower()
+    try:
+        if suffix == ".csv":
+            frame = pd.read_csv(input_path)
+            if frame.empty:
+                raise DataReadError(f"CSV has no records: {input_path}")
+            return Dataset(frame, {}, input_path)
+        if suffix == ".json":
+            with input_path.open(encoding="utf-8") as stream:
+                payload = json.load(stream)
+            if not isinstance(payload, list) or any(not isinstance(row, dict) for row in payload):
+                raise DataReadError("JSON input must be an array of record objects")
+            if not payload:
+                raise DataReadError("JSON records input is empty")
+            return Dataset(pd.DataFrame.from_records(payload), {}, input_path)
+        return _read_hdf5(input_path)
+    except DataReadError:
+        raise
+    except UnicodeError as exc:
+        raise DataReadError(f"Input is not valid UTF-8: {input_path}") from exc
+    except json.JSONDecodeError as exc:
+        raise DataReadError(f"Invalid JSON in {input_path}: {exc.msg}") from exc
+    except (OSError, pd.errors.ParserError, pd.errors.EmptyDataError) as exc:
+        raise DataReadError(f"Cannot read {input_path}: {exc}") from exc
+
+
+def write_hdf5(
+    dataset: Dataset,
+    output: str | Path,
+    schema: ProfileSchema,
+    validation: ValidationResult,
+    *,
+    field_mapping: dict[str, str] | None = None,
+    source_description: str | None = None,
+    operation_log: list[str] | None = None,
+    force: bool = False,
+) -> Path:
+    """Write the documented CPDataKit HDF5 interchange format."""
+    target = Path(output)
+    if target.exists() and not force:
+        raise OutputExistsError(f"Output already exists: {target}; pass force=True to replace it")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    declared_units = {item.name: item.unit for item in schema.fields if item.name in dataset.data}
+    units = {**declared_units, **dataset.metadata.get("units", {})}
+    stored_mapping = (
+        field_mapping if field_mapping is not None else dataset.metadata.get("field_mapping", {})
+    )
+    provenance = build_provenance(
+        dataset.source, source_description=source_description, operation_log=operation_log
+    )
+    with h5py.File(target, "w") as handle:
+        handle.attrs["format"] = "CPDataKit"
+        handle.attrs["format_version"] = "1.0"
+        handle.attrs["profile"] = schema.profile
+        handle.attrs["schema_version"] = schema.schema_version
+        handle.attrs["units_json"] = json.dumps(units, sort_keys=True)
+        handle.attrs["field_mapping_json"] = json.dumps(stored_mapping, sort_keys=True)
+        handle.attrs["provenance_json"] = json.dumps(provenance, sort_keys=True)
+        handle.attrs["validation_summary_json"] = json.dumps(
+            {
+                "valid": validation.valid,
+                "error_count": len(validation.errors),
+                "warning_count": len(validation.warnings),
+            },
+            sort_keys=True,
+        )
+        group = handle.create_group("data")
+        for name in dataset.data.columns:
+            values = dataset.data[name].to_numpy()
+            if values.dtype.kind in {"O", "U"}:
+                if len(values) and all(
+                    isinstance(item, (list, tuple, np.ndarray)) for item in values
+                ):
+                    try:
+                        values = np.stack(values)
+                    except ValueError as exc:
+                        raise DataReadError(
+                            f"Cannot write inconsistent array shapes in field {name!r}"
+                        ) from exc
+                else:
+                    values = values.astype(h5py.string_dtype(encoding="utf-8"))
+            group.create_dataset(name, data=values)
+    return target

cpdatakit/model.py

@@ -0,0 +1,59 @@
+"""Stable data and validation result objects."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+import pandas as pd
+
+
+@dataclass(slots=True)
+class Dataset:
+    """A tabular dataset plus explicit metadata and optional source path."""
+
+    data: pd.DataFrame
+    metadata: dict[str, Any] = field(default_factory=dict)
+    source: Path | None = None
+
+    def copy(self) -> Dataset:
+        """Return a deep-enough copy for safe normalization."""
+        return Dataset(self.data.copy(deep=True), dict(self.metadata), self.source)
+
+
+@dataclass(frozen=True, slots=True)
+class ValidationIssue:
+    """One actionable validation finding."""
+
+    code: str
+    field: str | None
+    message: str
+    affected_records: int
+    suggestion: str | None = None
+    severity: Literal["error", "warning"] = "error"
+
+
+@dataclass(slots=True)
+class ValidationResult:
+    """Structured validation report; validity means schema conformance only."""
+
+    errors: list[ValidationIssue] = field(default_factory=list)
+    warnings: list[ValidationIssue] = field(default_factory=list)
+
+    @property
+    def valid(self) -> bool:
+        """Whether no schema-conformance errors were found."""
+        return not self.errors
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable representation."""
+        return {
+            "valid": self.valid,
+            "errors": [asdict(item) for item in self.errors],
+            "warnings": [asdict(item) for item in self.warnings],
+            "scope_note": (
+                "Validation checks declared format constraints; it does not certify "
+                "physical or scientific correctness."
+            ),
+        }

cpdatakit/normalization.py

@@ -0,0 +1,101 @@
+"""Explicit field mapping and unit conversion."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import pandas as pd
+from pint import DimensionalityError, UndefinedUnitError, UnitRegistry
+
+from .exceptions import NormalizationError
+from .model import Dataset
+from .schema import ProfileSchema, load_schema
+
+_UREG = UnitRegistry()
+
+
+@dataclass(frozen=True, slots=True)
+class FieldMapping:
+    """An explicit, traceable field mapping and optional unit conversion."""
+
+    source: str
+    target: str
+    input_unit: str | None = None
+    output_unit: str | None = None
+    source_note: str = "user supplied"
+
+
+def normalize_dataset(
+    dataset: Dataset,
+    schema: str | ProfileSchema,
+    mappings: list[FieldMapping] | None = None,
+    *,
+    drop_unmapped: bool = False,
+) -> Dataset:
+    """Normalize fields only from explicit mappings; never infer scientific conventions."""
+    contract = load_schema(schema)
+    items = list(mappings or [])
+    sources = [item.source for item in items]
+    targets = [item.target for item in items]
+    if len(sources) != len(set(sources)) or len(targets) != len(set(targets)):
+        raise NormalizationError("Mappings contain a duplicate source or target")
+    unknown = set(targets) - set(contract.field_map())
+    if unknown:
+        raise NormalizationError(
+            f"Mapping targets are not declared by the schema: {sorted(unknown)}"
+        )
+    missing = set(sources) - set(dataset.data.columns)
+    if missing:
+        raise NormalizationError(f"Mapping sources do not exist: {sorted(missing)}")
+    collisions = {
+        item.target for item in items if item.target in dataset.data and item.target != item.source
+    }
+    if collisions:
+        raise NormalizationError(f"Mappings would overwrite existing fields: {sorted(collisions)}")
+
+    result = dataset.copy()
+    units = dict(result.metadata.get("units", {}))
+    mapping_log: dict[str, dict[str, str | None]] = {}
+    for item in items:
+        series = result.data[item.source]
+        if bool(item.input_unit) != bool(item.output_unit):
+            raise NormalizationError("Both input_unit and output_unit are required for conversion")
+        if item.input_unit and item.output_unit:
+            try:
+                values = series.astype(float).to_numpy()
+            except (TypeError, ValueError) as exc:
+                raise NormalizationError(f"Field {item.source!r} is not numeric") from exc
+            try:
+                converted = _UREG.Quantity(values, item.input_unit).to(item.output_unit).magnitude
+            except (DimensionalityError, UndefinedUnitError) as exc:
+                raise NormalizationError(
+                    f"Cannot convert {item.source!r} from {item.input_unit!r} "
+                    f"to {item.output_unit!r}: {exc}"
+                ) from exc
+            series = pd.Series(converted, index=series.index, name=series.name)
+            units[item.target] = item.output_unit
+        elif item.source in units:
+            units[item.target] = units[item.source]
+        result.data[item.target] = series
+        if item.target != item.source:
+            result.data = result.data.drop(columns=[item.source])
+            units.pop(item.source, None)
+        mapping_log[item.source] = {
+            "target": item.target,
+            "input_unit": item.input_unit,
+            "output_unit": item.output_unit,
+            "source_note": item.source_note,
+        }
+    if drop_unmapped:
+        keep = [item.name for item in contract.fields if item.name in result.data]
+        result.data = result.data.loc[:, keep]
+        units = {key: value for key, value in units.items() if key in keep}
+    result.metadata.update(
+        {
+            "profile": contract.profile,
+            "schema_version": contract.schema_version,
+            "units": units,
+            "field_mapping": mapping_log,
+        }
+    )
+    return result

cpdatakit/plotting.py

@@ -0,0 +1,132 @@
+"""Headless-safe scientific plotting helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import matplotlib
+
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib import rcParams
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+from .exceptions import CPDataKitError, OutputExistsError
+from .model import Dataset
+from .schema import ProfileSchema, load_schema
+
+_BLUE = "#3B6FB6"
+_INK = "#263238"
+rcParams["svg.hashsalt"] = "cpdatakit-0.1"
+
+
+def _unit(schema: ProfileSchema, field: str) -> str:
+    spec = schema.field_map().get(field)
+    return spec.unit if spec and spec.unit else "unit not declared"
+
+
+def _finish(fig: Figure, ax: Axes) -> tuple[Figure, Axes]:
+    ax.tick_params(colors=_INK)
+    for side in ("top", "right"):
+        ax.spines[side].set_visible(False)
+    ax.grid(axis="y", color="#D9DEE3", linewidth=0.7, alpha=0.7)
+    fig.tight_layout()
+    return fig, ax
+
+
+def plot_stress_strain(dataset: Dataset, schema: str | ProfileSchema) -> tuple[Figure, Axes]:
+    """Plot an explicitly declared scalar stress-strain curve."""
+    contract = load_schema(schema)
+    if "strain" not in dataset.data or "stress" not in dataset.data:
+        raise CPDataKitError("stress-strain plot requires declared 'strain' and 'stress' fields")
+    fig, ax = plt.subplots(figsize=(7.2, 4.5))
+    ax.plot(dataset.data["strain"], dataset.data["stress"], color=_BLUE, label="Synthetic curve")
+    ax.set(
+        title="Stress-strain curve",
+        xlabel=f"Strain [{_unit(contract, 'strain')}]",
+        ylabel=f"Stress [{_unit(contract, 'stress')}]",
+    )
+    ax.legend(frameon=False)
+    return _finish(fig, ax)
+
+
+def plot_histogram(
+    dataset: Dataset, schema: str | ProfileSchema, field: str
+) -> tuple[Figure, Axes]:
+    """Plot a finite-value histogram for a declared numeric field."""
+    contract = load_schema(schema)
+    if field not in dataset.data or field not in contract.field_map():
+        raise CPDataKitError(f"Histogram field is absent or undeclared: {field}")
+    spec = contract.field_map()[field]
+    if spec.dtype not in {"float", "integer"} or spec.shape:
+        raise CPDataKitError(f"Histogram field must be a declared scalar numeric field: {field}")
+    try:
+        values = np.asarray(dataset.data[field], dtype=float)
+    except (TypeError, ValueError) as exc:
+        raise CPDataKitError(f"Histogram field is not numeric: {field}") from exc
+    values = values[np.isfinite(values)]
+    if not len(values):
+        raise CPDataKitError(f"Histogram field has no finite data: {field}")
+    fig, ax = plt.subplots(figsize=(7.2, 4.5))
+    ax.hist(values, bins="auto", color=_BLUE, edgecolor="white", label=field)
+    ax.set(
+        title=f"Distribution of {field}",
+        xlabel=f"{field} [{_unit(contract, field)}]",
+        ylabel="Count [records]",
+    )
+    ax.legend(frameon=False)
+    return _finish(fig, ax)
+
+
+def plot_counts(dataset: Dataset, schema: str | ProfileSchema, field: str) -> tuple[Figure, Axes]:
+    """Plot record counts for grain_id or phase_id."""
+    load_schema(schema)
+    if field not in {"grain_id", "phase_id"} or field not in dataset.data:
+        raise CPDataKitError("Count plot field must be present grain_id or phase_id")
+    counts = dataset.data[field].value_counts().sort_index()
+    fig, ax = plt.subplots(figsize=(7.2, 4.5))
+    ax.bar(counts.index.astype(str), counts.values, color=_BLUE, label="Record count")
+    ax.set(title=f"Records by {field}", xlabel=f"{field} [identifier]", ylabel="Count [records]")
+    ax.legend(frameon=False)
+    return _finish(fig, ax)
+
+
+def plot_field2d(dataset: Dataset, schema: str | ProfileSchema) -> tuple[Figure, Axes]:
+    """Plot an irregular or regular 2D scalar field without interpolation claims."""
+    contract = load_schema(schema)
+    needed = {"x", "y", "value"}
+    if not needed.issubset(dataset.data):
+        raise CPDataKitError("field2d plot requires x, y, and value")
+    fig, ax = plt.subplots(figsize=(6.2, 5.2))
+    points = ax.scatter(
+        dataset.data["x"],
+        dataset.data["y"],
+        c=dataset.data["value"],
+        cmap="viridis",
+        s=35,
+        label="Samples",
+    )
+    colorbar = fig.colorbar(points, ax=ax)
+    colorbar.set_label(f"Value [{_unit(contract, 'value')}]")
+    ax.set(
+        title="Two-dimensional scalar field",
+        xlabel=f"x [{_unit(contract, 'x')}]",
+        ylabel=f"y [{_unit(contract, 'y')}]",
+    )
+    ax.legend(frameon=False)
+    return _finish(fig, ax)
+
+
+def save_figure(fig: Figure, output: str | Path, *, force: bool = False) -> Path:
+    """Save a PNG or SVG without overwriting unless requested."""
+    target = Path(output)
+    if target.suffix.lower() not in {".png", ".svg"}:
+        raise CPDataKitError("Plot output extension must be .png or .svg")
+    if target.exists() and not force:
+        raise OutputExistsError(f"Output already exists: {target}; pass force=True to replace it")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    metadata = {"Date": None} if target.suffix.lower() == ".svg" else {"Software": "CPDataKit"}
+    fig.savefig(target, dpi=180, bbox_inches="tight", metadata=metadata)
+    return target