operandomerge 0.1.1__py3-none-any.whl

operandomerge/__init__.py

@@ -0,0 +1,26 @@
+"""OperandoMerge public API."""
+
+from operandomerge.models import (
+    AlignmentConfig,
+    AlignmentMethod,
+    ChannelConfig,
+    DatasetConfig,
+    DataType,
+    DelayConfig,
+    MergeConfig,
+    TimeRepresentation,
+)
+from operandomerge.service import MergeService
+
+__all__ = [
+    "AlignmentConfig",
+    "AlignmentMethod",
+    "ChannelConfig",
+    "DataType",
+    "DatasetConfig",
+    "DelayConfig",
+    "MergeConfig",
+    "MergeService",
+    "TimeRepresentation",
+]
+__version__ = "0.1.1"

operandomerge/cli.py

@@ -0,0 +1,84 @@
+"""Command-line interface for inspectable, reproducible merges."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+
+from operandomerge import __version__
+from operandomerge.config import load_config
+from operandomerge.export import export_csv_bundle, export_excel, plot_alignment
+from operandomerge.io import inspect_columns
+from operandomerge.service import MergeService
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="operandomerge", description=__doc__)
+    parser.add_argument("--version", action="version", version=f"OperandoMerge {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    inspect_parser = subparsers.add_parser("inspect", help="List columns in a CSV/XLSX file")
+    inspect_parser.add_argument("input", type=Path)
+    inspect_parser.add_argument("--sheet", default=0)
+
+    merge_parser = subparsers.add_parser("merge", help="Run a merge from a JSON configuration")
+    merge_parser.add_argument("config", type=Path)
+    output = merge_parser.add_mutually_exclusive_group(required=True)
+    output.add_argument("--excel", type=Path, help="Write a multi-sheet XLSX report")
+    output.add_argument("--csv-dir", type=Path, help="Write a CSV report bundle")
+    merge_parser.add_argument("--plot", type=Path, help="Write an alignment-preview PNG/SVG/PDF")
+    merge_parser.add_argument("--fail-on-qc-error", action="store_true")
+
+    subparsers.add_parser("gui", help="Launch the desktop GUI")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "inspect":
+            columns = inspect_columns(args.input, _sheet_value(args.sheet))
+            print(json.dumps(columns, indent=2))
+            return 0
+        if args.command == "gui":
+            from operandomerge.gui import main as gui_main
+
+            gui_main()
+            return 0
+        datasets, merge_config = load_config(args.config)
+        result = MergeService().run(datasets, merge_config)
+        if args.excel:
+            export_excel(result, args.excel)
+            destination = args.excel
+        else:
+            export_csv_bundle(result, args.csv_dir)
+            destination = args.csv_dir
+        if args.plot:
+            figure = plot_alignment(result, args.plot)
+            plt.close(figure)
+        errors = sum(issue.severity == "error" for issue in result.qc)
+        warnings = sum(issue.severity == "warning" for issue in result.qc)
+        print(
+            f"Merged {len(datasets)} dataset(s), {len(result.merged)} timeline row(s); "
+            f"QC: {errors} error(s), {warnings} warning(s); output: {destination}"
+        )
+        return 2 if args.fail_on_qc_error and errors else 0
+    except (FileNotFoundError, KeyError, TypeError, ValueError) as error:
+        print(f"operandomerge: error: {error}", file=sys.stderr)
+        return 2
+
+
+def _sheet_value(value: object) -> str | int | None:
+    if value is None:
+        return None
+    text = str(value)
+    return int(text) if text.isdigit() else text
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

operandomerge/config.py

@@ -0,0 +1,94 @@
+"""JSON configuration parsing and serialization."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+from operandomerge.models import (
+    AlignmentConfig,
+    AlignmentMethod,
+    ChannelConfig,
+    DatasetConfig,
+    DataType,
+    DelayConfig,
+    MergeConfig,
+    TimeRepresentation,
+)
+
+
+def _dataset_from_dict(raw: dict[str, Any], base: Path) -> DatasetConfig:
+    source_path = Path(str(raw["path"])).expanduser()
+    if not source_path.is_absolute():
+        source_path = (base / source_path).resolve()
+    alignment_raw = raw.get("alignment", {})
+    delay_raw = raw.get("delay", {})
+    return DatasetConfig(
+        path=source_path,
+        name=raw.get("name"),
+        sheet_name=raw.get("sheet_name", 0),
+        time_column=str(raw["time_column"]),
+        time_representation=TimeRepresentation(raw["time_representation"]),
+        channels=tuple(
+            ChannelConfig(
+                source_column=str(channel["source_column"]),
+                data_type=DataType(channel.get("data_type", "continuous")),
+                output_name=channel.get("output_name"),
+            )
+            for channel in raw["channels"]
+        ),
+        alignment=AlignmentConfig(
+            method=AlignmentMethod(alignment_raw.get("method", "elapsed")),
+            manual_offset_s=float(alignment_raw.get("manual_offset_s", 0.0)),
+            source_event_time_s=_optional_float(alignment_raw.get("source_event_time_s")),
+            target_event_time_s=_optional_float(alignment_raw.get("target_event_time_s")),
+        ),
+        delay=DelayConfig(
+            manual_s=float(delay_raw.get("manual_s", 0.0)),
+            sampling_s=float(delay_raw.get("sampling_s", 0.0)),
+            transport_s=float(delay_raw.get("transport_s", 0.0)),
+            dead_volume_s=float(delay_raw.get("dead_volume_s", 0.0)),
+            analysis_s=float(delay_raw.get("analysis_s", 0.0)),
+        ),
+    )
+
+
+def _optional_float(value: Any) -> float | None:
+    return None if value in {None, ""} else float(value)
+
+
+def load_config(path: Path) -> tuple[list[DatasetConfig], MergeConfig]:
+    raw = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict) or not isinstance(raw.get("datasets"), list):
+        raise ValueError("Configuration must contain a 'datasets' list")
+    datasets = [_dataset_from_dict(item, path.parent) for item in raw["datasets"]]
+    merge_raw = raw.get("merge", {})
+    merge = MergeConfig(
+        timeline=merge_raw.get("timeline", "union"),
+        reference_dataset=merge_raw.get("reference_dataset"),
+        experiment_origin=merge_raw.get("experiment_origin"),
+        continuous_method=merge_raw.get("continuous_method", "linear"),
+        stepwise_method=merge_raw.get("stepwise_method", "previous"),
+        exact_tolerance_s=float(merge_raw.get("exact_tolerance_s", 1e-9)),
+    )
+    return datasets, merge
+
+
+def config_as_dict(datasets: list[DatasetConfig], merge: MergeConfig) -> dict[str, Any]:
+    dataset_items: list[dict[str, Any]] = []
+    for dataset in datasets:
+        item = asdict(dataset)
+        item["path"] = str(dataset.path)
+        item["time_representation"] = dataset.time_representation.value
+        item["alignment"]["method"] = dataset.alignment.method.value
+        for channel_item, channel in zip(item["channels"], dataset.channels, strict=True):
+            channel_item["data_type"] = channel.data_type.value
+        dataset_items.append(item)
+    return {"datasets": dataset_items, "merge": asdict(merge)}
+
+
+def save_config(datasets: list[DatasetConfig], merge: MergeConfig, path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(config_as_dict(datasets, merge), indent=2), encoding="utf-8")

