Stata 15 help for _mkvec

Title

[P] _mkvec -- Programmer's utility for creating a vector using from(init_specs)

Syntax

_mkvec matname [, from(init_specs [, copy skip]) update colnames(list_of_colfullnames) first error(string) ]

where init_specs is one of the following forms:

vectorname

{ [eqname:]name=# | /eqname=# } [...]

# [#] [...]

If the last form above is used, then the copy option must be specified.

list_of_colfullnames is a full matrix stripe, such as that returned by the colfullnames macro function.

Description

Programmers may need to process the elements of a from() specification (see [R] maximize) before passing it to ml model or otherwise using it. This command turns a from() specification into a row vector called matname.

If update is specified, matname is an existing row vector, and it is updated with the values in from().

If update or colnames() is specified, the equation and colnames implied by from() are checked against the original matname or colnames(). The returned row vector matname is labeled with the original matname or colnames() equation/colnames in the original order.

If update or colnames() is specified, any elements not specified by from() are filled in with zeros. Hence, when update or colnames() is specified, programmers can be assured of the dimension, equation/colnames, and order of the resulting row vector matname.

Using update with an initial row vector of all zeros is equivalent to using colnames(). With colnames(), however, you do not have to create an initial vector.

Options

from(..., copy) specifies that the initialization is to be copied into the vector without checking for valid column names. copy must be specified when init_specs is simply a list of numbers.

from(..., skip) indicates that if extra vector elements are specified, they are ignored. Note that too few elements are always allowed.

update specifies that matname is an existing row vector that is to be updated with the values in from(). If the copy option is NOT specified, then from() must be a properly labeled vector or have equation and colnames fully specified via the [eqname:]name=# syntax. The equation and colnames implied by from() are checked against those in the initial row vector.

colnames() specifies the full matrix stripe that the programmer expects to be present in the from() specification. If the copy option is NOT specified, then from() must be a properly labeled vector or have equation and colnames fully specified via the [eqname:]name=# syntax. The equation and colnames implied by from() are checked against those in colnames(). The resulting vector returned by _mkvec is always labeled by colnames().

first allows any blank equation names in from() to be interpreted as the first equation name in colnames(). This option is typically specified when there is one main equation and, possibly, auxiliary parameters.

error() specifies an optional label for error messages. For example, if the programmer is processing a from() option on the main command, error("from()") can be specified.

Examples

Although not intended for interactive use, these examples illustrate how the command works:

. _mkvec x, from(mpg=1.2 wei=0.003)

. matrix list x

x[1,2] mpg weight r1 1.2 .003

. _mkvec x, from(mpg=5) update

. matrix list x

x[1,2] mpg weight r1 5 .003

. _mkvec x, from(_cons=2 mp=1 /sigma=4) colnames(price:mpg price:weight price:_cons sigma:_cons) first

. matrix list x

x[1,4] price: price: price: sigma: mpg weight _cons _cons r1 1 0 2 4

. sreturn list

macros: s(k_fill) : "3" s(k) : "4"

. _mkvec x, from(junk=5 _cons=2 mp=1 /sigma=4, skip) colnames(price:mpg price:weight price:_cons sigma:_cons) first

. matrix list x

x[1,4] price: price: price: sigma: mpg weight _cons _cons r1 1 0 2 4

. _mkvec x, from(head=5 _cons=2 mp=1 /sigma=4) error("from()") colnames(price:mpg price:weight price:_cons sigma:_cons) first from(): extra parameter headroom found; specify skip option if necessary r(111);

. _mkvec x, from(1 2 3 4, copy)

. matrix list x

x[1,4] c1 c1 c1 c1 r1 1 2 3 4

. _mkvec x, from(1 2 3 4, copy) colnames(price:mpg price:weight price:_cons sigma:_cons)

. matrix list x

x[1,4] price: price: price: sigma: mpg weight _cons _cons r1 1 2 3 4

Here is an example of the use of _mkvec in a program:

program define mycmd syntax varlist [if] [in] [, from(string) ... ] ... if "`from'"!="" { tempname b0 _mkvec `b0', from(`from') error("from()") [process `b0'] local initopt "init(`b0',`s(copy)' `s(skip)')" } ... ml model ... , `initopt' ... ... end

In the above example, the programmer did not specify colnames() because the programmer did not need to check for proper equation/colnames (ml model will check it).

Stored results

_mkvec stores the following in s():

s(copy) = "copy" if copy specified in from() s(skip) = "skip" if skip specified in from() s(k) = the dimension of the vector s(k_fill) = the number of elements explicitly filled in by from()


© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index