@yeyuan98/opencode-bioresearcher-plugin 1.6.5 → 1.6.7

package/dist/skills/pzfx-io/pzfx.py

@@ -0,0 +1,1156 @@
+#!/usr/bin/env python3
+"""GraphPad Prism PZFX file reader, writer, and converter.
+
+Usage:
+    uv run python pzfx.py inspect <file>
+    uv run python pzfx.py read <file> [--table INDEX] [--format json|csv|tsv] ...
+    uv run python pzfx.py write <output_file> --data-file <path> --data-format <fmt> ...
+    uv run python pzfx.py edit <file> --column-title <name> --subcolumn INDEX --values '<json>' ...
+    uv run python pzfx.py add-column <file> --title "Col" --subcolumns N --values '<json>' ...
+    uv run python pzfx.py convert <file> [--format csv|tsv|json] ...
+"""
+
+import argparse
+import csv
+import io
+import json
+import os
+import re
+import sys
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+VALID_TABLE_TYPES = {"OneWay", "TwoWay", "XY", "Survival", "Contingency", "PartsOfWhole"}
+VALID_X_FORMATS = {"none", "numbers", "date", "error"}
+VALID_Y_FORMATS = {"replicates", "SD", "SE", "CV", "SDN", "SEN", "CVN", "low-high", "upper-lower-limits"}
+TABLE_TYPE_X_FORMAT = {
+    "OneWay": "none", "TwoWay": "none", "Contingency": "none",
+    "PartsOfWhole": "none", "XY": "numbers", "Survival": "numbers",
+}
+YFORMAT_SUBCOL_COUNT = {
+    "SD": 2, "SE": 2, "CV": 2,
+    "SDN": 3, "SEN": 3, "CVN": 3, "low-high": 3, "upper-lower-limits": 3,
+}
+YFORMAT_SUFFIXES: dict[str, list[str]] = {
+    "replicates": [],
+    "SD": ["_MEAN", "_SD"],
+    "SE": ["_MEAN", "_SE"],
+    "CV": ["_MEAN", "_CV"],
+    "SDN": ["_MEAN", "_SD", "_N"],
+    "SEN": ["_MEAN", "_SEM", "_N"],
+    "CVN": ["_MEAN", "_CV", "_N"],
+    "low-high": ["_MEAN", "_PLUSERROR", "_MINUSERROR"],
+    "upper-lower-limits": ["_MEAN", "_UPPERLIMIT", "_LOWERLIMIT"],
+}
+MINIMAL_TEMPLATE = (
+    "<!--Analyses, graphs and layouts as compressed binary."
+    " Don&apos;t edit this part of the file.-->\n\n"
+    '<Template dt:dt="bin.base64" xmlns:dt="urn:schemas-microsoft-com:datatypes">'
+    "eNqL ricCAAAPAw==</Template>"
+)
+
+# ---------------------------------------------------------------------------
+# Data classes
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Cell:
+    value: Optional[str] = None
+    excluded: bool = False
+
+
+@dataclass
+class ColumnData:
+    title: str
+    decimals: int = 0
+    width: int = 81
+    subcolumns: list[list[Cell]] = field(default_factory=list)
+    is_x_advanced: bool = False
+    x_advanced_version: Optional[str] = None
+
+
+@dataclass
+class PzfxTable:
+    table_id: str = "Table0"
+    table_type: str = "OneWay"
+    x_format: str = "none"
+    y_format: Optional[str] = None
+    replicates: Optional[int] = None
+    title: str = "Data 1"
+    is_huge: bool = False
+    floating_notes: list[str] = field(default_factory=list)
+    row_titles: Optional[list[str]] = None
+    x_column: Optional[ColumnData] = None
+    x_advanced_column: Optional[ColumnData] = None
+    y_columns: list[ColumnData] = field(default_factory=list)
+
+    @property
+    def row_count(self) -> int:
+        if self.y_columns and self.y_columns[0].subcolumns:
+            return len(self.y_columns[0].subcolumns[0])
+        if self.x_column and self.x_column.subcolumns:
+            return len(self.x_column.subcolumns[0])
+        if self.row_titles is not None:
+            return len(self.row_titles)
+        return 0
+
+
+@dataclass
+class PzfxFile:
+    tables: list[PzfxTable] = field(default_factory=list)
+    template_raw: str = ""
+    created_xml: str = ""
+    info_xml: str = ""
+    table_sequence_xml: str = ""
+    info_data: Optional[dict] = None
+    root_attrib: dict[str, str] = field(default_factory=dict)
+    _raw_pre_template: str = ""
+
+    # ------------------------------------------------------------------
+    # Factory: parse existing file
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def from_file(path: str) -> "PzfxFile":
+        if not os.path.exists(path):
+            _fail("FILE_NOT_FOUND", f"File not found: {path}", "Check the file path exists")
+
+        with open(path, "r", encoding="utf-8") as f:
+            text = f.read()
+
+        template_raw = ""
+        template_start = -1
+
+        comment_markers = ["<!--Analyses", "<!--Analyses,"]
+        for marker in comment_markers:
+            idx = text.find(marker)
+            if idx >= 0:
+                template_start = idx
+                break
+
+        if template_start < 0:
+            t_idx = text.find("<Template")
+            if t_idx >= 0:
+                nl = text.rfind("\n", 0, t_idx)
+                if nl >= 0 and text[nl:t_idx].strip().startswith("<!--"):
+                    template_start = nl
+                else:
+                    template_start = t_idx
+
+        if template_start >= 0:
+            template_raw = text[template_start:]
+            xml_text = text[:template_start].rstrip()
+            root_tag = _detect_root_tag(xml_text)
+            if root_tag:
+                xml_text += f"\n</{root_tag}>"
+        else:
+            xml_text = text
+
+        try:
+            root = ET.fromstring(xml_text)
+        except ET.ParseError as e:
+            _fail("PARSE_ERROR", f"XML parse error: {e}", "The file may be corrupted")
+
+        _strip_namespaces(root)
+
+        pf = PzfxFile()
+        pf.template_raw = template_raw
+        pf._raw_pre_template = xml_text
+        pf.root_attrib = dict(root.attrib)
+
+        created_el = root.find("Created")
+        if created_el is not None:
+            pf.created_xml = _element_to_string(created_el)
+
+        info_el = root.find("Info")
+        if info_el is not None:
+            pf.info_xml = _element_to_string(info_el)
+            pf.info_data = _parse_info(info_el)
+
+        ts_el = root.find("TableSequence")
+        if ts_el is not None:
+            pf.table_sequence_xml = _element_to_string(ts_el)
+
+        for tbl_el in root.iter():
+            tag = tbl_el.tag
+            if tag in ("Table", "HugeTable"):
+                tbl = _parse_table(tbl_el, tag == "HugeTable")
+                pf.tables.append(tbl)
+
+        return pf
+
+    # ------------------------------------------------------------------
+    # Factory: create from scratch
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def from_scratch(
+        table_type: str,
+        x_format: Optional[str] = None,
+        y_format: Optional[str] = None,
+        replicates: int = 1,
+        title: str = "Data 1",
+    ) -> "PzfxFile":
+        if x_format is None:
+            x_format = TABLE_TYPE_X_FORMAT.get(table_type, "none")
+        if y_format is None:
+            y_format = "replicates"
+
+        tbl = PzfxTable(
+            table_id="Table0",
+            table_type=table_type,
+            x_format=x_format,
+            y_format=y_format,
+            replicates=replicates if y_format == "replicates" else None,
+            title=title,
+        )
+
+        pf = PzfxFile()
+        pf.tables = [tbl]
+        pf.template_raw = MINIMAL_TEMPLATE
+        pf.created_xml = '<Created>\n<OriginalVersion CreatedByProgram="pzfx-io" CreatedByVersion="0.1.0" Login="" DateTime=""></OriginalVersion>\n</Created>'
+        pf.table_sequence_xml = '<TableSequence>\n\n<Ref ID="Table0" Selected="1"></Ref>\n</TableSequence>'
+        return pf
+
+    # ------------------------------------------------------------------
+    # Write
+    # ------------------------------------------------------------------
+
+    def to_file(self, path: str) -> dict[str, Any]:
+        xml_bytes = self._serialize()
+        try:
+            parent = os.path.dirname(path)
+            if parent:
+                os.makedirs(parent, exist_ok=True)
+            with open(path, "wb") as f:
+                f.write(b'<?xml version="1.0" encoding="UTF-8"?>')
+                if self.template_raw:
+                    close_tag = b"</GraphPadPrismFile>"
+                    if xml_bytes.endswith(close_tag):
+                        xml_bytes = xml_bytes[:-len(close_tag)]
+                    f.write(xml_bytes)
+                    f.write(b"\n\n")
+                    f.write(self.template_raw.encode("utf-8"))
+                else:
+                    f.write(xml_bytes)
+        except OSError as e:
+            _fail("WRITE_ERROR", f"Failed to write file: {e}", "Check output path and permissions")
+        return {"success": True, "file": path}
+
+    def _serialize(self) -> bytes:
+        root = ET.Element("GraphPadPrismFile", self.root_attrib if self.root_attrib else {"PrismXMLVersion": "5.00"})
+
+        if self.created_xml:
+            _append_xml_string(root, self.created_xml)
+
+        info_seq = ET.SubElement(root, "InfoSequence")
+        ET.SubElement(info_seq, "Ref", {"ID": "Info0", "Selected": "1"})
+
+        if self.info_xml:
+            _append_xml_string(root, self.info_xml)
+        else:
+            info = ET.SubElement(root, "Info", {"ID": "Info0"})
+            ET.SubElement(info, "Title").text = "Project info 1"
+            ET.SubElement(info, "Notes")
+            for name in ("Experiment Date", "Experiment ID", "Notebook ID", "Project", "Experimenter", "Protocol"):
+                c = ET.SubElement(info, "Constant")
+                ET.SubElement(c, "Name").text = name
+                ET.SubElement(c, "Value")
+
+        if self.table_sequence_xml:
+            _append_xml_string(root, self.table_sequence_xml)
+        else:
+            ts = ET.SubElement(root, "TableSequence")
+            for i, tbl in enumerate(self.tables):
+                ET.SubElement(ts, "Ref", {"ID": tbl.table_id, "Selected": "1"})
+
+        for tbl in self.tables:
+            tbl_el = _build_table_element(tbl)
+            root.append(tbl_el)
+
+        ET.indent(root, space="")
+        return ET.tostring(root, encoding="unicode", xml_declaration=False).encode("utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Parsing helpers
+# ---------------------------------------------------------------------------
+
+
+def _extract_title(el: ET.Element) -> str:
+    title_el = el.find("Title")
+    if title_el is None:
+        return ""
+    if title_el.text and title_el.text.strip():
+        return title_el.text.strip()
+    ta = title_el.find("TextAlign")
+    if ta is not None and ta.text:
+        return ta.text.strip()
+    return ""
+
+
+def _parse_subcolumn(sub_el: ET.Element) -> list[Cell]:
+    cells = []
+    for d_el in sub_el.iter("d"):
+        val = d_el.text
+        excluded = d_el.get("Excluded") == "1"
+        cells.append(Cell(value=val, excluded=excluded))
+    return cells
+
+
+def _parse_column_data(el: ET.Element, is_x_advanced: bool = False) -> ColumnData:
+    title = _extract_title(el)
+    decimals = int(el.get("Decimals", "0"))
+    width = int(el.get("Width", "81"))
+    subcols = []
+    for sc_el in el.findall("Subcolumn"):
+        subcols.append(_parse_subcolumn(sc_el))
+    col = ColumnData(
+        title=title, decimals=decimals, width=width,
+        subcolumns=subcols, is_x_advanced=is_x_advanced,
+    )
+    if is_x_advanced:
+        col.x_advanced_version = el.get("Version")
+    return col
+
+
+def _parse_table(tbl_el: ET.Element, is_huge: bool) -> PzfxTable:
+    tbl = PzfxTable()
+    tbl.table_id = tbl_el.get("ID", "Table0")
+    tbl.table_type = tbl_el.get("TableType", "OneWay")
+    tbl.x_format = tbl_el.get("XFormat", "none")
+    tbl.y_format = tbl_el.get("YFormat")
+    rep_str = tbl_el.get("Replicates")
+    tbl.replicates = int(rep_str) if rep_str else None
+    tbl.title = _extract_title(tbl_el)
+    tbl.is_huge = is_huge
+
+    for fn_el in tbl_el:
+        tag = fn_el.tag
+        if tag == "FloatingNote":
+            tbl.floating_notes.append(_element_to_string(fn_el))
+
+    rt_el = tbl_el.find("RowTitlesColumn")
+    if rt_el is not None:
+        sc = rt_el.find("Subcolumn")
+        if sc is not None:
+            tbl.row_titles = [
+                _get_cell_text(d) for d in sc.iter("d")
+            ]
+        else:
+            tbl.row_titles = []
+
+    xc_el = tbl_el.find("XColumn")
+    if xc_el is not None:
+        tbl.x_column = _parse_column_data(xc_el)
+
+    xac_el = tbl_el.find("XAdvancedColumn")
+    if xac_el is not None:
+        tbl.x_advanced_column = _parse_column_data(xac_el, is_x_advanced=True)
+
+    for yc_el in tbl_el.iter("YColumn"):
+        tbl.y_columns.append(_parse_column_data(yc_el))
+
+    return tbl
+
+
+def _get_cell_text(d_el: ET.Element) -> str:
+    if d_el.text:
+        return d_el.text.strip()
+    ta = d_el.find("TextAlign")
+    if ta is not None and ta.text:
+        return ta.text.strip()
+    return ""
+
+
+def _parse_info(info_el: ET.Element) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    title_el = info_el.find("Title")
+    if title_el is not None and title_el.text:
+        result["title"] = title_el.text
+    constants: dict[str, str] = {}
+    for c_el in info_el.iter("Constant"):
+        name_el = c_el.find("Name")
+        val_el = c_el.find("Value")
+        if name_el is not None:
+            constants[name_el.text or ""] = val_el.text if val_el is not None else ""
+    if constants:
+        result["constants"] = constants
+    return result
+
+
+def _strip_namespaces(root: ET.Element) -> None:
+    for el in root.iter():
+        if "}" in el.tag:
+            el.tag = el.tag.split("}", 1)[1]
+        attribs = {}
+        for key, val in el.attrib.items():
+            if "}" in key:
+                key = key.split("}", 1)[1]
+            attribs[key] = val
+        el.attrib = attribs
+
+
+def _detect_root_tag(xml_text: str) -> str:
+    m = re.search(r"<(\w+[\w:-]*)(?:\s[^>]*)?>", xml_text.lstrip())
+    if m:
+        return m.group(1)
+    return "GraphPadPrismFile"
+
+
+def _element_to_string(el: ET.Element) -> str:
+    ET.indent(el, space="")
+    return ET.tostring(el, encoding="unicode", xml_declaration=False)
+
+
+def _append_xml_string(parent: ET.Element, xml_str: str) -> None:
+    try:
+        el = ET.fromstring(xml_str)
+        parent.append(el)
+    except ET.ParseError:
+        pass
+
+
+# ---------------------------------------------------------------------------
+# Serialization helpers
+# ---------------------------------------------------------------------------
+
+
+def _build_title_element(title: str) -> ET.Element:
+    ta_match = re.match(r"^\s*$", title)
+    if ta_match:
+        el = ET.Element("Title")
+        el.text = title
+        return el
+    return _make_title_el(title)
+
+
+def _make_title_el(title: str) -> ET.Element:
+    el = ET.Element("Title")
+    el.text = title
+    return el
+
+
+def _build_subcolumn_element(cells: list[Cell]) -> ET.Element:
+    sc = ET.Element("Subcolumn")
+    for cell in cells:
+        d = ET.Element("d")
+        if cell.value is not None:
+            d.text = cell.value
+        if cell.excluded:
+            d.set("Excluded", "1")
+        sc.append(d)
+    return sc
+
+
+def _build_column_element(col: ColumnData, tag: str = "YColumn") -> ET.Element:
+    el = ET.Element(tag)
+    el.set("Width", str(col.width))
+    el.set("Decimals", str(col.decimals))
+    el.set("Subcolumns", str(len(col.subcolumns)))
+    el.append(_make_title_el(col.title))
+    for cells in col.subcolumns:
+        el.append(_build_subcolumn_element(cells))
+    return el
+
+
+def _build_x_column_element(col: ColumnData) -> ET.Element:
+    el = ET.Element("XColumn")
+    el.set("Width", str(col.width))
+    el.set("Subcolumns", str(len(col.subcolumns)))
+    el.set("Decimals", str(col.decimals))
+    el.append(_make_title_el(col.title))
+    for cells in col.subcolumns:
+        el.append(_build_subcolumn_element(cells))
+    return el
+
+
+def _build_x_advanced_element(col: ColumnData) -> ET.Element:
+    el = ET.Element("XAdvancedColumn")
+    if col.x_advanced_version:
+        el.set("Version", col.x_advanced_version)
+    el.set("Width", str(col.width))
+    el.set("Decimals", str(col.decimals))
+    el.set("Subcolumns", str(len(col.subcolumns)))
+    el.append(_make_title_el(col.title))
+    for cells in col.subcolumns:
+        el.append(_build_subcolumn_element(cells))
+    return el
+
+
+def _build_table_element(tbl: PzfxTable) -> ET.Element:
+    tag = "HugeTable" if tbl.is_huge else "Table"
+    el = ET.Element(tag)
+    el.set("ID", tbl.table_id)
+    el.set("XFormat", tbl.x_format)
+    el.set("TableType", tbl.table_type)
+    el.set("EVFormat", "AsteriskAfterNumber")
+    if tbl.y_format:
+        el.set("YFormat", tbl.y_format)
+    if tbl.replicates is not None:
+        el.set("Replicates", str(tbl.replicates))
+
+    el.append(_make_title_el(tbl.title))
+
+    for fn_xml in tbl.floating_notes:
+        _append_xml_string(el, fn_xml)
+
+    if tbl.row_titles is not None:
+        rt = ET.SubElement(el, "RowTitlesColumn", {"Width": "81"})
+        sc = ET.SubElement(rt, "Subcolumn")
+        for rt_val in tbl.row_titles:
+            d = ET.SubElement(sc, "d")
+            d.text = rt_val
+
+    if tbl.x_column is not None:
+        el.append(_build_x_column_element(tbl.x_column))
+
+    if tbl.x_advanced_column is not None:
+        el.append(_build_x_advanced_element(tbl.x_advanced_column))
+
+    for ycol in tbl.y_columns:
+        el.append(_build_column_element(ycol))
+
+    return el
+
+
+# ---------------------------------------------------------------------------
+# Value normalization
+# ---------------------------------------------------------------------------
+
+
+def _normalize_value(val: Optional[str]) -> Optional[Any]:
+    if val is None or val.strip() == "":
+        return None
+    val = val.strip()
+    val_comma = val.replace(",", ".")
+    try:
+        if "." in val_comma:
+            return float(val_comma)
+        else:
+            iv = int(val_comma)
+            try:
+                fv = float(val_comma)
+                if fv == iv and "." in val:
+                    return val
+                return iv
+            except ValueError:
+                return val
+    except ValueError:
+        return val
+
+
+def _cell_to_output(cell: Cell, mode: str) -> Optional[Any]:
+    if cell.excluded and mode == "exclude":
+        return None
+    norm = _normalize_value(cell.value)
+    if cell.excluded and mode == "star":
+        if norm is not None:
+            return f"{norm}*"
+        return "*"
+    return norm
+
+
+# ---------------------------------------------------------------------------
+# Subcolumn naming
+# ---------------------------------------------------------------------------
+
+
+def _yformat_subcol_names(yformat: Optional[str], n_subcols: int, col_title: str) -> list[str]:
+    if yformat is None or yformat == "replicates":
+        if n_subcols <= 1:
+            return [col_title]
+        return [f"{col_title}_{i}" for i in range(1, n_subcols + 1)]
+    suffixes = YFORMAT_SUFFIXES.get(yformat, [])
+    if not suffixes:
+        return [col_title] if n_subcols <= 1 else [f"{col_title}_{i}" for i in range(1, n_subcols + 1)]
+    return [f"{col_title}{s}" for s in suffixes[:n_subcols]]
+
+
+# ---------------------------------------------------------------------------
+# Read / output
+# ---------------------------------------------------------------------------
+
+
+def _table_to_json(tbl: PzfxTable, exclude_mode: str, include_row_titles: bool, include_x: bool) -> dict[str, Any]:
+    result: dict[str, Any] = {
+        "table_id": tbl.table_id,
+        "table_type": tbl.table_type,
+        "format": "json",
+        "exclude_mode": exclude_mode,
+    }
+
+    columns = []
+
+    if include_x and tbl.x_column is not None:
+        xcol = tbl.x_column
+        names = [xcol.title] * len(xcol.subcolumns) if len(xcol.subcolumns) <= 1 else [f"{xcol.title}_{i}" for i in range(len(xcol.subcolumns))]
+        data = []
+        for sc in xcol.subcolumns:
+            data.append([_cell_to_output(c, "keep") for c in sc])
+        columns.append({"title": xcol.title, "subcolumn_names": names, "data": data})
+
+    for ycol in tbl.y_columns:
+        n_sc = len(ycol.subcolumns)
+        names = _yformat_subcol_names(tbl.y_format, n_sc, ycol.title)
+        data = []
+        for sc in ycol.subcolumns:
+            data.append([_cell_to_output(c, exclude_mode) for c in sc])
+        columns.append({"title": ycol.title, "subcolumn_names": names, "data": data})
+
+    result["columns"] = columns
+
+    if include_row_titles and tbl.row_titles is not None:
+        result["row_titles"] = tbl.row_titles
+
+    return result
+
+
+def _table_to_tabular(tbl: PzfxTable, exclude_mode: str, include_row_titles: bool, include_x: bool, delimiter: str = "\t") -> str:
+    headers: list[str] = []
+    all_data: list[list[Optional[Any]]] = []
+
+    if include_row_titles and tbl.row_titles is not None:
+        headers.append("ROWTITLE")
+        all_data.append(list(tbl.row_titles))
+
+    if include_x and tbl.x_column is not None:
+        xcol = tbl.x_column
+        x_names = [xcol.title] * len(xcol.subcolumns) if len(xcol.subcolumns) <= 1 else [f"{xcol.title}_{i}" for i in range(len(xcol.subcolumns))]
+        for i, name in enumerate(x_names):
+            headers.append(name)
+            if i < len(xcol.subcolumns):
+                all_data.append([_cell_to_output(c, "keep") for c in xcol.subcolumns[i]])
+
+    for ycol in tbl.y_columns:
+        n_sc = len(ycol.subcolumns)
+        names = _yformat_subcol_names(tbl.y_format, n_sc, ycol.title)
+        for i, name in enumerate(names):
+            headers.append(name)
+            if i < len(ycol.subcolumns):
+                all_data.append([_cell_to_output(c, exclude_mode) for c in ycol.subcolumns[i]])
+
+    max_rows = max((len(col) for col in all_data), default=0)
+
+    output = io.StringIO()
+    writer = csv.writer(output, delimiter=delimiter, lineterminator="\n")
+    writer.writerow(headers)
+    for row_idx in range(max_rows):
+        row = []
+        for col in all_data:
+            if row_idx < len(col):
+                val = col[row_idx]
+                row.append("" if val is None else str(val))
+            else:
+                row.append("")
+        writer.writerow(row)
+
+    return output.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# Data input parsing (for write command)
+# ---------------------------------------------------------------------------
+
+
+def _parse_input_data(data_file: str, data_format: str) -> dict[str, Any]:
+    if not os.path.exists(data_file):
+        _fail("FILE_NOT_FOUND", f"Data file not found: {data_file}", "Check the data file path")
+
+    with open(data_file, "r", encoding="utf-8") as f:
+        raw = f.read()
+
+    if data_format == "json":
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as e:
+            _fail("PARSE_ERROR", f"JSON parse error: {e}", "Check JSON syntax")
+
+    sep = "\t" if data_format == "tsv" else ","
+    reader = csv.reader(io.StringIO(raw), delimiter=sep)
+    rows = list(reader)
+    if not rows:
+        return {"headers": [], "rows": []}
+
+    headers = rows[0]
+    data_rows = rows[1:]
+    columns: dict[str, list[str]] = {}
+    for h in headers:
+        columns[h] = []
+    for row in data_rows:
+        for i, h in enumerate(headers):
+            if i < len(row):
+                columns[h].append(row[i])
+            else:
+                columns[h].append("")
+
+    return {"headers": headers, "columns": columns, "rows": data_rows}
+
+
+def _data_to_table(data: dict[str, Any], table_type: str, x_format: str,
+                   y_format: str, replicates: int, title: str) -> PzfxTable:
+    tbl = PzfxTable(
+        table_id="Table0",
+        table_type=table_type,
+        x_format=x_format,
+        y_format=y_format,
+        replicates=replicates if y_format == "replicates" else None,
+        title=title,
+    )
+
+    if "headers" in data and "columns" in data:
+        headers = data["headers"]
+        cols = data["columns"]
+
+        row_title_key = None
+        for h in headers:
+            hl = h.upper().strip()
+            if hl in ("ROWTITLE", "ROW_TITLE", "ROWTITLES"):
+                row_title_key = h
+                break
+
+        x_keys = []
+        y_keys = []
+
+        if x_format != "none":
+            first_non_rt = None
+            for h in headers:
+                if h == row_title_key:
+                    continue
+                if first_non_rt is None:
+                    first_non_rt = h
+                    x_keys.append(h)
+                else:
+                    y_keys.append(h)
+        else:
+            for h in headers:
+                if h == row_title_key:
+                    continue
+                y_keys.append(h)
+
+        if row_title_key and row_title_key in cols:
+            tbl.row_titles = cols[row_title_key]
+
+        if x_keys:
+            x_title = x_keys[0]
+            x_vals = cols.get(x_title, [])
+            tbl.x_column = ColumnData(
+                title=x_title, decimals=8,
+                subcolumns=[[Cell(v) for v in x_vals]],
+            )
+
+        for yk in y_keys:
+            y_vals = cols.get(yk, [])
+            subcols_count = replicates if y_format == "replicates" else YFORMAT_SUBCOL_COUNT.get(y_format, 1)
+            per_sc = len(y_vals) // subcols_count if subcols_count > 0 else len(y_vals)
+            scs = []
+            for si in range(subcols_count):
+                start = si * per_sc
+                end = start + per_sc
+                chunk = y_vals[start:end]
+                scs.append([Cell(v) for v in chunk])
+            if scs:
+                tbl.y_columns.append(ColumnData(
+                    title=yk, decimals=2,
+                    width=162, subcolumns=scs,
+                ))
+
+    elif "headers" in data and "rows" in data:
+        headers = data["headers"]
+        rows = data["rows"]
+        for h in headers:
+            vals = [row[headers.index(h)] if h in row and headers.index(h) < len(row) else "" for row in rows]
+            tbl.y_columns.append(ColumnData(
+                title=h, decimals=2,
+                subcolumns=[[Cell(v) for v in vals]],
+            ))
+
+    return tbl
+
+
+# ---------------------------------------------------------------------------
+# Validation
+# ---------------------------------------------------------------------------
+
+
+def _validate_table(tbl: PzfxTable) -> list[str]:
+    errors: list[str] = []
+    if tbl.table_type not in VALID_TABLE_TYPES:
+        errors.append(f"Invalid TableType: {tbl.table_type}")
+    if tbl.x_format not in VALID_X_FORMATS:
+        errors.append(f"Invalid XFormat: {tbl.x_format}")
+    if tbl.y_format is not None and tbl.y_format not in VALID_Y_FORMATS:
+        errors.append(f"Invalid YFormat: {tbl.y_format}")
+
+    expected_xf = TABLE_TYPE_X_FORMAT.get(tbl.table_type)
+    if expected_xf and tbl.x_format != expected_xf:
+        if tbl.table_type == "XY" and tbl.x_format not in ("numbers", "date", "error"):
+            errors.append(f"TableType {tbl.table_type} requires XFormat in (numbers, date, error), got {tbl.x_format}")
+        elif tbl.table_type != "XY" and tbl.x_format != expected_xf:
+            errors.append(f"TableType {tbl.table_type} requires XFormat={expected_xf}, got {tbl.x_format}")
+
+    if tbl.y_format and tbl.y_format != "replicates":
+        expected = YFORMAT_SUBCOL_COUNT.get(tbl.y_format)
+        if expected:
+            for yc in tbl.y_columns:
+                if len(yc.subcolumns) != expected:
+                    errors.append(f"YFormat {tbl.y_format} requires {expected} subcolumns, column '{yc.title}' has {len(yc.subcolumns)}")
+
+    if tbl.table_type == "PartsOfWhole" and len(tbl.y_columns) != 1:
+        errors.append(f"PartsOfWhole requires exactly 1 YColumn, got {len(tbl.y_columns)}")
+
+    if tbl.table_type == "Contingency" and tbl.row_titles is None:
+        errors.append("Contingency requires RowTitlesColumn")
+
+    titles = [yc.title for yc in tbl.y_columns]
+    if len(titles) != len(set(titles)):
+        errors.append("YColumn titles must be unique")
+
+    return errors
+
+
+# ---------------------------------------------------------------------------
+# CLI Commands
+# ---------------------------------------------------------------------------
+
+
+def cmd_inspect(args: argparse.Namespace) -> None:
+    pf = PzfxFile.from_file(args.file)
+    result: dict[str, Any] = {"success": True, "file": os.path.abspath(args.file)}
+    tables_info = []
+    for tbl in pf.tables:
+        cols_info = []
+        if tbl.x_column:
+            cols_info.append({"title": tbl.x_column.title, "type": "XColumn", "subcolumns": len(tbl.x_column.subcolumns)})
+        if tbl.x_advanced_column:
+            cols_info.append({"title": tbl.x_advanced_column.title, "type": "XAdvancedColumn", "subcolumns": len(tbl.x_advanced_column.subcolumns)})
+        for yc in tbl.y_columns:
+            cols_info.append({"title": yc.title, "type": "YColumn", "subcolumns": len(yc.subcolumns)})
+        tables_info.append({
+            "table_id": tbl.table_id,
+            "table_type": tbl.table_type,
+            "x_format": tbl.x_format,
+            "y_format": tbl.y_format,
+            "replicates": tbl.replicates,
+            "title": tbl.title,
+            "is_huge": tbl.is_huge,
+            "row_count": tbl.row_count,
+            "columns": cols_info,
+        })
+    result["tables"] = tables_info
+    if pf.info_data:
+        result["info"] = pf.info_data
+    print(json.dumps(result, indent=2))
+
+
+def cmd_read(args: argparse.Namespace) -> None:
+    pf = PzfxFile.from_file(args.file)
+    idx = args.table
+    if idx < 0 or idx >= len(pf.tables):
+        _fail("VALIDATION_ERROR", f"Table index {idx} out of range (0-{len(pf.tables) - 1})", "Use inspect to see available tables")
+
+    tbl = pf.tables[idx]
+    exclude_mode = args.exclude_mode
+
+    if args.format in ("csv", "tsv"):
+        delim = "\t" if args.format == "tsv" else ","
+        output = _table_to_tabular(tbl, exclude_mode, args.include_row_titles, args.include_x, delim)
+        print(output, end="")
+    else:
+        result = _table_to_json(tbl, exclude_mode, args.include_row_titles, args.include_x)
+        result["success"] = True
+        print(json.dumps(result, indent=2))
+
+
+def cmd_write(args: argparse.Namespace) -> None:
+    table_type = args.table_type
+    x_format = args.x_format or TABLE_TYPE_X_FORMAT.get(table_type, "none")
+    y_format = args.y_format or "replicates"
+    replicates = args.replicates or 1
+    title = args.title or "Data 1"
+
+    data = _parse_input_data(args.data_file, args.data_format)
+
+    tbl = _data_to_table(data, table_type, x_format, y_format, replicates, title)
+    errors = _validate_table(tbl)
+    if errors:
+        _fail("VALIDATION_ERROR", "; ".join(errors), "Fix data to match table type constraints")
+
+    pf = PzfxFile.from_scratch(table_type, x_format, y_format, replicates, title)
+    pf.tables = [tbl]
+
+    if args.dry_run:
+        preview = {
+            "success": True, "dry_run": True,
+            "output_file": os.path.abspath(args.output_file),
+            "table_type": table_type, "x_format": x_format,
+            "y_format": y_format, "replicates": replicates,
+            "title": title,
+            "y_columns": [yc.title for yc in tbl.y_columns],
+            "row_count": tbl.row_count,
+        }
+        print(json.dumps(preview, indent=2))
+        return
+
+    pf.to_file(args.output_file)
+    print(json.dumps({"success": True, "file": os.path.abspath(args.output_file)}, indent=2))
+
+
+def cmd_edit(args: argparse.Namespace) -> None:
+    pf = PzfxFile.from_file(args.file)
+    idx = args.table
+    if idx < 0 or idx >= len(pf.tables):
+        _fail("VALIDATION_ERROR", f"Table index {idx} out of range", "Use inspect to see available tables")
+
+    tbl = pf.tables[idx]
+    col_title = args.column_title
+    sc_idx = args.subcolumn
+
+    target_col = None
+    for yc in tbl.y_columns:
+        if yc.title == col_title:
+            target_col = yc
+            break
+
+    if target_col is None:
+        if tbl.x_column and tbl.x_column.title == col_title:
+            target_col = tbl.x_column
+        else:
+            _fail("VALIDATION_ERROR", f"Column '{col_title}' not found", "Use inspect to see column names")
+
+    if sc_idx < 0 or sc_idx >= len(target_col.subcolumns):
+        _fail("VALIDATION_ERROR", f"Subcolumn index {sc_idx} out of range (0-{len(target_col.subcolumns) - 1})", "Check subcolumn count")
+
+    try:
+        values = json.loads(args.values)
+    except json.JSONDecodeError as e:
+        _fail("PARSE_ERROR", f"Invalid JSON in --values: {e}", "Provide a JSON array")
+
+    exclude_values = None
+    if args.exclude_values:
+        try:
+            exclude_values = json.loads(args.exclude_values)
+        except json.JSONDecodeError as e:
+            _fail("PARSE_ERROR", f"Invalid JSON in --exclude-values: {e}", "Provide a JSON array of booleans")
+
+    if args.dry_run:
+        old_vals = [c.value for c in target_col.subcolumns[sc_idx]]
+        preview = {
+            "success": True, "dry_run": True,
+            "column": col_title, "subcolumn": sc_idx,
+            "old_values": old_vals, "new_values": values,
+            "file": os.path.abspath(args.file),
+        }
+        print(json.dumps(preview, indent=2))
+        return
+
+    new_cells = []
+    for i, v in enumerate(values):
+        cell = Cell()
+        if v is None:
+            cell.value = ""
+        else:
+            cell.value = str(v)
+        if exclude_values and i < len(exclude_values):
+            cell.excluded = bool(exclude_values[i])
+        new_cells.append(cell)
+
+    target_col.subcolumns[sc_idx] = new_cells
+
+    output_path = args.output or args.file
+    pf.to_file(output_path)
+    print(json.dumps({"success": True, "file": os.path.abspath(output_path)}, indent=2))
+
+
+def cmd_add_column(args: argparse.Namespace) -> None:
+    pf = PzfxFile.from_file(args.file)
+    idx = args.table
+    if idx < 0 or idx >= len(pf.tables):
+        _fail("VALIDATION_ERROR", f"Table index {idx} out of range", "Use inspect to see available tables")
+
+    tbl = pf.tables[idx]
+
+    try:
+        values = json.loads(args.values)
+    except json.JSONDecodeError as e:
+        _fail("PARSE_ERROR", f"Invalid JSON in --values: {e}", "Provide a JSON array of arrays")
+
+    if not isinstance(values, list):
+        _fail("VALIDATION_ERROR", "--values must be a JSON array of arrays", "Example: [[1,2,3],[4,5,6]]")
+
+    n_sc = args.subcolumns
+    subcols = []
+    for i in range(n_sc):
+        if i < len(values):
+            sc_data = values[i]
+            cells = [Cell(str(v) if v is not None else "") for v in sc_data]
+        else:
+            cells = []
+        subcols.append(cells)
+
+    new_col = ColumnData(
+        title=args.title, decimals=2,
+        width=162, subcolumns=subcols,
+    )
+    tbl.y_columns.append(new_col)
+
+    errors = _validate_table(tbl)
+    if errors:
+        _fail("VALIDATION_ERROR", "; ".join(errors), "Fix column data")
+
+    if args.dry_run:
+        preview = {
+            "success": True, "dry_run": True,
+            "added_column": args.title,
+            "subcolumns": n_sc,
+            "row_count": max((len(sc) for sc in subcols), default=0),
+            "total_y_columns": len(tbl.y_columns),
+        }
+        print(json.dumps(preview, indent=2))
+        return
+
+    output_path = args.output or args.file
+    pf.to_file(output_path)
+    print(json.dumps({"success": True, "file": os.path.abspath(output_path)}, indent=2))
+
+
+def cmd_convert(args: argparse.Namespace) -> None:
+    pf = PzfxFile.from_file(args.file)
+    fmt = args.format or "csv"
+    exclude_mode = args.exclude_mode
+
+    idx = args.table
+    if idx is not None:
+        if idx < 0 or idx >= len(pf.tables):
+            _fail("VALIDATION_ERROR", f"Table index {idx} out of range", "Use inspect to see available tables")
+        tables = [pf.tables[idx]]
+    else:
+        tables = pf.tables
+
+    base = os.path.splitext(args.file)[0]
+
+    for i, tbl in enumerate(tables):
+        if fmt == "json":
+            result = _table_to_json(tbl, exclude_mode, True, True)
+            result["success"] = True
+            result["source_file"] = os.path.abspath(args.file)
+            out_path = args.output or f"{base}.json"
+            with open(out_path, "w", encoding="utf-8") as f:
+                json.dump(result, f, indent=2)
+        else:
+            delim = "\t" if fmt == "tsv" else ","
+            ext = ".tsv" if fmt == "tsv" else ".csv"
+            if len(tables) > 1:
+                out_path = args.output or f"{base}_Table{i}{ext}"
+            else:
+                out_path = args.output or f"{base}{ext}"
+            output = _table_to_tabular(tbl, exclude_mode, True, True, delim)
+            with open(out_path, "w", encoding="utf-8", newline="") as f:
+                f.write(output)
+
+    print(json.dumps({"success": True, "format": fmt, "tables_converted": len(tables)}, indent=2))
+
+
+# ---------------------------------------------------------------------------
+# Error handling
+# ---------------------------------------------------------------------------
+
+
+def _fail(category: str, message: str, hint: str = "") -> None:
+    result = {"success": False, "error": f"{category}: {message}"}
+    if hint:
+        result["hint"] = hint
+    print(json.dumps(result, indent=2))
+    sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="GraphPad Prism PZFX file reader/writer")
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # inspect
+    p = subparsers.add_parser("inspect", help="Show file metadata")
+    p.add_argument("file", help="Path to .pzfx file")
+
+    # read
+    p = subparsers.add_parser("read", help="Extract table data")
+    p.add_argument("file", help="Path to .pzfx file")
+    p.add_argument("--table", type=int, default=0, help="Table index (default: 0)")
+    p.add_argument("--format", choices=["json", "csv", "tsv"], default="json", help="Output format")
+    p.add_argument("--exclude-mode", choices=["keep", "exclude", "star"], default="exclude", help="Excluded data handling")
+    p.add_argument("--include-row-titles", action="store_true", help="Include row titles")
+    p.add_argument("--include-x", action="store_true", help="Include X column data")
+
+    # write
+    p = subparsers.add_parser("write", help="Create new PZFX file")
+    p.add_argument("output_file", help="Output .pzfx file path")
+    p.add_argument("--data-file", required=True, help="Input data file")
+    p.add_argument("--data-format", choices=["csv", "tsv", "json"], required=True, help="Input format")
+    p.add_argument("--table-type", required=True, choices=sorted(VALID_TABLE_TYPES), help="Table type")
+    p.add_argument("--x-format", choices=sorted(VALID_X_FORMATS), help="X format (auto-detected if omitted)")
+    p.add_argument("--y-format", choices=sorted(VALID_Y_FORMATS), help="Y format (default: replicates)")
+    p.add_argument("--replicates", type=int, help="Number of replicates")
+    p.add_argument("--title", help="Table title")
+    p.add_argument("--dry-run", action="store_true", help="Validate without writing")
+
+    # edit
+    p = subparsers.add_parser("edit", help="Modify existing PZFX file")
+    p.add_argument("file", help="Path to .pzfx file")
+    p.add_argument("--table", type=int, default=0, help="Table index")
+    p.add_argument("--column-title", required=True, help="Column title to edit")
+    p.add_argument("--subcolumn", type=int, default=0, help="Subcolumn index (0-based)")
+    p.add_argument("--values", required=True, help="JSON array of values")
+    p.add_argument("--exclude-values", help="JSON array of booleans for exclusion")
+    p.add_argument("--dry-run", action="store_true", help="Preview changes")
+    p.add_argument("--output", help="Output file path (default: in-place)")
+
+    # add-column
+    p = subparsers.add_parser("add-column", help="Add column to existing table")
+    p.add_argument("file", help="Path to .pzfx file")
+    p.add_argument("--table", type=int, default=0, help="Table index")
+    p.add_argument("--title", required=True, help="New column title")
+    p.add_argument("--subcolumns", type=int, required=True, help="Number of subcolumns")
+    p.add_argument("--values", required=True, help="JSON array of arrays")
+    p.add_argument("--dry-run", action="store_true", help="Preview changes")
+    p.add_argument("--output", help="Output file path (default: in-place)")
+
+    # convert
+    p = subparsers.add_parser("convert", help="Convert PZFX to other formats")
+    p.add_argument("file", help="Path to .pzfx file")
+    p.add_argument("--format", choices=["csv", "tsv", "json"], default="csv", help="Output format")
+    p.add_argument("--output", help="Output file path")
+    p.add_argument("--table", type=int, default=None, help="Table index (default: all)")
+    p.add_argument("--exclude-mode", choices=["keep", "exclude", "star"], default="exclude", help="Excluded data handling")
+
+    args = parser.parse_args()
+
+    if args.command == "inspect":
+        cmd_inspect(args)
+    elif args.command == "read":
+        cmd_read(args)
+    elif args.command == "write":
+        cmd_write(args)
+    elif args.command == "edit":
+        cmd_edit(args)
+    elif args.command == "add-column":
+        cmd_add_column(args)
+    elif args.command == "convert":
+        cmd_convert(args)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()