matsave and matload for Stata
current version: Mar 19, 2005
(contactMarc-Andreas Muendler)
The commands matsave and matload save Stata matrices to disk and load matrices from disk to memory.
To download the according .ado files, you can use the command
. net from http://econ.ucsd.edu/muendler/download/stata/
in Stata.
Alternatively, you can download the zip file.
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.
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. If there are data in memory and neither dropall nor preserve is specified, matsave and matload will result in the error "no; data in memory would be lost".
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