P4. ado 文档：定义自己的程序

整理人：刘雅玄 (北京大学，lyxbamboo@163.com)

在 Stata 中使用的每一个命令的背后，都对应着一个ado文档。因此我们完全可以自己编写ado文件，相当于自行定义自己的程序。

P4.1 Stata 程序的基本架构

首先，我们定义了一个非常简单的程序（共4行），实质内容只有 display “I Iove This Game!” 这一行，即在屏幕上显示一句话。

第一行命令指明：将要定义一个程序，并定义了一个程序的名称（myprog)，结尾 end，中间是程序的实质性过程。

     program define myprog
     version 12.0
        display "I Iove This Game!"
     end

在上方，我们还定义了 version。定义 version 的好处是，无论之后 Stata 更新到什么版本，当时在12.0版本下的语法定义的内容依然可以兼容。

并且，程序的名称必须由英文字母和数字构成，且不能和已有的命令冲突。

P4.2 程序的执行

对于定义的程序，有两种执行方式。

第一种执行方式：ado 文档执行方式

把刚才定义的这一段命令或程序保存在一个文档中，建立一个空白的do文件。保存时有两点需要特别注意：

保存的文件名称必须和程序完全一致，所以通常复制程序名称进行保存，可以保存文件在任意位置。
文件的保存类型默认的是.do，但是不符合保存程序的要求，需要点开下拉菜单，选择 ado，进行保存，即保存为 myprog.ado (文件的扩展名为 `.ado’)。另外，程序的名称不能与现有命令名称冲突

保存后，我们就可以关闭do文件了，这时候 Stata 就新增了myprog这个命令，在屏幕上输入该命令即可进行执行。

能够成功运行的前提是之前已经执行了adopath+这条命令（见下方），即把刚才的存放路径通过adopath+命令添加到了Stata 能够执行的目录。

    myprog
    adopath + "D:\stata12\ado\personal\LY_stata\_plus"
    myprog

执行这条命令后，屏幕上会显示多条路径，每执行一条命令的时候，Stata 会依次在这些路径中寻找一个名称为 myprog 后缀为.ado的文件，一旦找到，就会执行这个程序内的所有内容。Stata 在这些路径以外的地方，并不会进行查询，以提升运行速度。

有以下建议供参考：

把自己编写的程序统一存放于 ._Myado 下；
并在 profile.do 文件中定义如下 stata adopath + D:\stata11\ado\personal\_Myado
该文件夹下可进一步设定 a-z 等子文件夹，尤其是如果平时自行设定的命令较多
存放相应字母开头的文件
对于临时的 ado 文档，可以采用 adopath +命令定义存放地址
对于需要经常执行的命令，采用这种方式很好，与 Stata 官方命令完全相同。

第二种执行方式：run

Step 1: 将程序内容读入内存具体方法：选中, 点击`Execute Quietly(run)’键（快捷键：Ctrl+R）

Step 2：执行程序（方式同前，快捷键：Ctrl+D）

  program define mynike
    version 12.0
    dis in red "Just do it! "
  end  

  mynike

P4.3 程序的管理

如果想要编辑已经存在的程序，如编辑刚才定义好的 myprog.ado，可以使用adoedit命令。正如doedit可以编辑do文件。

adoedit myprog.ado   // 修改和编辑程序
adoedit winsor2.ado

注意程序的名称一定要和ado文件相一致。

如果想要修改已经存在内存中的程序，首先要进行program drop ，这时只是删除内存中调入的程序，但不影响硬盘中存储的文件。

之后运行再mynike，会显示错误信息，因为程序已不在内存中。

program drop mynike   
mynike

修改程序后，必须重新读入内存才能使新代码生效。

program define mynike
    version 12.0
    dis in red "Just do it! haha"
end  
mynike

我们可以在定义程序前，可以加一个capture program drop。如此一来，无论第一次执行还是反复执行，都不会报错。

    capture program drop mynike        // 新增语句
    program define mynike
      version 8.0
      dis in red "Just do it! ha   ha! "  // 请修改后执行
    end  
          
    mynike

P4.4 避免列印过多的结果

接下来将一些定义程序时的小技巧。

首先，避免打印过多的结果。通常在执行一个程序的时候，总有很多中间计算结果，需要借助 Stata 现有的命令进行中间结果的计算。可以用 quietly 命令实现“悄悄计算”的结果，所有中间计算的统计量都会存储在内存中。

比如调入汽车价格，通过sum统计 price 的平均值，以 r(mean) 的单值形式存储了均值，并定义为 avg进行存储。如果有多行命令需要静悄悄执行，可以用花括号”{}“来隐藏中间一系列代码的执行效果，仅呈现最终所需的价格差（diff）。

sysuse auto, clear
  quietly sum price, meanonly   // 静悄悄地做，单行
  scalar avg = r(mean)
  dis avg

  qui{                          // 静悄悄地做，整段
     sum price if foreign == 0
     scalar avg1 = r(mean)
     sum price if foreign == 1
     scalar avg2 = r(mean)
     scalar diff = avg2 - avg1
  }
  dis diff

P4.5 避免数据在程序执行过后有所变动

通常用户使用我们定义的程序，主要目的有两个：

做基本统计分析，配合制作图形。
进行回归分析。

多数情况下，我们不希望用户更改数据，除非生成新变量或剔除缺漏值/离群值等，可以使用preserve 和 restore 配合使用。

preserve执行时，Stata 会把当前的数据进行备份并存在内存的某个位置上，接下来可以执行删除的动作，再去做基本统计分析，或存一份更改后的数据等。但是一旦执行restore,就会回到preserve时的数据状态，不会产生影响。

  sysuse auto, clear
    preserve                      // 备份当前状态 s1
      keep price weight foreign
      drop if price > 10000
      sum 
      save auto_new.dta, replace
    restore                       // 恢复到状态 s1
  sum  

  use auto_new.dta,clear

以下为注意事项：

多数情况下，我们改动资料都是为了得到特定的结果；
在 preserve和 restore 之间对资料进行的任何修改都无法保留；
preserve 和 restore 不可“嵌套”使用，即只能使用一次，这是先天的缺陷。
Stata 11 及之后，提供了新的命令——snapshot，“嵌套”功能，”快照“功能，可以嵌套一千次。

*-Also See                         | 主页: lianxh.cn |

  help program   //程序相关命令菜单
  
  help capture   //避免程序因小错误而中断
  
  help syntax    //输入项的语法格式
  
  help simulate  //Monte Carlo Simulation