@yeyuan98/opencode-bioresearcher-plugin 1.6.5 → 1.6.7

package/README.md

@@ -137,6 +137,7 @@ Plugin-shipped skills are automatically copied into `.opencode/skills/` at plugi
 - `bioresearcher-core`: core patterns and utilities (retry, JSON tools, subagent waves) for skill development.
 - `env-jsonc-setup`: guided setup for database connection configuration (db-tools).
 - `gromacs-guides`: reusable guides for GROMACS molecular dynamics workflows.
+- `pzfx-io`: read, parse, write, and convert GraphPad Prism PZFX files (inspect, edit, add-column, CSV/TSV/JSON round-trips).
 - `bioresearcher-tests`: comprehensive test suite for plugin tools and skills.
 
 Prompt the following and follow along:

package/dist/skills/pzfx-io/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: pzfx-io
+description: Read, parse, write, and convert GraphPad Prism PZFX files
+allowedTools:
+  - Read
+  - Bash
+---
+
+# PZFX I/O
+
+This skill provides tools for working with GraphPad Prism PZFX files.
+
+## Quick Start
+
+### Step 1: Load This Skill
+The skill is loaded automatically when agent calls `skill pzfx-io`.
+
+### Step 2: Extract Skill Path
+From the `<skill_files>` section in the skill tool output, extract the `<skill_path>` value.
+
+### Step 3: Read the Relevant Guide
+```
+Read <skill_path>/guides/schema-reference.md
+Read <skill_path>/guides/read-parse.md
+Read <skill_path>/guides/write-edit.md
+Read <skill_path>/guides/convert.md
+```
+
+## Available Commands
+
+All commands are invoked via:
+```bash
+uv run python <skill_path>/pzfx.py <command> [options]
+```
+
+| Command | Purpose |
+|---------|---------|
+| `inspect` | Show file metadata (tables, columns, types) |
+| `read` | Extract table data to stdout (JSON/CSV/TSV) |
+| `write` | Create new PZFX file from CSV/TSV/JSON data |
+| `edit` | Modify cell values in an existing PZFX file |
+| `add-column` | Add a new column to an existing table |
+| `convert` | Convert PZFX to CSV/TSV/JSON files |
+
+## Available Guides
+
+| Task | Guide |
+|------|-------|
+| PZFX XML schema details | `guides/schema-reference.md` |
+| Reading and parsing files | `guides/read-parse.md` |
+| Writing and editing files | `guides/write-edit.md` |
+| Converting to other formats | `guides/convert.md` |
+
+## Guide Summaries
+
+### schema-reference.md
+Complete PZFX XML schema documentation:
+- File structure and XML style variants (Prism 6-7 vs 8+)
+- Table/Column element attributes and valid values
+- Cell data formats, excluded values, comma decimals
+- Validation rules per table type
+
+### read-parse.md
+How to inspect and read PZFX data:
+- `inspect` for metadata overview
+- `read` for data extraction (JSON, CSV, TSV)
+- Excluded data handling modes (keep, exclude, star)
+- Value normalization rules
+- Multi-table and HugeTable handling
+
+### write-edit.md
+Creating and modifying PZFX files:
+- `write` to create new files from CSV/TSV/JSON
+- `edit` to modify cell values (with exclusion flags)
+- `add-column` to append new columns
+- Dry-run mode for validation
+- Template preservation and round-trip safety
+
+### convert.md
+Converting PZFX to other formats:
+- CSV, TSV, JSON output formats
+- Single table or batch conversion
+- Custom output paths
+- Comparison with `read` command
+
+## Common Workflows
+
+### Inspect a file
+```bash
+uv run python <skill_path>/pzfx.py inspect <file.pzfx>
+```
+
+### Read data as CSV
+```bash
+uv run python <skill_path>/pzfx.py read <file.pzfx> --format csv --include-x --include-row-titles
+```
+
+### Edit a column
+```bash
+uv run python <skill_path>/pzfx.py edit <file.pzfx> --column-title "Col" --subcolumn 0 --values '[1,2,3]'
+```
+
+### Convert to CSV file
+```bash
+uv run python <skill_path>/pzfx.py convert <file.pzfx> --format csv
+```
+
+### Create new file from CSV
+```bash
+uv run python <skill_path>/pzfx.py write output.pzfx --data-file data.csv --data-format csv --table-type OneWay
+```

package/dist/skills/pzfx-io/guides/convert.md

