Next: matread() Up: MacAnova Help File Previous: mathhelp()   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
                                  Usage
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 read() and 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.

                             Keyword 'width'
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.

                             Default formats
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 read() and
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.

                              Naming output
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 .

                            Repeated keywords
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'
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'
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'
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 read() and 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'
Keyword 'header':
matprint(FileName,a,b,...,header:F) writes the variables without any
header lines.  They will not be readable by read() or 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'
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'
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'
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:",").

                              File name ""
On a version with windows, if FileName is "", you will be able to
specify the file name and folder using a dialog box.

                      Keywords 'nsig' and 'format'
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'.

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

                           Writing to CONSOLE
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.

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

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


Gary Oehlert 2005-08-12