NUMIN:  Facilities for input of numeric data.

Programs that take numeric data as input can use the 'numin'
facilities for reading this input from data files.  Such a data file
must consist of a number of lines, each of which contains a number of
"items", which are separated by whitespace, commas, or semicolons.
The number of numeric items to get from each line is fixed by the
program or user; the indexes of these items within a line are given by
a specification string, which is usually input by the user.  The
specification string also gives the file name and a range of lines to
read.
  
A specification string can have two forms:

    [filename][@[-]first[:[last]]]{,index}   or   .

If the range part or the index part is absent, it defaults to values
determined by the program (as left over from the previous
specification, if nothing special is done), provided the filename part
is also missing (it also defaults).  If the filename part is present,
the defaults are the entire file and indexes starting at one.  The "."
form leaves everything to default.

The "@" part of the specification gives the range of lines to read,
with the end of the range defaulting to the end of the file.  (Leaving
out just 'last' or both 'last' and the preceding colon do the same
thing.)  The presence of a "-" causes all the lines _except_ those in
the range to be read.  Line numbers start at one.

If 'filename' starts with "%", it is taken to be the name of a shell
command to be run to generate the data.  This command may be run
several times; it must deliver the same data each time.

The index specifications give the positions of items to read within a
line, with the first item in a line having index one.  An index of
zero is also allowed, and gives the value zero without any reference
to the file.  Any excess items in the line are ignored, but the line
must contain the items that are required.  The indexes of these items
need not be in increasing order.  It is an error for the specification
to give more item indexes than the number of items required.  The
number of indexes may be less than required, however, in which case
successive indexes following the last one specified are used.  If no
indexes are specified, they start with a default position, which will
be just after the last position for the numin specification used
immediately previously (provided a different default has not been set
up by the program, and provided no filename is specified this time).

Items read must be numbers in standard notation (including the
possibility of "e" for exponents), except that "?" may be used to
indicate a missing value.  However, some modules may not do sensible
things with missing values, which are represented internally by NaN.

            Copyright (c) 1995-2004 by Radford M. Neal