@@ -0,0 +1,102 @@
+# Converting PZFX Files
+
+## Convert to CSV
+
+```bash
+uv run python pzfx.py convert <file.pzfx> --format csv
+```
+
+Creates `<basename>.csv` next to the original file.
+
+## Convert to TSV
+
+```bash
+uv run python pzfx.py convert <file.pzfx> --format tsv
+```
+
+## Convert to JSON
+
+```bash
+uv run python pzfx.py convert <file.pzfx> --format json
+```
+
+JSON output includes full structured data:
+```json
+{
+  "success": true,
+  "table_id": "Table0",
+  "table_type": "OneWay",
+  "columns": [...],
+  "row_titles": [...],
+  "source_file": "/path/to/file.pzfx"
+}
+```
+
+## Convert Specific Table
+
+For multi-table files, convert a single table:
+```bash
+uv run python pzfx.py convert <file.pzfx> --table 0 --format csv
+```
+
+## Convert All Tables
+
+Without `--table`, all tables are converted. For CSV/TSV, each table gets a separate file:
+```
+basename_Table0.csv
+basename_Table1.csv
+```
+
+## Custom Output Path
+
+```bash
+uv run python pzfx.py convert <file.pzfx> --format csv --output /path/to/output.csv
+```
+
+Note: `--output` is only used when converting a single table (or the last table).
+
+## Excluded Data Modes
+
+```bash
+uv run python pzfx.py convert <file.pzfx> --exclude-mode keep
+uv run python pzfx.py convert <file.pzfx> --exclude-mode star
+```
+
+| Mode | Effect |
+|------|--------|
+| `exclude` (default) | Excluded values omitted (empty cells) |
+| `keep` | Excluded values preserved as raw numbers |
+| `star` | Excluded values marked with asterisk (e.g., `90*`) |
+
+## Convert Output Includes
+
+By default, converted output includes:
+- Row titles (if present)
+- X column data (if present, for XY/Survival tables)
+- All Y column subcolumns with proper naming
+
+Column naming follows YFormat conventions:
+- Replicates: `Title_1`, `Title_2`
+- SD: `Title_MEAN`, `Title_SD`
+- SE: `Title_MEAN`, `Title_SE`
+- etc.
+
+## Batch Conversion Example
+
+Convert all PZFX files in a directory:
+```bash
+for f in *.pzfx; do
+  uv run python pzfx.py convert "$f" --format csv
+done
+```
+
+## Comparison with `read` Command
+
+| Feature | `read` | `convert` |
+|---------|--------|-----------|
+| Output to stdout | Yes | No (writes file) |
+| Write to file | No | Yes |
+| Include row titles | `--include-row-titles` | Always included |
+| Include X column | `--include-x` | Always included |
+| Multi-table | One at a time (`--table`) | All or one |
+| Use case | Quick inspection, piping | File export, batch processing |

package/dist/skills/pzfx-io/guides/read-parse.md

