Next: matread_file Up: MacAnova Help File Previous: matprint()   Contents

matread()

Usage:
y <- matread(FileName,setName [,quiet:T or F, echo:T or F,printname:F,\
  labels:Labels, silent:T, notfoundok:T, nofileok:T, badkeyok:T,\
  prompt:F]),
  FileName and setName CHARACTER scalars; FileName can also be CONSOLE
  or have the form string:charVal where charVal is a CHARACTER scalar or
  vector.



Keywords: input, files, missing values
x <- matread(FileName,setName) searches a file for a data set whose name
matches setName.  If the data set is found, it is read and the data are
saved in variable x.  The data set must be a REAL, LOGICAL or CHARACTER
vector, matrix, or array or a structure with REAL, LOGICAL, CHARACTER or
macro components.  FileName and setName must be CHARACTER variables or
quoted strings.  See topic 'matread_file' for the required form for the
data set.

In searching the file for a matching name, case is ignored so that, so
that matread(FileName,"mydata") will find mydata, MyData, or MYDATA, for
example.

If setName is omitted (x <- matread("mydata.txt")), matread() will read
the first dataset on the file, expecting that the first non-blank and
non-empty line is a header line of the correct form (see below).

If the data set has keyword LOCKED on the header line, and the result is
assigned to a variable, that variable will be locked.  See topic
'locks'.

  Cmd> x <- matread("datafile.txt","x")
  x   3   COLUMNS LOCKED

  Cmd> list(x)
  x               REAL   3     (locked)

In a version with windows (Macintosh, Windows, Motif), if FileName is
the null string "", you will be able to select the file using a dialog
box.

Just reading a data set does not make it available; you must assign the
value of matread() using '<-'.

Pre-defined macro getdata() is somewhat easier to use, provided you have
set variable DATAFILE to the name of the file.  Since the default value
of DATAFILE is "macanova.dat", another way to read 'irisdata' is

  Cmd> x <- getdata(irisdata)

If you have a file of data sets you will be analyzing, say file
"mydata.txt", redefine DATAFILE by
  Cmd> DATAFILE <- "mydata.txt"
Then you can use macro getdata() to read data sets from your file.  See
topic getdata().

If any data items in numerical data set are too large to be represented
in the computer (for example "1e3000), they are set to MISSING.

If any data item in the file is not a proper number (for example
3."4a5"), it, together with numbers following it on the same line, are
set to MISSING.

matread() and getdata() work only with files in a special format with
header information.  Use vecread() and readcols() to read data files
that just consist of numbers.

matread(CONSOLE [,prompt:F]) reads from the regular input stream
allowing you to type in the matrix using the format described under
topic 'matread_file'.  On the Macintosh, type one line at a time in the
dialog box that is opened.  On Unix/Linux and DOS, type the necessary
lines after the prompt.  The value of CONSOLE is ignored.  The first
line entered must be a header which includes a name and dimensions.  On
any machine, when matread(CONSOLE) is used in a batch file, it reads the
data from the lines immediately following the matread() command.  This
allows even large data sets to be included directly in a batch file.
See batch().  No prompt is given if you include prompt:F as an argument.

There are several keywords, 'quiet', 'echo', 'silent', 'notfoundok' and
'nofileok' which control what will be printed by matread().

  Keyword phrase        Meaning
   quiet:T          Header and descriptive comments will not be printed
   quiet:F          All header and descriptive comments will be printed
   echo:T           Data lines will be printed as they are read
   silent:T         Only error messages will be printed; incompatible
                    with quiet:F or echo:T
   printname:F      The name of the file read will not be printed;
                    printname:T is ignored with silent:T
   notfoundok:T     Failure to find the data set is not considered an
                    error so no error message is printed.
   nofileok:T       Failure to open the file is not considered an error
                    so no error message is printed.
   badkeyok:T       Unrecognized or duplicate keywords are silently
                    ignored.

Without quiet:T or quiet:F, the header and comment lines not starting
with '))' preceding the macro will be echoed to output.

Even without echo:T, data lines are printed when FileName is CONSOLE
and the matread() command is in a batch file.  (In windowed versions,
data will be echoed if FileName is CONSOLE whether or not the command is
in a batch file.)  Such echoing can be suppressed by 'echo:F'.

When notfoundok:T is an argument and the data set is not found or when
nofileok:T is an argument and the file cannot be opend, matread()
returns NULL as value (see topic 'NULL').  When used in macro, this
feature allows special action if data setName is not found.

matread(file:FileName,...) is equivalent to matread(FileName,...).

matread(string:CharVar,...) where CharVec is a CHARACTER scalar or
vector, does not read from a file.  Instead, it "reads" CharVar as if
each element were a line (or several lines if there are embedded
end-of-line characters) read from a file.  The first element or line of
CharVar must be a header line with a name and dimensioning information.
In particular,
  Cmd> x <- matread(string:CLIPBOARD)
would read the first data set on a replica of a data file in the special
variable CLIPBOARD.  In the Macintosh, Windows and Motif versions this
would be taken from the Clipboard.  In the Motif version, you can also
"read" from special variable SELECTION in a similar way.  See topic
'CLIPBOARD'.

If either keyword 'file' or 'string' is used, they can appear in any
position in the argument list, as can setName which must be the only
non-keyword argument.  For example,
  Cmd> x <- matread(quiet:T,"mydataset",file:"myfile.dat")
is equivalent to
  Cmd> x <- matread("myfile.dat","mydataset",quiet:T).

See also topics vecread(), readcols(), macroread(), inforead(), 'files'.


Gary Oehlert 2003-01-15