Contents

matprint()

Usage:

matprint(fileName, a, b, ... [, new:T, format:Fmt, nsig:n, sep:sepChar,\
  quoted:T or bylines:T,missing:mVal, name:Name, comments:charVec,\
  width:w, header:F, oldstyle:T, stripdols:T]), a, b, ... arbitrary
  variables, Fmt, sepChar and Name CHARACTER scalars with sepChar only a
  single character, charVec a CHARACTER vector or scalar, mVal a REAL
  scalar, w >= 30 integer.

Keywords: output, files, missing values

matprint(FileName,a,b,... [,new:T]) writes REAL, LOGICAL and CHARACTER
variables a, b,...  (scalars, vectors, matrices, or arrays) file
FileName in a form which can be read by matread().  It can also write
NULL variables and structures.  GRAPH variables are legal arguments but
are currently written as NULL variables.  See topic 'NULL'.

matprint(a,b,...,file:FileName [,new:T]) is an alternative usage.

If new:T is present, anything already in the file is discarded before
writing.  Otherwise, writing is to the end of the file.

If width:w, with w an integer >= 30, is not an argument, the default
value is taken from option 'width' (see subtopi 'options:"width"').
This is the presumed line length and is used to determine the maximum
number of values printed on one line.

For REAL and LOGICAL variables, by default matprint() uses the format
that is used by print(), namely the format specified in option 'format';
this normally provides 5 significant digits in floating point form.

For CHARACTER variables, the default format, whenever possible, is "by
fields", that is elements are written as fields separated by spaces.
This is not feasible if there are any spaces or non-printable characters
in the data.  In that case, each element is quoted ("...").

Structures are written in a form that not only allows matread() to read
all the components, but also can read individual components if desired.
Since macros may be elements of structures, keyword phrases 'oldstyle:T'
and 'stripdols:T' may be arguments of matprint().  See macrowrite().

See topic 'matread_file' for description of the file format.

matprint(FileName,Name1:a,Name2:b,...) gives names Name1, Name2,... to
the data sets written in the file.  Name1, Name2,... must not be
keywords recognized by matprint, see below.  For example,
   matprint("Results.mat",values:releigenvals(h,e))
will write a matrix on file Results.mat with name 'values' on the first
line of the header .

Keywords 'nsig', 'format', 'name', 'header', 'missing' 'width',
'oldstyle', 'stripdols' and 'comments' are all recognized and can appear
more than once.  They affect the printing of objects that follow them,
until they are changed, except that the values of 'name' and 'comments'
are used only once.  Any of them that follow all items to be printed are
treated as coming before all items.  For example,
  Cmd> matprint("data.txt",x,nsig:5,y,nsig:10)
and
  Cmd> matprint("data.txt",nsig:10, x,nsig:5,y)
are equivalent.  This does not apply to keywords 'file' and 'new' which
can appear only once.

Keyword 'name':
matprint(FileName,name:charVar, a, b, ... ) prints a with the name
specified by quoted string or CHARACTER scalar charVar on the header.
This is an alternative to using a keyword to specify a name and can be
used when the name is not a legal MacAnova keyword name.  For example,
matprint("myfile", name:"Residuals",r) and matprint("myfile",
Residuals:r) are equivalent.  Keyword 'name' can be used several times
in the argument list, and affects only the next item to be written to
the file.  If name:charVar is the last argument, it is treated as if it
came before all items to be written to the file.

Keyword 'comment':
matprint(FileName, a, comment:charVec) writes each element of CHARACTER
vector or quoted string charVec, prefixed by ") ", as a comment line
after the header.  If header:F appears, no such comments are written.

Keyword 'missing':
matprint(FileName,a,b,...,missing:realVal) recodes MISSING values with
REAL number realVal.  For example, matprint("mydata.txt",x, missing:-99)
substitutes -99 for every MISSING value.  If 'missing' is not used,
MISSING values will be coded as -99999.9999.  In either case, for any
variable with MISSING values, a comment line of the form ')MISSING
value' is written before the data, where value is either -99999.9999 or
the value specified by 'missing'.  This enables matread() to recognize
missing values and read them appropriately.  Keyword 'missing' can be
used several times, each affecting any variables later in the argument
list.  If it follows all variables to be printed, as in the example, it
is as if it preceded them all.  The value for 'missing' cannot itself be
a MISSING value.

Note this use of 'missing' differs from print(), write() and
setoptions() -- its value must be a REAL scalar, not a character string.

Keyword 'header':
matprint(FileName,a,b,...,header:F) writes the variables without any
header lines.  They will not be readable by matread() but will be
readable by other programs that can read numbers separated by spaces.
The only time you need header:T is when sep:"c" is an argument and you
want to force the writing of a header.

Keyword 'width':
matprint(FileName,a,b,...,width:w) temporarily sets option 'width' to w,
an integer >= 30. This affects how many items are printed per line.

Keyword 'sep':
matprint(FileName,a,b,...,sep:"c"), where c is an arbitrary character,
writes items of data separated by c instead of by spaces.  This also
suppress the printing of header lines unless 'header:T' is an argument.
This option is useful if you want to export data to a spreadsheet or
other program that can read comma- or tab-separated items.  For example,
to write x with values separated by commas, use matprint("export.dat",x,
sep:",").  matprint("export.dat",x,sep:"\t") writes items separated by
tabs.

Keywords 'quoted' and 'bylines':
When writing a CHARACTER variable you can also include keyword phrases
quoted:T or bylines:T.  matprint(fileName, charVar, quoted:T) outputs
the data set in "quoted fields" format, that is with each element
enclosed in double quotes ("...").  matprint(fileName, charVar,
byline:T) outputs the data set in "by lines" format, with each element
starting on a new line.  However, if there are non-printable characters
in the data, "quoted" fields format will be used.  You can output a
character variable in comma separated quoted fields as is required form
some programs such as data bases, by matprint(fileName, charvar,
quoted:T,sep:",").

On a version with windows (Macintosh, Windows or Motif), if FileName is
"", you will be able to specify the file name and folder using a dialog
box.

Keywords 'nsig' and 'format':
matprint() uses the same default format for each item written as does
print() and has the same keywords 'nsig' and 'format'.  See print() for
information on 'nsig' and 'format'.

If an argument is LOGICAL, a comment line of the form ') LOGICAL' is
added to the header lines.  This is recognized by matread().

If FileName is variable CONSOLE or a CHARACTER variable whose value is
"CONSOLE", the output is written to the screen rather than to a file.
The value of variable CONSOLE is ignored.

You can change the default format for print() and matprint() by
setoptions() using keywords 'nsig' or 'format'.  See topics 'setoptions'
and 'options'.

See also topics write(), write(), matprint(), macrowrite(), matread(),
'files'.