如何整理一份规范的论文复现文档?

发布时间:2023-03-20 阅读 862

Stata连享会   主页 || 视频 || 推文 || 知乎 || Bilibili 站

温馨提示: 定期 清理浏览器缓存,可以获得最佳浏览体验。

New! lianxh 命令发布了:
随时搜索推文、Stata 资源。安装:
. ssc install lianxh
详情参见帮助文件 (有惊喜):
. help lianxh
连享会新命令:cnssc, ihelp, rdbalance, gitee, installpkg

课程详情 https://gitee.com/lianxh/Course

课程主页 https://gitee.com/lianxh/Course

⛳ Stata 系列推文:

PDF下载 - 推文合集

作者:马雨驰 (辽宁大学)
邮箱mycmyc99@163.com

编者按:本文主要整理自 AEADataEditor-replication-template,特此致谢!


目录


在下载论文后,您可以根据文中步骤尝试复现论文结果,并在文档中记录复现论文的步骤、生成的错误以及为解决这些问题而采取的步骤。

必须执行“数据说明”和“代码说明”部分内容。如果数据存在,必须执行“数据检查”部分内容。如果时间足够(初始评估!),请执行“复现步骤”部分内容,如未执行请解释原因。

一些有用的链接:

1. 标题

[MC 编号][原稿标题] 复现结果

在上述标题中,将 [原稿标题] 替换为论文的实际标题,将 [MC 编号] 替换为原稿中心编号(例如,AEJPol-2017-0097)。

2. 数据说明

2.1 数据来源

找到所有输入数据的来源,并创建一个列表。对于每个数据的来源,请在文档中列出是否存在数据源、数据信息或代码簿以及汇总统计。如果汇总统计和代码簿可用于公共使用数据,则没有必要在文档中列出。无论在什么情况下,作者都可以在文档中直接加入可跳转的相关链接。不要忘记检查数据引用。在本节中,仅指出有问题的部分即可。例如,

  • 未提供数据集,但在 README 文件中提供了链接;
  • 未说明访问条件,结果该网站需要注册并付费;
  • 论文和 README 文件中均未引用数据。

2.2 分析数据文件

分别找到所有被提供的分析数据文件。分析数据文件由数据源中储存的代码生成,但并非每次储存都会生成文件。例如,

  • 未提到分析数据文件;
  • 提到了分析数据文件,但并未提供 (原因如下);
  • 提到并提供了分析数据文件,文件名如下。

在此处列出所有被提供的文件名。如果储存量过大,可以使用 "Git Bash" 程序来完成:

  • 查找 . -name *.dta;
  • 将列出所有 Stata 数据集。将 .dta 替换成 .Rdata 或其他扩展名来查找其他格式数据文件。
./Output_Empirical/data/census_shp/counties_coord.dta
./Output_Empirical/data/census_shp/counties_db.dta
./Output_Empirical/data/census_shp/state_coord.dta
./Output_Empirical/data/census_shp/state_db.dta

3. 数据存储

大多数数据都存储在 openICPSR,但仍需检查元数据是否完整。详细指南请见:https://aeadataeditor.github.io/aea-de-guidance/

3.1 要求

请检查储存文件是否满足以下要求:

  • README 文件采用 TXT、MD 或 PDF 格式;
  • 没有 ZIP 格式压缩文件需要储存到 openICPSR;
  • 标题符合指南(以“数据和代码:”或“代码:”开头);
  • 作者 (存在从属关系) 的排列顺序与论文相同。

如果上面的项目存在不满足的情况,请保留以下与不满足选项相关的 [必需] 项:

  • 请确保在数据和代码储存时提供 ASCII(txt)、Markdown(md) 或 PDF 版本的 README 文件。
  • openICPSR 不应存在可见的 ZIP 格式压缩文件。ZIP 格式压缩文件应通过“上传文件”上传到 openICPSR。请删除 ZIP 文件,然后使用“从 ZIP 导入”功能重新上传。
  • 请根据我们下放放置的详细指南检查 openICPSR 储存的标题。
  • 请在 openICPSR 中检查储存的作者和隶属关系。一般情况下,它们与原稿相同且顺序一致,但作者也可以采用与原稿不同的顺序储存。

详细指南请见 https://aeadataeditor.github.io/aea-de-guidance/

3.2 元数据储存

其中一些数据是特定于 openICPSR (JEL 分类、稿件编号) 的。其他数据可能存在于其他受信任的数据库 (Dataverse、Zenodo 等)。验证 openICPSR 的所有项目,与监管员核实是否有其他储存数据。

  • JEL 分类 (必需)
  • 稿件编号 (必需)
  • 主题词 (强烈推荐)
  • 地理范围 (强烈推荐)
  • 时间周期 (强烈推荐)
  • 收集日期 (建议)
  • 领域 (建议)
  • 数据类型 (建议)
  • 数据来源 (建议)
  • 观测单位 (建议)

