社会科学研究复现包中的自述文档模板-夜雨聆风

社会科学研究复现包中的自述文档模板

连享会：2026五一论文班 · 线上
时间：5月2-4日
嘉宾：郭士祺 (上海交通大学)、戚树森 (厦门大学)、李学恒 (中山大学)
咨询：王老师 18903405450（微信）

温馨提示: 文中链接在微信中无法生效。请点击底部「阅读原文」。或直接长按/扫描如下二维码，直达原文：

作者：林枫 (南京大学)邮箱：fenglin@smail.nju.edu.cn

编者按：本文主要整理自下文，特此致谢！Source：Lars Vilhuber, Connolly, M., Koren, M., Llull, J., & Morrow, P. (2022). A template README for social science replication packages (v1.1). Social Science Data Editors. -Link-

写在前面

为了提升社会科学研究的可信度，越来越多的中文期刊开始要求或鼓励作者公开用于复现研究的数据和代码。然而，一个值得关注的现象是，极少有作者提供关于复现包的自述文档。这份文档的作用在于向读者说明复现研究结果所需的材料及其使用方法。它理应是复现包中不可或缺的组成部分，遗憾的是，它往往被大多数研究者所忽视。

为此，本文翻译整理了由 Lars Vilhuber，Miklos Kóren，Joan Llull，Marie Connolly 和 Peter Morrow 四位作者在 2022 年撰写的 A Template README for Social Science Replication Packages。这篇文章被许多社会科学期刊的数据编辑认为是自述文档的最佳实践。希望这篇推文能够得到研究者的重视，并在提交数据和代码的同时，附上一份规范的自述文档，来增强这些文件的可读性。

1. 概述

说明：概述是对可用材料的简要说明以及如何从头到尾运行这个项目的简要指南。

示例：复现包中的代码使用 Stata 和 Julia，从三个数据源 (Ruggles et al., 2018；Inglehart et al., 2019；BEA, 2016) 构建分析文件。两个主要的代码文件用于生成研究中的 15 张图片和 3 张表格，运行这些代码大约需要 14 个小时。

2. 数据可用性和来源声明

说明：每个自述文档都应包括对数据来源、位置和可访问性的描述，这些描述通常被称为“数据可用性声明” 。但是在某些情况下，作者没有使用外部数据。

□ 本文不涉及对外部数据的分析 (即没有使用任何数据，或者作者通过代码模拟生成了唯一的数据)。

如果勾选了上述方框，且没有提供模拟或拟合的数据文件，请直接跳到「4.运算要求」部分。否则，请继续。

说明：如果作者使用的是二手数据 (他们没有生成数据)，那么数据来源声明和数据可用性声明一致，并应描述 (a) 当前作者 (b) 任何未来用户访问数据的条件。如果数据由作者在实验室或实地实验中产生，或作为调查的一部分收集，则应描述数据产生过程，即调查或实验程序。

数据可用性声明应当包含这项研究中使用的全部数据，无论数据是否作为复现包的一部分提供，也无论其大小或范围如何。同时，数据可用性声明应提供足够的信息，即便是作者提供了文件，也需要让复现者能够从原始来源获得该数据。如果将数据作为复现包的一部分提供，作者需要清楚他们是否有权分发数据，在某些情况下，例如由于敏感性、IRB、数据使用协议中的专有条款等，数据分发可能会受到限制。

需要指出的是，数据可用性声明不能替换数据引用。通常来说，按照期刊要求或是作者写作风格，数据引用应出现在正文、附录或自述文件中。但是，数据引用仅提供在何处查找数据的信息，而不提供如何访问这些数据的信息。因此，数据可用性声明通过深入了解更多细节来增强数据引用，使研究人员能够评估作者使用数据的成本、复杂性和未来的可用性。

2.1 关于权力的声明

我证明这项研究的作者有权合法访问和使用研究中的数据；
我证明这项研究的作者已获得重新分发或发布本复现包中数据的许可，相应的权限记录在 LICENSE.txt 文件中。

2.2 数据许可证 (可选，但推荐)

