statdata-transfer / 统计数据格式转换器

致敬 Stat/Transfer — 业界格式转换标杆 / Honoring Stat/Transfer — the industry standard

Language Policy / 语言策略

• 默认英文；检测到中文环境时切换为中文提示。
• 常用模块备英文 + 中文两套；文档标题（不区分语言者）采用「英 / 中」顺序双语。
• 复杂 / 少用模块可暂只英文。

Core Capabilities / 核心能力

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) 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"}},
        # ... 全部元数据 / all metadata fields
    },
    "warnings": [],
    "column_report": {"q1": {"source_type": "int", "pandas_dtype": "int64"}},
}

Quick Start / 快速开始

# Check environment / 检查环境
python scripts/check_env.py --install

# Run via 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. 完整代码示例见 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 / 完整列表见 requirements.txt

Detailed Docs / 详细文档

• English: README.md — format limits, strategies, encoding, extension guide
• 中文: README_ZH.md — 格式限制、读入策略、编码注意事项、扩展指南

Security / 安全

• All R-invoking paths are opt-in & sandboxed by default / 所有调用 R 的路径默认隔离、需显式开启: reading .rda/.rds/.RData (readRDS()/load()), reading Minitab .mtw/.mpj and EpiData .rec (foreign::read.mtb()/read.epiinfo()), and writing R formats (.rda/.rds) are disabled by default. They only run when you explicitly 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 / 无静默 R 回退: If the pure-Python parser fails and allow_r_exec is not set, the skill raises a clear error instead of silently launching R — eliminating the risk of executing embedded code from untrusted files.
• R scripts are static templates / R 脚本为静态模板: When the opt-in R path is used, all R scripts are fully static templates; user inputs are passed only as CLI args (commandArgs(trailingOnly=TRUE) via jsonlite) — never concatenated into executable R code. Random temp filenames; no fixed paths.
• R bridge writes a temp CSV / R 桥接写临时 CSV: When R is used (opt-in), converted data is materialized to a temporary CSV on disk before being read back; the temp file is deleted immediately after use, but on crash or via backup/indexing tools it could briefly persist — avoid processing highly sensitive data through R-backed formats.
• No destructive writes / 无破坏性写入: Writing an existing .hyper first writes to a temp file; only after success is the existing file rotated to .bak (prior .bak demoted to .bak.1, never silently deleted), then atomically swapped in. On write failure the original is untouched.
• Pinned dependencies / 依赖已固定版本: Core deps carry upper-bound pins (pandas, pyreadstat, pyreadr) — see requirements.txt.
• Optional install / 可选安装: python scripts/check_env.py --install only runs on explicit request.
• Permissions required / 所需权限: Read the input file; write the output file to a path you specify. No network access unless you explicitly request package installation. No destructive writes — existing .hyper outputs are backed up to .bak before overwrite.
• Scope / 范围: Statistical data formats only. Text/JSON formats preserve metadata subset only — see «Format Limits» in README.

License / 许可证

MIT. See LICENSE. / 详见 LICENSE。