Stata 可重复性报告系列 B: 导出命令 (put*)

发布时间:2020-07-04 阅读 334

Stata 连享会   主页 || 视频 || 推文

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

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

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

作者:万莉 (北京航空航天大学)


目录


引言

本文是 「Stata 可重复性报告系列 A:动态文档命令 (dyn*)」 的姊妹篇。

在 Stata 16 发布页面, "truly reproducible reporting(可重复性报告)" 成为亮点之一。继 Stata 15 之后, Stata16 进一步引入和完善一系列相关命令。

对于 Stata 用户而言,我们可以用这些命令直接编写 dofile, 将报告正文、Stata 生成的图表等整合在一个文档中,自定义生成各种格式的文档(text,Word,PDF,Excel 或 HTML)。

更为重要的是,我们可实现可重复性研究,即报告中的数据、模型发生变化后,我们只需稍加修改 Stata 命令,便可输出更新后的文档,而不必逐个修改变动后的结果。

生成可重复性报告(Reproducible and automated reporting)的命令可分为两类:

  • 第一类:dyn 类——生成文档: 各种带 dyn 前缀的动态文档生成命令 (如 dyntext | dyndoc),用于生成 text、HTML 和 Word 文档。更重要的是,该命令支持 Markdown 文本格式语言。

  • 第二类:put 类——输出文档: 各种带 put 前缀的文档输出命令 (putdocx | putpdf | putexcel )。此类命令可自定义生成 Word、PDF 和 Excel 文件。

本文着重讲解第二类命令的使用方法。第一类命令的使用方法参考推文 「Stata 可重复性报告系列 A:动态文档命令 (dyn*)」

1. 命令一: putdocx

help putdocx // 输出 Word 文档

1.1 语法结构

该命令包含一系列子命令,主要分为一下四类: (需要特别说明的是:继 Stata 15 后,Stata 16 对该命令进行了完善,带 [*] 的选项不适用于 Stata 15。)

Step1. 新建、保存以及合并 .docx 文件

  • putdocx begin 新建一个空白 Word 文档。
  • putdocx describe 描述当前 Word 文档相关信息(比如有几个表格,有几段)。
  • putdocx save 保存并关闭 Word 文档。
  • putdocx clear 关闭 Word 文档时不保存更改。
  • putdocx append 对多个 Word 文档的内容进行合并。
   putdocx begin [, pagesize(psize) landscape font(fspec)]

* 描述当前 Word 文档相关信息(比如有几个表格,有几段)。
  putdocx describe

* 描述当前 Word 文档中的表格信息(比如有几行几列)。
  putdocx describe tablename
  
  putdocx save filename [, replace|append]
  
  putdocx clear
  
  putdocx append filename1 filename2 [filename3 [...]] 
                   [, saving(filename[, replace])]

Step2. 在 .docx 文件中插入分页符 (page break)

  • putdocx pagebreak 在 Word 文档中添加分页符 (page break)。
  • putdocx sectionbreak 在 Word 文档中添加分节符 (section break)。
putdocx pagebreak

putdocx sectionbreak [, pagesize(psize) landscape]

Step3. 在 .docx 文件中添加段落(包括文本、图像)

  • putdocx paragraph 另起新段落。
  • putdocx text 在当前段落添加文本。
    • putdocx textblock 在当前段落或新段落添加文本块。
    • putdocx textfile 在新的段落里添加预格式化的文本块。
  • putdocx image 在当前段落插入图像。
    • putdocx pagenumber 在页眉/页脚设置页码。
putdocx paragraph [, paragraph_options]

putdocx text (exp) [, text_options]

putdocx image filename [, image_options]

putdocx textblock begin 
// 另起一段添加文本块。

putdocx textblock append
// 在当前段落添加文本块。

putdocx textblock end
// 该命令是 putdocx textblock begin 或 putdocx textblock append 的结尾。

putdocx textfile textfile [, append stopat(string [, stopatopt])]

Step4. 在 .docx 文件中插入表格

  • putdocx table 创建新表格(估计结果/描述性统计/变量)
* 添加表格
putdocx table tablename = (nrows, ncols) [, table_options]

putdocx table tablename = data(varlist) [if] [in] [, varnames obsno table_options]

putdocx table tablename = matrix(matname) [, nformat(%fmt) rownames colnames table_options]