说明：大多数数据库提供默认许可证，但不强加特定许可证。作者应主动在 LICENSE.txt 中提供许可证，与自述文档分开，它可能与任何代码的许可证结合在一起。某些数据可能受到继承的许可证要求，比如说它可能会要求当前作者以及后续用户引用数据的提供者。如果数据中包括多个许可证，LICENSE.txt 文件可能包含一系列相应的许可证，例如一个文件的自定义许可证和一个文件的 CC-BY 许可证。需要注意的是，复现包的创建者不能简单地定义许可证，许可证可能具有长期性，并且由原始数据创建者定义。

示例：这些数据遵循 Creative Commons / CC-BY-NC 许可协议，有关详细信息，请参阅 LICENSE.txt。

2.3 可用性摘要

所有数据都是公开的
有些数据无法公开
没有数据可被公开

2.4 每个数据源的详细信息

对于每一个数据源，需要在此处列出包含该数据源的文件。如果提供的是组合或加工后的数据文件，请在数据可用性声明之后单独列出它们。对于每一个数据源或文件，应具体情况具体分析。表格形式的总结可能会很有帮助。

数据名称	数据文件	位置	是否提供	引用
《当前人口调查 2018 》	cepr_march_2018.dta	data/	是	CEPR (2018)
《省政府工作报告》	coast_simplepoint2.csv; rivers_simplepoint2.csv; RAIL_dummies.dta; railways_Dissolve_Simplify_point2.csv	Data/maps/	是	政府部门 (2017)
《2017 SAT 成绩》	不可用	data/to_clean/	否	大学理事会 (2020)

2.5 作者收集的公开数据示例

示例：用于支撑这项研究结果的 [数据类型] 数据已存入 [名称] 数据库 ([DOI 或其他永久性标识符])。这些数据由作者收集，可根据知识共享非商业许可使用。

2.6 来自其它地方并提供的公开数据示例

示例：国民收入和产品账户 (NIPA) 数据从美国经济分析局下载 (BEA，2016)。我们使用表 30。数据可以在网站 https://apps.bea.gov/regional/downloadzip.cfm 中的 [个人收入 (州和地方)] 下，选择 [CAINC30：按县划分的经济概况] 后下载。也可以使用 https://apps.bea.gov/regional/zip/CAINC30.zip 直接下载数据。数据副本作为此存档的一部分提供。这些数据属于公共领域。

数据文件：CAINC30__ALL_AREAS_1969_2018.csv

2.7 需要注册并提供摘录的公开数据示例

示例：这项研究使用 IPUMS TERRA 数据 (Ruggles et al., 2018)。除非用于复现存档，IPUMS-TERRA 不允许重新分发数据。从 https://terra.ipums.org/citation 获得的权限记录在 data/IPUMS-terra 文件夹中。

注意：对“Ruggles et al. (2018)”的引用将在本自述文档的参考文件部分和这项研究的正文中说明。

数据文件：data/raw/ipums_terra_2018.dta

2.8 需要注册但不提供摘录的免费数据示例

示例：这项研究使用第六次世界价值观调查 (Inglehart et al., 2019)。数据受到再分发限制，但可以从 http://www.worldvaluessurvey.org/WVSDocumentationWV6.jsp 免费下载。选择 WV6_Data_Stata_v20180912，填写注册表，包括项目的简要描述，并同意使用条款。其中要注意“数据文件本身被重新分发”等条件。文件被保存在 data/raw 文件夹中。

注意：对“Inglehart et al. (2019)”的引用将在本自述文件的参考文献部分和这项研究的正文中说明。

数据文件：data/raw/WV6_Data_Stata_v20180912.dta (未提供)

2.9 保密数据示例

说明：引用和描述保密数据，特别是当它没有常规的分发渠道或在线登录界面时，可能会很棘手。可以精心编写一段引文 (参阅此处)，同时数据可用性声明应描述如何访问、联系谁、以及其他相关信息，例如所需的公民身份或费用。

示例：该项目的数据 (DESE, 2019) 是保密的，但可以通过与马萨诸塞州中小学教育部 (DESE) 签订数据使用协议获得。有兴趣访问数据的研究人员可以通过 [电子邮件] 联系 [姓名]，另请参阅 https://www.doe.mass.edu/research/contact.html。协商数据使用协议并获得数据访问权限可能需要几个月的时间，作者将在这项研究发表的后两年内协助任何合理的复现尝试。

