{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}