putdocx table tablename = mata(matname) [, nformat(%fmt) table_options]

putdocx table tablename = etable[(#1 #2 ... #n)] [, table_options]

putdocx table tablename = returnset [, table_options]

* 修改表格和行列
1. 在单元格里添加内容 (Add content to cell)

putdocx table tablename(i,j) = (exp) [, cell_options]

putdocx table tablename(i,j) = image(filename) [, image_options cell_options]

putdocx table tablename(i,j) = table(mem_tablename) [, cell_options]

2. 修改表格的布局 (Alter table layout)

putdocx table tablename(i,.), row_col_options

putdocx table tablename(.,j), row_col_options

3. 自定义表格或单元格的形式 (Customize format of cells or table)

putdocx table tablename(i,j), cell_options

putdocx table tablename(numlist_i,.), cell_fmt_options

putdocx table tablename(.,numlist_j), cell_fmt_options

putdocx table tablename(numlist_i,numlist_j), cell_fmt_options

putdocx table tablename(.,.), cell_fmt_options
	```


 

> #### [连享会计量方法专题……](https://gitee.com/arlionn/Course/blob/master/README.md)



### 1.2 范例 1:生成 Cover Page

我们先新建一个 do 文件,命名为 `putdocx_example1`。**注意:**我们也可以不新建 do 文件,直接在已有 do 文件中输入并执行以下命令。

```stata
*--------------------------begin putdocx_example1.do------------------------
putdocx begin, pagesize(A4)
* 声明使用 putdocx 命令,新建 Word 文档
* 我们可这样理解:一个 .docx 文件包含很多段落,
* 每一次写入一段必须声明。

putdocx paragraph, halign(left) ///
  font("微软雅黑",28,black) 
* 写入一段,将段落内容左对齐,并提前预设好字体格式

putdocx text ("这只是个简单的例子。"), ///
  bold underline(dotted) linebreak
* 注意 text 和 ( 之间要留空格!  
* 输入文本,加粗字体,添加点式下划线,并在结尾处换行。

putdocx text (""), linebreak 
* 不输入文本内容,直接换行

putdocx paragraph, halign(center) 
* 新写入一段,将段落内容居中

putdocx text ("这是封面 Cover Page"), ///
  bold linebreak underline(dash) ///
  font("华文楷体",30,black)  
* 输入文本,设置字体格式(黑体,华文楷体,30 号,黑色),
* 在文本内容下添加虚下划线,并在结尾处换行。
  
putdocx text ("这是标题"),  ///
  bold linebreak ///
  font("华文楷体",75,black)    

putdocx text ("这是作者xx"),  ///
  bold linebreak ///
  font("华文楷体",30,purple)      

putdocx text ("这是学校xx"),  ///
  bold linebreak ///
  font("华文楷体",30,red) 
  
putdocx text ("2019.09.04"),  ///
  bold linebreak ///
  font("华文楷体",30,green)    
putdocx save CoverPage, replace	
*--------------------------end putdocx_example1.do---------------------------

我们可以通过命令 shellout 查看输出结果,也可以在当前路径直接打开 CoverPage.docx

ssc install outreg2 // 安装此命令,调用shellout命令
shellout "CoverPage.docx"

输出结果如下:

CoverPage.png
CoverPage.png

连享会计量方法专题……

1.3 范例 2:输出包含文字、图表的 Word 文档

我们先新建一个 do 文件,命名为 putdocx_example2注意: 我们也可以不新建 do 文件,直接在已有 do 文件中输入并执行以下命令。

*--------------------------begin putdocx_example2.do------------------------
webuse nhanes2, clear

putdocx begin // 声明使用 putdocx 命令,新建 Word 文档
// 我们可这样理解:一个 .docx 文件包含很多段落,每一次写入一段必须声明。

// 添加段落标题,样式为 "标题 (Title)"
putdocx paragraph, style(Title) 
putdocx text ("Blood pressure report")
// 查看相关样式的可选项: help putdocx_appendix

// 添加文本块
putdocx textblock begin
We use data from the Second National Health and Nutrition Examination Survey
 to study the incidence of high blood pressure.
putdocx textblock end

// 添加段落标题,样式为 "标题1 (Heading1)" 
putdocx paragraph, style(Heading1)
putdocx text ("Logistic regression results")

// 添加文本块
putdocx textblock begin
We fit a logistic regression model of high blood pressure on
 weight, age group, and the interaction between age group and sex.
putdocx textblock end

logistic highbp weight agegrp##sex, nopvalues vsquish

// 添加上述命令生成的估计表格
putdocx table results = etable

// 添加段落标题,样式为 "Heading1" 
putdocx paragraph, style(Heading1)
putdocx text ("Interaction plot")

// 进行边际效应分析,并画图
margins agegrp#sex
marginsplot, title(Age Group and Sex Interaction) ///
   ytitle(Expected Probability of High Blood Pressure) ///
   legend(ring(0) bplacement(seast) col(1))
graph export interaction.png, replace

// 另起一段,插入上述命令生成的图
putdocx paragraph, halign(center)
putdocx image interaction.png

// 保存 Word 文档
putdocx save report1, replace	

// 若出现错误:document already open in memory
// 可能是执行 putdocx begin 后遇到错误中断后,再重新执行。
// 解决该错误可尝试该命令:putdocx clear
// 再重新执行上述命令。
*--------------------------end putdocx_example2.do---------------------------

我们可以通过命令 shellout 查看输出结果,也可以在当前路径直接打开 report1.docx

ssc install outreg2 // 安装此命令,调用shellout命令
shellout "report1.docx"

输出结果如下

report1.png
report1.png

连享会计量方法专题……

1.4 范例 3:美化输出的 Word 文档

我们对范例 2 的输出结果进行进一步的美化,比如设置页眉、页脚、页码,美化图表等。我们新建一个 do 文件,命名为 putdocx_example3。 **注意:**我们也可以不新建 do 文件,直接在已有 do 文件中输入并执行以下命令。

*--------------------------begin putdocx_example3.do------------------------
webuse nhanes2, clear

// 声明新建带页眉的 Word 文档
putdocx begin, header(head)

// 自定义页眉的内容,并加上页码
putdocx paragraph, toheader(head) font(,14)
putdocx text ("Blood pressure report: ")
putdocx pagenumber

// 添加段落标题,样式为 "Heading1" 
putdocx paragraph, style(Heading1)
putdocx text ("Data")

// 添加文本块
putdocx textblock begin
We use data from the Second National Health and Nutrition Examination Survey
 to study the incidence of high blood pressure.
putdocx textblock end

// 添加段落标题,样式为 "Heading1" 
putdocx paragraph, style(Heading1)
putdocx text ("Logistic regression results")

// 添加文本块
putdocx textblock begin
We fit logistic regression models of high blood pressure on
 weight, age group, and the interaction between age group and sex.
putdocx textblock end

// 添加估计表格
logistic highbp weight agegrp##sex, nopvalues vsquish
putdocx table results = etable

// 对表格的某几行,添加背景色
putdocx table results(3 5 7 9 11 13 15 17,.), shading(lightgray)

// 设置表格中数字的显示格式,为:共占5个空格,小数位占三个空格
putdocx table results(2/17,2/5), nformat(%5.3f)

// 改变单元格中的内容
putdocx table results(1,1) = ("High BP")

// 添加段落标题,样式为 "Heading1" 
putdocx paragraph, style(Heading1)
putdocx text ("Interaction plot")

// 进行边际效应分析,并画图
margins agegrp#sex
marginsplot, title(Age Group and Sex Interaction) ///
   ytitle(Expected Probability of High Blood Pressure) ///
   legend(ring(0) bplacement(seast) col(1))
graph export interaction.png, replace

// 另起一段,插入上述命令生成的图,并设置图高度
putdocx paragraph, halign(center)
putdocx image interaction.png, height(5 in)

// 保存 Word 文档
putdocx save report2, replace	
*--------------------------end putdocx_example3.do---------------------------

我们可以通过命令 shellout 查看输出结果,也可以在当前路径直接打开 report2.docx

ssc install outreg2 // 安装此命令,调用shellout命令
shellout "report2.docx"

输出结果如下:

report2.png
report2.png

1.5 讨论:如何用 putdocx 写论文

参考「君生我未生!Stata - 论文四表一键出」「Stata 生成可重复性报告系列(一):运用动态文档命令 (dyn*)」,我们可以使用 putdocx 命令写论文。

为了更有条理地管理我们的论文,方便日后修改,建议:

  1. 为每篇论文建立一个文件夹,比如命名为 Mypaper_2019;

  2. 在这个文件夹里新建一些子文件夹,如 DataProgOutputFigsTable 等,用于存储不同类型的文件。

  3. 将论文拆分成三部分: My_Paper.docx,即论文主文档,包含引言、文献综述、理论分析、参考文献等; My_Table.docx,即表格文档,包含统计和回归表格; My_Fig.docx,即图形文档,包含各种图。 每部分都可以用 putdocxdyndoc 命令进行编写 do 文件,生成相应的 Word 文档。然后把这些 do 文件放到 Prog 子文件夹。如果某部分不想用命令,也可以直接在 Word 文档上码字,贴上图表。

    框架如下:

    论文模板.png
    论文模板.png

2. 命令二:putpdf

help putpdf // 输出 PDF 文档

putpdf 的语法结构与 putdocx 几乎完全相同,故不展开说明,直接看一个例子。该例子与 putdocx 的范例二几乎完全相同,只是将 putdocx 变成 putpdf

2.1 范例:输出包含文字、图表的 PDF 文档

我们先新建一个 do 文件,命名为 putpdf_example1。**注意:**我们也可以不新建 do 文件,直接在已有 do 文件中输入并执行以下命令。

*--------------------------begin putpdf_example1.do------------------------
webuse nhanes2, clear

putpdf begin // 声明使用 putpdf 命令,新建 PDF 文档
// 我们可这样理解:一个 .pdf 文件包含很多段落,每一次写入一段必须声明。

// 添加段落标题,段落内容居中,并设置字体大小
putpdf paragraph, font(,20) halign(center)
putpdf text ("Blood pressure report")

// 另起一段,添加文本
putpdf paragraph
putpdf text ("We use data from the Second National Health and Nutrition ")
putpdf text ("Examination Survey to study the incidence of high blood pressure.")

// 另起一段,添加文本
putpdf paragraph, font(,16)
putpdf text ("Logistic regression results")

// 另起一段,添加文本
putpdf paragraph
putpdf text ("We fit a logistic regression model of high blood pressure on ")
putpdf text ("weight, age group, and the interaction between age group and sex.")

logistic highbp weight agegrp##sex, nopvalues vsquish

// 添加上述命令生成的估计表格
putpdf table results = etable

// 另起一页,生成新的段落
putpdf pagebreak
putpdf paragraph, font(,16)
putpdf text ("Interaction plot")

// 进行边际效应分析,并画图
margins agegrp#sex
marginsplot, title(Age Group and Sex Interaction) ///
   ytitle(Expected Probability of High Blood Pressure) ///
   legend(ring(0) bplacement(seast) col(1))
graph export interaction.png, replace

// 另起一段,插入上述命令生成的图
putpdf paragraph, halign(center)
putpdf image interaction.png

// 保存 PDF 文档
putpdf save report-pdf, replace		
*--------------------------end putpdf_example1.do---------------------------

我们可以通过命令 shellout 查看输出结果,也可以在当前路径直接打开 report.pdf

ssc install outreg2 // 安装此命令,调用shellout命令
shellout "report.pdf"

输出结果如下:

report-pdf.png
report-pdf.png

连享会计量方法专题……

3. 命令三:putexcel

help putexcel // 输出 Excel 文档

putexcel 的语法结构与 putdocx 类似,可粗略地将段落 (paragraph) 的概念替换成单元格 (cell)。故不展开说明,直接看一个例子。该例子的输出结果与上述例子基本相同。

3.1 范例:输出包含文字、图表的 Excel 文档

我们先新建一个 do 文件,命名为 putexcel_example1。**注意:**我们也可以不新建 do 文件,直接在已有 do 文件中输入并执行以下命令。

*--------------------------begin putexcel_example1.do------------------------
webuse nhanes2, clear

// 新建 Excel 文档,命名为 report.xlsx。
putexcel set report.xlsx, replace  

// 添加标题
putexcel A1 = "Blood pressure report", bold
putexcel A1:E1, border(bottom, thick) merge hcenter

// 添加文本内容
putexcel A3 = "We use data from the Second National Health and "
putexcel A4 = "Nutrition Examination Survey to study the "
putexcel A5 = "incidence of high blood pressure."

// 为回归结果添加标题
putexcel A7 = "Logistic regression results"
putexcel A7:E7, border(bottom, double)

// 添加文本内容
putexcel A9 = "We fit a logistic regression model of high blood"
putexcel A10 = "pressure on weight, age group, and the "
putexcel A11 = "interaction between age group and sex." 

*--------------------------------------------
// *设置文字格式(字体和字号)
putexcel A1:A11, font("Arial Narrow",11)
*--------------------------------------------

logistic highbp weight agegrp##sex, nopvalues vsquish

// 添加上述命令生成的估计表格
putexcel A13 = etable

*--------------------------------------------
// *将表中数字保留到小数点后两位
putexcel B14:E29, nformat(number_d2)

// *设置文字格式(字体和字号)以及单元格格式
putexcel A13:E29, font("Arial Narrow",9)
putexcel A15, left
putexcel A21, left
putexcel A23, left
*--------------------------------------------

// 进行边际效应分析,并画图
putexcel D13:E13, merge

putexcel G7 = "Interaction plot"
putexcel G7:I7, border(bottom, double)

margins agegrp#sex
marginsplot, title(Age Group and Sex Interaction) ///
   ytitle(Expected Probability of High Blood Pressure) ///
   legend(ring(0) bplacement(seast) col(1))
graph export interaction.png, replace width(550) height(400)

// 插入上述命令生成的图
putexcel G9 = image(interaction.png)

// 保存 Excel 文档
putexcel save			
*--------------------------end putexcel_example1.do---------------------------

注意: *---- 之间的代码是为了进一步美化输出结果,可删掉对比差异。

我们可以通过命令 shellout 查看输出结果,也可以在当前路径直接打开 report.xlsx

ssc install outreg2 // 安装此命令,调用shellout命令
shellout "report.xlsx"

输出结果如下:

report-excel.png
report-excel.png

4. 结语

可通过 help putdocxhelp putpdfhelp putexcel 参考更多官方范例,熟悉相关用法。

为了减少平时写报告的工作量,我们可根据自身需求选择合适的工具。比如,你比较习惯 Markdown 语法,且对输出文档的格式要求不那么高,则可以选择用 dyndoc,而不是 putdocx;如果你比较习惯使用 Word 直接排版,且期望通过命令达到类似效果,则可以试试 putdocx

正所谓 “熟能生巧”!我们勤用这些命令,就能摸索出最适合自己的方法!

5. 相关链接

特别说明: 文中包含的链接在微信中无法生效。请点击本文底部左下角的【阅读原文】。

相关课程

连享会-直播课 上线了!
http://lianxh.duanshu.com

免费公开课:


课程一览

支持回看,所有课程可以随时购买观看。

专题 嘉宾 直播/回看视频
最新专题 DSGE, 因果推断, 空间计量等
Stata数据清洗 游万海 直播, 2 小时,已上线
研究设计 连玉君 我的特斯拉-实证研究设计-幻灯片-
面板模型 连玉君 动态面板模型-幻灯片-
面板模型 连玉君 直击面板数据模型 [免费公开课,2小时]

Note: 部分课程的资料,PPT 等可以前往 连享会-直播课 主页查看,下载。


关于我们

  • Stata连享会 由中山大学连玉君老师团队创办,定期分享实证分析经验。直播间 有很多视频课程,可以随时观看。
  • 连享会-主页知乎专栏,300+ 推文,实证分析不再抓狂。
  • 公众号推文分类: 计量专题 | 分类推文 | 资源工具。推文分成 内生性 | 空间计量 | 时序面板 | 结果输出 | 交乘调节 五类,主流方法介绍一目了然:DID, RDD, IV, GMM, FE, Probit 等。
  • 公众号关键词搜索/回复 功能已经上线。大家可以在公众号左下角点击键盘图标,输入简要关键词,以便快速呈现历史推文,获取工具软件和数据下载。常见关键词:课程, 直播, 视频, 客服, 模型设定, 研究设计, stata, plus, 绘图, 编程, 面板, 论文重现, 可视化, RDD, DID, PSM, 合成控制法

连享会主页  lianxh.cn
连享会主页 lianxh.cn

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

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

✏ 连享会学习群-常见问题解答汇总:
https://gitee.com/arlionn/WD