statdata-transfer

Statistical Data Format Converter

Safe by default — preview, not execute: the skill shows what it will read/convert and only writes a file when you explicitly ask. Every R-invoking path is opt-in and disabled by default.

Language

• English guide → README.md
• 中文指南 → README_zh-CN.md

This skill responds in the user's input language and auto-switches; runtime prompts switch by locale. SKILL.md body is English-only (agent-facing); bilingual walkthroughs live in the two READMEs.

Purpose

Read 50+ statistical-software and clinical-trial data formats into a pandas DataFrame, and inter-convert between most formats (SPSS ↔ Stata ↔ R ↔ SAS XPT ↔ Excel ↔ Parquet ↔ HDF5 ↔ JSON …). For statistical binary formats it preserves full variable/value labels and special-missing-value metadata; text/JSON formats preserve only a retainable subset.

Features

Supported Formats

50+ formats, sorted alphabetically.

✅=Full · ⚠️=Partial/conditional · ✗=Not preserved

12 detect-only formats (SAS CPORT .cpt, Statistica .sta, OxMetrics .in7, SYSTAT .sys/.syd, Paradox .db/.px, LIMDEP .lpw, NCSS .ncss, FST) give clear export guidance — see README.

Return Structure

{
    "dataframe": pd.DataFrame,
    "metadata": {
        "file_format": "spss_sav",
        "row_count": 100, "column_count": 10,
        "variable_labels": {"q1": "Question 1"},
        "value_labels": {"q1": {1: "Yes", 2: "No"}},
        "special_missing": {...},
    },
    "warnings": [],
    "column_report": {"q1": {"source_type": "int", "pandas_dtype": "int64"}},
}

Quick Start

# Check environment (optional install on request)
python scripts/check_env.py --install

In WorkBuddy (bilingual, auto-detects your language):

> convert data.sav to .dta
> read data.sav and show metadata
> 把 data.sav 转成 .dta 并保留变量标签

For complete code examples, see references/usage_examples.py.

Dependencies

requires:
  bins: [python3]
  packages:
    core: [pyreadstat>=1.3.5,<2, pyreadr>=0.4,<0.5, pandas>=2.0,<3]
    extended: [openpyxl, xlrd, scipy, h5py, pyarrow, lxml, odfpy, tableauhyperapi, dbfread, dbf, pyodbc]

Full list: requirements.txt

⚠️ Safety

• All R-invoking paths are opt-in and disabled by default; they only run when you pass allow_r_exec=True on a trusted file.
• Pure-Python parsers (pyreadr, mtbpy) are tried first and never execute code.
• No silent R fallback — if the pure-Python parser fails and allow_r_exec is not set, the skill raises a clear error.
• Writing an existing .hyper backs up to .bak before overwrite; on failure the original is untouched.
• Output for reference only; validate before regulatory submissions.

Security model (transparent disclosure)

License

MIT. See LICENSE.