发帖
雷达卡
投稿时被要求交复现包，多数人的第一反应是把文件夹压缩一下传上去。等编辑部回信说「无法复现表 3」，才发现问题不在代码跑不跑得动，而在没人知道该先跑哪个脚本、数据从哪来、用的哪个版本的包。
社会科学数据编辑（Social Science Data Editors, SSDE）维护的这份 template README，就是给这件事定标准的：它不是一篇讲原理的文章，而是一份可直接套用的 README 模板＋填写指引，被多家期刊的数据编辑采纳。作者是 Lars Vilhuber、Miklós Koren、Joan Llull、Marie Connolly、Peter Morrow，仓库在 GitHub，另有 Zenodo DOI 与 PDF／Word／LaTeX／Markdown 四种格式。
一份复现包 README 要先回答哪三个问题
模板开头的判断很直接：
a good README file should first provide a brief overview of the available material and a brief guide as to how to proceed from beginning to end, before then diving into the specifics.
也就是：先给材料概览，再给一条从开始到结束的路径，最后才进入细节。这个顺序反了（一上来就罗列几十个文件）读者会立刻失去方向。
落到模板的章节上，主体是八块：Overview（概览）、Data Availability and Provenance Statements（数据可得性与来源）、Dataset list（数据集清单）、Computational requirements（计算环境要求）、Description of programs/code（程序与代码说明）、Instructions to Replicators（给复现者的操作指引）、List of tables and programs（表与程序的对照）、References（引用）与 Acknowledgements（致谢）。
数据可得性怎么写：不止一个下载链接
模板里这块叫 DCAS（Data and Code Availability Statement，数据与代码可得性声明），它和「数据引用」不是一回事：
A DCAS goes beyond a typical data citation, as it describes additional information necessary for the obtention of the data.
差别在于「怎么拿到」这件事的全部障碍。模板明确列举，DCAS 需要写清可能涉及的注册要求、会员资格、申请流程、费用，以及其他资格条件——而不仅仅是一个下载 URL。这一条点中了很多复现包的死穴：作者以为给了链接就够了，读者点进去发现要机构账号、要签数据使用协议、要等两周审批。
DCAS 下面还分了几个子项：Statement about Rights（权利声明）、License for Data（数据许可，可选但建议）、Summary of Availability（可得性汇总）、Details on each Data Source（逐个数据源说明）。
七类数据来源各写什么
「逐个数据源说明」这块是整份模板最实用的部分，它按数据来源的性质给了七个示例：
| 数据情形 | 要写什么 |
| 作者自己采集的公开使用数据 | 采集方式、公开条件、随包提供 |
| 来自他处的公开使用数据 | 原始来源、版本、随包提供的方式 |
| 需注册才能用的公开数据（提供提取件） | 注册流程、费用、提供哪份提取件 |
| 需注册才能用的免费数据（不提供提取件） | 注册流程、获取路径、为什么不能随包给 |
| 保密数据 | 保密原因、获取条件、是否有替代方案 |
| 保密普查类数据（如 Census Bureau） | 申请渠道、使用限制、结果审核要求 |
| 编辑流程期间的初步代码 | 说明这是阶段性材料、后续会更新 |
这七类的价值在于：它承认「数据不能公开」是正常情况，但要求你把「为什么不能、别人怎么才能拿到、拿不到时怎么验证」写清楚。保密不等于不交代。
计算环境要交代到能被人复算
Computational requirements 这一块，模板要求逐项写，理由是「复现的难度差异可能极大」——简单的是一个笔记本加常用软件，复杂的要昂贵的商业软件甚至超算集群。需要写的是四类：
第一，软件及其版本号（写作时实际用的版本）；如果代码能在更低版本上跑，也要说明。
第二，所有附加包及其版本号。
第三，作者所用计算机的硬件规格：操作系统、CPU 型号与数量、内存、必要磁盘空间；用了多台机器就逐台写。
第四，在给定硬件下的墙钟时间（wall-clock time），用分钟或天表示。
这一节还有两个容易被忽略的子项。Software Requirements 之外是 Controlled Randomness（受控随机性）——凡涉及随机数的分析，要说明种子怎么设、怎么保证可复现。以及 Memory, Runtime, Storage Requirements，分 Summary（汇总）与 Details（明细）两层写：先给一句「在 16GB 内存的机器上约 40 分钟」，再给逐脚本的明细。
程序说明与运行顺序：先准备再分析
Description of programs/code 要求说明每个脚本做什么、输入输出是什么；Instructions to Replicators 则要求把操作指引分成两段：
The README should specify the instructions allowing a replicator to produce the same results. This should include separately instructions for data preparation and for analysis.
数据准备与分析分开写，是因为这两步的失败原因完全不同：前者多半是路径、编码、原始文件缺失，后者多半是包版本、随机种子、模型设定。混在一段里，读者出错时不知道该查哪一头。
模板还给了一条质量判断标准：
a good replication package uses a minimal number of automated scripts, with no manual interventions required unless absolutely unavoidable.
脚本越少越好，人工干预能免则免。这条标准的用意很实际：每多一个「这里手动改一下文件名」，复现失败率就上升一次。
表-程序对照表为什么最省事
List of tables and programs 这一节要求把论文里每张表、每张图与生成它的脚本对应起来，逐条列。格式通常是「表号—脚本名—输出文件名」。
这张表是编辑部最常用来验收的东西：他们不需要理解你的模型，只需要按表号找到脚本、跑一遍、比对数字。对作者来说，做这张表也是自查——凡是列不出对应脚本的表，多半是手工拼的或者用了没进包的中间文件。
许可与权利声明别留空
模板在数据与代码两块各留了一个可选项：License for Data 与 License for Code，都标注「optional, but recommended」。这不是形式主义：没有许可，别人即使拿到包也不知道能不能再用、能不能再分发，实务上等于默认「保留所有权利」。
模板本身也有许可，页面上写得很清楚：
The README is under a CC-BY-NC license.
Usage by commercial entities is allowed, reselling it is not.
也就是说可以自由使用（包括商业机构内部使用），但不能转售。对要套用这份模板的人，这句话意味着：直接拿它的结构改写成自己项目的 README 没问题，把模板本身打包卖钱不行。
最后提一句使用方式：模板给了 Markdown／txt、Word、LaTeX、PDF 四种格式，还有 GitHub Releases 里的正式版本与 Zenodo DOI。套用时建议保留章节顺序，只替换内容——因为期刊数据编辑是按这个顺序找信息的，你把「计算环境」挪到附录，审稿人就会多问一轮。
────────────────
回复本帖，可见这份 template README 的官方页面、GitHub 仓库与 Zenodo DOI、四种格式的直接下载地址、七个数据来源示例的完整清单与「表-程序对照」的填写样式，以及模板许可条款原文。
把经管之家装进你常用的 AI 智能体中 一键快捷安装经管之家 MCP／技能，让 AI 帮你查教程、找数据、读论坛帖子。 检索、阅读公开帖子不收费，安装可申请领取：3 通用积分＋100 论坛币＋3 元论坛资金 说明： AI 算力按所用平台规则计算；附件按原帖条件获取；福利领取条件以活动页面为准。 |
京公网安备 11010802022788号