@@ -0,0 +1,116 @@
+# Reading and Parsing PZFX Files
+
+## Quick Inspect
+
+Get file metadata without extracting data:
+
+```bash
+uv run python pzfx.py inspect <file.pzfx>
+```
+
+Output includes: table IDs, types, formats, row counts, column titles and subcolumn counts.
+
+## Read Table Data
+
+### JSON format (default)
+```bash
+uv run python pzfx.py read <file.pzfx> --format json --include-x --include-row-titles
+```
+
+JSON structure:
+```json
+{
+  "table_id": "Table0",
+  "table_type": "XY",
+  "columns": [
+    {
+      "title": "X Title",
+      "subcolumn_names": ["X Title"],
+      "data": [[1.0, 2.0, 3.0]]
+    },
+    {
+      "title": "Sample",
+      "subcolumn_names": ["Sample_1", "Sample_2"],
+      "data": [[100.0, 90.0, 80.0], [50.0, 60.0, 70.0]]
+    }
+  ],
+  "row_titles": ["A", "B", "C"]
+}
+```
+
+### CSV/TSV format
+```bash
+uv run python pzfx.py read <file.pzfx> --format csv --include-x --include-row-titles
+uv run python pzfx.py read <file.pzfx> --format tsv --include-x
+```
+
+Output:
+```
+ROWTITLE,XX,Ya_1,Ya_2,Yb_1,Yb_2
+A,1.0,100.0,50.0,1.0,10.0
+B,2.0,90.0,60.0,2.0,9.0
+C,3.0,80.0,70.0,3.0,8.0
+```
+
+## Multi-Table Files
+
+Specify table index (0-based):
+```bash
+uv run python pzfx.py read <file.pzfx> --table 1 --format csv
+```
+
+Use `inspect` first to see how many tables exist.
+
+## Excluded Data Handling
+
+Prism supports "excluding" (striking through) data points. Control with `--exclude-mode`:
+
+| Mode | Effect | Example |
+|------|--------|---------|
+| `exclude` (default) | Excluded values → `null`/empty | `[100, null, 80]` |
+| `keep` | Excluded values kept as-is | `[100, 90, 80]` |
+| `star` | Append asterisk to excluded | `[100, "90*", 80]` |
+
+```bash
+uv run python pzfx.py read <file.pzfx> --exclude-mode star --format csv
+```
+
+## Value Normalization
+
+Values are automatically normalized:
+- `"42."` → integer `42`
+- `"3.14"` → float `3.14`
+- `"3,5"` → float `3.5` (comma-decimal notation)
+- `""` or empty → `null`
+- Non-numeric text → kept as string
+
+## Reading Specific Table Types
+
+### XY Tables (with X column)
+```bash
+uv run python pzfx.py read <file.pzfx> --include-x --format csv
+```
+
+### Contingency Tables (with row titles)
+```bash
+uv run python pzfx.py read <file.pzfx> --include-row-titles --format csv
+```
+
+### Date-Formatted X Columns
+XColumn stores fractional years; XAdvancedColumn stores formatted date strings. Both are included with `--include-x`.
+
+### HugeTable Files
+Handled identically to regular Tables. `inspect` shows `"is_huge": true`.
+
+## Error Output Format
+
+On failure, JSON error is returned:
+```json
+{
+  "success": false,
+  "error": "CATEGORY: message",
+  "hint": "Suggested fix"
+}
+```
+
+Error categories: `FILE_NOT_FOUND`, `PARSE_ERROR`, `VALIDATION_ERROR`

package/dist/skills/pzfx-io/guides/schema-reference.md

