m1_ado.hlp

是一个经济学管理应用软件 很难找的 但是经济学学生又必须用到

{smcl}
{* 31mar2005}{...}
{cmd:help m1 ado}
{hline}
{* index ado-files}{...}
{* index programming use}{...}

{title:Title}

{pstd}
{bf:[M-1] ado -- Using Mata with ado-files}


{title:Description}

{pstd}
This section provides advice to ado-file programmers on how to use Mata
effectively and efficiently.


{title:Remarks}

{pstd}
For those interested in extending Stata by adding new commands, Mata is not a
replacement for ado-files.  Rather, the appropriate way to use Mata is to
create subroutines used by your ado-files.  Below we discuss how to do that
under the headings

	{bf:A first example}
	{bf:Where to store the Mata functions}
	{bf:Passing arguments to Mata functions}
	{bf:Returning results to ado-code}
	{bf:Advice:  Use of matastrict}
	{bf:Advice:  Some useful Mata functions}


{title:A first example}

{pstd}
We will pretend that Stata cannot produce sums and that we want to write a new
command for Stata that will report the sum of a single variable.
Here is our first take on how we might do this:

	{hline 50} varsum.ado {hline 5}
	{cmd}program varsum
		version 9.0
		syntax varname [if] [in]
		marksample touse
		mata: calcsum("`varlist'", "`touse'")
		display as txt "  sum = " as res r(sum)
	end

	version 9.0
	mata:
	void calcsum(string scalar varname, string scalar touse)
	{
		real colvector  x

		st_view(x, ., varname, touse)
		st_numscalar("r(sum)", colsum(x))
	}
	end{txt}
	{hline 50} varsum.ado {hline 5}

{pstd}
Running this program from Stata results in the output:

	. {cmd:varsum mpg}
	  sum = 1576

{pstd}
Note the following:

{phang2}
    1.  The ado-file has both ado-code and Mata code in it.

{phang2}
    2.  The ado-code handled all issues of parsing and identifying the 
        subsample of the data to be used.

{phang2}
    3.  The ado-code called a Mata function to perform the calculation.

{phang2}
    4.  The Mata function received as arguments the names of two 
        variables in the Stata dataset:  the variable on which the 
        calculation was to be made and the variable that identified 
        the subsample of the data to be used.

{phang2}
    5.  The Mata function returned the result in {cmd:r()}, from where 
        the ado-code could access it.

{pstd}
The outline that we showed above is a good one, although we will show you 
alternatives which, for some problems, are better.


{title:Where to store the Mata functions}

{pstd}
Our ado-file included a Mata function.  You have three choices as to 
where to put the Mata function:

{phang2}
    1.  You can put the code for the Mata function in the 
        ado-file, as we did.  In order to work, your {cmd:.ado} file 
        must be placed where Stata can find it.

{phang2}
    2.  You can omit code for the Mata function from the 
        ado-file, compile the Mata function separately, and store 
        the compiled code (the object code) in a separate file
        called a {cmd:.mo} file.  You place both your {cmd:.ado} and {cmd:.mo} 
	files where Stata can find them.
        
{phang2}
    3.  You can omit the code for the Mata function from the 
        ado-file, compile the Mata function separately, and store the 
        compiled code in a {cmd:.mlib} library.  In this case, both your 
        {cmd:.ado} file and your {cmd:.mlib} library will need to be placed
        where Stata can find them.

{pstd}
We will show you how to do each of these alternatives but, before we do, 
let's consider the advantages and disadvantages of each:

{phang2}
    1.  Putting your Mata source code right in the ado-file is 
        easiest, and it sure is convenient.  The disadvantage is that
        Mata must compile the source code into object code, and that will 
        slow execution.  The cost is small because it occurs infrequently;
        Mata compiles the code when the ado-file is loaded and, as 
        long as the ado-file is not dropped from memory, Stata and Mata 
        will use the same compiled code over and over again.

{phang2}
    2.  Saving your Mata code as {cmd:.mo} files saves Mata from having 
        to compile them at all.  The source code is compiled only 
        once -- at the time you create the {cmd:.mo} file -- and thereafter,
        it is the already-compiled copy that Stata and Mata will use.

{pmore2}
        There is a second advantage:  Rather than the Mata functions 
        ({cmd:calcsum()} in this case) being private to the ado-file, 
        you will be able to use {cmd:calcsum()} in your other ado-files.  
        {cmd:calcsum()} will become a utility always available to you.
        Perhaps {cmd:calcsum()} is not deserving of this honor.