operandomerge/controller.py

@@ -0,0 +1,63 @@
+"""GUI application state without a desktop-toolkit dependency."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol
+
+from operandomerge.config import load_config, save_config
+from operandomerge.export import export_excel
+from operandomerge.models import DatasetConfig, MergeConfig, MergeResult
+from operandomerge.service import MergeService
+
+
+class MergeRunner(Protocol):
+    def run(self, datasets: list[DatasetConfig], merge: MergeConfig) -> MergeResult: ...
+
+
+def merge_config_from_fields(
+    timeline: str,
+    reference_dataset: str,
+    experiment_origin: str,
+    continuous_method: str,
+    stepwise_method: str,
+    exact_tolerance_s: str,
+) -> MergeConfig:
+    """Convert GUI text controls into the same validated core model used by JSON."""
+
+    config = MergeConfig(
+        timeline=timeline,
+        reference_dataset=reference_dataset or None,
+        experiment_origin=experiment_origin or None,
+        continuous_method=continuous_method,
+        stepwise_method=stepwise_method,
+        exact_tolerance_s=float(exact_tolerance_s),
+    )
+    config.validate()
+    return config
+
+
+class GuiController:
+    """Testable GUI application layer; scientific work remains in MergeService."""
+
+    def __init__(self, service: MergeRunner | None = None) -> None:
+        self.service = service or MergeService()
+        self.datasets: list[DatasetConfig] = []
+        self.merge_config = MergeConfig()
+        self.result: MergeResult | None = None
+
+    def run_merge(self) -> MergeResult:
+        self.result = self.service.run(self.datasets, self.merge_config)
+        return self.result
+
+    def export(self, path: Path) -> None:
+        if self.result is None:
+            raise ValueError("Run a merge before exporting")
+        export_excel(self.result, path)
+
+    def load(self, path: Path) -> None:
+        self.datasets, self.merge_config = load_config(path)
+        self.result = None
+
+    def save(self, path: Path) -> None:
+        save_config(self.datasets, self.merge_config, path)

operandomerge/export.py

@@ -0,0 +1,66 @@
+"""Reproducible CSV/Excel and figure exports."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import matplotlib.pyplot as plt
+import pandas as pd
+from matplotlib.figure import Figure
+
+from operandomerge.models import MergeResult
+
+
+def qc_frame(result: MergeResult) -> pd.DataFrame:
+    return pd.DataFrame(
+        [issue.as_dict() for issue in result.qc],
+        columns=["severity", "code", "dataset", "channel", "message", "row"],
+    )
+
+
+def configuration_frame(configuration: dict[str, Any]) -> pd.DataFrame:
+    return pd.DataFrame(
+        [
+            {"setting": key, "value": json.dumps(value) if value is not None else ""}
+            for key, value in configuration.items()
+        ]
+    )
+
+
+def export_excel(result: MergeResult, path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with pd.ExcelWriter(path, engine="openpyxl") as writer:
+        result.merged.to_excel(writer, sheet_name="merged", index=False)
+        result.metadata.to_excel(writer, sheet_name="metadata", index=False)
+        result.provenance.to_excel(writer, sheet_name="provenance", index=False)
+        qc_frame(result).to_excel(writer, sheet_name="qc", index=False)
+        configuration_frame(result.configuration).to_excel(
+            writer, sheet_name="configuration", index=False
+        )
+
+
+def export_csv_bundle(result: MergeResult, directory: Path) -> None:
+    directory.mkdir(parents=True, exist_ok=True)
+    result.merged.to_csv(directory / "merged.csv", index=False)
+    result.metadata.to_csv(directory / "metadata.csv", index=False)
+    result.provenance.to_csv(directory / "provenance.csv", index=False)
+    qc_frame(result).to_csv(directory / "qc.csv", index=False)
+    configuration_frame(result.configuration).to_csv(directory / "configuration.csv", index=False)
+
+
+def plot_alignment(result: MergeResult, path: Path | None = None) -> Figure:
+    figure, axis = plt.subplots(figsize=(9, 5), constrained_layout=True)
+    time = result.merged["experiment_time_s"]
+    for column in result.merged.columns[1:]:
+        axis.plot(time, result.merged[column], marker=".", linewidth=1, label=column)
+    axis.set_xlabel("Experiment time / s")
+    axis.set_ylabel("Signal (source units)")
+    axis.set_title("OperandoMerge alignment preview")
+    if len(result.merged.columns) > 1:
+        axis.legend(loc="best", fontsize="small")
+    if path is not None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        figure.savefig(path, dpi=160)
+    return figure