2.10 人口普查局保密数据示例

示例：这项研究的所有结果均使用美国人口普查局的保密微观数据。如要访问人口普查微观数据，请按照此处有关如何编写通过联邦统计研究数据中心访问数据的提议的说明进行操作：https://www.census.gov/ces/rdcresearch/howtoapply.html。您必须在提议中请求以下数据集：

纵向商业数据库 (LBD)，2002 年和 2007 年
外贸数据库 – 进口 (IMP)，2002 年和 2007 年 […]

改编自 Fort (2016)

2.11 编辑过程中的初步代码示例

示例：数据清理和分析的代码作复现包的一部分提供。可在 https://dropbox.com/link/to/code/XYZ123ABC 上查看。一旦这项研究被有条件接收，它将被上传到 [期刊存储库]。

3. 数据集列表

说明：在某些情况下，作者将为每个数据源提供一个数据集 (文件)，以及合并它们的代码。在其他情况下，特别是当数据访问可能受到限制时，复现包可能仅包括导出或分析数据。应对每个文件进行描述，并以 Excel 或 CSV 表格的形式提供。

虽然用于分析和处理数据的软件的本机格式提供数据通常是最方便的，但并非所有格式都是“开放的”并且可以由其他 (免费) 软件读取。数据至少应以开源软件 (R、Python 等) 可以读取的格式提供，并且最好以非专有、便于存档的格式提供。

所有数据文件都应被完整记录。变量或列应有标签 (长格式有意义的名称)，并且应对数值进行解释。这可能意味着生成密码本、指向公共密码本或提供允许丰富描述的 (非专有) 格式的数据。这对于不可分发的数据尤其重要。

一些期刊要求提供与未公开的限制访问数据具有相似关键特征的合成或模拟数据，这被视为一种有益的尝试。合成数据的保真度水平可能有所不同，有时仅对调试有用，或者应该能够评估统计或计量经济学过程的关键特征及研究的主要结论。

数据文件	来源	备注	是否提供
data/raw/lbd.dta	LBD	保密	否
data/raw/terra.dta	IPUMS Terra	根据使用条款	是
data/derived/regression_input.dta	列出的全部	合并了多个数据源，作为表 2、3 和图 5 的输入	是

4. 运算要求

说明：一般来说，用于生成这项研究结果的特定代码将位于包含此自述文档的存储库中。然而，其他运算要求，例如，共享库或代码包、所需的软件、特定的计算硬件，对于复现的目标来说可能很重要，而且总是有用的。我们强烈建议提供用于安装或设置环境的脚本。Stata、R、Julia 的示例脚本很容易设置和实现。特定的软件可能有更复杂的工具：Python、Julia。

4.1 软件要求

说明：请列出整套代码的所有软件要求，包括任何操作系统要求。如果可能，建议将大部分依赖项与复现包一起分发，特别是那些来自未版本化的代码仓库、GitHub 存储库和个人网页的依赖项。在所有情况下，请务必列出所使用的软件版本。

Stata (代码运行的版本为 Stata 15)

estout (2018-05-12)
rdrobust (2019-01-05)
程序 0_setup.do 将在本地安装所有依赖项，并且应当运行一次。

Python 3.6.4

pandas 0.24.2
numpy 1.16.4
文件 requirements.txt 列出了这些依赖项，请第一步运行 pip install -r requirements.txt。有关创建和使用 requirements.txt 文件的更多说明，请参阅 https://pip.pypa.io/en/stable/user_guide/#ensuring-repeatability

英特尔 Fortran 编译器版本 20200104
Matlab (代码使用 Matlab Release 2018a 运行)
R 3.4.3

tidyr (0.8.3)
rdrobust (0.99.4)
文件 0_setup.R 将安装所有依赖项 (最新版本) ，并且应在运行其他程序之前运行一次

部分代码使用 bash 脚本，这可能需要 Linux
部分代码使用 Powershell 脚本，这可能需要 Windows 10 或更高版本

4.2 受控随机性

