{smcl}
{* 19mar2004}{...}
{hline}
help for {hi:matsave} and {hi:matload}{right:({hi:contact {browse "mailto:muendler@econ.ucsd.edu":Marc Muendler}})}
{hline}
{title:Save and load matrices}
{p 8 15}{cmdab:matsave}
{it:matrix}
[{cmd:,}
{cmdab:replace}
{cmdab:sav:ing}
{cmdab:dropall}
{cmdab:p:ath}{cmd:(}{it:path}{cmd:)}
{cmdab:t:ype}{cmd:(}{it:type}{cmd:)}
]
{p 8 15}{cmdab:matload}
{it:filename}
[{cmd:,}
{cmdab:sav:ing}
{cmdab:dropall}
{cmdab:p:ath}{cmd:(}{it:path}{cmd:)}
{cmdab:m:issing}{cmd:(}{it:value}{cmd:)}
{cmdab:row:name}{cmd:(}{it:variable}{cmd:)}
{cmdab:over:write}
]
{title:Description}
{p}{cmd:matsave} saves a matrix from memory to disk as a Stata dataset
({it:matrix.dta}). {cmd:matload} loads a matrix that has been saved with
{cmd:matsave}. matsave and matload are based on Stata commands svmat and mkmat
({help mkmat}).
{p}{cmd:matsave} creates a Stata dataset. The variable names correspond to the
column names of {it:matrix}. Column names must be unique. matsave also creates
a variable {it:_rowname} containing the row names of {it:matrix}. {it:matrix}
is saved as {it:path}\{it:matrix.dta}. (To assign column and row names, see
{help matrname}.)
{p}{cmd:matload} expects a variable {it:_rowname} for backward conversion, or a variable that takes the role of {it:_rowname} must be specified.
{title:Common Options}
{p 0 4}{cmd:saving} forces matsave and matload to save the data that are
presently in memory and to restore the data upon completion. Setting
{cmd:saving} does not affect a preceding {cmd:preserve} command. If there are
data in memory and {cmd:saving} is not specified, matsave and matload will
abort.
{p 0 4}{cmd:dropall} makes matsave and matload drop data from
memory if present. The data will not be restored upon completion. dropall
may not be abbreviated.
{p 0 4}{cmd:path()} supplies the path where matsave saves {it:matrix} and from
where matload loads {it:matrix.dta}. The {it:pathname} in {cmd:path(}{it:pathname}{cmd:)}
needs to be a string. If {cmd:path()} is not specified, then matsave and matload
expect files in the current Stata working directory.
{title:Options for matsave}
{p 0 4}{cmd:replace} permits matsave to overwrite an existing dataset {it:matrix.dta}.
replace may not be abbreviated.
{p 0 4}{cmd:type(}{it:type}{cmd:)} makes matsave save all variables as {it:type}. The default {it:type} is float.
{title:Options for matload}
{p 0 4}{cmd:missing(}{it:value}{cmd:)}. Matrices cannot contain missing
entries in versions of Stata before 8. The option {cmd:missing(}{it:value}{cmd:)}
replaces any missing values in the file {it:matrix.dta} with the specified
{it:value} when loading the file. The default {it:value} is -999.
{p 0 4}{cmd:rowname(}{it:variable}{cmd:)}. matload expects a variable
{it:_rowname} for backward conversion. Alternatively, the option {cmd:rowname(}{it:variable}{cmd:)}
renames the variable {it:variable} in the file {it:matrix.dta} to {it:_rowname} when loading
the file.
{p 0 4}{cmd:overwrite} permits matload to overwrite an existing matrix in memory with the dataset
{it:matrix.dta} from disk.
{title:Remarks on matsave}
{p}A typical use of matsave is{p_end}
{p 8 12}{inp:. matsave A, p("matrices") dropall}{p_end}
{p} This saves matrix {it:A} to subdirectory "{it:dir}\matrices", where {it:dir}
stands for the current Stata working directory. The option {cmd:dropall}
works like a preceding {inp:drop _all} command and removes all data from
memory.{p_end}
{p} matsave uses the Stata command {cmd:svmat}, and svmat requires that data
are removed from memory. If a dataset is in memory, an error message would result
{p 8 12}{inp:. matsave A}{p_end}
{p 8 12}no; data in memory would be lost{p_end}
{p 8 12}r(4);{p_end}
{p} matsave can remove and restore the data for you. Under the option
{cmd:saving}, matsave saves the current dataset temporarily, drops all
variables, and restores the data upon completion.{p_end}
{p 8 12}{inp:. matsave A, replace p("matrices") saving}{p_end}
{p} The option saving is different from {cmd:preserve} in that it can be
applied in addition to a preceding preserve command. In other words,
{cmd:saving} allows a double preservation of data.
{p} 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.{p_end}
{p 8 12}{inp:. preserve}{p_end}
{p 8 12}{inp:. matsave A, replace p("matrices") dropall}{p_end}
{p 8 12}{inp:. matsave B, replace p("matrices") dropall}{p_end}
{p 10 12}{it:rest of code}{p_end}
{p 8 12}{inp:. restore}{p_end}
{p} If the path "{it:dir}\matrices\" does not exist, matsave will result in the
error {p_end}
{p 8 12}{inp:. matsave A, replace p("matrices") dropall}{p_end}
{p 8 12}error (after svmat was applied){p_end}
{p 8 12}file could not be opened{p_end}
{p 8 12}r(603);{p_end}
{title:Remarks on matload}
{p} The command{p_end}
{p 8 12}{inp:. matload A, p("matrices") saving over}{p_end}
{p} loads the saved matrix {it:A} back into memory. matload is based on
the Stata command {cmd:mkmat} and also requires temporary removal of data
from memory. {p_end}
{p} Under the option {cmd:overwrite}, matload replaces the current
matrix {it:A} in memory with the one loaded from "{it:dir}\matrices\A.dta".
Without the option overwrite, matload would have responded with an
error message. {p_end}
{p 8 12}{inp:. matload A, p("matrices")}{p_end}
{p 8 12}no; matrix A would be lost{p_end}
{p 8 12}r(4);{p_end}
{title:A note on column names}
{p} matsave saves the row names of {it:matrix} in a variable {it:_rowname}. The
column names of {it:matrix} will become the variable names in {it:matrix.dta}.
Column names must be unique. If a column of {it:matrix} is called "_cons", "_b"
or "_coef", the according variables will be named "__cons", "__b" or "__coef"
in {it:matrix.dta} ("_cons", "_b" and "_coef" are protected system variables).
matload expects the variable {it:_rowname} for backward conversion. matload
transforms column names "__cons", "__b" or "__coef" back to "_cons", "_b" or
"_coef".{p_end}
{p} To assign column and row names to {it:matrix}, see {help matrname}.{p_end}
{p} The name of {it:matrix} is not allowed to coincide with a variable name in
memory.{p_end}
{title:Examples}
{p 8 12}{inp:. matsave A, p("matrices") s replace}{p_end}
{p 8 12}{inp:. matload A, p("matrices") s over}{p_end}
{title:Author}
{p}Marc-Andreas Muendler, Assistant Professor, Department of Economics, University of California, San Diego.{p_end}
{p}URL: {browse "http://econ.ucsd.edu/~muendler/":http://econ.ucsd.edu/~muendler/}, Email: {browse "mailto:muendler@econ.ucsd.edu":muendler@econ.ucsd.edu}.{p_end}
{title:Also see}
Manual: {hi:[P] matrix utility}
{p 0 19}On-line: help for {help matrix}, {help mkmat}, {help matrname}{p_end}