-------------------------------------------------------------------------------
help for xsvmat                                                  (Roger Newson)
-------------------------------------------------------------------------------

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

        xsvmat [type] A [,
                 list( [varlist] [if] [in] [ , [list_options] ] )
                 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 an existing matrix, 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 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 2 groups:

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

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


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.

    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 a stronger version of norestore, intended for use by programmers.
        It specifies that the pre-existing dataset in the memory will not be
        restored, even if the user presses Break during the execution of
        xsvmat.  If norestore is specified and fast is absent, then xsvmat
        will go to extra work so that it can restore the original data if the
        user presses Break.

    Note that the user must specify at least one of the four options list(),
        saving(), norestore and fast.  These four options specify whether the
        output dataset is listed to the Stata log, 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, or using dsconcat
        (downloadable from SSC) if installed.


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, or using dsconcat if installed.

    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, or using dsconcat if installed.

    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 parmest 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


Author

    Roger Newson, National Heart and Lung Institute, 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
             help for dsconcat if installed