@@ -0,0 +1,167 @@
+# PZFX Schema Reference
+
+## File Structure
+
+Every PZFX file follows this layout:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<GraphPadPrismFile PrismXMLVersion="5.00">
+  <Created>...</Created>
+  <InfoSequence><Ref ID="Info0" Selected="1"></Ref></InfoSequence>
+  <Info ID="Info0">...</Info>
+  <TableSequence><Ref ID="Table0" Selected="1"></Ref></TableSequence>
+  <Table ...>...</Table>
+  <!--Analyses, graphs and layouts as compressed binary. Don't edit this part of the file.-->
+  <Template dt:dt="bin.base64" xmlns:dt="urn:schemas-microsoft-com:datatypes">base64...</Template>
+</GraphPadPrismFile>
+```
+
+The `<Template>` block is an opaque base64-encoded zlib blob containing graphs, analyses, and layouts. It must never be modified.
+
+## XML Style Variants
+
+| Variant | Prism Version | Features |
+|---------|---------------|----------|
+| Classic | 6-7 | Closing tags (`</Subcolumn></YColumn>`), no xmlns |
+| Modern  | 8+  | Self-closing tags (`<Subcolumn/>`), `xmlns="http://graphpad.com/prism/Prism.htm"` on root |
+
+Both variants are handled by stripping XML namespaces at parse time.
+
+## Table Element Attributes
+
+```xml
+<Table ID="Table0" XFormat="numbers" YFormat="replicates" Replicates="2"
+       TableType="XY" EVFormat="AsteriskAfterNumber">
+```
+
+| Attribute | Required | Values |
+|-----------|----------|--------|
+| ID | Yes | Unique table identifier (e.g. "Table0") |
+| TableType | Yes | `OneWay`, `TwoWay`, `XY`, `Survival`, `Contingency`, `PartsOfWhole` |
+| XFormat | Yes | `none`, `numbers`, `date`, `error` |
+| YFormat | Conditional | `replicates`, `SD`, `SE`, `CV`, `SDN`, `SEN`, `CVN`, `low-high`, `upper-lower-limits` |
+| Replicates | Conditional | Integer, required when YFormat="replicates" |
+| EVFormat | Yes | Always `AsteriskAfterNumber` |
+
+### TableType to XFormat Mapping
+
+| TableType | Required XFormat |
+|-----------|-----------------|
+| OneWay | none |
+| TwoWay | none |
+| Contingency | none |
+| PartsOfWhole | none |
+| XY | numbers (or date, error) |
+| Survival | numbers |
+
+## Column Types
+
+### XColumn (XY/Survival tables only)
+
+```xml
+<XColumn Width="199" Subcolumns="1" Decimals="8">
+  <Title>X Title</Title>
+  <Subcolumn>
+    <d>1.0</d>
+    <d>2.0</d>
+  </Subcolumn>
+</XColumn>
+```
+
+- When XFormat="error", has 2 subcolumns (value ± error)
+- Subcolumns count is always 1 for numbers/date formats
+
+### XAdvancedColumn (Date-formatted X columns)
+
+```xml
+<XAdvancedColumn Version="1" Width="199" Decimals="8" Subcolumns="1">
+  <Title>Date X</Title>
+  <Subcolumn>
+    <d>2023-01-15</d>
+  </Subcolumn>
+</XAdvancedColumn>
+```
+
+- Stores formatted date strings alongside XColumn fractional years
+- Always paired with an XColumn when XFormat="date"
+
+### YColumn
+
+```xml
+<YColumn Width="89" Decimals="0" Subcolumns="2">
+  <Title>Sample</Title>
+  <Subcolumn><d>1.</d><d>2.</d></Subcolumn>
+  <Subcolumn><d>3.</d><d>4.</d></Subcolumn>
+</YColumn>
+```
+
+Subcolumn count depends on YFormat:
+
+| YFormat | Subcolumns | Naming Convention |
+|---------|------------|-------------------|
+| replicates | = Replicates | `{Title}_1`, `{Title}_2`, ... |
+| SD | 2 | `{Title}_MEAN`, `{Title}_SD` |
+| SE | 2 | `{Title}_MEAN`, `{Title}_SE` |
+| CV | 2 | `{Title}_MEAN`, `{Title}_CV` |
+| SDN | 3 | `{Title}_MEAN`, `{Title}_SD`, `{Title}_N` |
+| SEN | 3 | `{Title}_MEAN`, `{Title}_SEM`, `{Title}_N` |
+| CVN | 3 | `{Title}_MEAN`, `{Title}_CV`, `{Title}_N` |
+| low-high | 3 | `{Title}_MEAN`, `{Title}_PLUSERROR`, `{Title}_MINUSERROR` |
+| upper-lower-limits | 3 | `{Title}_MEAN`, `{Title}_UPPERLIMIT`, `{Title}_LOWERLIMIT` |
+
+### RowTitlesColumn (Contingency tables)
+
+```xml
+<RowTitlesColumn Width="81">
+  <Subcolumn>
+    <d>Male</d>
+    <d>Female</d>
+  </Subcolumn>
+</RowTitlesColumn>
+```
+
+## Cell Data (`<d>` Elements)
+
+```xml
+<d>42.5</d>                        <!-- Normal value -->
+<d>3,5</d>                         <!-- Comma decimal (3.5) -->
+<d Excluded="1">99.0</d>           <!-- Excluded/strikethrough value -->
+<d></d>                            <!-- Empty cell -->
+<d><TextAlign>Label</TextAlign></d> <!-- Text cell (non-numeric) -->
+```
+
+- Comma-as-decimal: values like `3,5` are normalized to `3.5`
+- Excluded cells have `Excluded="1"` attribute
+- Empty `<d></d>` or `<d/>` represents missing data
+
+## Other Elements
+
+### Info Block
+```xml
+<Info ID="Info0">
+  <Title>Project info 1</Title>
+  <Notes></Notes>
+  <Constant><Name>Experiment Date</Name><Value>2024-01-01</Value></Constant>
+</Info>
+```
+
+### HugeTable
+Identical to `Table` internally, just uses `<HugeTable>` tag for large datasets.
+
+### FloatingNote
+```xml
+<FloatingNote ID="#0" Width="262" Height="137" Left="451" Top="33" Expanded="1">
+  <Title>Note</Title>
+  <Content>Some annotation text</Content>
+</FloatingNote>
+```
+
+## Validation Rules
+
+1. PartsOfWhole tables must have exactly 1 YColumn
+2. Contingency tables must have a RowTitlesColumn
+3. YColumn titles must be unique within a table
+4. SD/SE/CV format requires exactly 2 subcolumns per YColumn
+5. SDN/SEN/CVN/low-high/upper-lower-limits requires exactly 3 subcolumns
+6. XY tables require XFormat in (numbers, date, error)

package/dist/skills/pzfx-io/guides/write-edit.md

@@ -0,0 +1,150 @@
+# Writing and Editing PZFX Files
+
+## Creating New PZFX Files
+
+### From CSV/TSV data
+```bash
+uv run python pzfx.py write output.pzfx \
+  --data-file data.csv \
+  --data-format csv \
+  --table-type OneWay
+```
+
+### From TSV data
+```bash
+uv run python pzfx.py write output.pzfx \
+  --data-file data.tsv \
+  --data-format tsv \
+  --table-type XY \
+  --x-format numbers \
+  --y-format replicates \
+  --replicates 2
+```
+
+### From JSON data
+```bash
+uv run python pzfx.py write output.pzfx \
+  --data-file data.json \
+  --data-format json \
+  --table-type TwoWay \
+  --y-format SD
+```
+
+### Input CSV/TSV Format
+
+Headers determine column assignment. For XY tables, the first non-ROWTITLE column becomes the X column:
+
+```csv
+ROWTITLE,Xconc,Ya,Yb
+A,1.0,100,50
+B,2.0,90,60
+C,3.0,80,70
+```
+
+For non-XY tables (XFormat=none), all columns become YColumns:
+
+```csv
+Aa,Bb
+1,100
+2,90
+3,80
+```
+
+### Dry Run (validate without writing)
+```bash
+uv run python pzfx.py write output.pzfx \
+  --data-file data.csv --data-format csv \
+  --table-type OneWay --dry-run
+```
+
+## Editing Existing Files
+
+### Modify cell values
+```bash
+uv run python pzfx.py edit <file.pzfx> \
+  --column-title "Aa" \
+  --subcolumn 0 \
+  --values '[10,20,30,40]'
+```
+
+### Edit with exclusion flags
+```bash
+uv run python pzfx.py edit <file.pzfx> \
+  --column-title "Sample" \
+  --subcolumn 0 \
+  --values '[100,90,80]' \
+  --exclude-values '[false,true,false]'
+```
+
+### Edit and save to different file
+```bash
+uv run python pzfx.py edit <file.pzfx> \
+  --column-title "Aa" \
+  --subcolumn 0 \
+  --values '[10,20,30,40]' \
+  --output modified.pzfx
+```
+
+### Preview changes without writing
+```bash
+uv run python pzfx.py edit <file.pzfx> \
+  --column-title "Aa" \
+  --subcolumn 0 \
+  --values '[10,20,30,40]' \
+  --dry-run
+```
+
+## Adding Columns
+
+### Add a single-subcolumn column
+```bash
+uv run python pzfx.py add-column <file.pzfx> \
+  --title "NewCol" \
+  --subcolumns 1 \
+  --values '[[1,2,3,4]]' \
+  --output modified.pzfx
+```
+
+### Add a multi-subcolumn column (e.g., Mean ± SD)
+```bash
+uv run python pzfx.py add-column <file.pzfx> \
+  --title "Treatment" \
+  --subcolumns 2 \
+  --values '[[100,110,120],[10,20,30]]' \
+  --output modified.pzfx
+```
+
+The `--values` is a JSON array of arrays: one inner array per subcolumn.
+
+### Dry run
+```bash
+uv run python pzfx.py add-column <file.pzfx> \
+  --title "NewCol" --subcolumns 1 \
+  --values '[[1,2,3]]' --dry-run
+```
+
+## Table Type Constraints
+
+| TableType | XFormat | YColumns | Special |
+|-----------|---------|----------|---------|
+| OneWay | none | >= 1 | Default column type |
+| TwoWay | none | >= 1 | Supports error formats |
+| XY | numbers/date/error | >= 1 | Requires XColumn |
+| Survival | numbers | >= 1 | X = time, Y = event |
+| Contingency | none | >= 1 | Requires RowTitlesColumn |
+| PartsOfWhole | none | exactly 1 | Pie chart data |
+
+## Template Preservation
+
+All write/edit operations preserve the original `<Template>` base64 blob unchanged. This ensures graphs, analyses, and layouts survive round-trips.
+
+## Round-Trip Safety
+
+Read → edit → write preserves:
+- All columns not being edited
+- XColumn and XAdvancedColumn data
+- RowTitlesColumn data
+- FloatingNote annotations
+- Table metadata (ID, type, format, replicates)
+- The complete Template blob
+- Info block data

package/dist/skills/pzfx-io/pyproject.toml

@@ -0,0 +1,6 @@
+[project]
+name = "pzfx-io-skill"
+version = "0.1.0"
+description = "GraphPad Prism PZFX file read/write skill"
+requires-python = ">=3.10"
+dependencies = []