mf_st_data.hlp

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

{smcl}
{* 23mar2005}{...}
{cmd:help mata st_data()}
{hline}
{* index _st_data()}{...}
{* index _st_sdata()}{...}
{* index st_data()}{...}
{* index st_sdata()}{...}
{* index data matrix}{...}
{* index variable}{...}

{title:Title}

{p 4 4 2}
{bf:[M-5] st_data() -- Load copy of current Stata dataset}


{title:Syntax}

{col 5}{it:real scalar}{...}
{col 19}{cmd:_st_data(}{...}
{it:real scalar i}{cmd:,} {...}
{it:real scalar j}{cmd:)}

{col 5}{it:real matrix}{...}
{col 20}{cmd:st_data(}{...}
{it:real matrix i}{cmd:,} {...}
{it:rowvector j}{cmd:)}{...}
{right:(1,2)}

{col 5}{it:real matrix}{...}
{col 20}{cmd:st_data(}{...}
{it:real matrix i}{cmd:,} {...}
{it:rowvector j}{cmd:,} {...}
{it:scalar selectvar}{...}
{cmd:)}{...}
{right:(1,2,3)}


{col 5}{it:string scalar}{...}
{col 20}{cmd:_st_sdata(}{...}
{it:real scalar i}{cmd:,} {...}
{it:real scalar j}{...}
{cmd:)}

{col 5}{it:string matrix}{...}
{col 20}{cmd:st_sdata(}{...}
{it:real matrix i}{cmd:,} {...}
{it:rowvector j}){...}
{right:(1,2)}

{col 5}{it:string matrix}{...}
{col 20}{cmd:st_sdata(}{...}
{it:real matrix i}{cmd:,} {...}
{it:rowvector j}{cmd:,} {...}
{it:scalar selectvar}{cmd:)}{...}
{right:(1,2,3)}


{p 4 4 2}
where

{p 7 11 2}
1.  {it:i} may be specified as a 1 {it:x} 1 scalar, 
    as a 1 {it:x} 1 scalar containing missing, 
    as a column vector of observation numbers, 
    as a row vector specifying an observation range, 
    or as a {it:k x} 2 matrix specifying both.

{p 14 18 2}
a.  {cmd:st_data(1, 2)} returns the first observation on the second variable.

{p 14 18 2}
b.  {cmd:st_data(., 2)} returns all observations on the second variable.

{p 14 18 2}
c.  {cmd:st_data((1\2\5), 2)} returns observations 1, 2, and 5 on the 
    second variable.

{p 14 18 2}
d.  {cmd:st_data((1,5), 2)} returns observations 1 through 5 on the second 
    variable.

{p 14 18 2}
d.  {cmd:st_data((1,5\7,9), 2)} returns observations 1 through 5 and 
    observations 7 through 9 on the second variable.

{p 11 11 2}
When a range is specified, any element of the range 
({it:i1},{it:i2}) may be specified so as to contribute zero observations
if {it:i2}={it:i1}-1.

{p 7 11 2}
2.  {it:j} may be specified as a real row vector or as a string row vector.

{p 14 18 2}
a.  {cmd:st_data(2, .)} returns the values of all variables, second observation,
    of the Stata dataset.

{p 14 18 2}
b.  {cmd:st_data(2, 1)} returns the value of the first variable, second
    observation.

{p 14 18 2}
c.  {cmd:st_data(2, (3,1,9))} returns the values of the 3rd, 1st, and 9th
    variables of the second observation.

{p 14 18 2}
d.  {cmd:st_data(2, ("mpg", "weight"))} returns the values of variables 
    mpg and weight, second observation.

{p 14 18 2}
e.  {cmd:st_data(2, ("gnp", "l.gnp"))} returns the values of gnp and the 
    lag of gnp, second observation.

{p 7 11 2}
3.  {it:selectvar} may be specified as real or as a string.
    Observations for which {it:selectvar}!=0 will be selected.
    If {it:selectvar} is real, it is interpreted as a variable number.  If
    string, {it:selectvar} should contain the name of a Stata variable.

{p 11 11 2}
    Specifying {it:selectvar} as {cmd:""} or as missing ({cmd:.})
    has the same result as not specifying {it:selectvar} at all.

{p 11 11 2}
    Specifying {it:selectvar} as {cmd:0} means that observations 
    with missing values of the variables specified by {it:j} are to be
    excluded.