{phang2}
    3.  Saving your Mata code in a {cmd:.mlib} library has the same 
        advantages and disadvantages as (2); the only difference is 
        that we save the precompiled code in a different way.
        The {cmd:.mo}/{cmd:.mlib} choice is of more concern to those who 
        intend to distribute their ado-file to others.  
        {cmd:.mlib} libraries allow you to place lots of Mata functions 
        (subroutines for your ado-files) into a single file, and so it is 
        easier to distribute.

{pstd}
Let's restructure our ado-file to save {cmd:calcsum()} in a {cmd:.mo} file.
First, we simply remove {cmd:calcsum()} from our ado-file, so it now 
reads

	{hline 50} varsum.ado {hline 5}
	{cmd}program varsum
		version 9.0
		syntax varname [if] [in]
		marksample touse
		mata: calcsum("`varlist'", "`touse'")
		display as txt "  sum = " as res r(sum)
	end{txt}
	{hline 50} varsum.ado {hline 5}

{pstd}
Next, we enter Mata, enter our {cmd:calcsum()} program, and save the 
object code:

	: {cmd:void calcsum(string scalar varname, string scalar touse)}
	> {cmd:{c -(}}
	>        {cmd:real colvector  x}
	>
	>        {cmd:st_view(x, ., varname, touse)}
	>        {cmd:st_numscalar("r(sum)", colsum(x))}
	> {cmd:{c )-}}

	: {cmd:mata mosave calcsum(), dir(PERSONAL)}

{pstd}
This step we do only once.  The {cmd:mata} {cmd:mosave} command 
created file {cmd:calcsum.mo} stored in our {cmd:PERSONAL} sysdir
directory; see 
{bf:{help mata_mosave:[M-3] mosave}}
and 
{bf:{help sysdir:[P] sysdir}}
for more details.
We put the {cmd:calcsum.mo} file in our {cmd:PERSONAL} directory so that 
Stata and Mata would be able to find it, just as you probably did with 
the {cmd:varsum.ado} ado-file.

{pstd}
Typing in the {cmd:calcsum()} program interactively is too prone to
error, so instead what we can do is create a do-file to perform the 
step, and then run the do-file once:


	{hline 51} varsum.do {hline 5}
	{cmd:version 9.0}
	{cmd:mata:}
	{cmd:void calcsum(string scalar varname, string scalar touse)}
	{cmd:{c -(}}
	       {cmd:real colvector  x}

	       {cmd:st_view(x, ., varname, touse)}
	       {cmd:st_numscalar("r(sum)", colsum(x))}
	{cmd:{c )-}}

	{cmd:mata mosave calcsum(), dir(PERSONAL) replace}
	{cmd:end}
	{hline 51} varsum.do {hline 5}

{pstd}
We save the do-file someplace safe in case we should need to modify our 
code later, either to fix bugs or to add features.  For the same reason, we
added a {cmd:replace} option on the command that creates the {cmd:.mo} file,
so we can run the do-file over and over.

{pstd}
To follow the third organization -- putting our {cmd:calcsum()} subroutine
in a library -- is just a matter of modifying {cmd:varsum.do} to 
do {cmd:mata} {cmd:mlib} {cmd:add} rather than {cmd:mata} {cmd:mosave}.
See {bf:{help mata_mlib:[M-3] mlib}}; there are important details having to do
with how you will manage all the different functions you will put in the
library, but that has nothing to do with our problem here.

{pstd}
Where and how you store your Mata subroutines has nothing to do
with what your Mata subroutines do or how you use them.


{title:Passing arguments to Mata functions}

{pstd}
In designing a subroutine, you have two paramount interests:  how you get
data into your subroutine and how you get results back.  You get data in
by the values you pass as the arguments.  In the case of {cmd:calcsum()}, we
called the subroutine by coding

	{cmd:mata: calcsum("`varlist'", "`touse'")}

{pstd}
After macro expansion, that line turned into something like

	{cmd:mata: calcsum("mpg", "__0001dc")}

{pstd}
The {cmd:__0001dc} variable is a temporary variable created by 
the {cmd:marksample} command earlier in our ado-file.
{cmd:mpg} was the variable specified by the user.
What is important to understand is that, after expansion,