检查上面的清单并从以下结果中选择一个:

  • [注] openICPSR 元数据充足。
  • [必需] 请更新被标记为(必需)的 openICPSR 元数据字段,以便在补充数据和代码时可以找到。
  • [建议] 我们建议您更新被标记为 (强烈推荐) 的 openICPSR 元数据字段,以便在补充数据和代码时可以找到。
  • [建议] 我们建议您更新被标记为 (建议) 的 openICPSR 元数据字段,以便在补充数据和代码时可以找到。

其他相关指南,请参阅 https://aeadataeditor.github.io/aea-de-guidance/data-deposit-aea-guidance.html

4. 数据检查

当数据都存在时,进行检查:

  • 数据是否可被读取(使用作者指定的软件)?
  • 数据集是归档格式 (CSV、TXT) 还是自定义格式 (DTA, SAS7BDAT, Rdata)?注:Numbers 和 Mathematica 数据文件不被视为存档安全文件,无法接收。
  • 数据文件是否有变量标签 (Stata:运行 describe using (name of DTA) 并检查“变量标签”中是否有内容)?
  • 运行检查 PII (如果使用 Stata:PII_stata_scan.do,来源于 这里) 并报告结果。注:该检查可能会出现很多误报,比如敏感字段识别不清,需要自行判断。

5. 代码说明

