-------------------------------------------------------------------------------
help for matsave and matload                            (contact Marc Muendler)
-------------------------------------------------------------------------------

Save and load matrices

        matsave matrix [, replace saving dropall path(path) type(type) ]

        matload filename [, saving dropall path(path) missing(value)
               rowname(variable) overwrite ]


Description

matsave saves a matrix from memory to disk as a Stata dataset (matrix.dta).
matload loads a matrix that has been saved with matsave. matsave and matload
are based on Stata commands svmat and mkmat (mkmat).

matsave creates a Stata dataset. The variable names correspond to the column
names of matrix. Column names must be unique. matsave also creates a variable
_rowname containing the row names of matrix. matrix is saved as
path\matrix.dta. (To assign column and row names, see matrname.)

matload expects a variable _rowname for backward conversion, or a variable that
takes the role of _rowname must be specified.


Common Options

saving forces matsave and matload to save the data that are presently in memory
    and to restore the data upon completion. Setting saving does not affect a
    preceding preserve command. If there are data in memory and saving is not
    specified, matsave and matload will abort.

dropall makes matsave and matload drop data from memory if present. The data
    will not be restored upon completion. dropall may not be abbreviated.

path() supplies the path where matsave saves matrix and from where matload
    loads matrix.dta. The pathname in path(pathname) needs to be a string. If
    path() is not specified, then matsave and matload expect files in the
    current Stata working directory.

Options for matsave

replace permits matsave to overwrite an existing dataset matrix.dta.  replace
    may not be abbreviated.

type(type) makes matsave save all variables as type. The default type is float.

Options for matload

missing(value). Matrices cannot contain missing entries in versions of Stata
    before 8. The option missing(value) replaces any missing values in the file
    matrix.dta with the specified value when loading the file. The default
    value is -999.

rowname(variable). matload expects a variable _rowname for backward conversion.
    Alternatively, the option rowname(variable) renames the variable variable
    in the file matrix.dta to _rowname when loading the file.

overwrite permits matload to overwrite an existing matrix in memory with the
    dataset matrix.dta from disk.


Remarks on matsave

A typical use of matsave is

        . matsave A, p("matrices") dropall

This saves matrix A to subdirectory "dir\matrices", where dir stands for the
current Stata working directory. The option dropall works like a preceding drop
_all command and removes all data from memory.

matsave uses the Stata command svmat, and svmat requires that data are removed
from memory. If a dataset is in memory, an error message would result

        . matsave A
        no; data in memory would be lost
        r(4);

matsave can remove and restore the data for you. Under the option saving,
matsave saves the current dataset temporarily, drops all variables, and
restores the data upon completion.

        . matsave A, replace p("matrices") saving

The option saving is different from preserve in that it can be applied in
addition to a preceding preserve command. In other words, saving allows a
double preservation of data.

The option saving can be time consuming, however, if your dataset in memory is
large. Dropping all variables can be more efficient when many matrices are
saved or loaded.

        . preserve
        . matsave A, replace p("matrices") dropall
        . matsave B, replace p("matrices") dropall
          rest of code
        . restore

If the path "dir\matrices\" does not exist, matsave will result in the error

        . matsave A, replace p("matrices") dropall
        error (after svmat was applied)
        file could not be opened
        r(603);


Remarks on matload

The command

        . matload A, p("matrices") saving over

loads the saved matrix A back into memory. matload is based on the Stata
command mkmat and also requires temporary removal of data from memory.

Under the option overwrite, matload replaces the current matrix A in memory
with the one loaded from "dir\matrices\A.dta".  Without the option overwrite,
matload would have responded with an error message.

        . matload A, p("matrices")
        no; matrix A would be lost
        r(4);


A note on column names

matsave saves the row names of matrix in a variable _rowname. The column names
of matrix will become the variable names in matrix.dta.  Column names must be
unique. If a column of matrix is called "_cons", "_b" or "_coef", the according
variables will be named "__cons", "__b" or "__coef" in matrix.dta ("_cons",
"_b" and "_coef" are protected system variables).  matload expects the variable
_rowname for backward conversion. matload transforms column names "__cons",
"__b" or "__coef" back to "_cons", "_b" or "_coef".

To assign column and row names to matrix, see matrname.

The name of matrix is not allowed to coincide with a variable name in memory.


Examples

        . matsave A, p("matrices") s replace
        . matload A, p("matrices") s over

Author

Marc-Andreas Muendler, Assistant Professor, Department of Economics, University
of California, San Diego.
URL: http://econ.ucsd.edu/~muendler/, Email: muendler@econ.ucsd.edu.

Also see

 Manual:  [P] matrix utility
On-line:  help for matrix, mkmat, matrname