help for xsvmat(Roger Newson)

Convert a matrix to variables in an output dataset (or resultsset)

xsvmat [type] [ A ] [,

from(matrix_expression)

list( [varlist] [if] [in] [ , [list_options] ] )

frame( framename [ , replace change ] )

saving(filename[, replace])

norestore fast

flist(global_macro_name)

names:(col|eqcol|matcol|string)

idnum(#) nidnum(newvarname)
idstr(string) nidstr(newvarname)

roweq(newvarname)
rownames(newvarname)
roweqnames(newvarname)
rowlabels(newvarname)

coleq(charname)
colnames(charname)
coleqnames(charname)
collabels(charname)

rename(renaming_list)
format(varlist_1 format_1 ... varlist_n format_n)

]

where A is the name of an existing matrix, and type is a storage type for new variables,
and renaming_list is a list of variable names of form

oldvarname_1 newvarname_1 ... oldvarname_n newvarname_n

Description

xsvmat is an extended version of svmat.
It creates an output dataset (or resultsset),
with one observation per row of either an existing matrix or the result of a matrix expression,
and data on the values of the column entries in that row,
and, optionally, extra variables specified by the user.
The output dataset created by xsvmat
may be listed to the Stata log,
or saved to a data frame,
or saved to a disk file,
or written to the memory (overwriting any pre-existing dataset).

Options for use with xsvmat

xsvmat has a large number of options, which are listed in 3 groups:

1. Input-source options. (These specify the input matrix.)

2. Output-destination options.
(These specify where the output dataset will be written.)

3. Output-variable options. (These specify the variables in the output dataset.)

Input-source options

from(matrix_expression) specifies a matrix expression,
which is used to generate the input matrix.
Either the from() option or the input matrix name A must be present,
but not both.

Output-destination options

list( [varlist] [if] [in] [, list_options ] )
specifies a list of variables in the output
dataset, which will be listed to the Stata log by xsvmat.
The list() option can be used with the format() option (see below)
to produce a listing
with user-specified numbers of decimal places or significant figures.
The user may optionally also specify if or in qualifiers to list subsets of combinations
of variable values,
or change the display style using a list of list_options allowed as options by the list command.

frame( name, [ replace change ] ) specifies an output data frame,
containing the output dataset.
If replace is specified, then any existing data frame of the same name is overwritten.
If change is specified,
then the current data frame will be changed to the output data frame after the execution of xsvmat.
The frame() option may not specify the current data frame.
To do this, use one of the options norestore or fast.

saving(filename[, replace]) saves the output dataset to a disk file.
If replace is specified, and a file of that name already exists,
then the old file is overwritten.

norestore specifies that the output dataset will be written to the memory,
overwriting any pre-existing dataset.
This option is automatically set if fast is specified.
Otherwise, if norestore is not specified, then the pre-existing dataset is restored
in the memory after the execution of xsvmat.

fast is an alternative way of specifying norestore

Note that the user must specify at least one of the five options
list(), frame(), saving(), norestore and fast.
These five options specify whether the output dataset is listed to the Stata log,
saved to a data frame,
saved to a disk file, or written to the memory (overwriting any pre-existing dataset).
More than one of these options can be specified.

flist(global_macro_name) specifies the name of a global macro,
containing a filename list (possibly empty).
If saving() is also specified, then
xsvmat will append the name of the dataset specified in the
saving() option to the value of the global macro specified in flist().
This enables the user to build a list of filenames in a global macro, containing the
output of a sequence of output datasets.
These files may later be concatenated using append.

Output-variable options

names(col|eqcol|matcol|string)
specifies how the new variables created from the matrix columns are to be named.

names(col) uses the column names of the matrix to name the variables.

names(eqcol) uses the equation names prefixed to the column names.

names(matcol) uses the matrix name prefixed to the column names.

names(string) names the variables
string1, string2, ..., stringn, where string
is a user-specified string and n is the number of columns of the
matrix.

If names() is not specified, the variables are named
A1, A2, ..., where A is the name of the matrix.

idnum(#) specifies an ID number for the output dataset.
It is used to create a numeric variable, with default name idnum, in the output dataset,
with that value for all observations.
This is useful if the output dataset is concatenated with other xsvmat output datasets
using append.

nidnum(newvarname) specifies a name for the numeric ID variable
evaluated by idnum().
If idnum() is present and nidnum() is absent,
then the name of the numeric ID variable is set to idnum.

idstr(string) specifies an ID string for the output dataset.
It is used to create a string variable, with default name idstr in the output dataset,
with that value for all observations.
This is useful if the output dataset is concatenated with other xsvmat output datasets
using append.

nidstr(newvarname) specifies a name for the string ID variable
evaluated by idstr().
If idstr() is present and nidstr() is absent,
then the name of the string ID variable is set to idstr.

roweq(newvarname) specifies a name for a new variable to be created in the output dataset,
containing the matrix row equation name.

rownames(newvarname) specifies a name for a new variable to be created in the output dataset,
containing the matrix row name.

roweqnames(newvarname) specifies a name for a new variable to be created in the output dataset,
containing the matrix row name,
prefixed by the row equation name followed by a colon,
if the row equation name is present.

rowlabels(newvarname) specifies a name for a new variable to be created in the output dataset,
containing, in the observation corresponding to each row,
the variable label of the variable in the existing dataset whose name is the matrix row name
(if such a variable exists),
or "Constant" if the row name is _cons.

coleq(charname) specifies a name for a variable characteristic
to be set for each matrix column variable in the output dataset,
containing the matrix column equation name.

colnames(charname) specifies a name for a variable characteristic
to be set for each matrix column variable in the output dataset,
containing the matrix column name.

coleqnames(charname) specifies a name for a variable characteristic
to be set for each matrix column variable in the output dataset,
containing the matrix column name,
prefixed by the column equation name followed by a colon,
if the column equation name is present.

collabels(charname) specifies a name for a variable characteristic
to be set for each matrix column variable in the output dataset,
containing the variable label of the variable in the existing dataset
whose name is the matrix column name
(if such a variable exists),
or "Constant" if the column name is _cons.

rename(oldvarname_1 newvarname_1 ... oldvarname_n newvarname_n)
specifies a list of pairs of variable names.
The first variable name of each pair specifies a
variable in the output dataset, which is renamed to the second
variable name of the pair.

format(varlist_1 format_1 ... varlist_n format_n)
specifies a list of pairs of variable lists and display formats.
The formats will be allocated to
the variables in the output dataset specified by the corresponding varlist_i lists.
If rename() is specified, then
any variable names specified by the format() option must be the new names.

Examples

Set-up commands:

. sysuse auto, clear

. regress mpg weight length price foreign

. matrix define covmat=e(V)

. matrix list covmat

The following examples use the list() option to list the output dataset to the Stata log.
After these examples are executed, there is no new dataset either in the memory or on disk.

. xsvmat covmat, list(,)

. xsvmat covmat, rowname(xvar) rowlab(label) list(, abbr(32))

The following example uses the rowlabel(), collabel() and list() options
to list a matrix,
with its rows and columns labelled
with the corresponding variable labels in the existing dataset.

. xsvmat covmat, rowlabel(rowid) collabel(varname) list(, abbr(32) subvarname)

The following example uses the norestore option to create an output dataset in the memory,
overwriting any pre-existing dataset.

. xsvmat double covmat, norestore rownames(param) rowlabels(varlab)

. describe

. list

The following example uses the saving() option to create an output dataset in a disk file.

. xsvmat covmat, rowname(parm) rowlab(parmlab) name(matcol) saving(mycovs1.dta, replace)

. describe using mycovs1

The following example uses the from() option to create and list an output dataset,
with 1 observation per parameter of a fitted model.

. regress mpg weight length price foreign

. xsvmat, from(r(table)') rowname(parm) names(col) rowlab(label) list(,)

The following example uses the from() option to create an output dataset
in a new data frame outframe,
with 1 observation per parameter of a fitted model.
It then uses describe and list
to describe and list the output data set,
before dropping the output data frame.

. regress mpg weight length price foreign

. xsvmat, from(r(table)') rowname(parm) names(col) rowlab(label) frame(outframe, replace)

. frame outframe {

. describe, full

. list, abbr(32)

. }

. frame drop outframe

Author

Roger Newson, Imperial College London, UK.
Email: r.newson@imperial.ac.uk

Also see

Manual: [P] matrix mkmat, [D] append, [D] format

Online: help for svmat, mkmat, append, format