{title:Description}

{p 4 4 2}
{cmd:_st_data(}{it:i}, {it:j}{cmd:)} returns the numeric value of the
{it:i}th observation of the 
{it:j}th Stata variable.  
Observations are numbered 1 through
{bf:{help mf_st_nvar:st_nobs()}}.
Variables are numbered 1
through {bf:{help mf_st_nvar:st_nvar()}}.  

{p 4 4 2}
{cmd:st_data(}{it:i}, {it:j}{cmd:)} is similar to {cmd:_st_data(}{it:i},
{it:j}{cmd:)} except

{p 6 10 2}
1.  {it:i} may be specified as a vector or matrix to obtain multiple 
observations simultaneously.

{p 6 10 2}
2.  {it:j} may be specified using names or indices (indices are faster).

{p 6 10 2}
3.  {it:j} may be specified as a vector to obtain multiple variables 
    simultaneously.

{p 4 4 2}
The net effect is that {cmd:st_data()} can return a scalar (the value of one
variable in one observation), a rowvector (the value of many variables in an
observation), a colvector (the value of a variable in many observations), or a
matrix (the value of many variables in many observations).

{p 4 4 2}
{cmd:st_data(}{it:i}, {it:j}, {it:selectvar}{cmd:)} works like 
{cmd:st_data(}{it:i}, {it:j}{cmd:)} except
that only observations for which {it:selectvar}!=0 are returned.

{p 4 4 2}
{cmd:_st_sdata()} and {cmd:st_sdata()} are the string variants of 
{cmd:_st_data()} and {cmd:st_data()}.
{cmd:_st_data()} and {cmd:st_data()} are for use with numeric variables; 
they return missing ({cmd:.}) when used with string variables.
{cmd:_st_sdata()} and {cmd:st_sdata()} are for use with string variables; 
they return empty string ({cmd:""}) when used with numeric variables.


{title:Remarks}

{p 4 4 2}
Remarks are presented under the headings 

	{bf:Description of _st_data() and _st_sdata()}
	{bf:Description of st_data() and st_sdata()}
	{bf:Details of observation subscripting using st_data() and st_sdata()}


{title:Description of _st_data() and _st_sdata()}

{p 4 4 2}
{cmd:_st_data()} returns one variable's value in one observation.  You refer to
variables and observations by their numbers.  The first variable in the Stata
dataset is 1; the first observation is 1.

	{cmd:_st_data(1, 1)}            value if 1st obs., 1st variable
	{cmd:_st_data(1, 2)}            value if 1st obs., 2nd variable
	{cmd:_st_data(2, 1)}            value if 2nd obs., 1st variable

{p 4 4 2}
{cmd:_st_sdata()} works the same way.  {cmd:_st_data()} is for use with
numeric variables, and {cmd:_st_data()} is for use with string variables.

{p 4 4 2}
{cmd:_st_data()} and {cmd:_st_sdata()} are the fastest way to obtain the 
value of a variable in a single observation.


{title:Description of st_data() and st_sdata()}

{p 4 4 2}
{cmd:st_data()} can be used just like {cmd:_st_data()}, and used that way, 
it produces the same result.  

{p 4 4 2}
Variables, however, can be referred to by their names or the numbers:

	st_data(1, 1)             value if 1st obs., 1st variable
	st_data(1, 2)             value if 1st obs., 2nd variable
	st_data(2, 1)             value if 2nd obs., 1st variable

        st_data(1, "mpg")         value of 1st obs, variable mpg
        st_data(2, "mpg")         value of 2nd obs, variable mpg

{p 4 4 2}
In addition, you may specify more than one variable:

	st_data(2, (1,2,3))       value of 2nd obs., variables 1, 2, and 3

	st_data(2, ("mpg","weight","displ"))
				  value of 2nd obs., variables mpg, weight,
				  and displ.

{p 4 4 2}
Used this way, st_data() returns a rowvector.

{p 4 4 2}
Similarly, you may obtain multiple observations:

       st_data((1\2\3), 10)       values of obs. 1, 2, and 3, var. 10

       st_data((1,5), 10)         values of obs. 1 through 5, var. 10

       st_data((1,5)\(7,9), 10)   values of obs. 1 through 5 and 7 through 9,
                                  var. 10

{p 4 4 2}
{cmd:st_sdata()} works the same way as {cmd:st_data()}.


