% Stata Markdown
% wintryheart
% 2019年7月1日

STATA Markdown

前言

本文基于markstat命令的开发者Germán Rodríguez的使用说明整理。原文请见
GR的Stata Markdown主页。

0、准备

STATA 15开始支持Markdown。个人认为markstat比STATA15自带的markdown命令更好用。

我的STATA版本是14，需要安装两个命令和一些外部程序。

1）安装两个命令：

markstat 用于执行包含stata和markdown代码的动态文件。

ssc install markstat

whereis 用于指定外部程序和辅助文件的路径目录。

**ssc install whereis **

2）安装外部程序

Pandoc 用于把Markdown转换成HTML，PDF，或DOCX的程序。

首先，请去Pandoc的官网下载。

安装好后，打开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转成HTML，然后用浏览器转成PDF。

2、编写markstat文件(.stmd)

注意：markstat使用{{n}}作为stata代码的预留块的标记，所以在编写markstat文件时，
不要使用双大括号。

1）包含stata代码的最简单的文件

Stata代码只需要缩进 1个tab或4个空格。如下例：

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）数学公式

支持$ $ 行内插入公式。
支持$$ $$ 插入公式块。
输出漂亮的公式，建议执行markstat命令时添加mathjax选项。
公式块，建议缩进输入公式。不用担心会和stata命令相混淆。

$$
    y = \alpha + \beta x + e
$$

输出结果为：

4）Metadata 文件标记

Pandoc支持文件的标题、作者和日期作为metadata。

注意，必须在文件开头第一行开始用%标注相关信息。

例如：

% Stata Markdown
% Germán Rodríguez
% 26 October 2016

5）代码块Fenced Code Blocks

前面提到用“1个tab或4个空格”的规则来区分STATA和Markdown的代码。

规范做法最好用代码块。

a) STATA代码块

```s 
    //STATA code goes here
```

或者

```{s}
    //STATA code goes here
```

如果不返回命令

```s/ 或者 {s/} 
    //STATA code goes here
```

6）行内代码（Inline code）

行内代码的语法：

`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) `。

如果要在行内引用R代码的结果，语法类似为` r expression `。注意，这里没有fmt选项。如果对结果格式化，可以使用round()函数。例如

    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选项设定。

默认在HTML中使用图片的实际尺寸，在PDF中使用行宽的75%的尺寸。

Markdown连接中添加width选项，可以修改和设置图片尺寸。有三种选择：

使用设定英寸宽度;
使用设定厘米宽度；
使用设定相对尺寸。
例如：

![caption](filename.png){width=100%}  //设定图片的相对宽度为100%，图片将随浏览器的大小而变化。

8）文献引用

由于使用Pandoc作为转换引擎，markstat还可以处理参考文献引用。

简单来说，先为参考文献创建一个BibTex数据库文件，然后在markstat文件的Metadata行中包含对该数据库文件的引用。详细例子参见Citations说明。

例子

第一步，创建BibTex数据库，本例命名为markstat.bib。内容如下：

% 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块指定该数据库文件。

---
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
---

第三步，设定引用格式

markstat默认的是 the Chicago Manual of Style author-date 格式。

文献管理样式库（the Zotero Style Repository）中有8000多种文献引用样式，可以从中选择所需下载引用样式语言（Citation Style Language）文件（.csl文件），然后添加进YAML块的Metadata数据行中。

例如，采用IEEE格式。

---
title: Literate Data Analysis
author: Germán Rodríguez
date: 1 June 2017
bibliography: markstat.bib
csl: proceedings-of-the-ieee.csl
---

第四步，运行markstat时添加bibliography选项。

9）幻灯片
还是由于Pandoc，markstat也支持生成幻灯片，在HTML显示使用S5引擎，在PDF中显示使用Beamer。

首先，必须在YAML metadata块，提供title，author和data，这些信息会显示在幻灯片的首页。

其次，在STATA和Markdown代码中使用特定的语法来设定每张幻灯片。

在一个简单的PPT中，level 1的每个标题（heading）定义一个幻灯片，然后是内容。内容通常包括要点（Bullet points），以及使用Stata生成的图和表。
在一个多部件PPT中，级别1的标题（level1 heading）定义部件（parts）并生成标题幻灯片页（title slides），级别2的标题（level2 heading）定义幻灯片。Pandoc计算出幻灯片级别，寻找最高级别的标题，紧接着是内容。
如果PPT中包含图片，可以用使用Mardown语法![title](source){width="60%"}来引用图片。
如果使用Beamer，要在包含STATA命令和输出的幻灯片页的标题中(the heading of slides)添加{.fragile}。

例子：

简单的例子
幻灯片包含两列的例子

3、执行markstat文件(.stmd)

STATA命令：

** markstat using filename [, pdf docx slides beamer mathjax bibliography strict nodo nor keep]**

STATA中的Markdown转换命令markstat