说明：一些估计代码使用随机数，且几乎总是由伪随机数生成器 (PRNG) 提供。出于可复制性的目的，应为它们设置确定性的种子，以便提供的数字序列对于原作者和任何复现者都是相同的。虽然这并不总是可能的，但这是许多期刊政策的要求。种子应该设置一次，而不是使用时间戳。如果使用并行处理，需要特别小心。如果按顺序使用多个程序，则必须注意如何调用这些程序，最好是从主程序调用，这样顺序就不会改变。

随机种子设置在程序 ______ 的第 ____ 行

4.3 内存和运行时间要求

说明：内存和计算时间要求也可能相关甚至至关重要。下面是一些示例文本。通过表或图进行展示可能很有帮助。例如，某些估算例程可能会运行数周，但数据准备和创建图片可能只需要几分钟。

4.3.1 概述

在标准 (当前年份) 台式机上重现分析所需要的大约时间：

< 10 分钟
10 – 60 分钟
1 – 2 小时
2 – 8 小时
8 – 24 小时
1 – 3 天
3 – 14 天
14 天
无法在台式机上运行，如下所述

4.3.2 细节

该代码上次在 MacOS 版本 10.14.4 的基于 Intel 的 4 核笔记本电脑上运行。
部分代码在 1024 GB RAM、12 TB 快速本地存储的 32 核 Intel 服务器上运行，计算花费 734 小时。
部分代码在 12 节点 AWS R3 集群上运行，消耗了 20,000 个核心小时。

说明：可以通过多种方式获取硬件和操作系统的标识：其中一些详细信息如下：

Windows：在文件资源管理器中右键单击 [此电脑] 并选择 [属性]
MAC：Apple 菜单 > 关于本机
LINUX：参考 tools/linux-system-info.sh 中的代码

5. 程序和代码的描述

说明：对程序文件及其用途进行高级概述，从复现存档中删除冗余或过时的文件。

programs/01_dataprep 中的程序将提取并重新格式化上面引用的所有数据集。文件 programs/01_dataprep/main.do 将运行它们。
programs/02_analysis 中的程序将生成这项研究中的所有表格和图片。程序 programs/02_analysis/main.do 将运行它们。从 main.do 调用的每个程序都会标记有它创建的表或图 (例如，05_table5.do)。输出文件被命名为相应的名称 (table5.tex，figure12.png)，并且应该很容易与这项研究的正文相关联。
programs/03_appendix 中的程序将生成在线附录中的所有表格和图片。程序 programs/03_appendix/main-appendix.do 将运行它们。
ado 文件已存储在 programs/ado 中，并且 main.do 文件设置了相应地 ADO 目录。
程序 programs/00_setup.do 将使用更新的 ado 包填充 programs/ado 目录，但为了精确复现，这不是必需的。文件 programs/00_setup.log 记录了上次更新的版本。
程序 programs/config.do 包含所有程序使用的参数，包括随机种子。请注意，随机种子为两个序列中的每一个设置一次 (在 02_analysis 和 03_appendix 中)。如果按照除下面列出的顺序以外的任何顺序运行，您的结果可能会有所不同。

大多数期刊数据库提供默认许可证，但不强加特定许可证。作者应主动在 LICENSE.txt 中提供许可证，与自述文档分开，它可能与任何数据的许可证结合在一起。某些数据可能受到继承的许可证要求，比如说一些代码的作者要求引用他们描述代码包的计量经济学文章。

示例：该代码根据 MIT/BSD/GPL [选择一个] 许可证获得许可。有关详细信息，请参阅 LICENSE.txt。

6. 对复现者的说明

说明：前几部分确保复现者已准备好所有进行复现所需的数据和软件。本节将具体描述复现的流程。该流程可能简单，也可能包含许多复杂步骤。建议以简洁的列表形式呈现，确保内容严格按照线性顺序排列，避免冗余的叙述。如果手动步骤超过 4-5 个，请根据逻辑顺序将其整合为一个主程序，示例如下：

编辑 programs/config.do 调整默认路径；
在新系统上运行 programs/00_setup.do 一次以设置工作环境；
下载上面引用的数据文件。每个文件都应以您下载的格式存储在准备好的 data/ 子目录中，请勿解压缩。每个目录中都提供了下载公用文件的脚本。作为 FSRDC 项目一部分请求的保密数据文件将出现在 /data 文件夹中。复现者不需要进一步采取行动；
运行 programs/01_main.do 以按顺序运行所有步骤。

