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 ]


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.


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


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