{title:Details of observation subscripting using st_data() and st_sdata()}

{p 4 8 2}
1.  {it:i} may be specified as a scalar:{break}
    the specified, single observation is returned.
    {it:i} must be between 1 and {cmd:st_nobs()}.

{p 4 8 2}
2.  {it:i} may be specified as a scalar containing missing value:{break}
    all observations are returned.

{p 4 8 2}
3.  {it:i} may be specified as a colvector:{break}
    the specified observations are returned.  Each element of {it:i} 
    must be between 1 and {cmd:st_nobs()} or may be missing.  Missing 
    is interpreted as {cmd:st_nobs()}.

{p 4 8 2}
4.  {it:i} may be specified as a rowvector with 2 columns:{break}
    the specified range of observations is returned;
    {cmd:(}{it:c1}{cmd:,}{it:c2}{cmd:)} returns the {it:c2}-{it:c1}+1 
    observations {it:c1} through {it:c2}.

{p 8 8 2}
    {it:c2}-{it:c1}+1 must evaluate to a number greater than or equal to 0.
    In general, {it:c1} and {it:c2} must be between 1 and {cmd:st_nobs()}, but
    if {it:c2}-{it:c1}+1=0, then {it:c1} may be between 1 and
    {cmd:st_nobs()}+1 and {it:c2} may be between 0 and {cmd:st_nobs()}.
    Regardless, {it:c1}==. or {it:c2==.} is interpreted as {cmd:st_nobs()}.

{p 4 8 2}
5.  {it:i} may be specified as a {it:k x} 2 matrix:{break}
    {cmd:((1,5)\(7,7)\(20,30))} specifies observations 1 through 5, 7, 
    and 20 through 30.


{title:Conformability}

{p 4 8 2}
{cmd:_st_data(}{it:i}, {it:j}{cmd:)},
{cmd:_st_sdata(}{it:i}, {it:j}{cmd:)}:
{p_end}
		{it:i}:  1 {it:x} 1
		{it:j}:  1 {it:x} 1
	   {it:result}:  1 {it:x} 1

{p 4 8 2}
{cmd:st_data(}{it:i}, {it:j}{cmd:)},
{cmd:st_sdata(}{it:i}, {it:j}{cmd:)}:
{p_end}
		{it:i}:  {it:n x} 1  or  {it:n2 x} 2
		{it:j}:  1 {it:x k}
	   {it:result}:  {it:n x k}

{p 4 8 2}
{cmd:st_data(}{it:i}, {it:j}, {it:selectvar}{cmd:)},
{cmd:st_sdata(}{it:i}, {it:j}, {it:selectvar}{cmd:)}:
{p_end}
		{it:i}:  {it:n x} 1  or  {it:n2 x} 2
		{it:j}:  1 {it:x k}
	{it:selectvar}:  1 {it:x} 1
{p 11 30 2}
        {it:result}:  ({it:n}-{it:e}) {it:x k}, where {it:e} is number of
                   observations excluded by {it:selectvar}


{title:Diagnostics}

{p 4 4 2}
{cmd:_st_data(}{it:i}, {it:j}{cmd:)} 
returns missing ({cmd:.}) if {it:i} 
or {it:j} is out of range; it does not abort with error.

{p 4 4 2}
{cmd:_st_sdata(}{it:i}, {it:j}{cmd:)} returns "" if {it:i} 
or {it:j} is out of range; it does not abort with error.

{p 4 4 2}
{cmd:st_data(}{it:i}{cmd:,} {it:j}{cmd:)} and
{cmd:st_sdata(}{it:i}{cmd:,} {it:j}{cmd:)} 
abort with error if any element of {it:i} or {it:j} is out of range.
Note that {it:j} may be specified as a vector of variable names
or a vector of variable indices.  If names are specified, 
abbreviations are allowed.  If you do not want this, 
use {bf:{help mf_st_varindex:[M-5] st_varindex()}} to translate 
variable names into variable indices.


{title:Source code}

{p 4 4 2}
Functions are built-in.


{title:Also see}

{p 4 13 2}
Manual:  {hi:[M-5] st_data()}

{p 4 13 2}
Online:  help for 
{bf:{help mf_st_view:[M-5] st_view()}},
{bf:{help mf_st_store:[M-5] st_store()}};
{bf:{help m4_stata:[M-4] stata}}
{p_end}