查看代码 (但暂时不要运行)。找到创建“分析文件”的程序 (“数据准备代码”。找到生成表格和图形的程序。但并不是所有存储文件在这些部分都有单独的程序。

找到所有图形、表格和文本中的数字,并创建一个列表,将它们在程序中的特定部分和行号与之对应。(使用此模板) 在本节中,仅需指出总结性描述,包括缺点。例如:

共有四个被提供的 Stata 的 do 文件,三个 Matlab 的 .m 文件,其中包含一个 "master.do" 文件。

  • 表 5:未找到生成表 5 的代码。
  • 在程序代码和 README 文件中均未找到表格是由哪段程序生成的。

文本中引用表格中的数字无需被单独列出,仅需列出表格和图形中未出现的文本中的数字。

6. 规定要求

作者可能对计算机软件、硬件等方面的条件作出了具体要求,请在该部分列出。这与复制者的计算环境不同。你可以根据实际情况,用没被列出的要求修改下面的例子。如果所有的要求都被列出来了,请选中“要求已完成”框。

  • 未指定要求
  • 软件要求如下:
    • 软件 1
    • 软件 2
  • 计算要求如下:
    • 集群大小等
  • 时间要求如下:
    • 必要的计算长度(小时、周等)
  • 要求已完成

也可以将作者列出的要求复制粘贴过来。

7. 要求缺失

如果某些方面 (软件、软件包、操作系统等) 的要求没有进行相关说明或说明不完整,请在该部分列出缺失的要求。请根据实际情况删除例子中没有必要的行。如果规定要求已完成,请删除该节,包括末尾标记为[必需]的部分。

  • 软件要求如下:
    • Stata
      • 版本
      • 软件包放在这
    • Matlab
      • 版本
    • R
      • 版本
      • R 软件包放在这
    • Python
      • 版本
      • Python 软件包放在这
    • 用其他所需软件替换此处,同上方已列出的格式一样
  • 计算要求如下:
    • 集群大小、磁盘大小、内存大小等
  • 时间要求如下:
    • 必要的计算长度 (小时、周等)

[必需] 请修改 README 文件,列出完整的要求。您可以直接复制上述部分并进行修改。

8. 复制者的计算环境

删除不相关的示例,根据自身情况进行调整。其中一些可以从 Stata 或 R 输出的标准记录获得。下面是一些常用的详细信息。其中一些可以通过以下三种方法获得:

  • (Windows) 右键单击“此电脑”
  • (Mac) 苹果菜单 > “关于本机”
  • (Linux) 请参阅 tools/linux-system-info.sh 中的代码

请同时列出您使用的软件 (特定版本。仅列出您使用的那些,并增添示例中未列出的内容:

  • Stata/MP 16.1
  • Matlab R2019a
  • Intel Compiler 3.14152

9. 复现步骤

请提供您读取代码和数据的详细过程。不用详细说明“我将它们保存在桌面上”之类的内容。请描述您对每条命令执行的操作。请描述您需要执行的其他操作 (“我必须更改多个程序”),无需详细说明。例如:

  • 根据提供的 URL 下载代码。
  • 根据 README 文件中写明的 URL 下载数据。需要注册(README 文件中未注明)。
  • 添加 config.do 生成的系统信息,注释掉生成记录,因为作者已经创建了记录文件。
  • 按照 README 文件运行代码,但是第三步不起作用。
  • 对第三步的运行方式进行更改,以使其正常工作。

10. 研究结果

请详细描述您对于每个数据准备代码、图片、表格和文本中的数字的研究结果并分为积极和消极两方面进行说明。您可以重复使用在代码说明部分创建的 Excel 文件。当运行出错时,尽可能精确地指出出错的步骤。如果图表出现了显著差异,请提供原稿内容的屏幕截图和您自己通过运行代码生成的图表。如果数字出现了显著差异,请提供原稿中的数字和复现生成的数字。如果不同的数字过多,请联系您的监管员。

数据准备代码,例如:

  • 程序 1-create-data.do 运行成功,输出预期数据。
  • 程序 2-create-appendix-data.do 未输出任何结果。

表格,例如:

  • 表 1:相同
  • 表 2:(数据未找到)
  • 表 3:第 5 行第 3 列有细微差异,生成结果为 0.003 而不是 0.3

图片,当图片看起来不同时,请使用论文的屏幕截图和程序生成的图表进行比较。将程序生成的图形作为存储库中的本地文件引用。例如:

  • 图 1:相同
  • 图 2:未提供程序
  • 图 3:论文版本看起来与程序生成的版本不同

文本中的数字,请列出文本中数字的页和行号。如果存在争议,请引用周围的文本,例如:“该比率下降到所有工作的 52%:已验证”。

没有文本数字,或所有文本数字都源于表格和图片。存在文本数字,但未在代码中找到。

  • 第 21 页,第 5 行:相同

11. 分类

在此处进行判定。完全复制可以包含少量表中数字的不重要的改变。当需要对程序进行更改且已成功实施时,也可以说此类复现属于完全复制。部分复制意味着大量 (>25%) 的程序或数据是不同的。

如果任一数据是保密且不可用的,则属于部分复制,并需要在原因中注明。如果所有数据都是机密的,则不太可能进行复现操作。复现失败意味着只有少数程序成功运行,或只有少数 (<25%) 数据成功生成。

在此处标记未实现完全复现的原因,并在 JIRA 中输入此信息:

  • Discrepancy in output 输出差异 (表格或文本中的图片或数字不同。
  • Bugs in code 复制者可修复的代码错误 (但应在最终储存时修复)。
  • Code missing 尤其是在代码缺失阻止了复制者完成复现性检查的情况下。
    • Data preparation code missing 如果缺少的代码可能是数据准备代码,则应检查数据准备代码是否缺失。
  • Code not functional 代码无效比普通错误更严重,因为它会阻止复制者完成复现性检查。
  • Software not available to replicator 复制者无法使用软件可能有多种原因:(a) 软件是商业软件,复制者无法访问许可副本。(b) 软件是开源的,但无法使用进行复现性检查所需的特定版本。
  • Insufficient time available to replicator 复制者可用的时间不足可能有多种原因:(a) 运行代码需要几周或更长时间。(b) 如果使用足够的计算资源,运行代码可能需要更少的时间,但复制者无法及时访问这些资源。(c) 复制包非常复杂,执行所有(手动和脚本化)步骤需要太长时间。
  • Data missing 当数据应该可用,但却未提供或无法通过复制包中描述的过程访问时,会标记数据缺失。
  • Data not available 当数据需要额外的访问步骤 (例如购买或申请程序) 时,会标记数据不可用。

12. 相关推文

Note:产生如下推文列表的 Stata 命令为:
lianxh 复现, m
安装最新版 lianxh 命令:
ssc install lianxh, replace

相关课程

免费公开课

最新课程-直播课

专题 嘉宾 直播/回看视频
最新专题 文本分析、机器学习、效率专题、生存分析等
研究设计 连玉君 我的特斯拉-实证研究设计-幻灯片-
面板模型 连玉君 动态面板模型-幻灯片-
面板模型 连玉君 直击面板数据模型 [免费公开课,2小时]
  • Note: 部分课程的资料,PPT 等可以前往 连享会-直播课 主页查看,下载。

课程主页

课程主页

关于我们

  • Stata连享会 由中山大学连玉君老师团队创办,定期分享实证分析经验。
  • 连享会-主页知乎专栏,700+ 推文,实证分析不再抓狂。直播间 有很多视频课程,可以随时观看。
  • 公众号关键词搜索/回复 功能已经上线。大家可以在公众号左下角点击键盘图标,输入简要关键词,以便快速呈现历史推文,获取工具软件和数据下载。常见关键词:课程, 直播, 视频, 客服, 模型设定, 研究设计, stata, plus, 绘图, 编程, 面板, 论文重现, 可视化, RDD, DID, PSM, 合成控制法

连享会小程序:扫一扫,看推文,看视频……

扫码加入连享会微信群,提问交流更方便

✏ 连享会-常见问题解答:
https://gitee.com/lianxh/Course/wikis

New! lianxhsongbl 命令发布了:
随时搜索连享会推文、Stata 资源,安装命令如下:
. ssc install lianxh
使用详情参见帮助文件 (有惊喜):
. help lianxh