% Stata Markdown
% wintryheart
% 2019年7月1日
STATA Markdown
前言
本文基于markstat命令的開發(fā)者Germán Rodríguez的使用說明整理患久。原文請(qǐng)見
GR的Stata Markdown主頁薄料。
0哈扮、準(zhǔn)備
STATA 15開始支持Markdown庄岖。個(gè)人認(rèn)為markstat比STATA15自帶的markdown命令更好用。
我的STATA版本是14，需要安裝兩個(gè)命令和一些外部程序痒钝。
1）安裝兩個(gè)命令：
- markstat 用于執(zhí)行包含stata和markdown代碼的動(dòng)態(tài)文件痴昧。
ssc install markstat
- whereis 用于指定外部程序和輔助文件的路徑目錄。
**ssc install whereis **
2）安裝外部程序
- Pandoc 用于把Markdown轉(zhuǎn)換成HTML巨朦，PDF米丘，或DOCX的程序。
??首先糊啡，請(qǐng)去Pandoc的官網(wǎng)下載拄查。
??安裝好后，打開STATA棚蓄，使用whereis命令指定Pandoc程序的位置堕扶。
whereis pandoc "c:/program files/pandoc/pandoc.exe"
- R 如果想包含R代碼腺毫，需要先安裝R，然后用whereis指定R程序位置挣柬。
whereis R "c:/program files/R/R-3.4.3/R/bin/x64/R.exe"
- Latex 可選潮酒。操作同上類似。但我傾向于用Pandoc轉(zhuǎn)成HTML邪蛔，然后用瀏覽器轉(zhuǎn)成PDF急黎。
2、編寫markstat文件(.stmd)
注意：markstat使用{{n}}作為stata代碼的預(yù)留塊的標(biāo)記侧到，所以在編寫markstat文件時(shí)勃教，
不要使用雙大括號(hào)。
1）包含stata代碼的最簡單的文件
Stata代碼只需要縮進(jìn) 1個(gè)tab或4個(gè)空格匠抗。如下例：
Let's read the fuel efficiency data that comes with Stata,
compute gallons per 100 miles, and regress that on weight
?? sysuse auto, clear
?? gen gphm = 100/mpg
?? regress gphm weight
We see that heavier cars use more fuel, with 1,000 pounds requiring
an extra 1.4 gallons to travel 100 miles.
Let's read the fuel efficiency data that comes with Stata,
compute gallons per 100 miles, and regress that on weight
sysuse auto, clear
gen gphm = 100/mpg
regress gphm weight
We see that heavier cars use more fuel, with 1,000 pounds requiring
an extra 1.4 gallons to travel 100 miles.
2）Markdown
Markstat支持通用的markdown語法故源。也支持HTML語法，但是如果要直接生成PDF文件汞贸，
建議不要插入HTML語法绳军。
3）數(shù)學(xué)公式
- 支持$ $ 行內(nèi)插入公式。
- 支持$$ $$ 插入公式塊矢腻。
- 輸出漂亮的公式门驾，建議執(zhí)行markstat命令時(shí)添加mathjax選項(xiàng)。
- 公式塊多柑，建議縮進(jìn)輸入公式奶是。不用擔(dān)心會(huì)和stata命令相混淆。
$$
y = \alpha + \beta x + e
$$
輸出結(jié)果為：
4）Metadata 文件標(biāo)記
Pandoc支持文件的標(biāo)題竣灌、作者和日期作為metadata聂沙。
注意，必須在文件開頭第一行開始用%標(biāo)注相關(guān)信息初嘹。
例如：
% Stata Markdown
% Germán Rodríguez
% 26 October 2016
5）代碼塊Fenced Code Blocks
前面提到用“1個(gè)tab或4個(gè)空格”的規(guī)則來區(qū)分STATA和Markdown的代碼及汉。
規(guī)范做法最好用代碼塊。
a) STATA代碼塊
```s
//STATA code goes here
```
或者
```{s}
//STATA code goes here
```
如果不返回命令
```s/ 或者 {s/}
//STATA code goes here
```
6）行內(nèi)代碼（Inline code）
行內(nèi)代碼的語法：
`s [fmt] expression` // fmt是可選格式
例如：
quietly sysuse auto, clear
quietly gen gphm = 100/mpg
quietly regress gphm foreign
The R-squared of the regression is ` s e(r2) `, or ` s%5.2f e(r2) `削樊。
如果要在行內(nèi)引用R代碼的結(jié)果豁生，語法類似為` r expression `。注意漫贞，這里沒有fmt選項(xiàng)甸箱。如果對(duì)結(jié)果格式化，可以使用round()函數(shù)迅脐。例如
library(haven)
auto <- read_dta("auto.dta")
q <- quantile(auto$price, 0.75); q
the 75-th percentile is ` r round(q, 1) `芍殖。
7）圖片
圖片的物理尺寸是由STATA的graph export命令中的width選項(xiàng)設(shè)定。
默認(rèn)在HTML中使用圖片的實(shí)際尺寸谴蔑，在PDF中使用行寬的75%的尺寸豌骏。
Markdown連接中添加width選項(xiàng)龟梦，可以修改和設(shè)置圖片尺寸。有三種選擇：
- 使用
設(shè)定英寸寬度;
- 使用
設(shè)定厘米寬度窃躲；
- 使用
設(shè)定相對(duì)尺寸计贰。
例如 ：
{width=100%} //設(shè)定圖片的相對(duì)寬度為100%，圖片將隨瀏覽器的大小而變化蒂窒。
8）文獻(xiàn)引用
由于使用Pandoc作為轉(zhuǎn)換引擎躁倒，markstat還可以處理參考文獻(xiàn)引用。
簡單來說洒琢，先為參考文獻(xiàn)創(chuàng)建一個(gè)BibTex數(shù)據(jù)庫文件秧秉，然后在markstat文件的Metadata行中包含對(duì)該數(shù)據(jù)庫文件的引用。詳細(xì)例子參見Citations說明衰抑。
例子
第一步象迎，創(chuàng)建BibTex數(shù)據(jù)庫，本例命名為markstat.bib呛踊。內(nèi)容如下：
% Encoding: UTF-8
@book{knuth92,
author = "Donald Knuth",
title = "Literate Programming",
publisher = "{CSLI} Lecture Notes",
address = "Stanford, CA",
year = 1992
@article{peng09,
author = "Roger D. Peng",
title = "Reproducible Research and {\em Biostatistics}",
journal = "Biostatistics",
volume = 10,
number = 3,
pages = "405--408",
year = 2009
}
@inproceedings{rossini01,
author = "A. J. Rossini",
title = "Literate Statistical Practice",
editor = "K. Hornick and F. Leisch",
booktitle = "DSC 2001. Proceedings of the 2nd International Workshop on Distributed Statistical Computing",
url = "http://www.R-project.org/conferences/DSC-2001",
year = 2001
}
@inproceedings{leisch02,
author = "F. Leisch",
title = "Sweave: Dynamic generation of statistical reports using literate data analysis",
editor = {Wolfgang H{\"a}rdle and Bernd R{\"o}nz},
booktitle = "Compstat 2002. Proceedings in Computational Statistics",
pages = "575-580",
publisher = "Physika Verlag, Heidelberg, Germany",
year = 2002
第二步砾淌，在markstat文件(.stmd)的YAML metadata塊指定該數(shù)據(jù)庫文件。
---
title: Literate Data Analysis
author: Germán Rodríguez
date: 1 June 2017
bibliography: markstat.bib
---
Donald Knuth [-@knuth84] is a strong believer in documenting computer programs and originated the term *literate programming*. This concept is even more important in data analysis, where documenting each step
in data collection, processing and analysis is crucial [see @leisch02; @rossini01].
## References
---
第三步恋技，設(shè)定引用格式
markstat默認(rèn)的是 the Chicago Manual of Style author-date 格式拇舀。
文獻(xiàn)管理樣式庫（the Zotero Style Repository）中有8000多種文獻(xiàn)引用樣式逻族，可以從中選擇所需下載引用樣式語言（Citation Style Language）文件（.csl文件）蜻底，然后添加進(jìn)YAML塊的Metadata數(shù)據(jù)行中。
例如聘鳞，采用IEEE格式薄辅。
---
title: Literate Data Analysis
author: Germán Rodríguez
date: 1 June 2017
bibliography: markstat.bib
csl: proceedings-of-the-ieee.csl
---
第四步，運(yùn)行markstat時(shí)添加bibliography選項(xiàng)抠璃。
9）幻燈片
還是由 于Pandoc站楚，markstat也支持生成幻燈片，在HTML顯示使用S5引擎搏嗡，在PDF中顯示使用Beamer窿春。
首先，必須在YAML metadata塊采盒，提供title旧乞，author和data，這些信息會(huì)顯示在幻燈片的首頁磅氨。
其次尺栖，在STATA和Markdown代碼中使用特定的語法來設(shè)定每張幻燈片。
- 在一個(gè)簡單的PPT中烦租，level 1的每個(gè)標(biāo)題（heading）定義一個(gè)幻燈片延赌，然后是內(nèi)容除盏。內(nèi)容通常包括要點(diǎn)（Bullet points），以及使用Stata生成的圖和表挫以。
- 在一個(gè)多部件PPT中者蠕，級(jí)別1的標(biāo)題（level1 heading）定義部件（parts）并生成標(biāo)題幻燈片頁（title slides），級(jí)別2的標(biāo)題（level2 heading）定義幻燈片掐松。Pandoc計(jì)算出幻燈片級(jí)別蠢棱，尋找最高級(jí)別的標(biāo)題，緊接著是內(nèi)容甩栈。
- 如果PPT中包含圖片泻仙，可以用使用Mardown語法
{width="60%"}來引用圖片。 - 如果使用Beamer量没，要在包含STATA命令和輸出的幻燈片頁的標(biāo)題中(the heading of slides)添加
{.fragile}玉转。
例子：
3、執(zhí)行markstat文件(.stmd)
STATA命令：
** markstat using filename [, pdf docx slides beamer mathjax bibliography strict nodo nor keep]**