programs/00_setup.do：将创建所有输出目录，安装所需的 ado 包。

如果希望更新此存档使用的 ado 包，请将参数 update_ado 更改为 yes。然而，这并不是成功复现这项研究所必需的

programs/01_dataprep：

这些程序是在 2018 年的不同时间运行的；
顺序不重要，如果需要，所有程序都可以并行运行；
programs/01_dataprep/main.do 将按顺序运行它们，这大约需要 2 个小时。

programs/02_analysis/main.do：

如果单独运行程序，请注意顺序很重要；
该程序最后一次运行是在 2019 年 7 月 4 日。

programs/03_appendix/main-appendix.do 该程序最后一次运行是在 2019 年 7 月 4 日。

图 1：可以使用文件夹 2_data/data_map 中提供的数据和 ArcGIS Desktop (版本 10.7.1) 按照以下说明复现该图：

在 ArcGIS ArcMap 中创建一个新的地图文档，浏览 [目录] 中的文件夹 2_data/data_map，其中包含文件 provinceborders.shp、lakes.shp 和 cities.shp；
将上面列出的文件拖放到新地图上，创建三个单独的图层。将 lakes 放在最上面的图层，cites 放在最下面的图层；
右键单击城市文件，在属性中选择变量 health … (更多详细信息)。

7. 图表和程序的列表

说明：程序应按编号清楚地标记处这项研究中出现的表格和图片。有时，这可能是显而易见的，例如名为 table1.do 的程序生成一个名为 table1.png 的文件。在所有情况下，请提供表格和图片的列表，并给出创建表格和图片的程序 (可能还有行号)。

注意：如果公共存储库不完整，就像在数据部分说的那样，因为无法提供所有数据，则表格列表应清楚表明哪些表格、图片和研究中的编号可以使用提供的公共材料复现。

提供的代码将复现：

这项研究中所有的数字；
这项研究中所有的表格和图片；
这项研究中选定的表格和图片，如下所述。

图或表	程序	行号	输出文件	注释
表 1	02_analysis/table1.do		summarystats.csv
表 2	02_analysis/table2and3.do	15	table2.csv
表 3	02_analysis/table2and3.do	145	table3.csv
图 1	– (无数据)			来源: Herodus (2011)
图 2	02_analysis/fig2.do		figure2.png
图 3	02_analysis/fig3.do		figure-robustness.png	需要保密数据

8. 参考文献

说明：与任何科学研究一样，应当有相应的参考文献。例如，我们在数据可用性声明中引用了 Ruggles et al. (2019) 和 DESE (2019) 等。因此，参考文献应该按照期刊的格式列在这里。

Steven Ruggles, Steven M. Manson, Tracy A. Kugler, David A. Haynes II, David C. Van Riper, and Maryia Bakhtsiyarava. 2018. “IPUMS Terra: Integrated Data on Population and Environment: Version 2 [dataset].” Minneapolis, MN: Minnesota Population Center, IPUMS. https://doi.org/10.18128/D090.V2.

Department of Elementary and Secondary Education (DESE), 2019. “Student outcomes database [dataset]” Massachusetts Department of Elementary and Secondary Education (DESE). Accessed January 15, 2019.

U.S. Bureau of Economic Analysis (BEA). 2016. “Table 30: “Economic Profile by County, 1969-2016.” (accessed Sept 1, 2017).

Inglehart, R., C. Haerpfer, A. Moreno, C. Welzel, K. Kizilova, J. Diez-Medrano, M. Lagos, P. Norris, E. Ponarin & B. Puranen et al. (eds.). 2014. World Values Survey: Round Six – Country-Pooled Datafile Version: http://www.worldvaluessurvey.org/WVSDocumentationWV6.jsp. Madrid: JD Systems Institute.

连享会：2026五一论文班 · 线上
时间：5月2-4日
嘉宾：郭士祺 (上海交通大学)、戚树森 (厦门大学)、李学恒 (中山大学)
咨询：王老师 18903405450（微信）